belaran@999: <?xml version="1.0"?>
belaran@999: 
belaran@999: <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
belaran@999:  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: <book id="hg">
belaran@999:   <title>Mercurial: The Definitive Guide</title>
belaran@999:   
belaran@999:   <!-- hg parents &#x2d;&#x2d;template '{node|short} ({date|shortdate})' 
belaran@999:   <subtitle>Compiled from 8a1d3f1aff17 (2009-03-10)</subtitle>
belaran@999:   -->
belaran@999:   <subtitle>Compiled from $rev_id$</subtitle>
belaran@999:   <bookinfo>
belaran@999:     <edition>1</edition>
belaran@999:     <isbn>9780596800673</isbn>
belaran@999:     <authorgroup>
belaran@999:       <author>
belaran@999:         <firstname>Bryan</firstname>
belaran@999:         <surname>O'Sullivan</surname>
belaran@999:       </author>
belaran@999:     </authorgroup>
belaran@999: 
belaran@999:     <editor>
belaran@999:       <firstname>Mike</firstname>
belaran@999:       <surname>Loukides</surname>
belaran@999:     </editor>
belaran@999: 
belaran@999:     <copyright>
belaran@999:       <year>2006</year>
belaran@999:       <year>2007</year>
belaran@999:       <year>2008</year>
belaran@999:       <year>2009</year>
belaran@999:       <holder>Bryan O'Sullivan</holder>
belaran@999:     </copyright>
belaran@999:   </bookinfo>
belaran@999: 
belaran@999:   <!-- BEGIN ch00 -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <preface id="chap:preface">
belaran@999:   <?dbhtml filename="preface.html"?>
belaran@999:   <title>Preface</title>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Un conte technique</title>
belaran@999: 
belaran@999:     <para id="x_72e">Il y a quelques années, quand j'ai voulu expliqué
belaran@999:     pourquoi je pensais que le gestion de révision distribuée est importante,
belaran@999:     le domaine était encore si nouveau qu'il n'y avait presque aucune 
belaran@999:     littérature publiée pour servir de référence aux personnes intéressées.</para>
belaran@999: 
belaran@999:     <para id="x_72f">Bien qu'à cette époque je passais beaucoup de temps
belaran@999:     à travailler sur les entrailles de Mercurial, je me suis mis à la 
belaran@999:     rédaction de ce livre parce qu'il me semblait la manière la plus efficace
belaran@999:     d'aider notre logiciel à atteindre un vaste auditoire, toujours avec 
belaran@999:     l'idée que la gestion de révision devrait être distribuée par nature. J'ai 
belaran@999:     publié ce libre en ligne sous une licence libre pour la même raison : pour 
belaran@999:     diffuser la parole auprès du monde.</para>
belaran@999: 
belaran@999:     <para id="x_730">Il y a un rythme familier à un bon livre sur un logiciel 
belaran@999:     qui ressemble de près au fait de conter une histoire : Pourquoi ceci est ? 
belaran@999:     Pourquoi ceci est important ? Comment peut il m'aider ? Comment m'en 
belaran@999:     servir ? Dans ce livre, j'essaye de répondre à toutes ces questions pour
belaran@999:     la gestion de révision distribuée en général, et pour Mercurial en 
belaran@999:     particulier.</para>
belaran@999:   </sect1>
belaran@999:     
belaran@999:   <sect1>
belaran@999:     <title>Merci de votre soutien à Mercurial</title>
belaran@999: 
belaran@999:     <para id="x_731">En achetant une copie de ce livre, vous soutenez le
belaran@999:     développement et la liberté de Mercurial en particulier, et dans 
belaran@999:     l'Open Source, au logiciel libre en général. O'Reilly Media et 
belaran@999:     moi-même donnons les revenus issus des ventes de ce livre à la
belaran@999:     Software Freedom Conservancy (<ulink url="http://www.softwarefreedom.org/">http://www.softwarefreedom.org/</ulink>) 
belaran@999:       qui fournit un support juridique à Mercurial et à de 
belaran@999:       nombreux autres projets Open Source proéminents et de qualité.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Remerciements</title>
belaran@999: 
belaran@999:     <para id="x_732">Ce livre n'aurait pas vu le jour sans les
belaran@999:     efforts de Matt Mackal, l'auteur et le chef du projet Mercurial.
belaran@999:     Il est assisté très efficacement par des centaines de contributeurs
belaran@999:     volontaires à travers le monde.</para>
belaran@999: 
belaran@999:     <para id="x_733">Les enfants, Cian et Ruairi, ont toujours été prêt
belaran@999:     à m'aider à me reposer avec de merveilleux et impulsif jeux d'enfants. 
belaran@999:     Je tiens aussi à remercier mon ex-femme, Shannon, pour son soutien.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_734">Mes collègues et amis m'ont aidé et assisté de 
belaran@999:     de nombreuses manières. Cette liste de personne est nécessaire mais très
belaran@999:     incomplète : Stephen Hahn, Karyn Ritter, Bonnie Corwin, James Vasile,
belaran@999:     Matt Norwood, Eben Moglen, Bradley Kuhn, Robert Walsh, Jeremy
belaran@999:     Fitzhardinge, Rachel Chalmers.</para>
belaran@999: 
belaran@999:     <para id="x_735">J'ai conçu ce livre de manière ouverte, en publiant
belaran@999:     des brouillons des chapitres du livre sur des site web, au fur et à 
belaran@999:     mesure que je les réalisais. Leurs lecteurs m'ont fait des retours 
belaran@999:     utilisant l'application web que j'avais développée. A la fin de sa
belaran@999:     conception, plus de 100 personnes m'avaient fait des commentaires, 
belaran@999:     un chiffre incroyable quand l'on considère que ce système de 
belaran@999:     commentaire n'a tourné que dans les deux derniers mois de la 
belaran@999:     rédaction du livre.</para>
belaran@999: 
belaran@999:     <para id="x_736">J'aimerais particulièrement remercier les 
belaran@999:     personnes suivantes, dont les commentaires représentent plus
belaran@999:     d'un tiers de l'ensemble de ces derniers. Je voudrais les 
belaran@999:     remercier pour leur attention et effort à me faire des retours
belaran@999:     très détaillés.</para>
belaran@999: 
belaran@999:     <para id="x_737">Martin Geisler, Damien Cassou, Alexey Bakhirkin, Till Plewe,
belaran@999:       Dan Himes, Paul Sargent, Gokberk Hamurcu, Matthijs van der
belaran@999:       Vleuten, Michael Chermside, John Mulligan, Jordi Fita, Jon
belaran@999:       Parise.</para>
belaran@999: 
belaran@999:     <para id="x_738">Je souhaite aussi remercier l'aide des personnes
belaran@999:     qui ont découvert des erreurs et fournit des suggestions avisées
belaran@999:     à travers tout le livre.</para>
belaran@999: 
belaran@999:     <para id="x_739">Jeremy W. Sherman, Brian Mearns, Vincent Furia, Iwan
belaran@999:       Luijks, Billy Edwards, Andreas Sliwka, Paweł Sołyga, Eric
belaran@999:       Hanchrow, Steve Nicolai, Michał Masłowski, Kevin Fitch, Johan
belaran@999:       Holmberg, Hal Wine, Volker Simonis, Thomas P Jakobsen, Ted
belaran@999:       Stresen-Reuter, Stephen Rasku, Raphael Das Gupta, Ned
belaran@999:       Batchelder, Lou Keeble, Li Linxiao, Kao Cardoso Félix, Joseph
belaran@999:       Wecker, Jon Prescot, Jon Maken, John Yeary, Jason Harris,
belaran@999:       Geoffrey Zheng, Fredrik Jonson, Ed Davies, David Zumbrunnen,
belaran@999:       David Mercer, David Cabana, Ben Karel, Alan Franzoni, Yousry
belaran@999:       Abdallah, Whitney Young, Vinay Sajip, Tom Towle, Tim Ottinger,
belaran@999:       Thomas Schraitle, Tero Saarni, Ted Mielczarek, Svetoslav
belaran@999:       Agafonkin, Shaun Rowland, Rocco Rutte, Polo-Francois Poli,
belaran@999:       Philip Jenvey, Petr Tesałék, Peter R. Annema, Paul Bonser,
belaran@999:       Olivier Scherler, Olivier Fournier, Nick Parker, Nick Fabry,
belaran@999:       Nicholas Guarracino, Mike Driscoll, Mike Coleman, Mietek Bák,
belaran@999:       Michael Maloney, László Nagy, Kent Johnson, Julio Nobrega, Jord
belaran@999:       Fita, Jonathan March, Jonas Nockert, Jim Tittsler, Jeduan
belaran@999:       Cornejo Legorreta, Jan Larres, James Murphy, Henri Wiechers,
belaran@999:       Hagen Möbius, Gábor Farkas, Fabien Engels, Evert Rol, Evan
belaran@999:       Willms, Eduardo Felipe Castegnaro, Dennis Decker Jensen, Deniz
belaran@999:       Dogan, David Smith, Daed Lee, Christine Slotty, Charles Merriam,
belaran@999:       Guillaume Catto, Brian Dorsey, Bob Nystrom, Benoit Boissinot,
belaran@999:       Avi Rosenschein, Andrew Watts, Andrew Donkin, Alexey Rodriguez,
belaran@999:       Ahmed Chaudhary.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Conventions utilisées dans ce livre</title>
belaran@999: 
belaran@999:     <para id="x_73a">Les conventions typographiques suivantes sont utilisées dans ce livre :</para>
belaran@999: 
belaran@999:     <variablelist>
belaran@999:       <varlistentry>
belaran@999:         <term>Italique</term>
belaran@999: 
belaran@999:         <listitem>
belaran@999:           <para id="x_73b">Indique les termes nouveaux, les URLs, les
belaran@999:             adresses mail, les noms de fichiers et les extensions de
belaran@999:             fichier.</para>
belaran@999:         </listitem>
belaran@999:       </varlistentry>
belaran@999: 
belaran@999:       <varlistentry>
belaran@999:         <term><literal moreinfo="none">Taille constante</literal></term>
belaran@999: 
belaran@999:         <listitem>
belaran@999:           <para id="x_73c">Utilisé pour les extraits de code, comme 
belaran@999:           dans les paragraphes pour référer aux éléments du programme,
belaran@999:           tels que les variables ou les noms de fonctions, de bases
belaran@999:           de données, de types de données, de variables d'environnement,
belaran@999:           d'instructions, et de mots clés.</para>
belaran@999:         </listitem>
belaran@999:       </varlistentry>
belaran@999: 
belaran@999:       <varlistentry>
belaran@999:         <term><userinput moreinfo="none">Taille constante avec gras</userinput></term>
belaran@999: 
belaran@999:         <listitem>
belaran@999:           <para id="x_73d">Afficher les commandes ou autres textes qui
belaran@999:           devraient être saisis par l'utilisateur.</para>
belaran@999:         </listitem>
belaran@999:       </varlistentry>
belaran@999: 
belaran@999:       <varlistentry>
belaran@999:         <term><replaceable>Constante avec italique</replaceable></term>
belaran@999: 
belaran@999:         <listitem>
belaran@999:           <para id="x_73e">Affiche les textes qui devraient être remplacés 
belaran@999:           par une valeur définie par l'utilisateur ou des valeurs définies
belaran@999:           selon le contexte.</para>
belaran@999:         </listitem>
belaran@999:       </varlistentry>
belaran@999:     </variablelist>
belaran@999: 
belaran@999:     <tip>
belaran@999:       <para id="x_73f">Cette icône indique une astuce, une suggestion ou 
belaran@999:       une note d'ordre général.</para>
belaran@999:     </tip>
belaran@999: 
belaran@999:     <caution>
belaran@999:       <para id="x_740">Cette icône est un message d'alerte ou de prudence.</para>
belaran@999:     </caution>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Utiliser les exemples de code</title>
belaran@999: 
belaran@999:     <para id="x_741">Ce livre est ici pour vous aider dans votre
belaran@999:     travail. De manière générale, vous pouvez donc utiliser le code
belaran@999:     de ce livre dans vos programmes et votre documentation. Vous
belaran@999:     n'avez pas à nous contacter pour nous demander la permission
belaran@999:     de le faire, à moins que vous ne reproduisiez une partie significative
belaran@999:     du code. Par exemple, écrire un programme qui utilise plusieurs 
belaran@999:     extraits de code du livre ne demande aucune autorisation particulière.
belaran@999:     Vendre ou distribuer un CD-ROM provenant des livres O'Reilly demande
belaran@999:     à l'inverse une autorisation. Répondre à une question en citant ce 
belaran@999:     livre ou ses exemples de code ne demande aucune autorisation préalable.
belaran@999:     Intégrer une grande quantité des codes d'exemples de ce livre dans
belaran@999:     votre propre ouvrage demande une autorisation de notre part.</para>
belaran@999: 
belaran@999:     <para id="x_742">Nous apprécions, sans l'exiger, que vous citiez 
belaran@999:     l'ouvrage dans vos écrits l'utilisant, en indiquant le titre, 
belaran@999:     l'auteur, l'éditeur et son ISBN. Par exemple: “<emphasis>Titre du 
belaran@999:     livre</emphasis> par Son Auteur. Copyright 2008 O’Reilly Media, Inc.,
belaran@999:     978-0-596-xxxx-x.”</para>
belaran@999: 
belaran@999:     <para id="x_743">Si vous estimez que votre usage des exemples de code
belaran@999:     dépasse le cadre défini ci dessus, n'hésitez pas à nous contacter :
belaran@999:       <email>permissions@oreilly.com</email>.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Safari® Books Online</title>
belaran@999: 
belaran@999:     <note role="safarienabled">
belaran@999:       <para id="x_744">Quand vous voyez l'icône de Safari® Books Online 
belaran@999:       sur la couverture d'un de vos livres techniques préférés, cela signifie
belaran@999:       que le livre est disponible, en ligne, à travers le O’Reilly Network Safari
belaran@999:         Bookshelf.</para>
belaran@999:     </note>
belaran@999: 
belaran@999:     <para id="x_745">Safari offre une solution qui est meilleure que
belaran@999:     les e-books. C'est une bibliothèque virtuelle qui vous laisse
belaran@999:     aisément rechercher dans des milliers de livres, mais aussi 
belaran@999:     copier-coller leurs exemples, télécharger des chapitres, et 
belaran@999:     trouver des réponses rapides quand vous avez besoin d'une 
belaran@999:     information précise et à jour. Essayez le gratuitement :
belaran@999:     <ulink role="orm:hideurl:ital" url="http://my.safaribooksonline.com/?portal=oreilly">http://my.safaribooksonline.com</ulink>.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Comment nous contacter</title>
belaran@999: 
belaran@999:     <para id="x_746">Merci d'adresser vos commentaires et vos questions
belaran@999:     sur ce livre à son éditeur:</para>
belaran@999: 
belaran@999:     <simplelist type="vert">
belaran@999:       <member>O’Reilly Media, Inc.</member>
belaran@999: 
belaran@999:       <member>1005 Gravenstein Highway North</member>
belaran@999: 
belaran@999:       <member>Sebastopol, CA 95472</member>
belaran@999: 
belaran@999:       <member>800-998-9938 (in the United States or Canada)</member>
belaran@999: 
belaran@999:       <member>707-829-0515 (international or local)</member>
belaran@999: 
belaran@999:       <member>707 829-0104 (fax)</member>
belaran@999:     </simplelist>
belaran@999: 
belaran@999:     <para id="x_747">Nous avons une page web pour cet ouvrage, où nous
belaran@999:     publions des errata, des exemples, et encore d'autres informations
belaran@999:     additionnelles. Vous pouvez accéder à cette page par l'URL suivante:
belaran@999:     </para>
belaran@999: 
belaran@999:     <simplelist type="vert">
belaran@999:       <member><ulink url="http://www.oreilly.com/catalog/&lt;catalog           page&gt;"/></member>
belaran@999:     </simplelist>
belaran@999: 
belaran@999:     <remark>N'oubliez pas de mettre à jour l'attribut &lt;url&gt; aussi.</remark>
belaran@999: 
belaran@999:     <para id="x_748">Pour commenter ou poser des questions techniques 
belaran@999:     sur cet ouvrage, envoyez un email à :</para>
belaran@999: 
belaran@999:     <simplelist type="vert">
belaran@999:       <member><email>bookquestions@oreilly.com</email></member>
belaran@999:     </simplelist>
belaran@999: 
belaran@999:     <para id="x_749">Pour plus d'informations sur nos livres, nos
belaran@999:     conférences, nos centres d'informations, et le réseau O’Reilly, 
belaran@999:     voyez notre site web :</para>
belaran@999: 
belaran@999:     <simplelist type="vert">
belaran@999:       <member><ulink url="http://www.oreilly.com"/></member>
belaran@999:     </simplelist>
belaran@999:   </sect1>
belaran@999: </preface>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "preface")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN ch01 -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <chapter id="chap:intro">
belaran@999:   <?dbhtml filename="how-did-we-get-here.html"?>
belaran@999:   <title>Comment en est on arrivé là ?</title>
belaran@999: 
belaran@999: <sect1>
belaran@999: <title>À propos de la gestion source</title>
belaran@999: 
belaran@999:     <para id="x_6d">La gestion de sources est un processus permettant de gérer différentes
belaran@999: versions de la même information. Dans sa forme la plus simple, c'est
belaran@999: ce que tout le monde fait manuellement : quand vous modifiez
belaran@999: un fichier, vous le sauvegardez sous un nouveau nom contenant un numéro,
belaran@999: à chaque fois plus grand que celui de la version précédente.</para>
belaran@999: 
belaran@999:     <para id="x_6e">Ce genre de gestion de version manuelle est cependant facilement sujette
belaran@999: aux erreurs, ainsi, depuis longtemps, des logiciels existent pour
belaran@999: résoudre cette problématique. Les premiers outils de gestion de sources
belaran@999: étaient destinés à aider un seul utilisateur, à automatiser la gestion
belaran@999: des versions d'un seul fichier. Dans les dernières décades, cette cible
belaran@999: s'est largement agrandie, ils gèrent désormais de multiples fichiers, et
belaran@999: aident un grand nombre de personnes à travailler ensemble. Les outils les
belaran@999: plus modernes n'ont aucune difficulté à gérer plusieurs milliers de
belaran@999: personnes travaillant ensemble sur des projets regroupant plusieurs
belaran@999: centaines de milliers de fichiers.</para>
belaran@999: 
belaran@999:     <para id="x_6f">L'arrivée de la gestion de révision distribuée est
belaran@999:     relativement récente, et, pour le moment, ce nouveau domaine a grandi
belaran@999:     grâce à la volonté des gens d'explorer ces territoires encore inconnus.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_70">J'écris un livre sur la gestion de révision distribuée
belaran@999:     parce que je pense qu'il s'agit d'un sujet important qui mérite un guide
belaran@999:     du terrain. J'ai choisi d'écrire un livre sur Mercurial car il est
belaran@999:     l'outil le plus facile pour découvrir ce nouveau domaine, tout en étant
belaran@999:     un outil efficace qui répond aux demandes d'environnements réels et
belaran@999:     difficiles, là où d'autres outils de gestions de versions s'effondrent.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Pourquoi utiliser un gestionnaire de source ?</title>
belaran@999: 
belaran@999:       <para id="x_71">Il y a de nombreuses raisons pour que vous ou votre équipe souhaitiez
belaran@999: utiliser un outil automatisant la gestion de version pour votre projet.</para>
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_72">L'outil se chargera de suivre l'évolution de votre projet, sans
belaran@999: que vous ayez à le faire. Pour chaque modification, vous aurez à votre
belaran@999: disposition un journal indiquant <emphasis>qui</emphasis> a fait quoi, <emphasis>pourquoi</emphasis>
belaran@999: il l'a fait, <emphasis>quand</emphasis> il l'a fait, et
belaran@999: <emphasis>ce</emphasis> qu'il a modifié.</para>
belaran@999: </listitem>
belaran@999: <listitem><para id="x_73">Quand vous travaillez avec d'autres personnes, les logiciels de
belaran@999: gestion de source facilitent le travail collaboratif. Par exemple, quand
belaran@999: plusieurs personnes font, plus ou moins simultanément, des modifications
belaran@999: incompatibles, le logiciel vous aidera à identifier et à résoudre les conflits.</para>
belaran@999: </listitem>
belaran@999: <listitem><para id="x_74">L'outil vous aidera à réparer vos erreurs. Si vous effectuez un changement
belaran@999: qui se révèle être une erreur, vous pourrez revenir à une version
belaran@999: antérieure d'un fichier ou même d'un ensemble de fichiers. En fait, un outil de
belaran@999: gestion de source <emphasis>vraiment</emphasis> efficace vous permettra d'identifier à quel
belaran@999: moment le problème est apparu (voir la section <xref linkend="sec:undo:bisect"/> pour plus
belaran@999: de détails).</para>
belaran@999: </listitem>
belaran@999: <listitem><para id="x_75">L'outil vous permettra aussi de travailler sur plusieurs versions différentes
belaran@999: de votre projet et de gérer l'écart entre chacune.</para>
belaran@999: </listitem></itemizedlist>
belaran@999: <para id="x_76">La plupart de ces raisons ont autant d'importances —du
belaran@999:   moins en théorie— que vous travailliez sur un projet pour vous, ou
belaran@999:   avec une centaine d'autres personnes.
belaran@999: </para>
belaran@999: 
belaran@999: <para id="x_77">Une question fondamentale à propos des outils de gestion de
belaran@999:   source, qu'il s'agisse du projet d'une personne ou d'une grande équipe, est
belaran@999:   quels sont ses <emphasis>avantages</emphasis> par rapport à ses
belaran@999:   <emphasis>coûts</emphasis>. Un outil qui est difficile à utiliser ou à
belaran@999:   comprendre exigera un lourd effort d'adaptation.
belaran@999: </para>
belaran@999: 
belaran@999: <para id="x_78">)Un projet de cinq milles personnes s'effondrera très
belaran@999:   certainement de lui même sans aucun processus et outil de gestion de
belaran@999:   source. Dans ce cas, le coût d'utilisation d'un logiciel de gestion de
belaran@999:   source est dérisoire puisque <emphasis>sans</emphasis>, l'échec est presque
belaran@999:   garanti.
belaran@999: </para>
belaran@999: 
belaran@999: <para id="x_79">D'un autre coté, un <quote>rapide hack</quote> d'une personne
belaran@999:   peut sembler un contexte bien pauvre pour utiliser un outil de gestion de
belaran@999:   source, car, bien évidement le coût d'utilisation dépasse le coût total du
belaran@999:   projet. N'est ce pas ?
belaran@999: </para>
belaran@999: 
belaran@999:       <para id="x_7a">Mercurial supporte ces <emphasis>deux</emphasis>
belaran@999:         échelles de travail. Vous pouvez apprendre les bases en quelques
belaran@999:         minutes seulement, et, grâce à sa performance, vous pouvez l'utiliser
belaran@999:         avec facilité sur le plus petit des projets. Cette simplicité
belaran@999:         signifie que vous n'avez pas de concept obscurs ou de séquence de
belaran@999:         commandes défiant l'imagination, sans aucune corrélation avec
belaran@999:         <emphasis>ce que vous êtes entrain de faire</emphasis>. En même
belaran@999:         temps, ces mêmes performances et sa nature
belaran@999:         <quote>peer-to-peer</quote> vous permettent d'adapter, sans
belaran@999:         difficulté, son utilisation à de très grands projets.
belaran@999: </para>
belaran@999: 
belaran@999:       <para id="x_7b">Aucun outil de gestion de source ne peut sauver un
belaran@999:         projet mal mené, mais un bon outil peut rendre beaucoup plus fluide
belaran@999:         votre travail.
belaran@999: </para>
belaran@999: 
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Les multiples noms de la gestion de source</title>
belaran@999: 
belaran@999:       <para id="x_7c">La gestion de source
belaran@999:         <!-- TODO:<footnote><J'ai utilisé systématiquement le terme
belaran@999:             <quote>gestion de source</quote> à travers tout l'ouvrage. Ce
belaran@999:             n'est pas forcement la meilleure traduction, et ceci peut rendre
belaran@999:             la lecture un peu lourde, mais je pense que le document y gagne
belaran@999:             en clarté et en précision. -->
belaran@999:         est un domaine tellement large qu'il n'existe pas qu'un seul nom ou
belaran@999:         acronyme pour le désigner. Voici quelques noms ou acronymes que vous
belaran@999:         rencontrerez le plus souvent.
belaran@999:         <!-- TODO:<footnote> J'ai conservé la liste des noms en anglais pour
belaran@999:           des raisons de commodité (ils sont plus <quote>googelable</quote>).
belaran@999:           En outre, j'ai opté  pour conserver l'ensemble des opérations de
belaran@999:           Mercurial (\textit{commit},\textit{push}, \textit{pull},...) en
belaran@999:           anglais, là aussi pour faciliter la lecture d'autres documents en
belaran@999:           anglais, ainsi que l'utilisation de Mercurial. -->
belaran@999: </para>
belaran@999: 
belaran@999: <para>:
belaran@999: </para>
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_7d">Revision control (RCS)</para></listitem>
belaran@999: 	<listitem><para id="x_7e">Software configuration management (SCM), ou
belaran@999: 	    configuration management</para></listitem>
belaran@999: 	<listitem><para id="x_7f">Source code management</para></listitem>
belaran@999: 	<listitem><para id="x_80">Source code control, ou source control</para></listitem>
belaran@999: 	<listitem><para id="x_81">Version control (VCS)</para></listitem></itemizedlist>
belaran@999: 
belaran@999:  <para id="x_82">Certaines personnes prétendent que ces termes ont en fait
belaran@999:    des sens différents mais en pratique ils se recouvrent tellement qu'il n'y
belaran@999:    a pas réellement de manière pertinente de les distinguer. </para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999: 
belaran@999: <title>A propos des exemples dans ce livre</title>
belaran@999: 
belaran@999:     <para id="x_84">Ce livre prend une approche non usuel pour les exemples
belaran@999:       de code. Tous les exemples sont en <quote>live</quote> — Chacun
belaran@999:       est actuellement le résultat d'un script shell qui exécute les
belaran@999:       commandes Mercurial que vous voyez. A chaque fois qu'une image du livre
belaran@999:       est construite à partir des sources, tous les scripts d'exemple sont
belaran@999:       lancés automatiquement, et leurs résultats effectifs sont comparés aux
belaran@999:       résultats attendus.</para>
belaran@999: 
belaran@999:     <para id="x_85">L'avantage de dette approche est que les exemples sont
belaran@999:       toujours précis ; ils décrivent <emphasis>exactement</emphasis> la
belaran@999:       conduite de la version de Mercurial qui est mentionnée en entête du
belaran@999:       livre. Si je met à jour la version de Mercurial que je suis en train de
belaran@999:       documenter, et que la sortie de certaines commandes change, la
belaran@999:       construction du livre échoue.</para>
belaran@999: 
belaran@999:     <para id="x_86">
belaran@999:       Il existe un petit désavantage à cette approche qui est que les dates et
belaran@999:       heures que vous verrez dans les exemples tendent à être
belaran@999:       <quote>écrasés</quote> ensemble, dans le sens où elles ne sont pas
belaran@999:       celles qu'elles auraient été si un humain avait tapé les commandes. En
belaran@999:       effet, humain ne peut pas taper plus d'une commande toutes les quelques
belaran@999:       secondes, avec le temps qui s'écoule, mes scripts d'exemples exécutent
belaran@999:       plusieurs commandes en une seconde.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_87">Une circonstance de ceci est que plusieurs commits
belaran@999:       consécutifs dans un exemple peuvent apparaître comme ayant eu lieu
belaran@999:       durant la même seconde.
belaran@999:       Vous pouvez observer le phénomène dans l'exemple <literal role="hg-ext" moreinfo="none">bisect</literal> dans <xref linkend="sec:undo:bisect"/>
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_88">Donc, lorsque vous lisez ces exemples, ne prêtez pas trop
belaran@999:       d'importance aux dates et heures que vous voyez dans la sortie des
belaran@999:       commandes. Cependant, <emphasis>soyez</emphasis> confiants que le
belaran@999:       comportement que vous voyez est consistent et reproductible 
belaran@999:     </para>
belaran@999: 
belaran@999:   </sect1>
belaran@999: 
belaran@999: <!-- The next section has disapper from this part of the book. it may be splaced somewhere else... t-->
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Tendances de la gestion de source</title>
belaran@999: 
belaran@999:     <para id="x_89">Il y a eu une tendance évidente dans le développement et
belaran@999:       l'utilisation d'outils de gestion de source depuis les quatre dernières
belaran@999:       décades, au fur et à mesure que les utilisateurs se sont habitués à
belaran@999:       leur outils et se sont sentis contraints par leurs limitations.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_8a">La première génération commença simplement par gérer un
belaran@999:       fichier unique sur un ordinateur individuel. Cependant, même si ces
belaran@999:       outils présentaient une grande avancée par rapport à la gestion
belaran@999:       manuelle des versions, leur modèle de verrouillage et leur utilisation
belaran@999:       limitée à un seul ordinateur rendaient leur utilisation possible
belaran@999:       uniquement dans une très petite équipe.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_8b">La seconde génération a assoupli ces contraintes en
belaran@999:       adoptant une architecture réseau et centralisée, permettant de gérer
belaran@999:       plusieurs projets entiers en même temps. Alors que les projets
belaran@999:       grandirent en taille, ils rencontrèrent de nouveaux problèmes. Avec les
belaran@999:       clients discutant régulièrement avec le serveurs, la montée en charge
belaran@999:       devint un réel problème sur les gros projets. Une connexion réseau peu
belaran@999:       fiable pouvait complètement empêcher les utilisateurs distants de
belaran@999:       dialoguer avec le serveur. Alors que les projets <emphasis remap="it">Open Source</emphasis> commencèrent à mettre en place des
belaran@999:       accès en lecture seule disponible anonymement, les utilisateurs sans
belaran@999:       les privilèges de <quote>commit</quote> réalisèrent qu'ils ne pouvaient
belaran@999:       pas utiliser les outils pour collaborer naturellement avec le projet,
belaran@999:       comme ils ne pouvaient pas non plus enregistrer leurs modifications.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_8c">La génération actuelle des outils de gestion de source
belaran@999:       est <quote>peer-to-peer</quote> par nature. Tous ces systèmes ont
belaran@999:       abandonné la dépendance à un serveur central, et ont permis à leur
belaran@999:       utilisateur de distribuer les données de leur gestion de source à qui
belaran@999:       en a besoin. La collaboration à travers Internet a transformé la
belaran@999:       contrainte technologique en une simple question de choix et de
belaran@999:       consensus. Les outils modernes peuvent maintenant fonctionner en mode
belaran@999:       déconnecté sans limite et de manière autonome, la connexion au réseau
belaran@999:       n'étant nécessaire que pour synchroniser les modifications avec les
belaran@999:       autres dépôts.
belaran@999:     </para>
belaran@999:   </sect1>
belaran@999:     
belaran@999:   <sect1>
belaran@999:     <title>Quelques avantages des gestionnaires de source distribués</title>
belaran@999:       
belaran@999:     <para id="x_8d">Même si les gestionnaire de source distribués sont depuis
belaran@999:       plusieurs années assez robustes et aussi utilisables que leurs
belaran@999:       prédécesseurs, les utilisateurs d'autres outils n'y ont pas encore été
belaran@999:       sensibilisés. Les gestionnaires de source distribués se distinguent
belaran@999:       particulièrement de leurs équivalents centralisés de nombreuses
belaran@999:       manières.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_8e">Pour un développeur individuel, ils restent beaucoup plus
belaran@999:       rapides que les outils centralisés. Cela pour une raison simple : un
belaran@999:       outil centralisé doit toujours dialoguer à travers le réseau pour la
belaran@999:       plupart des opérations, car presque toutes les métadonnées sont
belaran@999:       stockées sur la seule copie du serveur central. Un outil distribué
belaran@999:       stocke toute ses métadonnées localement. À tâche égale, effectuer un
belaran@999:       échange avec le réseau ajoute un délai aux outils centralisés. Ne
belaran@999:       sous-estimez pas la valeur d'un outil rapide : vous allez passer
belaran@999:       beaucoup de temps à interagir avec un logiciel de gestion de source.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_8f">Les outils distribués sont complètement indépendants des
belaran@999:       aléas de votre serveur, d'autant plus qu'ils répliquent les métadonnées
belaran@999:       à beaucoup d'endroits. Si votre serveur central prend feu, vous avez
belaran@999:       intérêt à ce que les médias de sauvegardes soient fiables, et que votre
belaran@999:       dernier <quote>backup</quote> soit récent et fonctionne sans problème.
belaran@999:       Avec un outil distribué, vous avez autant de <quote>backup</quote> que
belaran@999:       de contributeurs.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_90">En outre, la fiabilité de votre réseau affectera beaucoup
belaran@999:       moins les outils distribués. Vous ne pouvez même pas utiliser un outil
belaran@999:       centralisé sans connexion réseau, à l'exception de quelques commandes,
belaran@999:       très limitées. Avec un outil distribué, si votre connexion réseau tombe
belaran@999:       pendant que vous travaillez, vous pouvez ne même pas vous en rendre
belaran@999:       compte. La seule chose que vous ne serez pas capable de faire sera de
belaran@999:       communiquer avec des dépôts distants, opération somme toute assez rare
belaran@999:       en comparaison aux opérations locales. Si vous avez une équipe de
belaran@999:       collaborateurs très dispersée ceci peut être significatif.
belaran@999:     </para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Avantages pour les projets Open Source</title>
belaran@999: 
belaran@999:       <para id="x_91">Si vous prenez goût à un projet <emphasis remap="it">Open Source</emphasis> et que vous décidez de commencer
belaran@999:         à toucher à son code, et que le projet utilise un gestionnaire de
belaran@999:         source distribué, vous êtes immédiatement un "pair" avec les
belaran@999:         personnes formant le <quote>cœur</quote> du projet. S'ils publient
belaran@999:         leurs dépôts, vous pouvez immédiatement copier leurs historiques de
belaran@999:         projet, faire des modifications, enregistrer votre travail en
belaran@999:         utilisant les mêmes outils qu'eux. Par comparaison avec un outil
belaran@999:         centralisé, vous devez utiliser un logiciel en mode <quote>lecture
belaran@999:           seule</quote> à moins que quelqu'un ne vous donne les privilèges de
belaran@999:         <quote>commit</quote> sur le serveur central. Avant ça, vous ne serez
belaran@999:         pas capable d'enregistrer vos modifications, et vos propres
belaran@999:         modifications risqueront de se corrompre chaque fois que vous
belaran@999:         essayerez de mettre à jour à votre espace de travail avec le serveur
belaran@999:         central.
belaran@999:       </para>
belaran@999: 
belaran@999:     <sect3>
belaran@999:       <title>Le non-problème du "fork"</title>
belaran@999:       
belaran@999:       <para id="x_92">Il a été souvent suggéré que les gestionnaires de
belaran@999:         source distribués posent un risque pour les projets <emphasis remap="it">Open Source</emphasis> car ils facilitent grandement la
belaran@999:         création de <quote>fork</quote>.
belaran@999:         <!--footnote{NdT:Création d'une <ulink url="version alternative du
belaran@999:           logiciel">version alternative du
belaran@999:           logiciel</ulink>{http://fr.wikipedia.org/wiki/Fork#Embranchement_d.27un_projet_informatique}
belaran@999:         -->
belaran@999:         Un <quote>fork</quote> apparait quand il y des divergences d'opinion
belaran@999:         ou d'attitude au sein d'un groupe de développeurs qui aboutissent à
belaran@999:         la décision de ne plus travailler ensemble. Chaque parti s'empare
belaran@999:         d'une copie plus ou moins complète du code source du projet et
belaran@999:         continue dans sa propre direction.
belaran@999:       </para>
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_93">Parfois ces différents partis décident de se
belaran@999:         réconcilier. Avec un serveur central, l'aspect
belaran@999:         <emphasis>technique</emphasis> de cette réconciliation est un
belaran@999:         processus douloureux, et essentiellement manuel. Vous devez décider
belaran@999:         quelle modification est <quote>la gagnante</quote>, et replacer, par
belaran@999:         un moyen ou un autre, les modifications de l'autre équipe dans
belaran@999:         l'arborescence du projet. Ceci implique généralement la perte d'une
belaran@999:         partie de l'historique d'un des partis, ou même des deux.
belaran@999:       </para>
belaran@999:     
belaran@999:       <para id="x_94">Ce que les outils distribués permettent à ce sujet est
belaran@999:         probablement la <emphasis>meilleure</emphasis> façon de développer un
belaran@999:         projet. Chaque modification que vous effectuez est potentiellement un
belaran@999:         <quote>fork</quote>. La grande force de cette approche est que les
belaran@999:         gestionnaires de source distribués doivent être vraiment très
belaran@999:         efficaces pour <emphasis>fusionner (merge)</emphasis>
belaran@999:         <!-- TODO footnote{NdT:j'ai choisi de traduire ici <emphasis
belaran@999:           remap="it">merging</emphasis> par <quote>fusionner</quote> pour des
belaran@999:         raisons de clarté} -->
belaran@999:         des <quote>forks</quote>, car les <quote>forks</quote>, dans ce
belaran@999:         contexte, arrivent tout le temps.
belaran@999:       </para>
belaran@999:       
belaran@999:       <para id="x_95">Si chaque altération que n'importe qui effectue, à tout
belaran@999:         moment, est vue comme un <quote>fork</quote> à fusionner, alors ce
belaran@999:         que le monde de l'<emphasis remap="it">Open Source</emphasis> voit
belaran@999:         comme un <quote>fork</quote> devient <emphasis>uniquement</emphasis>
belaran@999:         une problématique sociale. En fait, les outils de gestions de source
belaran@999:         distribués <emphasis>réduisent</emphasis> les chances de
belaran@999:         <quote>fork</quote> :
belaran@999:       </para>
belaran@999:         
belaran@999:       <itemizedlist>
belaran@999:         <listitem>
belaran@999:         <para>Ils éliminent la distinction sociale qu'imposent les outils
belaran@999:           centralisés entre les membres du projets (ceux qui ont accès au
belaran@999:           <quote>commit</quote>) et ceux de l'extérieur (ce qui ne l'ont
belaran@999:           pas).
belaran@999:         </para>
belaran@999:         <para>Ils rendent plus facile la réconciliation après un
belaran@999:           <quote>fork</quote> social, car tout ce qu'elle implique est une
belaran@999:           simple fusion.
belaran@999:         </para>
belaran@999:         </listitem>
belaran@999:       </itemizedlist>
belaran@999: 
belaran@999:       <para id="x_98">Certaines personnes font de la résistance envers les
belaran@999:         gestionnaires de source distribués parce qu'ils veulent garder un
belaran@999:         contrôle ferme sur leur projet, et ils pensent que les outils
belaran@999:         centralisés leur fournissent ce contrôle. Néanmoins, si c'est votre
belaran@999:         cas, sachez que si vous publiez votre dépôt CVS ou Subversion de
belaran@999:         manière publique, il existe une quantité d'outils disponibles pour
belaran@999:         récupérer entièrement votre projet et son historique (quoique
belaran@999:         lentement) et le récréer ailleurs, sans votre contrôle. En fait,
belaran@999:         votre contrôle sur votre projet est illusoire, vous ne faites
belaran@999:         qu'interdire à vos collaborateurs de travailler de manière fluide, en
belaran@999:         disposant d'un miroir ou d'un <quote>fork</quote> de votre
belaran@999:         historique.
belaran@999:       </para>
belaran@999: 
belaran@999:     </sect3>
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Avantages pour les projets commerciaux</title>
belaran@999: 
belaran@999:       <para id="x_99">Beaucoup de projets commerciaux sont réalisés par des
belaran@999:         équipes éparpillées à travers le globe. Les contributeurs qui sont
belaran@999:         loin du serveur central devront subir des commandes lentes et même
belaran@999:         parfois peu fiables. Les solutions propriétaires de gestion de source
belaran@999:         tentent de palier ce problème avec des réplications de sites distants
belaran@999:         qui sont à la fois coûteuses à mettre en place et lourdes à
belaran@999:         administrer. Un système distribué ne souffre pas de ce genre de
belaran@999:         problèmes. En outre, il est très aisé de mettre en place plusieurs
belaran@999:         serveurs de références, disons un par site, de manière à ce qu'il n'y
belaran@999:         ait pas de communication redondante entre les dépôts, sur une
belaran@999:         connexion longue distance souvent onéreuse.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_9a">Les systèmes de gestion de source supportent
belaran@999:         généralement assez mal la monté en charge. Il n'est pas rare pour un
belaran@999:         gestionnaire de source centralisé pourtant onéreux de s'effondrer
belaran@999:         sous la charge combinée d'une douzaine d'utilisateurs concurrents
belaran@999:         seulement. Une fois encore, la réponse à cette problématique est
belaran@999:         généralement encore la mise en place d'un ensemble complexe de
belaran@999:         serveurs synchronisés par un mécanisme de réplication. Dans le cas
belaran@999:         d'un gestionnaire de source distribué, la charge du serveur central
belaran@999:         — si vous avez un— est plusieurs fois inférieure (car
belaran@999:         toutes les données sont déjà répliquées ailleurs), un simple serveur,
belaran@999:         pas très cher, peut gérer les besoins d'une plus grande équipe, et la
belaran@999:         réplication pour balancer la charge devient le travail d'un simple
belaran@999:         script.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_9b">Si vous avez des employés sur le terrain, en train de
belaran@999:         chercher à résoudre un souci sur le site d'un client, ils
belaran@999:         bénéficieront aussi d'un gestionnaire de source distribué. Cet outil
belaran@999:         leur permettra de générer des versions personnalisées, d'essayer
belaran@999:         différentes solutions, en les isolant aisément les unes des autres,
belaran@999:         et de rechercher efficacement à travers l'historique des sources, la
belaran@999:         cause des bugs ou des régressions, tout ceci sans avoir besoin de la
belaran@999:         moindre connexion au réseau de votre compagnie.
belaran@999:       </para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     </sect1>
belaran@999:     <sect1>
belaran@999:       <title>Pourquoi choisir Mercurial?</title>
belaran@999: 
belaran@999:       <para id="x_9c">Mercurial a plusieurs caractéristiques qui en font un
belaran@999:         choix particulièrement pertinent pour la gestion de source :
belaran@999:       </para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_9d">Il est simple à apprendre et à utiliser.</para></listitem>
belaran@999:       <listitem><para id="x_9e">Il est léger.</para></listitem>
belaran@999:       <listitem><para id="x_9f">Il s'adapte très bien à la charge.</para></listitem>
belaran@999:       <listitem><para id="x_a0">Il se personnalise facilement.</para></listitem>
belaran@999:     </itemizedlist>
belaran@999: 
belaran@999:     <para id="x_a1">Si vous êtes déjà familier d'un outil de gestion de
belaran@999:       source, vous serez capable de l'utiliser en moins de 5 minutes. Sinon,
belaran@999:       ça ne sera pas beaucoup plus long. Les commandes utilisées par
belaran@999:       Mercurial, comme ses fonctionnalités, sont généralement uniformes et
belaran@999:       cohérentes, et vous pouvez ainsi garder en tête simplement quelques
belaran@999:       règles générales, plutôt qu'un lot complexe d'exceptions.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_a2">Sur un petit projet, vous pouvez commencer à travailler
belaran@999:       avec Mercurial en quelques instants. Ajouter des modifications ou des
belaran@999:       branches, transférer ces modifications (localement ou via le réseau),
belaran@999:       et les opérations d'historique ou de statut sont aussi très rapides.
belaran@999:       Mercurial reste hors de votre chemin grâce à sa simplicité
belaran@999:       d'utilisation et sa rapidité d'exécution.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_a3">L'utilité de Mercurial ne se limite pas à de petits
belaran@999:       projets: il est aussi utilisé par des projets ayant des centaines ou
belaran@999:       même des milliers de contributeurs, avec plusieurs dizaines de milliers
belaran@999:       de fichiers, et des centaines de méga octets de code source.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_a4">Si les fonctionnalités au cœur de Mercurial ne sont pas
belaran@999:       suffisantes pour vous, il est très aisé d'en construire d'autres.
belaran@999:       Mercurial est adapté à l'utilisation de scripts, et son implémentation
belaran@999:       interne en Python, propre et claire, rend encore plus facile l'ajout de
belaran@999:       fonctionnalités sous forme d'extensions. Il en existe déjà un certain
belaran@999:       nombre de très populaires et très utiles, dont le périmètre va de la
belaran@999:       recherche de bugs à l'amélioration des performances.
belaran@999:     </para>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Mercurial comparé aux autres outils</title>
belaran@999: 
belaran@999:     <para id="x_a5">Avant que vous n'alliez plus loin, comprenez bien que
belaran@999:       cette section reflète mes propres expériences, et elle est donc (j'ose
belaran@999:       le dire) peu objective. Néanmoins, j'ai utilisé les outils de gestion
belaran@999:       de source listés ci dessous, dans la plupart des cas, pendant plusieurs
belaran@999:       années.
belaran@999:     </para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Subversion</title>
belaran@999: 
belaran@999:       <para id="x_a6">Subversion est un des outils de gestion de source les
belaran@999:         plus populaire, il fût développé pour remplacer CVS. Il a une
belaran@999:         architecture client/server centralisée.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_a7">Subversion et Mercurial ont des noms de commandes très
belaran@999:         similaires pour les mêmes opérations, ainsi si vous êtes familier
belaran@999:         avec l'un, c'est facile d'apprendre l'autre. Ces deux outils sont
belaran@999:         portables sur les systèmes d'exploitation les plus populaires.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_a8">Avant la version 1.5, Subversion n'offrait aucune forme
belaran@999:         de support pour les fusions. Lors de l'écriture de ce livre, ses
belaran@999:         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">
belaran@999:           complexes et buguées</ulink>.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_a9">Mercurial dispose d'un avantage substantiel en terme de
belaran@999:         performance par rapport à Subversion sur la plupart des opérations
belaran@999:         que j'ai pu tester. J'ai mesuré une différence de performance allant
belaran@999:         de deux à six fois plus rapide avec le système de stockage de fichier
belaran@999:         local de Subversion 1.4.3 (<emphasis>ra_local</emphasis>), qui est la
belaran@999:         méthode d'accès la plus rapide disponible. Dans un déploiement plus
belaran@999:         réaliste, impliquant un stockage réseau, Subversion serait encore
belaran@999:         plus désavantagé. Parce que la plupart des commandes Subversion
belaran@999:         doivent communiquer avec le serveur et que Subversion n'a pas de
belaran@999:         mécanisme de réplication, la capacité du serveur et la bande passante
belaran@999:         sont devenues des goulots d'étranglement pour les projets de taille
belaran@999:         moyenne ou grande.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_aa">En outre, Subversion implique une surcharge
belaran@999:         substantielle dans le stockage local de certaines données, pour
belaran@999:         éviter des transactions avec le serveur, pour certaines opérations
belaran@999:         communes, telles que la recherche des fichiers modifiés
belaran@999:         (<literal moreinfo="none">status</literal>) et l'affichage des modifications par
belaran@999:         rapport à la révision courante (<literal moreinfo="none">diff</literal>). En
belaran@999:         conséquence, un répertoire de travail Subversion a souvent la même
belaran@999:         taille, ou est plus grand, qu'un dépôt Mercurial et son espace de
belaran@999:         travail, et ceci bien que le dépôt Mercurial contienne l'intégralité
belaran@999:         de l'historique.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_ab">Subversion est largement supporté par les outils
belaran@999:         tierces. Mercurial est actuellement encore en retrait de ce point de
belaran@999:         vue. L'écart se réduit néanmoins, en effet, certains des outils
belaran@999:         graphiques sont maintenant supérieurs à leurs équivalents Subversion.
belaran@999:         Comme Mercurial, Subversion dispose d'un excellent manuel
belaran@999:         utilisateur.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_ac">Parce que Subversion ne stocke pas l'historique chez
belaran@999:         ses clients, il est parfaitement adapté à la gestion de projets qui
belaran@999:         doivent suivre un ensemble de larges fichiers binaires et opaques. Si
belaran@999:         vous suivez une cinquantaine de versions d'un fichier incompressible
belaran@999:         de 10MB, l'occupation disque coté client d'un projet sous Subversion
belaran@999:         restera à peu près constante. A l'inverse, l'occupation disque du
belaran@999:         même projet sous n'importe lequel des gestionnaires de source
belaran@999:         distribués grandira rapidement, proportionnellement aux nombres de
belaran@999:         versions, car les différences entre chaque révisions seront très
belaran@999:         grandes.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_ad">En outre, c'est souvent difficile ou, généralement,
belaran@999:         impossible de fusionner des différences dans un fichier binaire. La
belaran@999:         capacité de Subversion de verrouiller des fichiers, pour permettre à
belaran@999:         l'utilisateur d'être le seul à le mettre à jour
belaran@999:         (<quote>commit</quote>) temporairement, est un avantage significatif
belaran@999:         dans un projet doté de beaucoup de fichiers binaires.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_ae">Mercurial peut importer l'historique depuis un dépôt
belaran@999:         Subversion. Il peut aussi exporter l'ensemble des révisions d'un
belaran@999:         projet vers un dépôt Subversion. Ceci rend très facile de
belaran@999:         <quote>prendre la température</quote> et d'utiliser Mercurial et
belaran@999:         Subversion en parallèle, avant de décider de migrer vers Mercurial.
belaran@999:         La conversion de l'historique est incrémentale, donc vous pouvez
belaran@999:         effectuer une conversion initiale, puis de petites additions par la
belaran@999:         suite pour ajouter les nouvelle modifications.
belaran@999:       </para>
belaran@999: 
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Git</title>
belaran@999: 
belaran@999:       <para id="x_af">Git est un outil de gestion de source distribué qui fût
belaran@999:         développé pour gérer le code source de noyau de Linux. Comme
belaran@999:         Mercurial, sa conception initiale a été inspirée par Monotone.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_b0">Git dispose d'un ensemble conséquent de commandes, avec
belaran@999:         plus de 139 commandes individuelles pour la version 1.5.0. Il a aussi
belaran@999:         la réputation d'être difficile à apprendre. Comparé à Git, le point
belaran@999:         fort de Mercurial est clairement sa simplicité.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_b1">En terme de performance, Git est extrêmement rapide.
belaran@999:         Dans la plupart des cas, il est plus rapide que Mercurial, tout du
belaran@999:         moins sur Linux, alors que Mercurial peut être plus performant sur
belaran@999:         d'autres opérations. Néanmoins, sur Windows, les performances et le
belaran@999:         niveau de support général fourni par Git, au moment de l'écriture de
belaran@999:         cet ouvrage, est bien derrière celui de Mercurial.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_b2">Alors que le dépôt Mercurial ne demande aucune
belaran@999:         maintenance, un dépôt Git exige d'exécuter manuellement et
belaran@999:         régulièrement la commande <quote>repacks</quote> sur ses métadonnées.
belaran@999:         Sans ceci, les performances de git se dégradent et la consommation de
belaran@999:         l'espace disque augmente rapidement. Un serveur qui contient
belaran@999:         plusieurs dépôts Git qui ne sont pas régulièrement et fréquemment
belaran@999:         <quote>repacked</quote> deviendra un vrai problème lors des
belaran@999:         <quote>backups</quote> du disque, et il y eu des cas, où un
belaran@999:         <quote>backup</quote> journalier pouvait durer plus de 24 heures. Un
belaran@999:         dépôt fraichement <quote>repacked</quote> sera légèrement plus petit
belaran@999:         qu'un dépôt Mercurial, mais un dépôt non <quote>repacked</quote> est
belaran@999:         beaucoup plus grand.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_b3">Le cœur de Git est écrit en C. La plupart des commandes
belaran@999:         Git sont implémentées sous forme de scripts Shell ou Perl, et la
belaran@999:         qualité de ces scripts varie grandement. J'ai plusieurs fois constaté
belaran@999:         que certains de ces scripts étaient chargés en mémoire aveuglément et
belaran@999:         que la présence d'erreurs pouvait s'avérer fatal.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_b4">Mercurial peut importer l'historique d'un dépôt Git.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>CVS</title>
belaran@999: 
belaran@999:       <para id="x_b5">CVS est probablement l'outil de gestion de source le
belaran@999:         plus utilisé aujourd'hui dans le monde. À cause de son manque de
belaran@999:         clarté interne, il n'est plus maintenu depuis plusieurs années.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_b6">Il a une architecture client/serveur centralisée. Il ne
belaran@999:         regroupe pas les modifications de fichiers dans une opération de
belaran@999:         <quote>commit</quote> atomique, ce qui permet à ses utilisateurs de
belaran@999:         <quote>casser le <emphasis>build</emphasis></quote> assez facilement
belaran@999:         : une personne peut effectuer une opération de <quote>commit</quote>
belaran@999:         sans problème puis être bloquée par besoin de fusion, avec comme
belaran@999:         conséquence néfaste, que les autres utilisateurs ne récupèreront
belaran@999:         qu'une partie de ses modifications. Ce problème affecte aussi la
belaran@999:         manière de travailler avec l'historique du projet. Si vous voulez
belaran@999:         voir toutes les modifications d'une personne du projet, vous devrez
belaran@999:         injecter manuellement les descriptions et les <emphasis remap="it">timestamps</emphasis> des modifications de chacun des
belaran@999:         fichiers impliqués (si vous savez au moins quels sont ces fichiers).
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_b7">CVS a une notion étrange des <emphasis remap="it">tags</emphasis> et des branches que je n'essayerai même
belaran@999:         pas de décrire ici. Il ne supporte pas bien les opérations de
belaran@999:         renommage d'un fichier ou d'un répertoire, ce qui facilite la
belaran@999:         corruption de son dépôt. Il n'a presque pas pour ainsi dire de
belaran@999:         contrôle de cohérence interne, il est donc pratiquement impossible de
belaran@999:         dire si un dépôt est corrompu ni à quel point. Je ne recommanderai
belaran@999:         pas CVS pour un projet existant ou nouveau.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_b8">Mercurial peut importer l'historique d'un projet CVS.
belaran@999:         Néanmoins, il y a quelques principes à respecter; ce qui est vrai
belaran@999:         aussi pour les autres outils d'import de projet CVS. À cause de
belaran@999:         l'absence de <quote>commit</quote> atomique et gestion de version de
belaran@999:         l'arborescence, il n'est pas possible de reconstruire de manière
belaran@999:         précise l'ensemble de l'historique. Un travail de
belaran@999:         <quote>devinette</quote> est donc nécessaire, et les fichiers
belaran@999:         renommés ne sont pas détectés. Parce qu'une bonne part de
belaran@999:         l'administration d'un dépôt CVS est effectuée manuellement, et est
belaran@999:         donc, sujette à erreur, il est courant que les imports CVS
belaran@999:         rencontrent de nombreux problèmes avec les dépôt corrompus (des
belaran@999:         <emphasis remap="it">timestamps</emphasis> de révision complètement
belaran@999:         buggés et des fichiers verrouillés depuis des années sont deux des
belaran@999:         problèmes les moins intéressants dont je me souvienne).
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_b9">Mercurial peut importer l'historique depuis un dépôt CVS.
belaran@999:       </para>
belaran@999: 
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Outils propriétaires</title>
belaran@999: 
belaran@999:       <para id="x_ba">Perforce a une architecture client/serveur centralisée,
belaran@999:         sans aucun mécanisme de mise en cache de données coté client.
belaran@999:         Contrairement à la plupart des outils modernes de gestion de source,
belaran@999:         Perforce exige de ses utilisateurs d'exécuter une commande pour
belaran@999:         informer le serveur central de tout fichier qu'ils souhaitent
belaran@999:         modifier.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_bb">Les performances de Perforce sont plutôt bonnes pour
belaran@999:         des petites équipes, mais elles s'effondrent rapidement lorsque le
belaran@999:         nombre d'utilisateurs augmente au delà de la douzaine. Des
belaran@999:         installations de Perforce assez larges nécessitent le déploiement de
belaran@999:         proxies pour supporter la montée en charge associée.
belaran@999:       </para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Choisir un outil de gestion de source</title>
belaran@999: 
belaran@999:       <para id="x_bc">A l'exception de CVS, tous les outils listés ci-dessus
belaran@999:         ont des forces qui leur sont propres et qui correspondent à certaines
belaran@999:         formes de projet. Il n'y a pas un seul meilleur outil de gestion de
belaran@999:         source qui correspondrait le mieux à toutes les situations.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_bd">En guise exemple, Subversion est un très bon choix
belaran@999:         lorsqu'on travaille avec beaucoup de fichiers binaires, qui évoluent
belaran@999:         régulièrement, grâce à sa nature centralisée et sa capacité à
belaran@999:         verrouiller des fichiers.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_be">Personnellement, je préfère Mercurial pour sa
belaran@999:         simplicité, ses performances et sa bonne capacité de fusion, et il
belaran@999:         m'a très bien rendu service de plusieurs années maintenant.
belaran@999:       </para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Migrer depuis un outil à Mercurial</title>
belaran@999: 
belaran@999:     <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
belaran@999:       importer des révisions depuis différents autres outils de gestion de
belaran@999:       source. Par <quote>incrémental</quote>, j'entends que vous pouvez
belaran@999:       convertir l'historique entier du projet en une seule fois, puis
belaran@999:       relancer l'outil d'import plus tard pour obtenir les modifications
belaran@999:       effectuées depuis votre import initial.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_c0">Les outils de gestion de source supportés par <literal role="hg-ext" moreinfo="none">convert</literal> sont :
belaran@999:     </para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_c1">Subversion</para></listitem>
belaran@999:       <listitem><para id="x_c2">CVS</para></listitem>
belaran@999:       <listitem><para id="x_c3">Git</para></listitem>
belaran@999:       <listitem><para id="x_c4">Darcs</para></listitem>
belaran@999:     </itemizedlist>
belaran@999: 
belaran@999:     <para id="x_c5">En outre, <literal role="hg-ext" moreinfo="none">convert</literal> peut
belaran@999:       exporter les modifications depuis Mercurial vers Subversion. Ceci rend
belaran@999:       possible d'essayer Subversion en parallèle avant de choisir une
belaran@999:       solution définitive, sans aucun risque de perte de données.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_c6">La commande <command role="hg-ext-conver" moreinfo="none">convert</command> est très simple à utiliser.
belaran@999:       Simplement, indiquez le chemin ou l'URL du dépôt de source, en lui
belaran@999:       indiquant éventuellement le nom du chemin de destination, et la
belaran@999:       conversion se met en route. Après cet import initial, il suffit de
belaran@999:       relancer la commande encore une fois pour importer les modifications
belaran@999:       effectuées depuis.
belaran@999:     </para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Une courte histoire de la gestion de source</title>
belaran@999: 
belaran@999:     <para id="x_c7">Le plus célèbre des anciens outils de gestion de source
belaran@999:       est <emphasis remap="it">SCCS</emphasis> (Source Code Control System)},
belaran@999:       que Marc Rochkind conçu dans les laboratoires de recherche de Bell
belaran@999:       (<emphasis remap="it">Bell Labs</emphasis>), dans le début des années
belaran@999:       70. <emphasis remap="it">SCCS</emphasis> ne fonctionnait que sur des
belaran@999:       fichiers individuels, et obligeait chaque personne travaillant sur le
belaran@999:       projet d'avoir un accès à un répertoire de travail commun, sur le même
belaran@999:       système. Seulement une seule personne pouvait modifier un fichier au
belaran@999:       même moment, ce fonctionnement était assuré par l'utilisation de verrou
belaran@999:       (<quote>lock</quote>). Il était courant que des personnes verrouillent
belaran@999:       des fichiers, et plus tard, oublient de le déverrouiller ; empêchant
belaran@999:       n'importe qui d'autre de travailler sur ces fichiers sans l'aide de
belaran@999:       l'administrateur...
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_c8">Walter Tichy a développé une alternative libre à
belaran@999:       <emphasis remap="it">SCCS</emphasis> au début des années 80, qu'il
belaran@999:       nomma <emphasis remap="it">RCS (Revision Control System)</emphasis>.
belaran@999:       Comme <emphasis remap="it">SCCS</emphasis>, <emphasis remap="it">RCS</emphasis> demandait aux développeurs de travailler
belaran@999:       sur le même répertoire partagé, et de verrouiller les fichiers pour se
belaran@999:       prémunir de tout conflit issu de modifications concurrentes.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_c9">Un peu plus tard dans les années 1980, Dick Grune utilisa
belaran@999:       <emphasis remap="it">RCS</emphasis> comme une brique de base pour un
belaran@999:       ensemble de scripts <emphasis remap="it">shell</emphasis> qu'il
belaran@999:       intitula cmt, avant de la renommer en <emphasis remap="it">CVS
belaran@999:         (Concurrent Versions System)</emphasis>.  La grande innovation de CVS
belaran@999:       était que les développeurs pouvaient travailler simultanément et
belaran@999:       indépendamment dans leur propre espace de travail. Ces espaces de
belaran@999:       travail privés assuraient que les développeurs ne se marchent pas
belaran@999:       mutuellement sur les pieds, comme c'était souvent le cas avec RCS et
belaran@999:       SCCS. Tous les développeurs disposaient donc de leur copie de tous les
belaran@999:       fichiers du projet, et ils pouvaient donc librement les modifier. Ils
belaran@999:       devaient néanmoins effectuer la <quote>fusion</quote> (<emphasis remap="it"><quote>merge</quote></emphasis>) de leurs fichiers, avant
belaran@999:       d'effectuer le <quote>commit</quote> de leurs modifications sur le dépôt
belaran@999:       central.
belaran@999:     </para>
belaran@999:     
belaran@999:     <para>Brian Berliner reprit les scripts de Grune's et les réécrit en C,
belaran@999:       qu'il publia en 1989. Depuis, ce code a été modifié jusqu'à devenir la
belaran@999:       version moderne de CVS. CVS a acquis ainsi la capacité de fonctionner
belaran@999:       en réseau, transformant son architecture en client/serveur.
belaran@999:       L'architecture de CVS est centralisée, seul le serveur a une copie de
belaran@999:       l'historique du projet. L'espace de travail client ne contient qu'une
belaran@999:       copie de la dernière version du projet, et quelques métadonnées pour
belaran@999:       indiquer où le serveur se trouve. CVS a été un grand succès,
belaran@999:       aujourd'hui il est probablement l'outil de gestion de contrôle le plus
belaran@999:       utilisé au monde.
belaran@999:     </para>
belaran@999:     
belaran@999:     <para>Au début des années 1990, Sun Microsystems développa un premier
belaran@999:       outil de gestion de source distribué, nommé TeamWare. Un espace de
belaran@999:       travail TeamWare contient une copie complète de l'historique du projet.
belaran@999:       TeamWare n'a pas de notion de dépôt central. (CVS utilisait RCS pour le
belaran@999:       stockage de l'historique, TeamWare utilisait SCCS).
belaran@999:     </para>
belaran@999:     
belaran@999:     <para>Alors que les années 1990 avançaient, les utilisateurs ont pris
belaran@999:       conscience d'un certain nombre de problèmes avec CVS. Il enregistrait
belaran@999:       simultanément des modifications sur différents fichiers
belaran@999:       individuellement, au lieu de les regrouper dans une seule opération
belaran@999:       cohérente et atomique. Il ne gère pas bien sa hiérarchie de fichier, il
belaran@999:       est donc assez aisé de créer le chaos en renommant les fichiers et les
belaran@999:       répertoires. Pire encore, son code source est difficile à lire et à
belaran@999:       maintenir, ce qui agrandit largement le <quote>niveau de
belaran@999:         souffrance</quote> associé à la réparation de ces problèmes
belaran@999:       d'architecture de manière prohibitive.
belaran@999:     </para>
belaran@999:     
belaran@999:     <para>En 2001, Jim Blandy et Karl Fogel, deux développeurs qui avaient
belaran@999:       travaillé sur CVS, initièrent un projet pour le remplacer par un outil
belaran@999:       qui aurait une meilleure architecture et un code plus propre. Le
belaran@999:       résultat, Subversion, ne quitte pas le modèle centralisé et
belaran@999:       client/server de CVS, mais ajoute les opérations de
belaran@999:       <quote>commit</quote> atomique sur de multiples fichiers, une meilleure
belaran@999:       gestion des espaces de noms, et d'autres fonctionnalités qui en font un
belaran@999:       meilleur outil que CVS. Depuis sa première publication, il est
belaran@999:       rapidement devenu très populaire.
belaran@999:     </para>
belaran@999:     
belaran@999:     <para>Plus ou moins simultanément, Graydon Hoare a commencé sur
belaran@999:       l'ambitieux système de gestion distribué Monotone. Bien que Monotone
belaran@999:       corrige plusieurs défauts de CVS tout en offrant une architecture
belaran@999:       <quote>peer-to-peer</quote>, il va aussi plus loin que la plupart des
belaran@999:       outils de révision de manière assez innovante. Il utilise des
belaran@999:       <quote>hashs</quote> cryptographiques comme identifiants, et il a une
belaran@999:       notion complète de <quote>confiance</quote> du code issu des
belaran@999:       différentes sources.
belaran@999:     </para>
belaran@999:     
belaran@999:     <para>Mercurial est né en 2005. Bien que très influencé par Monotone,
belaran@999:       Mercurial se concentre sur la facilité d'utilisation, les performances
belaran@999:       et la capacité à monter en charge pour de très gros projets.
belaran@999:     </para>
belaran@999:   
belaran@999:   </sect1>
belaran@999: 
belaran@999: </chapter>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "chapter")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN ch02 -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <chapter id="chap:tour-basic">
belaran@999:   <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?>
belaran@999:   <title>Une rapide présentation de Mercurial : les bases</title>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Installer Mercurial sur votre système</title>
belaran@999: 
belaran@999:     <para id="x_1">Des paquetages binaires de Mercurial sont disponibles pour la
belaran@999:       plupart des systèmes d'exploitation, ce qui rend facile l'utilisation
belaran@999:       immédiate de Mercurial sur votre ordinateur.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Windows</title>
belaran@999: 
belaran@999:       <para id="x_c">La meilleur version de Mercurial pour Windows est
belaran@999:         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>.
belaran@999:         Ce logiciel n'a aucune dépendance exterieure; il fonctionne <quote>et
belaran@999:           c'est tout</quote>. Il fournit aussi bien les outils en ligne de
belaran@999:         commmande qu'une interface graphique.</para>
belaran@999:  
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Mac OS X</title>
belaran@999:   
belaran@999:       <para id="x_a">Lee Cantey publie un installeur de Mercurial pour Mac OS
belaran@999:         X sur <ulink url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para>
belaran@999:     </sect2>
belaran@999:       
belaran@999:     <sect2>
belaran@999:       <title>Linux</title>
belaran@999: 
belaran@999:       <para id="x_2">Parce que chaque distribution de Linux a ses propres
belaran@999:         outils de gestion de paquets, politiques et rythmes de
belaran@999:         développements, il est difficile de donner un ensemble
belaran@999:         d'instructions unique pour installer les binaires de Mercurial. La
belaran@999:         version de Mercurial avec laquelle vous vous retrouverez dépendra
belaran@999:         grandement de l'activité de la personne en charge du paquetage pour
belaran@999:         la distribution.</para>
belaran@999: 
belaran@999:       <para id="x_3">Pour rester simple, je me concentrerai sur
belaran@999:         l'installation de Mercurial en ligne de commande, sous les
belaran@999:         distributions les plus courantes. La plupart des distributions
belaran@999:         fournissent des gestionnaires graphiques de paquetage qui vous
belaran@999:         permettront d'installer Mercurial en quelques clicks. Le paquetage
belaran@999:         devrait se nommer <literal moreinfo="none">mercurial</literal>.</para>
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999:         <listitem><para id="x_4">Ubuntu et Debian:</para>
belaran@999:           <programlisting format="linespecific">apt-get install mercurial</programlisting></listitem>
belaran@999:         <listitem><para id="x_5">Fedora:</para>
belaran@999:           <programlisting format="linespecific">yum install mercurial</programlisting></listitem>
belaran@999:         <listitem><para id="x_6">Gentoo:</para>
belaran@999:            <programlisting format="linespecific">emerge mercurial</programlisting></listitem>
belaran@999:         <listitem><para id="x_715">OpenSUSE:</para>
belaran@999:           <programlisting format="linespecific">zypper install
belaran@999:           mercurial</programlisting></listitem>
belaran@999:       </itemizedlist>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Solaris</title>
belaran@999: 
belaran@999:       <para id="x_09">SunFreeWare, à <ulink url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>,
belaran@999:       fournit des paquets précompilés pour Mercurial.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Commencer à utiliser Mercurial</title>
belaran@999: 
belaran@999:     <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
belaran@999:       installé proprement. Les informations affichées sur la version ne sont
belaran@999:       pas réellement importantes en soit, c'est surtout de savoir si elles
belaran@999:       s'affichent qui nous intéresse.</para>
belaran@999: 
belaran@999:     <!-- BEGIN tour.version -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg version</userinput>
belaran@999: Mercurial Distributed SCM (version 1.2.1)
belaran@999: 
belaran@999: Copyright (C) 2005-2009 Matt Mackall &lt;mpm@selenic.com&gt; and others
belaran@999: This is free software; see the source for copying conditions. There is NO
belaran@999: warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
belaran@999: </screen>
belaran@999: <!-- END tour.version -->
belaran@999: 
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>L'aide intégrée</title>
belaran@999: 
belaran@999:       <para id="x_f">Mercurial fournit un système d'aide intégré, ce qui est
belaran@999:         inestimable quand vous vous retrouvez coincé à essayer de vous
belaran@999:         rappeler comment lancer une commande. Si vous êtes bloqué, exécutez
belaran@999:         simplement <command role="hg-cmd" moreinfo="none">hg help</command>; elle affichera
belaran@999:         une brève liste des commandes, avec une description pour chacune. Si
belaran@999:         vous demandez de l'aide sur une commande spécifique (voir
belaran@999:         ci-dessous), elle affichera des informations plus détaillées.</para>
belaran@999: 
belaran@999:       <!-- BEGIN tour.help -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg help init</userinput>
belaran@999: hg init [-e CMD] [--remotecmd CMD] [DEST]
belaran@999: 
belaran@999: create a new repository in the given directory
belaran@999: 
belaran@999:     Initialize a new repository in the given directory. If the given
belaran@999:     directory does not exist, it is created.
belaran@999: 
belaran@999:     If no directory is given, the current directory is used.
belaran@999: 
belaran@999:     It is possible to specify an ssh:// URL as the destination.
belaran@999:     See 'hg help urls' for more information.
belaran@999: 
belaran@999: options:
belaran@999: 
belaran@999:  -e --ssh        specify ssh command to use
belaran@999:     --remotecmd  specify hg command to run on the remote side
belaran@999: 
belaran@999: use "hg -v help init" to show global options
belaran@999: </screen>
belaran@999: <!-- END tour.help -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_10">Pour un niveau d'informations encore plus détaillé 
belaran@999:         (ce dont vous aurez rarement besoin), exécuter <command role="hg-cmd" moreinfo="none">hg 
belaran@999:         help <option role="hg-opt-global">-v</option></command>.  L'option 
belaran@999:         <option role="hg-opt-global">-v</option> est l'abréviation de 
belaran@999:         <option role="hg-opt-global">--verbose</option>, et indique à Mercurial 
belaran@999:         d'ficher plus d'informations que d'habitude.</para>
belaran@999: 
belaran@999:      </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Travailler avec un dépôt</title>
belaran@999: 
belaran@999:     <para id="x_11">Avec Mercurial, tout se déroule au sein du 
belaran@999:       <emphasis>dépôt</emphasis>. Le dépôt d'un projet contient tous 
belaran@999:       les fichiers qui <quote>appartiennent</quote> au projet.</para>
belaran@999: 
belaran@999:     <para id="x_12">Il n'y a rien de particulièrement magique au sujet de 
belaran@999:       ce dépôt, c'est simplement une arborescence sur votre système de fichiers 
belaran@999:       que Mercurial traite de manière spéciale. Vous pouvez renommer ou effacer 
belaran@999:       ce répertoire à n'impporte quel moment, en utilisant la ligne de commande 
belaran@999:       ou votre explorateur de fichiers.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Faire une copie locale de votre dépôt</title>
belaran@999:       
belaran@999:       <para id="x_13"><emphasis>Copier</emphasis> un dépôt est juste un 
belaran@999:         peu spécial. Bien que vous puissiez utiliser une commande habituelle de 
belaran@999:         copie pour copier votre dépôt, il vaut mieux utiliser une commande fournie par
belaran@999:         Mercurial. Cette commande est appelée <command role="hg-cmd" moreinfo="none">hg clone</command>, 
belaran@999:         car elle crée une copie identique à un dépôt existant.</para>
belaran@999: 
belaran@999:       <!-- BEGIN tour.clone -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone http://hg.serpentine.com/tutorial/hello</userinput>
belaran@999: destination directory: hello
belaran@999: requesting all changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 5 changesets with 5 changes to 2 files
belaran@999: updating working directory
belaran@999: 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: </screen>
belaran@999: <!-- END tour.clone -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_67c">Un avantage de la commande <command role="hg-cmd" moreinfo="none">hg
belaran@999:           clone</command> est que, comme nous l'avons vu ci dessus, elle nous
belaran@999:         permet de faire de cloner les dépôts à travers le réseau. Un autre
belaran@999:         est qu'elle se rappelle d'où a été cloné un dépôt, ce qui est utile
belaran@999:         quand on veut mettre à jour le clone.</para>
belaran@999: 
belaran@999:       <para id="x_14">Si votre opération de clonage réussit, vous devriez maintenant
belaran@999:         avoir un répertoire local appelé <filename class="directory" moreinfo="none">hello</filename>. 
belaran@999:         Ce répertoire contiendra quelques fichiers.</para>
belaran@999: 
belaran@999:       <!-- BEGIN tour.ls -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls -l</userinput>
belaran@999: total 4
belaran@999: drwxr-xr-x 3 rpelisse rpelisse 4096 Aug 16 14:05 hello
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls hello</userinput>
belaran@999: Makefile  hello.c
belaran@999: </screen>
belaran@999: <!-- END tour.ls -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_15">Ces fichiers ont le même contenu et historique dans votre dépôt
belaran@999:         qu'ils ont dans le dépôt que vous avez cloné.</para>
belaran@999: 
belaran@999:       <para id="x_16">Chaque dépôt Mercurial est complet, autonome et
belaran@999:         indépendant. Il contient sa propre copie privée des fichiers du
belaran@999:         projet et de leur historique. Le clone d'un dépôt se souvient de la
belaran@999:         localisation du dépôt à partir duquel il a été clôné, mais il ne
belaran@999:         communique pas avec ce dernier, ou un autre, à moins que vous ne lui
belaran@999:         demandiez.</para>
belaran@999: 
belaran@999:       <para id="x_17">Ce que tout ceci signifie pour le moment est que nous
belaran@999:         sommes libres d'expérimenter avec ce dépôt, confiants dans le fait
belaran@999:         qu'il s'agit d'un <quote>bac à sable</quote> qui n'affectera personne
belaran@999:         d'autre.</para>
belaran@999: 
belaran@999:     </sect2>  
belaran@999:     <sect2>
belaran@999:       <title>Quel est le contenu d'un dépôt ?</title>
belaran@999: 
belaran@999:       <para id="x_18">Prêtons plus attention un instant au contenu d'un dépôt. 
belaran@999:         Nous voyons qu'il contient un répertoire nommé <filename class="directory" moreinfo="none">.hg
belaran@999:         </filename>. C'est ici que Mercurial conserve toutes ses
belaran@999:         métadonnées.</para>
belaran@999: 
belaran@999:       <!-- BEGIN tour.ls-a -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd hello</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls -a</userinput>
belaran@999: .  ..  .hg  Makefile  hello.c
belaran@999: </screen>
belaran@999: <!-- END tour.ls-a -->
belaran@999:  
belaran@999: 
belaran@999:       <para id="x_19">Le contenu du répertoire <filename class="directory" moreinfo="none">.hg
belaran@999:         </filename> et ses sous répertoires sont les seuls propres à Mercurial. 
belaran@999:         Tous les autres fichiers et répertoires dans le dépôt sont à vous, et 
belaran@999:         vous pouvez en faire ce que vous voulez.</para>
belaran@999: 
belaran@999:       <para id="x_1a">Pour introduire un peu de terminologie, le répertoire 
belaran@999:         <filename class="directory" moreinfo="none">.hg</filename> est un <quote>vrai</quote> 
belaran@999:         dépôt, et tous les fichiers et les répertoires qui coexistent avec lui, 
belaran@999:         sont désignés sous le nom <emphasis>espace de travail</emphasis>. Une 
belaran@999:         manière facile de se rappeler cette distinction est de retenir que le 
belaran@999:         <emphasis>dépôt</emphasis> contient l'<emphasis>historique</emphasis>
belaran@999:         de votre projet, alors que l'<emphasis>espace de travail</emphasis> 
belaran@999:         contient un "<emphasis>snapshot</emphasis>"  de votre projet à un certain 
belaran@999:         point de son historique.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Une promenade dans l'historique</title>
belaran@999: 
belaran@999:     <para id="x_1b">Une des premières choses que vous aurez envie 
belaran@999:       de faire avec un nouveau dépôt, sera de comprendre son historique. 
belaran@999:       La commande <command role="hg-cmd" moreinfo="none">hg log</command> vous donne une 
belaran@999:       vue de l'historique.</para>
belaran@999: 
belaran@999:     <!-- BEGIN tour.log -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log</userinput>
belaran@999: changeset:   4:2278160e78d4
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sat Aug 16 22:16:53 2008 +0200
belaran@999: summary:     Trim comments.
belaran@999: 
belaran@999: changeset:   3:0272e0d5a517
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sat Aug 16 22:08:02 2008 +0200
belaran@999: summary:     Get make to generate the final binary from a .o file.
belaran@999: 
belaran@999: changeset:   2:fef857204a0c
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sat Aug 16 22:05:04 2008 +0200
belaran@999: summary:     Introduce a typo into hello.c.
belaran@999: 
belaran@999: changeset:   1:82e55d328c8c
belaran@999: user:        mpm@selenic.com
belaran@999: date:        Fri Aug 26 01:21:28 2005 -0700
belaran@999: summary:     Create a makefile
belaran@999: 
belaran@999: changeset:   0:0a04b987be5a
belaran@999: user:        mpm@selenic.com
belaran@999: date:        Fri Aug 26 01:20:50 2005 -0700
belaran@999: summary:     Create a standard "hello, world" program
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tour.log -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_1c">Par défaut, cette commande affiche à l'écran un bref paragraphe pour chaque
belaran@999:       révision enregistrée pour ce projet. Dans la terminologie de Mercurial, nous
belaran@999:       appelons chacun de ces évènements enregistrés un <emphasis>changeset</emphasis>, parce
belaran@999:       qu'il contient un ensemble de modifications sur plusieurs fichiers.</para>
belaran@999: 
belaran@999:     <para id="x_1d">La commande <command role="hg-cmd" moreinfo="none">hg log</command> affiche 
belaran@999:     ainsi ces informations :</para>
belaran@999: 
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_1e"><literal moreinfo="none">changeset</literal> : Ce champ contient 
belaran@999:         un nombre, séparé par deux points (:), d'une chaine hexadécimale. Il 
belaran@999:         s'agit en fait d'<emphasis>identifiants</emphasis>  d'un changeset. Il y a 
belaran@999:         deux identifiants car le numéro de la révision est plus court et plus à 
belaran@999:         facile à saisir qu'une séquence hexadécimale.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_1f"><literal moreinfo="none">user</literal> : L'identité de la personne 
belaran@999:         qui a créée ce  %%% laisser le terme anglais car il sera affiché
belaran@999:         changeset. C'est un champ libre de forme, mais la plupart du
belaran@999:         temps il contient le nom et l'email de la personne.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_20"><literal moreinfo="none">date</literal> : La date et l'heure à 
belaran@999:         laquelle le \textit{changeset} a été créé, ainsi que le fuseau horaire dans 
belaran@999:         lequelle il a été créé. (La date et l'heure sont locales à ce
belaran@999:         \textit{fuseau}, elles indiquent donc quelle date et heure il était
belaran@999:         pour la personne qui a créé ce changeset.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_21"><literal moreinfo="none">résumé</literal>: La première ligne du 
belaran@999:         message que le créateur a associé à son changeset pour le décrire.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_67d">Certains changesets, comme le premier de la
belaran@999:         liste ci-dessus ont un champ <literal moreinfo="none">tag</literal>. Le tag est une autre
belaran@999:         façon d'identifier un changeset en lui donnant un nom simple à retenir.
belaran@999:         (Le tag nommé <literal moreinfo="none">tip</literal> est spécial : il fait toujours
belaran@999:         référence aux derniers changements dans le dépôt.)</para></listitem>
belaran@999:     </itemizedlist>
belaran@999: 
belaran@999:     <para id="x_22">Par défaut, la commande <command role="hg-cmd" moreinfo="none">hg log</command> 
belaran@999:       n'affiche qu'un résumé, il manque beaucoup de détails.</para>
belaran@999: 
belaran@999:     <para id="x_23">La figure <xref linkend="fig:tour-basic:history"/> fournit une 
belaran@999:       représentation graphique de l'historique du dépôt <filename class="directory" moreinfo="none">hello
belaran@999:       </filename>, pour rendre plus facile de voir dans quelle direction 
belaran@999:       l'historique se <quote>déroule</quote>. Nous reviendrons régulièrement 
belaran@999:       sur cette représentation dans ce chapitre et ceux qui suivent.</para>
belaran@999: 
belaran@999: 
belaran@999:     <figure id="fig:tour-basic:history" float="0">
belaran@999:       <title>Graphical history of the <filename class="directory" moreinfo="none">hello</filename> repository</title>
belaran@999:       <mediaobject>
belaran@999:         <imageobject><imagedata fileref="figs/tour-history.png"/></imageobject>
belaran@999:         <textobject><phrase>XXX add text</phrase></textobject>
belaran@999:       </mediaobject>
belaran@999:     </figure>
belaran@999: 
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Changesets, révisions, et collaboration</title>
belaran@999:       
belaran@999:       <para id="x_25">Comme l'anglais est réputé pour être un langage maladroit,
belaran@999:         et que l'informatique est la source de bien des erreurs de terminologie
belaran@999:         (pourquoi utiliser un seul terme quand quatre feront l'affaire ?), la
belaran@999:         gestion de version a une variété de mots et de phrases qui veulent dire
belaran@999:         la même chose. Si vous discutez d'historique de Mercurial avec d'autres
belaran@999:         personnes, vous constaterez que souvent, le mot <quote>changeset</quote>
belaran@999:         est contracté simplement en <quote>change</quote> ou (à l'écrit)
belaran@999:         <quote>cset</quote>, et même parfois un changeset
belaran@999:         <quote>révision</quote>, abrégé en <quote>rev</quote>.</para>
belaran@999: 
belaran@999:       <para id="x_26">Bien que le <emphasis>mot</emphasis> que vous utilisez pour 
belaran@999:         désigner le concept de changeset importe peu, l'<emphasis>identifiant</emphasis> 
belaran@999:         que vous utilisez pour désigner un <emphasis>changeset</emphasis> spécifique 
belaran@999:         a une grande importance. Rappelez vous que le champ changeset affiché par la
belaran@999:         commande <command role="hg-cmd" moreinfo="none">hg log</command> identifie un changeset à
belaran@999:         la fois avec un numéro de révision et une séquence hexadécimale.</para>
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999:         <listitem><para id="x_27">Le numéro de révision est <emphasis>seulement 
belaran@999:         valable dans ce dépôt</emphasis>,</para></listitem>
belaran@999:         <listitem><para id="x_28">La séquence hexadécimale est un
belaran@999:         <emphasis>identifiant permanent, et invariant</emphasis> qui 
belaran@999:         pourra toujours être associé au changeset exact de <emphasis>chaque</emphasis> 
belaran@999:         copie de votre dépôt.</para></listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_29">La distinction est importante. Si vous envoyez un email 
belaran@999:          à quelqu'un en parlant de la <quote>révision 33</quote>, il est très 
belaran@999:          probable que sa révision 33 <emphasis>ne sera pas la même</emphasis> 
belaran@999:          que la votre. La raison de ceci est que le numéro de révision dépend 
belaran@999:          de l'ordre dans lequel les modifications sont arrivées dans le dépôt, 
belaran@999:          et il n'y a aucune garantie que les mêmes changements soient arrivés 
belaran@999:          dans le même ordre dans différents dépôts. Trois modifications
belaran@999:          <literal moreinfo="none">a,b,c</literal> peuvent aisément apparaitre dans un dépôt 
belaran@999:          comme <literal moreinfo="none">0,1,2</literal>, et dans un autre comme <literal moreinfo="none">0,2,1
belaran@999:          </literal>.</para>
belaran@999: 
belaran@999:       <para id="x_2a">Mercurial utilise les numéros de révision uniquement comme des raccourcis
belaran@999:         pratiques. Si vous devez discuter d'un \textit{changeset} avec quelqu'un,
belaran@999:         ou identifer un \textit{changeset} pour une quelconque raison (par exemple,
belaran@999:         un rapport de \textit{bug}), utilisez la séquence hexadécimale.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Afficher une révision spécifique</title>
belaran@999: 
belaran@999:       <para id="x_2b">Pour réduire la sortie de <command role="hg-cmd" moreinfo="none">hg log
belaran@999:         </command> à une seule révision, utilisez l'option <option role="hg-opt-log">-r
belaran@999:         </option> (ou <option role="hg-opt-log">--rev</option>). Vous pouvez utiliser
belaran@999:         le numéro de révision ou la séquence hexadécimale comme identifiant, et
belaran@999:         demander autant de révisions que vous le souhaitez.</para>
belaran@999: 
belaran@999:       <!-- BEGIN tour.log-r -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r 3</userinput>
belaran@999: changeset:   3:0272e0d5a517
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sat Aug 16 22:08:02 2008 +0200
belaran@999: summary:     Get make to generate the final binary from a .o file.
belaran@999: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r 0272e0d5a517</userinput>
belaran@999: changeset:   3:0272e0d5a517
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sat Aug 16 22:08:02 2008 +0200
belaran@999: summary:     Get make to generate the final binary from a .o file.
belaran@999: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r 1 -r 4</userinput>
belaran@999: changeset:   1:82e55d328c8c
belaran@999: user:        mpm@selenic.com
belaran@999: date:        Fri Aug 26 01:21:28 2005 -0700
belaran@999: summary:     Create a makefile
belaran@999: 
belaran@999: changeset:   4:2278160e78d4
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sat Aug 16 22:16:53 2008 +0200
belaran@999: summary:     Trim comments.
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tour.log-r -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_2c">Si vous voulez voir l'historique de plusieurs révisions
belaran@999:         sans avoir à les énumérer, vous pouvez utiliser la <emphasis>intervalle
belaran@999:         de numérotation</emphasis> qui vous permet d'exprimer l'idée <quote>je
belaran@999:         veux toutes les révisions entre $a$ et $b$, inclus</quote></para>
belaran@999: 
belaran@999:       <!-- BEGIN tour.log.range -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r 2:4</userinput>
belaran@999: changeset:   2:fef857204a0c
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sat Aug 16 22:05:04 2008 +0200
belaran@999: summary:     Introduce a typo into hello.c.
belaran@999: 
belaran@999: changeset:   3:0272e0d5a517
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sat Aug 16 22:08:02 2008 +0200
belaran@999: summary:     Get make to generate the final binary from a .o file.
belaran@999: 
belaran@999: changeset:   4:2278160e78d4
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sat Aug 16 22:16:53 2008 +0200
belaran@999: summary:     Trim comments.
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tour.log.range -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_2d">Mercurial respecte aussi l'ordre dans lequel vous spécifiez
belaran@999:         les révisions, ainsi <command role="hg-cmd" moreinfo="none">hg log -r 2:4</command>
belaran@999:         affichera <literal moreinfo="none">2,3,4</literal> alors que <command role="hg-cmd" moreinfo="none">hg
belaran@999:         log -r 4:2</command> affichera <literal moreinfo="none">4,3,2</literal>.</para>
belaran@999: 
belaran@999:     </sect2>  
belaran@999:     <sect2>
belaran@999:       <title>Informations détaillées</title>
belaran@999: 
belaran@999:       <para id="x_2e">Le résumé affiché par <command role="hg-cmd" moreinfo="none">hg log</command> 
belaran@999:         est suffisant si vous savez déjà ce que vous cherchez. En 
belaran@999:         revanche, vous aurez probablement besoin de voir une description 
belaran@999:         complète du changement, ou une liste des fichiers modifiés si vous 
belaran@999:         cherchez à déterminer qu'un changeset est bien celui que vous
belaran@999:         recherchez. L'option \hgopt{-v} de la commande <command role="hg-cmd" moreinfo="none">hg 
belaran@999:         log</command> (ou <option role="hp-opt-global">--verbose</option>) vous 
belaran@999:         donne ces informations supplémentaires.</para>
belaran@999: 
belaran@999:       <!-- BEGIN tour.log-v -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -v -r 3</userinput>
belaran@999: changeset:   3:0272e0d5a517
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sat Aug 16 22:08:02 2008 +0200
belaran@999: files:       Makefile
belaran@999: description:
belaran@999: Get make to generate the final binary from a .o file.
belaran@999: 
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tour.log-v -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_2f">Si vous voulez voir à la fois la description 
belaran@999:         et le contenu d'une modification, ajouter l'option <option role="hg-opt-log">-p</option> (ou <option role="hg-opt-log">
belaran@999:         --patch</option>). Ceci affiche le contenu d'une modification 
belaran@999:         comme un <emphasis>diff unifié</emphasis>
belaran@999:         <!-- \footnote{NdT: \textit{unified diff}} -->
belaran@999:         (si vous n'avez jamais vu de diff unifié avant, consultez la 
belaran@999:         section <xref linkend="sec:mq:patch"/> pour un rapide 
belaran@999:         survol).</para>
belaran@999: 
belaran@999:       <!-- BEGIN tour.log-vp -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -v -p -r 2</userinput>
belaran@999: changeset:   2:fef857204a0c
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sat Aug 16 22:05:04 2008 +0200
belaran@999: files:       hello.c
belaran@999: description:
belaran@999: Introduce a typo into hello.c.
belaran@999: 
belaran@999: 
belaran@999: diff -r 82e55d328c8c -r fef857204a0c hello.c
belaran@999: --- a/hello.c	Fri Aug 26 01:21:28 2005 -0700
belaran@999: +++ b/hello.c	Sat Aug 16 22:05:04 2008 +0200
belaran@999: @@ -11,6 +11,6 @@
belaran@999:  
belaran@999:  int main(int argc, char **argv)
belaran@999:  {
belaran@999: -	printf("hello, world!\n");
belaran@999: +	printf("hello, world!\");
belaran@999:  	return 0;
belaran@999:  }
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tour.log-vp -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_67e">L'option <option role="hg-opt-log">-p</option> est
belaran@999:         incroyablement utile, il est donc important dans s'en rappeller.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Tout sur les options de commandes</title>
belaran@999:     
belaran@999:     <para id="x_30">Avant d'aller plus loin sur le fonctionnement 
belaran@999:       des commandes de Mercurial, étudions un moment comment elles 
belaran@999:       fonctionnent de manière générale. Vous trouverez ça probablement 
belaran@999:       utile pour la suite de notre parcours.</para>
belaran@999: 
belaran@999:     <para id="x_31">Mercurial utilise une approche directe et cohérente 
belaran@999:       pour interpréter les options que vous passez aux commandes. Il suit une
belaran@999:       convention commune à la plupart des systèmes Unix et Linux modernes.</para>
belaran@999: 
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_32">Chaque option a un nom complet. Par exemple, 
belaran@999:         comme nous l'avons déjà vu, la commande <command role="hg-cmd" moreinfo="none">hg 
belaran@999:         log</command> accepte l'option <option role="hg-opt-log">--rev
belaran@999:         </option>.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_33">La plupart des options disposent de 
belaran@999:         noms abrégés. Aussi, au lieu d'utiliser <option role="hg-opt-log">--rev
belaran@999:         </option>, vous pouvez utiliser <option role="hg-opt-log">-r</option>. 
belaran@999:         (Les options qui  n'ont pas de noms abrégés sont généralement 
belaran@999:         rarement utilisées).</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_34">Les noms complets commencent par deux 
belaran@999:         tirets (i.e. <option role="hg-opt-log">--rev</option>),
belaran@999:         alors que les options courtes commencent avec un seul (i.e. 
belaran@999:         <option role="hg-opt-log">-r</option>).</para>
belaran@999:       </listitem>
belaran@999:      <listitem><para id="x_35">Les noms des options sont cohérents 
belaran@999:        entre les commandes. Par exemple, chaque commande qui accepte 
belaran@999:        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
belaran@999:        </option> comme arguments.</para>
belaran@999:      </listitem>
belaran@999:    </itemizedlist>
belaran@999: 
belaran@999:    <para id="x_36">Dans les exemples de ce livre, j'utilise les noms abrégés 
belaran@999:      plutôt que les noms complets. Ceci est une préférence personnelle, pas 
belaran@999:      une recommandation.</para>
belaran@999: 
belaran@999:    <para id="x_37">La plupart des commandes qui affichent une quelconque sortie 
belaran@999:      à l'écran, afficheront davantage avec l'option <option role="hg-opt-global">
belaran@999:      -v</option> (ou <option role="hg-opt-global">--verbose</option>), et
belaran@999:      moins avec l'option <option role="hg-opt-global">-q</option> (ou 
belaran@999:      <option role="hg-opt-global">--quiet</option>).</para>
belaran@999: 
belaran@999:     <note>
belaran@999:       <title>Option naming consistency</title>
belaran@999:       
belaran@999:       <para id="x_680">Presque toujours, les commandes de Mercurial utilisent
belaran@999:       des noms d'options cohérentes pour référer à des concepts identiques.
belaran@999:       Par exemple, si une commande concerne les changesets, vous les
belaran@999:       identifierez toujours avec l'option <option role="hg-opt-log">-r</option>.
belaran@999:       Cette utilisation cohérente des noms d'options permet de mémoriser plus
belaran@999:       facilement quelles options accepte une commande.</para>
belaran@999:    </note>
belaran@999: 
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Faire et vérifier des modifications</title>
belaran@999: 
belaran@999:     <para id="x_38">Maintenant que nous avons une bonne idée des 
belaran@999:       commandes pour consulter l'historique de Mercurial, regardons 
belaran@999:       comment faire des modifications et les examiner.</para>
belaran@999:      
belaran@999:     <para id="x_39">La première chose que nous allons faire c'est isoler notre
belaran@999:       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
belaran@999:       une copie de dépôt distant. Comme nous avons déjà une copie locale, nous
belaran@999:       pouvons juste faire un clone de celle-ci à la place. C'est beaucoup plus
belaran@999:       rapide que de faire une copie à travers le réseau, et un dépôt cloné
belaran@999:       localement prend également moins d'espace disque<footnote>
belaran@999:       <para id="x_681">L'économie d'espace disque apparait clairement quand les
belaran@999:         dépôts source et destination sont sur le même système de fichier, où, dans
belaran@999:         ce cas, Mercurial utilisera des liens physiques pour effectuer des partages
belaran@999:         copie-lors-des-écritures de ses métadonnées internes. Si cette explication
belaran@999:         ne signifie rien pour vous, ne vous inquietez pas : tout ceci se passe de
belaran@999:         manière transparente et automatiquement. Vous n'avez pas du tout besoin de
belaran@999:         comprendre ceci.</para></footnote>.</para>
belaran@999:   
belaran@999:     <!-- BEGIN tour.reclone -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone hello my-hello</userinput>
belaran@999: updating working directory
belaran@999: 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-hello</userinput>
belaran@999: </screen>
belaran@999: <!-- END tour.reclone -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_3a">On notera au passage qu'il est souvent considéré comme
belaran@999:       une bonne pratique de conserver une copie <quote>immaculée</quote>
belaran@999:       du dépôt distant, à partir de laquelle vous pourrez faire des 
belaran@999:       copies locales temporaires pour créer des <quote>bacs à sable</quote> 
belaran@999:       pour chaque tâche sur laquelle vous souhaitez travailler. Ceci 
belaran@999:       vous permet de travailler sur plusieurs choses en parallèle, 
belaran@999:       chacune isolée les unes des autres en attendant que ces tâches 
belaran@999:       soient finies et que vous soyez prêt à les réintégrer. Parce 
belaran@999:       que les copies locales sont peu coûteuses, il est très rapide 
belaran@999:       de créer ou détruire des dépôts dès que vous n'en avez plus
belaran@999:       besoin.</para>
belaran@999: 
belaran@999:     <para id="x_3b">Dans notre dépôt <filename class="directory" moreinfo="none">my-hello</filename>, nous avons un fichier
belaran@999:       <filename moreinfo="none">hello.c</filename> qui contient le classique <quote>hello,
belaran@999:         world</quote>.</para>
belaran@999:    
belaran@999:     <!-- BEGIN tour.cat1 -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat hello.c</userinput>
belaran@999: /*
belaran@999:  * Placed in the public domain by Bryan O'Sullivan.  This program is
belaran@999:  * not covered by patents in the United States or other countries.
belaran@999:  */
belaran@999: 
belaran@999: #include &lt;stdio.h&gt;
belaran@999: 
belaran@999: int main(int argc, char **argv)
belaran@999: {
belaran@999: 	printf("hello, world!\");
belaran@999: 	return 0;
belaran@999: }
belaran@999: </screen>
belaran@999: <!-- END tour.cat1 -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_682">Editons ce fichier pour qu'il affiche une autre ligne
belaran@999:       sur la sortie standard.</para>
belaran@999:     
belaran@999:     <!-- BEGIN tour.cat2 -->
belaran@999: <screen format="linespecific"># ... edit edit edit ...
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat hello.c</userinput>
belaran@999: /*
belaran@999:  * Placed in the public domain by Bryan O'Sullivan.  This program is
belaran@999:  * not covered by patents in the United States or other countries.
belaran@999:  */
belaran@999: 
belaran@999: #include &lt;stdio.h&gt;
belaran@999: 
belaran@999: int main(int argc, char **argv)
belaran@999: {
belaran@999: 	printf("hello, world!\");
belaran@999: 	printf("hello again!\n");
belaran@999: 	return 0;
belaran@999: }
belaran@999: </screen>
belaran@999: <!-- END tour.cat2 -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_3c">La commande Mercurial <command role="hg-cmd" moreinfo="none">hg
belaran@999:         status</command> nous dira ce que Mercurial sait des fichiers du
belaran@999:       dépôts.</para>
belaran@999: 
belaran@999:     <!-- BEGIN tour.status -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls</userinput>
belaran@999: Makefile  hello.c
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: M hello.c
belaran@999: </screen>
belaran@999: <!-- END tour.status -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_3d">La commande <command role="hg-cmd" moreinfo="none">hg status</command>
belaran@999:       n'affichera pas le contenu des fichiers, mais une ligne commençant par
belaran@999:       <quote><literal moreinfo="none">M</literal></quote> pour <filename moreinfo="none">hello.c</filename>.
belaran@999:       A moins que vous lui demandiez, la commande <command role="hg-cmd" moreinfo="none">hg
belaran@999:         status</command> n'affichera aucune information sur les fichiers que
belaran@999:       vous n'avez pas modifiés.</para>
belaran@999:  
belaran@999:     <para id="x_3e">Le <quote><literal moreinfo="none">M</literal></quote> indique que
belaran@999:       Mercurial a remarqué que nous avons modifié le fichier
belaran@999:       <filename moreinfo="none">hello.c</filename>. Nous n'avons pas besoin
belaran@999:       <emphasis>d'informer</emphasis> Mercurial que nous allons modifier un
belaran@999:       fichier avant de commencer à le faire, ou que nous avons modifié un
belaran@999:       fichier après avoir commencé à le faire, il est capable de découvrir ça
belaran@999:       tout seul. </para>
belaran@999: 
belaran@999:     <para id="x_3f">C'est déjà pratique de savoir que nous avons modifié le
belaran@999:       fichier <filename moreinfo="none">hello.c</filename>, mais nous préférerions savoir
belaran@999:       exactement <emphasis>ce que</emphasis> nous avons changé. Pour ceci, nous
belaran@999:       utilisons la commande <command role="hg-cmd" moreinfo="none">hg diff</command>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN tour.diff -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
belaran@999: diff -r 2278160e78d4 hello.c
belaran@999: --- a/hello.c	Sat Aug 16 22:16:53 2008 +0200
belaran@999: +++ b/hello.c	Sun Aug 16 14:05:26 2009 +0000
belaran@999: @@ -8,5 +8,6 @@
belaran@999:  int main(int argc, char **argv)
belaran@999:  {
belaran@999:  	printf("hello, world!\");
belaran@999: +	printf("hello again!\n");
belaran@999:  	return 0;
belaran@999:  }
belaran@999: </screen>
belaran@999: <!-- END tour.diff -->
belaran@999: 
belaran@999: 
belaran@999:     <tip>
belaran@999:       <title>Comprendre les patches</title>
belaran@999:    
belaran@999:       <para id="x_683">Penser à jeter un oeil à <xref linkend="sec:mq:patch"/> si vous n'arrivez pas à lire la sortie
belaran@999:         ci-dessus.</para>
belaran@999:     </tip>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Enregister vos modifications dans une nouvelle révision</title>
belaran@999:    
belaran@999:     <para id="x_40">Nous pouvons modifier des fichiers, compiler et tester
belaran@999:       nos modifications, et utiliser les commandes <command role="hg-cmd" moreinfo="none">hg
belaran@999:         status</command> et <command role="hg-cmd" moreinfo="none">hg diff</command> pour
belaran@999:       voir les modifications effectuées, jusqu'à ce que nous soyons assez
belaran@999:       satisfaits pour décider d'enregistrer notre travail dans un
belaran@999:       \textit{changeset}.</para>
belaran@999: 
belaran@999:     <para id="x_41">La commande <command role="hg-cmd" moreinfo="none">hg commit</command>
belaran@999:       vous laisse créer une nouvelle révision, nous désignerons généralement
belaran@999:       cette opération par <quote>faire un commit</quote> ou
belaran@999:       <quote>committer</quote>.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:     <title>Définir le nom d'utilisateur</title>
belaran@999: 
belaran@999:       <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
belaran@999:         pas garanti qu'elle réussisse du premier coup. En effet, Mercurial
belaran@999:         enregistre votre nom et votre adresse avec chaque modification que
belaran@999:         vous effectuez, de manière à ce que vous soyez capable (ou d'autres
belaran@999:         le soient) de savoir qui a fait quelle modification. Mercurial essaye
belaran@999:         automatiquement de découvrir un nom d'utilisateur qui ait un minimum
belaran@999:         de sens pour effectuer l'opération de commit avec. Il va essayer
belaran@999:         chacune des méthodes suivantes, dans l'ordre :</para>
belaran@999: 
belaran@999:       <orderedlist inheritnum="ignore" continuation="restarts">
belaran@999:         <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
belaran@999:             d'utilisateur, ceci aura toujours la priorité sur les autres
belaran@999:             méthodes ci dessous.</para></listitem>
belaran@999:         <listitem><para id="x_44">Si vous avez défini une variable
belaran@999:             d'environnement <envar>HGUSER</envar>, c'est cette valeur qui est
belaran@999:             alors utilisée.</para></listitem>
belaran@999:         <listitem><para id="x_45">Si vous créez un fichier nommé <filename role="special" moreinfo="none">.hgrc</filename> dans votre répertoire
belaran@999:             \textit{home}, avec une entrée <envar role="rc-item-ui">username</envar>, c'est la valeur associée
belaran@999:             qui sera utilisée. Pour voir à quoi ressemble le contenu de ce
belaran@999:             fichier regardez la section <xref linkend="sec:tour-basic:username"/>
belaran@999:             ci-dessous.</para></listitem>
belaran@999:         <listitem><para id="x_46">Si vous avez défini une variable
belaran@999:             d'environnement <envar>EMAIL</envar> celle ci sera utilisée
belaran@999:             ensuite.</para></listitem>
belaran@999:         <listitem><para id="x_47">Enfin, Mercurial interrogera votre système
belaran@999:             pour trouver votre nom d'utilisateur local ainsi que le nom de la
belaran@999:             machine hôte, et il fabriquera un nom d'utilisateur à partir de
belaran@999:             ces données. Comme il arrive souvent que ce genre de noms soit
belaran@999:             totalement inutile, il vous préviendra en affichant un message
belaran@999:             d'avertissement.</para></listitem>
belaran@999:       </orderedlist>
belaran@999:    
belaran@999:       <para id="x_48">Si tous ces mécanismes échouent, Mercurial n'exécutera
belaran@999:         pas la commande, affichant un message d'erreur. Dans ce cas, il ne
belaran@999:         vous laissera pas effectuer de commit tant que vous n'aurez pas
belaran@999:         défini un nom d'utilisateur.</para>
belaran@999:    
belaran@999:       <para id="x_49">Vous devriez penser à utiliser la variable
belaran@999:         d'environement <envar>HGUSER</envar> et l'option <option role="hg-opt-commit">-u</option> comme moyen pour
belaran@999:         <emphasis>changer</emphasis> le nom d'utilisateur par défaut. Pour
belaran@999:         une utilisation normale, la manière la plus simple et robuste
belaran@999:         d'opérer est de créer un fichier <filename role="special" moreinfo="none">.hgrc</filename>, voir ci-dessous pour  les détails
belaran@999:         à ce sujet.</para>
belaran@999: 
belaran@999:       <sect3 id="sec:tour-basic:username">
belaran@999:         <title>Créer un fichier de configuration pour Mercurial</title>
belaran@999: 
belaran@999:         <para id="x_4a">Pour définir un nom d'utilisateur, utilisez votre 
belaran@999:           éditeur de texte favori pour créer un fichier <filename role="special" moreinfo="none">.hgrc</filename> dans votre répertoire home. 
belaran@999:           Mercurial va utiliser ce fichier pour retrouver votre 
belaran@999:           configuration personnelle. Le contenu initial devrait
belaran@999:           ressembler à ceci :</para>
belaran@999:    
belaran@999:         <tip>
belaran@999:           <title><quote>Home directory</quote> sous Windows</title>
belaran@999:    
belaran@999:           <para id="x_716">Quand on parle de répertoire home, sur une version
belaran@999:             anglaise d'une installation de Windows, il s'agira habituellement
belaran@999:             d'un répertoire nommée comme votre nom dans <filename moreinfo="none">C:\Documents 
belaran@999:               and Settings</filename>. Vous pouvez trouver de quelle répertoire
belaran@999:             il s'agit en lançant une fenêtre d'interpréteur de commande et en
belaran@999:             exécutant la commande suivante :</para>
belaran@999:           
belaran@999:           <screen format="linespecific"><prompt moreinfo="none">C:\</prompt> <userinput moreinfo="none">echo
belaran@999:               %UserProfile</userinput></screen>
belaran@999:         </tip>
belaran@999:    
belaran@999:         <programlisting format="linespecific"># This is a Mercurial configuration file.
belaran@999: [ui]
belaran@999: username = Firstname Lastname &lt;email.address@domain.net&gt;</programlisting>
belaran@999: 
belaran@999:         <para id="x_4b">La ligne avec <literal moreinfo="none">[ui]</literal> commence une
belaran@999:           <emphasis>section</emphasis> du fichier de configuration, ainsi la ligne
belaran@999:           <quote><literal moreinfo="none">username = ...</literal></quote> signifie <quote>
belaran@999:             définir la valeur de l'élément <literal moreinfo="none">username</literal> dans la
belaran@999:             section <literal moreinfo="none">ui</literal></quote>. Une section continue jusqu'à ce
belaran@999:           qu'une nouvelle commence, ou que la fin du fichier soit atteinte.
belaran@999:           Mercurial ignore les lignes vides et traite tout texte situé à la suite
belaran@999:           d'un <quote><literal moreinfo="none">#</literal></quote> jusqu'à la fin de la ligne
belaran@999:           comme un commentaire.</para>
belaran@999: 
belaran@999:       </sect3>
belaran@999:       <sect3>
belaran@999:         <title>Choisir un nom d'utilisateur</title>
belaran@999:  
belaran@999:         <para id="x_4c">Vous pouvez utiliser n'importe quelle valeur 
belaran@999:           pour votre <literal moreinfo="none">username</literal>, car cette information 
belaran@999:           est destinée à d'autres personnes et non à être interprétée 
belaran@999:           par Mercurial. La convention que la plupart des personnes
belaran@999:           suivent est d'utiliser leurs noms suivies de leurs adresses emails,
belaran@999:           comme montré ci-dessus :</para>
belaran@999:         <note>
belaran@999:           <para id="x_4d">Le mécanisme interne du serveur web intégré à Mercurial,
belaran@999:             masque les adresses emails, pour rendre plus difficile leurs
belaran@999:             récupérations par les outils utilisés par les spammmers.
belaran@999:             Ceci réduit la probabilité que de recevoir encore plus de
belaran@999:             spam si vous vous publiez un dépôt sur internet.</para>
belaran@999:         </note>
belaran@999:       </sect3>
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Rédiger un message de \textit{commit}</title>
belaran@999:   
belaran@999:       <para id="x_4e">Lorsqu'on effectue une opération de commit, Mercurial
belaran@999:         lance automatiquement un éditeur de texte pour permettre de saisir
belaran@999:         un message qui décrira les modifications effectuées dans cette
belaran@999:         révision. Ce message est nommé le <emphasis>message de commit</emphasis>. 
belaran@999:         Ce sera un enregistrement pour tout lecteur expliquant le pourquoi 
belaran@999:         et le comment de vos modifications, et il sera affiché par la 
belaran@999:         commande <command role="hg-cmd" moreinfo="none">hg log</command>.</para>
belaran@999:  
belaran@999:       <!-- BEGIN tour.commit -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit</userinput>
belaran@999: </screen>
belaran@999: <!-- END tour.commit -->
belaran@999:  
belaran@999:   
belaran@999:       <para id="x_4f">L'éditeur que la commande <command role="hg-cmd" moreinfo="none">hg 
belaran@999:           commit</command> déclenche ne contiendra qu'une ligne vide suivi 
belaran@999:         d'un certain nombre de lignes commençant par <quote><literal moreinfo="none">HG:
belaran@999:         </literal></quote>.</para>
belaran@999:     
belaran@999:         <programlisting format="linespecific">
belaran@999:     This is where I type my commit comment.
belaran@999:     
belaran@999:     HG: Enter commit message.  Lines beginning with 'HG:' are removed.
belaran@999:     HG: --
belaran@999:     HG: user: Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999:     HG: branch 'default'
belaran@999:     HG: changed hello.c</programlisting>
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_50">Mercurial ignore les lignes qui commencent 
belaran@999:         avec <quote><literal moreinfo="none">HG:</literal></quote>, il ne les 
belaran@999:         utilise que pour nous indiquer quels fichiers modifiés il se
belaran@999:         prépare à \textit{commiter}. Modifier ou effacer ces lignes n'a
belaran@999:         aucune conséquence sur l'opération de commit.
belaran@999:       </para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Rédiger un message \textit{approprié}</title>
belaran@999:   
belaran@999:       <para id="x_51">Comme <command role="hg-cmd" moreinfo="none">hg log</command> n'affiche
belaran@999:         que la première ligne du message de commit par défaut, il est souvent
belaran@999:         considéré comme une bonne pratique de rédiger des messages de commit
belaran@999:         qui tiennent sur une seule ligne. Voilà un exemple concret de message 
belaran@999:         de commit qui <emphasis>ne suit pas</emphasis> cette directive, et
belaran@999:         qui a donc un résumé peu lisible.</para>
belaran@999: 
belaran@999:       <programlisting format="linespecific">
belaran@999: changeset:   73:584af0e231be
belaran@999: user:        Censored Person &lt;censored.person@example.org&gt;
belaran@999: date:        Tue Sep 26 21:37:07 2006 -0700
belaran@999: summary:     include buildmeister/commondefs.   Add an exports and install
belaran@999:       </programlisting>
belaran@999:   
belaran@999:       <para id="x_52">A ce sujet, il faut noter qu'il n'existe pas de règle 
belaran@999:         absolue dans ce domaine. Mercurial lui-même n'interprète pas les 
belaran@999:         contenus des messages de commit, ainsi votre projet est libre de 
belaran@999:         concevoir différentes politiques de mise en page des messages.</para>
belaran@999:       
belaran@999:       <para id="x_53">Ma préférence personnelle va au message court, mais 
belaran@999:         informatif, qui offre des précisions supplémentaires par rapport à ce 
belaran@999:         que pourrait m'apprendre une commande <command role="hg-cmd" moreinfo="none">hg log 
belaran@999:           --patch</command>.</para>
belaran@999:       
belaran@999:       <para id="x_55">Si vous exécutez la commande <command role="hg-cmd" moreinfo="none">hg
belaran@999:           commit</command> sans aucun argument, elle enregistre tous les 
belaran@999:         changements qui ont été fait, et qui sont indiqué par les commandes
belaran@999:         <command role="hg-cmd" moreinfo="none">hg status</command> et  <command role="hg-cmd" moreinfo="none">hg diff</command>.</para>
belaran@999:       
belaran@999:       <note>
belaran@999:         <title>Une surprise pour les utilisateurs habitués à Subversion</title>
belaran@999:    
belaran@999:         <para id="x_717">Comme n'importe quel autre commande de Mercurial, si
belaran@999:           vous soumettez pas de manière explicite les noms des fichiers à
belaran@999:           committer à la commande <command role="hg-cmd" moreinfo="none">hg commit</command>, elle
belaran@999:           va travailler sur l'ensemble du répertoire de travail. Soyez conscient
belaran@999:           de ceci si vous venez du monde Subversion ou CVS, car vous pourriez
belaran@999:           attendre qu'elle opère uniquement le répertoire courant et ses sous
belaran@999:           répertoires.</para>
belaran@999:       </note>
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Annuler un \textit{commit}</title>
belaran@999: 
belaran@999:       <para id="x_54">Si, en rédigeant le message, vous décidez que 
belaran@999:         finalement vous ne voulez pas effectuer ce commit, il suffit 
belaran@999:         de quitter simplement l'éditeur sans sauver. Ceci n'aura aucune 
belaran@999:         conséquence sur le dépôt ou les fichiers du répertoire de 
belaran@999:         travail.</para>
belaran@999:     </sect2>
belaran@999:   
belaran@999:     <sect2>
belaran@999:       <title>Admirer votre travail</title>
belaran@999:   
belaran@999:       <para id="x_56">Une fois que votre \textit{commit} est terminé, vous
belaran@999:         pouvez utiliser la commande <command role="hg-cmd" moreinfo="none">hg tip</command>
belaran@999:         pour afficher le \textit{changeset} que vous venez de créer. Cette
belaran@999:         commande produit  une sortie à l'écran qui est identique à celle du
belaran@999:         <command role="hg-cmd" moreinfo="none">hg log</command>, mais qui n'affiche que la
belaran@999:         dernière révision du dépôt.</para>
belaran@999:  
belaran@999:       <!-- BEGIN tour.tip -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip -vp</userinput>
belaran@999: changeset:   5:c94f208d1dfb
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:26 2009 +0000
belaran@999: files:       hello.c
belaran@999: description:
belaran@999: Added an extra line of output
belaran@999: 
belaran@999: 
belaran@999: diff -r 2278160e78d4 -r c94f208d1dfb hello.c
belaran@999: --- a/hello.c	Sat Aug 16 22:16:53 2008 +0200
belaran@999: +++ b/hello.c	Sun Aug 16 14:05:26 2009 +0000
belaran@999: @@ -8,5 +8,6 @@
belaran@999:  int main(int argc, char **argv)
belaran@999:  {
belaran@999:  	printf("hello, world!\");
belaran@999: +	printf("hello again!\n");
belaran@999:  	return 0;
belaran@999:  }
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tour.tip -->
belaran@999:  
belaran@999:   
belaran@999:       <para id="x_57">On fait couramment référence à la dernière révision 
belaran@999:         du dépôt comme étant la <emphasis>révision tip</emphasis>, ou plus
belaran@999:         simplement le <emphasis>tip</emphasis>.</para>
belaran@999:   
belaran@999:       <para id="x_684">Au passage, la commande <command role="hg-cmd" moreinfo="none">hg
belaran@999:           tip</command> accepte la plupart des options qu'accepte 
belaran@999:         <command role="hg-cmd" moreinfo="none">hg log</command>. Ainsi <option role="hg-opt-global">-v</option> ci dessus implique <quote>soit
belaran@999:           verbeux</quote>, <option role="hg-opt-tip">-p</option>
belaran@999:         veux dire <quote>affiche le patch</quote>. L'utilisation de l'option
belaran@999:         <option role="hg-opt-tip">-p</option> pour afficher un patch est un
belaran@999:         autre exemple de la cohérence des commandes évoquée plus tôt.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Partager ses modifications</title>
belaran@999: 
belaran@999:     <para id="x_58">Nous avons mentionné plus haut que les dépôts 
belaran@999:       de Mercurial sont autosuffisants. Ce qui signifie que la nouvelle
belaran@999:       révision que vous venez de créer existe seulement dans votre 
belaran@999:       répertoire <filename class="directory" moreinfo="none">my-hello</filename>. Étudions 
belaran@999:       comment propager cette modification dans d'autres dépôts.</para>
belaran@999: 
belaran@999:     <sect2 id="sec:tour:pull">
belaran@999:       <title>Récupérer les modifications d'autres dépôts</title>
belaran@999: 
belaran@999:       <para id="x_59">Pour commencer, construisons un clone de notre dépôt 
belaran@999:         <filename class="directory" moreinfo="none">hello</filename> qui ne contiendra pas 
belaran@999:         le changement que nous venons d'effectuer. Nous l'appellerons notre 
belaran@999:         dépôt temporaire <filename class="directory" moreinfo="none">hello-pull</filename>.</para>
belaran@999:  
belaran@999:       <!-- BEGIN tour.clone-pull -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone hello hello-pull</userinput>
belaran@999: updating working directory
belaran@999: 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: </screen>
belaran@999: <!-- END tour.clone-pull -->
belaran@999: 
belaran@999:  
belaran@999:       <para id="x_5a">Nous allons utiliser la commande <command role="hg-cmd" moreinfo="none">hg pull</command> pour envoyer les modifications
belaran@999:         depuis <filename class="directory" moreinfo="none">my-hello</filename> dans <filename class="directory" moreinfo="none">hello-pull</filename>. Néanmoins, récupérer
belaran@999:         aveuglement des modifications depuis un dépôt a quelque chose d'un
belaran@999:         peu effrayant. Mercurial propose donc une commande <command role="hg-cmd" moreinfo="none">hg incoming</command> qui permet de savoir quelles
belaran@999:         modifications la commande <command role="hg-cmd" moreinfo="none">hg pull</command>
belaran@999:         <emphasis>pourrait</emphasis> entraîner dans notre dépôt, et ceci
belaran@999:         sans effectuer réellement de modification dessus.</para>
belaran@999: 
belaran@999:       <!-- BEGIN tour.incoming -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd hello-pull</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg incoming ../my-hello</userinput>
belaran@999: comparing with ../my-hello
belaran@999: searching for changes
belaran@999: changeset:   5:c94f208d1dfb
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:26 2009 +0000
belaran@999: summary:     Added an extra line of output
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tour.incoming -->
belaran@999:  
belaran@999:   
belaran@999:       <para id="x_5c">Apporter les modifications rapatriées dans un dépôt se
belaran@999:         résume donc à exécuter la commande <command role="hg-cmd" moreinfo="none">hg
belaran@999:           pull</command>, et préciser depuis quel dépôt effectuer le <command role="hg-cmd" moreinfo="none">hg pull</command>.</para>
belaran@999:       
belaran@999:       <!-- BEGIN tour.pull -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
belaran@999: changeset:   4:2278160e78d4
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sat Aug 16 22:16:53 2008 +0200
belaran@999: summary:     Trim comments.
belaran@999: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../my-hello</userinput>
belaran@999: pulling from ../my-hello
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 1 changes to 1 files
belaran@999: (run 'hg update' to get a working copy)
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
belaran@999: changeset:   5:c94f208d1dfb
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:26 2009 +0000
belaran@999: summary:     Added an extra line of output
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tour.pull -->
belaran@999: 
belaran@999:   
belaran@999:       <para id="x_5d">Comme vous le voyez avec une sortie avant et après de la
belaran@999:         commande <command role="hg-cmd" moreinfo="none">hg tip</command>, nous avons réussi à
belaran@999:         récupérer aisément les modifications dans notre dépôt. Il reste néanmoins
belaran@999:         quelque chose à faire avant de placer ces modifications dans l'espace de
belaran@999:         travail.</para>
belaran@999:    
belaran@999:       <tip>
belaran@999:         <title>Récupérer des changements précis</title>
belaran@999:    
belaran@999:         <para id="x_5b">Il est possible à cause du délai entre l'exécution de la
belaran@999:           commande <command role="hg-cmd" moreinfo="none">hg incoming</command> et l'exécution de
belaran@999:           la commande <command role="hg-cmd" moreinfo="none">hg pull</command>, que vous ne
belaran@999:           puissiez pas voir toutes les modifications que vous rapporterez d'un
belaran@999:           autre dépôt. Supposons que vous récupériez les modifications d'un dépôt
belaran@999:           situé quelque part sur le réseau. Alors que vous regardez le résultat de
belaran@999:           la commande <command role="hg-cmd" moreinfo="none">hg incoming</command>, et avant que
belaran@999:           vous ne décidiez de récupérer ces modifications, quelqu'un peut ajouter
belaran@999:           de nouvelles révisions dans le dépôt distant. Ce qui signifie que vous
belaran@999:           récupérez plus de révision que ce que vous aviez regardées en utilisant
belaran@999:           la commande <command role="hg-cmd" moreinfo="none">hg incoming</command>.</para>
belaran@999: 
belaran@999:         <para id="x_718">Si vous voulez seulement récupérer ce que vous aviez
belaran@999:           vérifier à l'aide de la commande <command role="hg-cmd" moreinfo="none">hg
belaran@999:             incoming</command>, ou que pour d'autres raisons vous souhaitiez ne
belaran@999:           récupérer qu'un sous ensemble des révisions supplémentaires
belaran@999:           disponibles, indiquant simplement les modifications que vous souhaitez
belaran@999:           récupérer par leurs ID de révision, soit <command moreinfo="none">hg pull
belaran@999:             -r7e95bb</command>. </para>
belaran@999:       </tip>
belaran@999:   
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Mise à jour de l'espace de travail</title>
belaran@999:   
belaran@999:       <para id="x_5e">Nous avons jusqu'à maintenant grossièrement défini la
belaran@999:         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 
belaran@999:         <xref linkend="sec:tour:pull"/> a apporté des modifications, que nous
belaran@999:         avons vérifiées, dans notre dépôt, mais il n'y a aucune trace de ces
belaran@999:         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
belaran@999:         de travail. C'est la commande <command role="hg-cmd" moreinfo="none">hg update</command>
belaran@999:         qui s'en charge.</para>
belaran@999:  
belaran@999:       <!-- BEGIN tour.update -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">grep printf hello.c</userinput>
belaran@999: 	printf("hello, world!\");
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update tip</userinput>
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">grep printf hello.c</userinput>
belaran@999: 	printf("hello, world!\");
belaran@999: 	printf("hello again!\n");
belaran@999: </screen>
belaran@999: <!-- END tour.update -->
belaran@999: 
belaran@999:   
belaran@999:       <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
belaran@999:         automatiquement. Il y a en fait une très bonne raison à cela : vous
belaran@999:         pouvez utilisez la commande <command role="hg-cmd" moreinfo="none">hg update</command>
belaran@999:         pour mettre à jour votre espace de travail à l'état dans lequel il était 
belaran@999:         à <emphasis>n'importe quelle révision</emphasis> de l'historique du dépôt. 
belaran@999:         Si vous aviez un espace de travail contenant une ancienne
belaran@999:         révision—pour chercher l'origine d'un bug, par exemple—et
belaran@999:         que vous effectuiez un <command role="hg-cmd" moreinfo="none">hg pull</command> qui
belaran@999:         mettrait à jour automatiquement votre espace de travail, vous ne seriez
belaran@999:         probablement pas très satisfait.</para>
belaran@999:   
belaran@999:       <para id="x_60">Néanmoins, comme les opérations de pull sont très souvent
belaran@999:         suivies d'un update, Mercurial vous permet de combiner les
belaran@999:         deux aisément en passant l'option <option role="hg-opt-pull">-u</option> 
belaran@999:         à la commande <command role="hg-cmd" moreinfo="none">hg pull</command>.</para>
belaran@999:   
belaran@999:       <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
belaran@999:         <option role="hg-opt-pull">-u</option>, vous pouvez constater qu'elle a
belaran@999:         affiché un rappel assez utile : vous devez encore effectuer une
belaran@999:         opération pour mettre à jour votre espace de travail.</para>
belaran@999: 
belaran@999:       <para id="x_62">Pour découvrir sur quelle révision de l'espace de 
belaran@999:         travail on se trouve, utilisez la commande <command role="hg-cmd" moreinfo="none">hg
belaran@999:           parents</command>.</para>
belaran@999:  
belaran@999:       <!-- BEGIN tour.parents -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
belaran@999: changeset:   5:c94f208d1dfb
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:26 2009 +0000
belaran@999: summary:     Added an extra line of output
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tour.parents -->
belaran@999: 
belaran@999:    
belaran@999:       <para id="x_63">Si vous regardez de nouveau le dessin <xref linkend="fig:tour-basic:history"/>, vous verrez les flèches reliant
belaran@999:         entre elles les révisions. Le nœud d'où la flèche
belaran@999:         <emphasis>part</emphasis> est dans chaque cas un parent,
belaran@999:         et le nœud où la flèche <emphasis>arrive</emphasis> est un
belaran@999:         enfant.</para>
belaran@999: 
belaran@999:       <para id="x_64">Pour mettre à jour l'espace de travail d'une révision
belaran@999:         particulière, indiquez un numéro de révision ou un \textit{changeset
belaran@999:         ID} à la commande <command role="hg-cmd" moreinfo="none">hg update</command>.</para>
belaran@999:   
belaran@999:       <!-- BEGIN tour.older -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update 2</userinput>
belaran@999: 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
belaran@999: changeset:   2:fef857204a0c
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sat Aug 16 22:05:04 2008 +0200
belaran@999: summary:     Introduce a typo into hello.c.
belaran@999: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update</userinput>
belaran@999: 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
belaran@999: changeset:   5:c94f208d1dfb
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:26 2009 +0000
belaran@999: summary:     Added an extra line of output
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tour.older -->
belaran@999: 
belaran@999:    
belaran@999:       <para id="x_65">Si vous ne précisez pas de manière explicite de numéro 
belaran@999:         de révision la commande <command role="hg-cmd" moreinfo="none">hg update</command>
belaran@999:         mettra à jour votre espace de travail avec le contenu de la révison
belaran@999:         \textit{tip}, comme montré dans l'exemple ci dessus lors du second
belaran@999:         appel à <command role="hg-cmd" moreinfo="none">hg update</command>.</para>
belaran@999:     
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Transférer les modifications vers un autre dépôt</title>
belaran@999:   
belaran@999:       <para id="x_66">Mercurial vous laisse transférer les modifications vers
belaran@999:         un autre dépôt, depuis votre dépôt actuel. Comme dans l'exemple du
belaran@999:         <command role="hg-cmd" moreinfo="none">hg pull</command> ci-dessus, nous allons créer
belaran@999:         un dépôt temporaire vers lequel transférer nos modifications.</para>
belaran@999:         
belaran@999:       <!-- BEGIN tour.clone-push -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone hello hello-push</userinput>
belaran@999: updating working directory
belaran@999: 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: </screen>
belaran@999: <!-- END tour.clone-push -->
belaran@999: 
belaran@999:   
belaran@999:       <para id="x_67">La commande <command role="hg-cmd" moreinfo="none">hg outgoing</command>
belaran@999:         nous indique quels changements nous allons transférer vers l'autre
belaran@999:         serveur.</para>
belaran@999:  
belaran@999:       <!-- BEGIN tour.outgoing -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-hello</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg outgoing ../hello-push</userinput>
belaran@999: comparing with ../hello-push
belaran@999: searching for changes
belaran@999: changeset:   5:c94f208d1dfb
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:26 2009 +0000
belaran@999: summary:     Added an extra line of output
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tour.outgoing -->
belaran@999: 
belaran@999:   
belaran@999:       <para id="x_68">Et la commande <command role="hg-cmd" moreinfo="none">hg push</command> 
belaran@999:         effectue réellement le transfert.</para>
belaran@999:  
belaran@999:       <!-- BEGIN tour.push -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push ../hello-push</userinput>
belaran@999: pushing to ../hello-push
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 1 changes to 1 files
belaran@999: </screen>
belaran@999: <!-- END tour.push -->
belaran@999: 
belaran@999:   
belaran@999:       <para id="x_69">Comme avec <command role="hg-cmd" moreinfo="none">hg pull</command>, la
belaran@999:         commande <command role="hg-cmd" moreinfo="none">hg push</command> ne met pas à jour
belaran@999:         le répertoire de travail du dépôt dans lequel il transfère les
belaran@999:         modifications. À l'inverse de <command role="hg-cmd" moreinfo="none">hg
belaran@999:           pull</command>, <command role="hg-cmd" moreinfo="none">hg push</command> ne fournit
belaran@999:         pas d'option <literal moreinfo="none">-u</literal> pour forcer la mise à jour de
belaran@999:         l'espace de travail cible. Cette asymétrie est délibéré : le dépot
belaran@999:         vers lequel nous transférons peut très bien être un serveur distant
belaran@999:         et partagé par plusieurs personnes. Si nous devions mettre à jour son
belaran@999:         répertoire de travail alors que quelqu'un d'autre travaille dessus,
belaran@999:         nous risquerions de perturber son travail.</para>
belaran@999:   
belaran@999:       <para id="x_6a">Qu'est ce qui se passe lorsque vous essayez de récupérer
belaran@999:         ou de transférer vos modifications et que le dépôt cible a déjà reçu
belaran@999:         ces modifications ? Rien de bien excitant.</para>
belaran@999:  
belaran@999:       <!-- BEGIN tour.push.nothing -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push ../hello-push</userinput>
belaran@999: pushing to ../hello-push
belaran@999: searching for changes
belaran@999: no changes found
belaran@999: </screen>
belaran@999: <!-- END tour.push.nothing -->
belaran@999: 
belaran@999:   
belaran@999:     </sect2>
belaran@999:   
belaran@999:     <sect2>
belaran@999:       <title>Emplacements par défaut</title>
belaran@999: 
belaran@999:       <para id="x_719">Quand nous faisons un clone d'un dépôt, Mercurial
belaran@999:         enregistre l'emplacement du dépôt d'origine dans le fichier
belaran@999:         <filename moreinfo="none">.hg/hgrc</filename> de notre nouveau dépôt. Si nous ne
belaran@999:         fournissons pas d'emplacement à la commande <command moreinfo="none">hg
belaran@999:           pull</command> ou à la commande <command moreinfo="none">hg push</command>, ces
belaran@999:         commandes utiliseront alors cet emplacement comme valeur par défaut.
belaran@999:         Les commandes <command moreinfo="none">hg incoming</command> et <command moreinfo="none">hg
belaran@999:           outgoing</command> feront de même.</para>
belaran@999:   
belaran@999:       <para id="x_71a">Si vous regardez le fichier
belaran@999:         <filename moreinfo="none">.hg/hgrc</filename>, vous constaterez que son contenu
belaran@999:         ressemble à ce qui suit.</para>
belaran@999:   
belaran@999:       <programlisting format="linespecific">[paths]
belaran@999: default = http://www.selenic.com/repo/hg</programlisting>
belaran@999:       
belaran@999:       <para id="x_71b">Il est possible—et souvent
belaran@999:         pratique—d'avoir un emplacement par défaut pour les commandes
belaran@999:         <command moreinfo="none">hg push</command> et <command moreinfo="none">hg outgoing</command>
belaran@999:         différent de celui des commandes <command moreinfo="none">hg pull</command> et
belaran@999:         <command moreinfo="none">hg incoming</command>. C'est faisable en ajoutant une entrée
belaran@999:         <literal moreinfo="none">default-push</literal> à la section
belaran@999:         <literal moreinfo="none">[paths]</literal> du <filename moreinfo="none">.hg/hgrc</filename>, comme
belaran@999:         suit.</para>
belaran@999:    
belaran@999:       <programlisting format="linespecific">[paths]
belaran@999: default = http://www.selenic.com/repo/hg
belaran@999: default-push = http://hg.example.com/hg</programlisting>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Partager ses modifications à travers le réseau</title>
belaran@999:   
belaran@999:       <para id="x_6b">Les commandes que nous avons étudiées dans les sections
belaran@999:         précédentes ne sont pas limitées aux dépôts locaux. Chacune fonctionne 
belaran@999:         de la même manière à travers une connexion réseau, il suffit de lui 
belaran@999:         passer une URL à la place d'un chemin de fichier local.</para>
belaran@999:  
belaran@999:       <!-- BEGIN tour.outgoing.net -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg outgoing http://hg.serpentine.com/tutorial/hello</userinput>
belaran@999: comparing with http://hg.serpentine.com/tutorial/hello
belaran@999: searching for changes
belaran@999: changeset:   5:c94f208d1dfb
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:26 2009 +0000
belaran@999: summary:     Added an extra line of output
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tour.outgoing.net -->
belaran@999: 
belaran@999:   
belaran@999:       <para id="x_6c">Dans cet exemple, nous allons voir quels changements 
belaran@999:         nous pourrions transférer vers le dépôt distant, mais le dépôt est, 
belaran@999:         de manière tout à fait compréhensible, pas configuré pour accepter 
belaran@999:         des modifications d'utilisateurs anonymes.</para>
belaran@999:  
belaran@999:       <!-- BEGIN tour.push.net -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push http://hg.serpentine.com/tutorial/hello</userinput>
belaran@999: pushing to http://hg.serpentine.com/tutorial/hello
belaran@999: searching for changes
belaran@999: ssl required
belaran@999: </screen>
belaran@999: <!-- END tour.push.net -->
belaran@999:  
belaran@999:     
belaran@999:     </sect2>
belaran@999: 
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Commencer un nouveau projet</title>
belaran@999: 
belaran@999:     <para id="x_71c">Il est tout aussi aisé de commencer un nouveau projet
belaran@999:       que de travailler sur un qui existe déjà. La commande <command moreinfo="none">hg
belaran@999:         init</command> crée un nouveau dépôt Mercurial vide.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch01/new.init -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init myproject</userinput>
belaran@999: </screen>
belaran@999: <!-- END ch01/new.init -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_71d">Ceci crée simplement un répertoire nommé
belaran@999:       <filename moreinfo="none">myproject</filename> dans le répertoire courant.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch01/new.ls -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls -l</userinput>
belaran@999: total 12
belaran@999: -rw-r--r-- 1 rpelisse rpelisse   47 Aug 16 14:04 goodbye.c
belaran@999: -rw-r--r-- 1 rpelisse rpelisse   45 Aug 16 14:04 hello.c
belaran@999: drwxr-xr-x 3 rpelisse rpelisse 4096 Aug 16 14:04 myproject
belaran@999: </screen>
belaran@999: <!-- END ch01/new.ls -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_71e">Nous pouvons dire que <filename moreinfo="none">myproject</filename> est
belaran@999:       un dépôt Mercurial car il contient un répertoire
belaran@999:       <filename moreinfo="none">.hg</filename>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch01/new.ls2 -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls -al myproject</userinput>
belaran@999: total 12
belaran@999: drwxr-xr-x 3 rpelisse rpelisse 4096 Aug 16 14:04 .
belaran@999: drwx------ 3 rpelisse rpelisse 4096 Aug 16 14:04 ..
belaran@999: drwxr-xr-x 3 rpelisse rpelisse 4096 Aug 16 14:04 .hg
belaran@999: </screen>
belaran@999: <!-- END ch01/new.ls2 -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_71f">Si vous voulons ajouter quelques fichiers préexistants
belaran@999:       dans ce dépôt, il suffit de les recopier dans le répertoire de travail,
belaran@999:       et demander à Mercurial de commencer à les suivre en utilisant la
belaran@999:       commande <command moreinfo="none">hg add</command>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch01/new.add -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd myproject</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cp ../hello.c .</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cp ../goodbye.c .</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add</userinput>
belaran@999: adding goodbye.c
belaran@999: adding hello.c
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: A goodbye.c
belaran@999: A hello.c
belaran@999: </screen>
belaran@999: <!-- END ch01/new.add -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_720">Une fois que nous sommes satisfaits de notre projet,
belaran@999:       nous pouvons commencer à ajouter nos révisions.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch01/new.commit -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Initial commit'</userinput>
belaran@999: </screen>
belaran@999: <!-- END ch01/new.commit -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_721">Il ne prend que quelques instants pour commencer à
belaran@999:       utiliser Mercurial sur un nouveau projet, ce qui fait aussi de ses
belaran@999:       points forts. Travailler avec une gestion de révision devient très
belaran@999:       facile, nous pouvons même l'utiliser pour les plus petits projets où
belaran@999:       nous aurions probablement jamais penser utiliser un outils aussi
belaran@999:       complexe.</para>
belaran@999:   </sect1>
belaran@999: </chapter>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "chapter")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN ch03 -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <chapter id="chap:tour-merge">
belaran@999:   <?dbhtml filename="a-tour-of-mercurial-merging-work.html"?>
belaran@999:   <title>Un rapide tour de Mercurial: fusionner les travaux</title>
belaran@999:   
belaran@999:   <para id="x_338">Nous avons maintenant étudié comment cloner un dépôt, effectuer
belaran@999:     des changements dedans, et récupérer ou transférer depuis un
belaran@999:     autre dépôt. La prochaine étape est donc de <emphasis>fusionner</emphasis> les
belaran@999:     modifications de différents dépôts.</para>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Fusionner différents travaux</title>
belaran@999:       <para id="x_339">La fusion  est un aspect fondamental lorsqu'on
belaran@999:       travaille iavec un gestionnaire de source distribué.</para>
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999:         <listitem>
belaran@999:           <para id="x_33a">Alice et Bob ont chacun une copie personnelle du dépôt d'un
belaran@999:             projet sur lequel ils collaborent. Alice corrige un bug
belaran@999:             dans son dépôt, et Bob ajoute une nouvelle fonctionnalité dans le
belaran@999:             sien. Ils veulent un dépôt partagé avec à la fois le correctif du
belaran@999:             bug et la nouvelle fonctionnalité.</para>
belaran@999:        </listitem>
belaran@999:        <listitem>
belaran@999:          <para id="x_33b">Je travaille régulièrement sur plusieurs tâches différentes sur
belaran@999:            un seul projet en même temps, chacun isolé dans son propre dépôt.
belaran@999:            Travailler ainsi signifie que je dois régulièrement fusionner une
belaran@999:            partie de mon code avec celui des autres.</para>
belaran@999:        </listitem>
belaran@999:      </itemizedlist>
belaran@999: 
belaran@999:      <para id="x_33c">Parce que la fusion est une opération si commune à réaliser,
belaran@999:        Mercurial la rend facile. Étudions ensemble le déroulement des
belaran@999:        opérations. Nous commencerons encore par faire un clone d'un autre
belaran@999:        dépôt (vous voyez que l'on fait ça tout le temps ?) puis nous ferons 
belaran@999:        quelques modifications dessus.</para>
belaran@999:        
belaran@999:        <!-- BEGIN tour.merge.clone -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone hello my-new-hello</userinput>
belaran@999: updating working directory
belaran@999: 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-new-hello</userinput>
belaran@999: # Make some simple edits to hello.c.
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">my-text-editor hello.c</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'A new hello for a new day.'</userinput>
belaran@999: </screen>
belaran@999: <!-- END tour.merge.clone -->
belaran@999: 
belaran@999:        
belaran@999:      <para id="x_33d">Nous devrions avoir maintenant deux copies de
belaran@999:        <filename moreinfo="none">hello.c</filename> avec des contenus différents. Les
belaran@999:        historiques de ces deux dépôts ont aussi divergés, comme illustré dans
belaran@999:        la figure <xref linkend="fig:tour-merge:sep-repos"/>.</para>
belaran@999: 
belaran@999:       <!-- BEGIN tour.merge.cat1 -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat hello.c</userinput>
belaran@999: /*
belaran@999:  * Placed in the public domain by Bryan O'Sullivan.  This program is
belaran@999:  * not covered by patents in the United States or other countries.
belaran@999:  */
belaran@999: 
belaran@999: #include &lt;stdio.h&gt;
belaran@999: 
belaran@999: int main(int argc, char **argv)
belaran@999: {
belaran@999: 	printf("once more, hello.\n");
belaran@999: 	printf("hello, world!\");
belaran@999: 	printf("hello again!\n");
belaran@999: 	return 0;
belaran@999: }
belaran@999: </screen>
belaran@999: <!-- END tour.merge.cat1 -->
belaran@999: 
belaran@999:      
belaran@999:      <para id="x_722">Et ici est notre légèrement différente version du
belaran@999:        dépôt.</para>
belaran@999:      
belaran@999:       <!-- BEGIN tour.merge.cat2 -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat ../my-hello/hello.c</userinput>
belaran@999: /*
belaran@999:  * Placed in the public domain by Bryan O'Sullivan.  This program is
belaran@999:  * not covered by patents in the United States or other countries.
belaran@999:  */
belaran@999: 
belaran@999: #include &lt;stdio.h&gt;
belaran@999: 
belaran@999: int main(int argc, char **argv)
belaran@999: {
belaran@999: 	printf("hello, world!\");
belaran@999: 	printf("hello again!\n");
belaran@999: 	return 0;
belaran@999: }
belaran@999: </screen>
belaran@999: <!-- END tour.merge.cat2 -->
belaran@999: 
belaran@999:      
belaran@999:      <figure id="fig:tour-merge:sep-repos" float="0">
belaran@999:        <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>
belaran@999:        <mediaobject>
belaran@999:          <imageobject><imagedata fileref="figs/tour-merge-sep-repos.png"/></imageobject>
belaran@999:          <textobject><phrase>XXX ajoute un test</phrase></textobject>
belaran@999:        </mediaobject>
belaran@999:      </figure>
belaran@999: 
belaran@999:      <para id="x_33f">Nous savons déjà que récupérer les modifications depuis
belaran@999:        notre dépôt <filename class="directory" moreinfo="none">my-hello</filename> n'aura
belaran@999:        aucun effet sur l'espace de travail.</para>
belaran@999: 
belaran@999:       <!-- BEGIN tour.merge.pull -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../my-hello</userinput>
belaran@999: pulling from ../my-hello
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 1 changes to 1 files (+1 heads)
belaran@999: (run 'hg heads' to see heads, 'hg merge' to merge)
belaran@999: </screen>
belaran@999: <!-- END tour.merge.pull -->
belaran@999: 
belaran@999: 
belaran@999:      <para id="x_340">Néanmoins, la commande <command role="hg-cmd" moreinfo="none">hg
belaran@999:        pull</command> nous indique quelque chose au sujet des 
belaran@999:        <quote>heads</quote>.</para>
belaran@999: 
belaran@999:      <sect2>
belaran@999:        <title>Les révisions 'heads'</title>
belaran@999: 
belaran@999:        <para id="x_341">Rappellez vous que Mercurial enregistre quelle révision
belaran@999:          est le parent de chaque révision. Si une révision a un parent, nous
belaran@999:          l'appelons un enfant(child) ou un descendant de ce parent. Une
belaran@999:          "head" est une révision qui n'a donc pas d'enfant. La révision tip
belaran@999:          est donc une "head", car c'est la révision la plus récente du dépôt
belaran@999:          qui n'a pas d'enfant. Il y a des moments où un dépôt peut contenir
belaran@999:          plusieurs "head".</para>
belaran@999: 
belaran@999:        <figure id="fig:tour-merge:pull" float="0">
belaran@999:          <title>Contenu du dépôt après une récupération ("pull") depuis le
belaran@999:            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>
belaran@999:          <mediaobject>
belaran@999:            <imageobject>
belaran@999:              <imagedata fileref="tour-merge-pull"/>
belaran@999:            </imageobject>
belaran@999:            <textobject><phrase>XXX ajoute un texte</phrase></textobject>
belaran@999:          </mediaobject>
belaran@999:        </figure>
belaran@999: 
belaran@999:        <para id="x_343">Dans la figure <xref linkend="fig:tour-merge:pull"/>,
belaran@999:          vous pouvez constater l'effet d'un \textit{pull} depuis le dépôt
belaran@999:          <filename class="directory" moreinfo="none">my-hello</filename> dans le dépôt
belaran@999:          <filename class="directory" moreinfo="none">my-new-hello</filename>. L'historique qui
belaran@999:          était déjà présent dans le dépôt <filename class="directory" moreinfo="none">my-new-hello</filename> reste intact, mais une
belaran@999:          nouvelle révision a été ajoutée. En vous reportant à la figure <xref linkend="fig:tour-merge:sep-repos"/>, vous pouvez voir que le
belaran@999:          <emphasis>ID de révision (changeset ID)</emphasis> reste le même dans
belaran@999:          le nouveau dépôt, mais que le <emphasis>numéro de
belaran@999:          révision</emphasis> reste le même. (Ceci est un parfait exemple de
belaran@999:          pourquoi il n'est fiable d'utiliser les numéros de révision lorsque
belaran@999:          l'on discute d'un \textit{changeset}.) Vous pouvez voir les "heads"
belaran@999:          présentes dans le dépôt en utilisant la commande <command role="hg-cmd" moreinfo="none">hg heads</command>.</para>
belaran@999: 
belaran@999:         <!-- BEGIN tour.merge.heads -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg heads</userinput>
belaran@999: changeset:   6:c94f208d1dfb
belaran@999: tag:         tip
belaran@999: parent:      4:2278160e78d4
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:26 2009 +0000
belaran@999: summary:     Added an extra line of output
belaran@999: 
belaran@999: changeset:   5:5f06f94fbeca
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:31 2009 +0000
belaran@999: summary:     A new hello for a new day.
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tour.merge.heads -->
belaran@999: 
belaran@999:       </sect2>
belaran@999: 
belaran@999:       <sect2>
belaran@999:         <title>Effectuer la fusion</title>
belaran@999: 
belaran@999:         <para id="x_344">Que se passe-t-il quand vous essayez d'utiliser la
belaran@999:           commande <command role="hg-cmd" moreinfo="none">hg update</command> pour mettre à
belaran@999:           jour votre espace de travail au nouveau "tip"</para>
belaran@999:          
belaran@999:          <!-- BEGIN tour.merge.update -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update</userinput>
belaran@999: abort: crosses branches (use 'hg merge' or 'hg update -C')
belaran@999: </screen>
belaran@999: <!-- END tour.merge.update -->
belaran@999: 
belaran@999: 
belaran@999:          
belaran@999:         <para id="x_345">Mercurial nous prévient que la commande <command role="hg-cmd" moreinfo="none">hg update</command> n'effectuera pas
belaran@999:           la fusion, il ne veut pas mettre à jour l'espace de travail quand il
belaran@999:           estime que nous pourrions avoir besoin d'une fusion, à moins de lui
belaran@999:           forcer la main. À la place, il faut utiliser la commande <command role="hg-cmd" moreinfo="none">hg merge</command> pour fusionner les deux
belaran@999:           "heads".</para>
belaran@999: 
belaran@999:        <para id="x_723">Pour commencer une fusion (merge) entre deux "heads",
belaran@999:        nous utilisons la commande <command role="hg-cmd" moreinfo="none">hg merge</command>.</para>
belaran@999: 
belaran@999:         <!-- BEGIN tour.merge.merge -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
belaran@999: merging hello.c
belaran@999: 0 files updated, 1 files merged, 0 files removed, 0 files unresolved
belaran@999: (branch merge, don't forget to commit)
belaran@999: </screen>
belaran@999: <!-- END tour.merge.merge -->
belaran@999:  
belaran@999:       
belaran@999:        <para id="x_347">Nous résolvons les conflits dans le fichier
belaran@999:          <filename moreinfo="none">hello.c</filename>. Ceci met à jour le répertoire de travail
belaran@999:          de sorte qu'il ne contienne les modifications ne provenance des
belaran@999:          <emphasis>deux</emphasis> "heads", ce qui est indiqué par la
belaran@999:          la sortie de la commande <command role="hg-cmd" moreinfo="none">hg
belaran@999:          parents</command> et le contenu du fichier
belaran@999:          <filename moreinfo="none">hello.c</filename>.</para>
belaran@999: 
belaran@999:         <!-- BEGIN tour.merge.parents -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
belaran@999: changeset:   5:5f06f94fbeca
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:31 2009 +0000
belaran@999: summary:     A new hello for a new day.
belaran@999: 
belaran@999: changeset:   6:c94f208d1dfb
belaran@999: tag:         tip
belaran@999: parent:      4:2278160e78d4
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:26 2009 +0000
belaran@999: summary:     Added an extra line of output
belaran@999: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat hello.c</userinput>
belaran@999: /*
belaran@999:  * Placed in the public domain by Bryan O'Sullivan.  This program is
belaran@999:  * not covered by patents in the United States or other countries.
belaran@999:  */
belaran@999: 
belaran@999: #include &lt;stdio.h&gt;
belaran@999: 
belaran@999: int main(int argc, char **argv)
belaran@999: {
belaran@999: 	printf("once more, hello.\n");
belaran@999: 	printf("hello, world!\");
belaran@999: 	printf("hello again!\n");
belaran@999: 	return 0;
belaran@999: }
belaran@999: </screen>
belaran@999: <!-- END tour.merge.parents -->
belaran@999: 
belaran@999:      </sect2>
belaran@999: 
belaran@999:      <sect2>
belaran@999:        <title>Effectuer l'ajout (commit) du résultat de la fusion</title>
belaran@999: 
belaran@999:        <para id="x_348">Dès l'instant où vous avez effectué une fusion
belaran@999:          (merge), <command role="hg-cmd" moreinfo="none">hg parents</command> vous
belaran@999:          affichera deux parents, avant que vous n'exécutiez la commande
belaran@999:          <command role="hg-cmd" moreinfo="none">hg commit</command> sur le résultat de la
belaran@999:          fusion.</para>
belaran@999: 
belaran@999:         <!-- BEGIN tour.merge.commit -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Merged changes'</userinput>
belaran@999: </screen>
belaran@999: <!-- END tour.merge.commit -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_349">Nous avons maintenant un nouveau tip, remarquer qu'il
belaran@999:         contient <emphasis>à la fois</emphasis> nos anciennes "heads" et leurs
belaran@999:         parents. Ce sont les mêmes révisions que nous avions affichées avec
belaran@999:         la commande <command role="hg-cmd" moreinfo="none">hg parents</command>.</para>
belaran@999: 
belaran@999:        <!-- BEGIN tour.merge.tip -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
belaran@999: changeset:   7:b8e1e756ef55
belaran@999: tag:         tip
belaran@999: parent:      5:5f06f94fbeca
belaran@999: parent:      6:c94f208d1dfb
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:33 2009 +0000
belaran@999: summary:     Merged changes
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tour.merge.tip -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_34a">Dans la figure <xref linkend="fig:tour-merge:merge"/>,
belaran@999:         vous pouvez voir une représentation de ce qui se passe dans l'espace
belaran@999:         de travail pendant la fusion, et comment ceci affecte le dépôt lors
belaran@999:         du "commit". Pendant la fusion, l'espace de travail, qui a deux
belaran@999:         révisions (changesets) comme parents, voit ces derniers devenir le parent
belaran@999:         d'une nouvelle révision (changeset).</para>
belaran@999: 
belaran@999:       <figure id="fig:tour-merge:merge" float="0">
belaran@999:         <title>Working directory and repository during merge, and
belaran@999:           following commit</title>
belaran@999:         <mediaobject>
belaran@999:           <imageobject>
belaran@999:             <imagedata fileref="figs/tour-merge-merge.png"/>
belaran@999:           </imageobject>
belaran@999:           <textobject><phrase>XXX ajoute texte</phrase></textobject>
belaran@999:         </mediaobject>
belaran@999:       </figure>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Fusionner les modifications en conflit</title>
belaran@999: 
belaran@999:     <para id="x_34b">La plupart des fusions sont assez simple à réaliser, mais 
belaran@999:       parfois vous vous retrouverez à fusionner des fichiers où la modification 
belaran@999:       touche la même portion de code, au sein d'un même fichier. À moins 
belaran@999:       que ces modification ne soient identiques, ceci aboutira à un 
belaran@999:       <emphasis>conflit</emphasis>, et vous devrez décider comment réconcilier 
belaran@999:       les différentes modifications dans un tout cohérent.</para>
belaran@999: 
belaran@999:     <figure id="fig:tour-merge:conflict" float="0">
belaran@999:       <title>Modifications en conflits dans un document</title>
belaran@999:       <mediaobject>
belaran@999:         <imageobject><imagedata fileref="tour-merge-conflict"/></imageobject>
belaran@999:         <textobject><phrase>XXX ajoute texte</phrase></textobject>
belaran@999:       </mediaobject>
belaran@999:     </figure>
belaran@999: 
belaran@999:     <para id="x_34d">La figure <xref linkend="fig:tour-merge:conflict"/>
belaran@999:       illustre un cas de modifications conflictuelles dans un document. Nous
belaran@999:       avons commencé avec une version simple de ce fichier, puis nous avons
belaran@999:       ajouté des modifications, pendant que quelqu'un d'autre modifiait le même
belaran@999:       texte. Notre tâche dans la résolution du conflit est de décider à quoi le
belaran@999:       fichier devrait ressembler.</para>
belaran@999: 
belaran@999:     <para id="x_34e">Mercurial n'a pas de mécanisme interne pour gérer 
belaran@999:       les conflits. À la place, il exécute un programme externe appelé 
belaran@999:       <command moreinfo="none">hgmerge</command>. Il s'agit d'un script shell qui est 
belaran@999:       embarqué par Mercurial, vous pouvez le modifier si vous le voulez. 
belaran@999:       Ce qu'il fait par défaut est d'essayer de trouver un des différents 
belaran@999:       outils de fusion qui seront probablement installés sur le système. 
belaran@999:       Il commence par les outils totalement automatiques, et si ils 
belaran@999:       échouent (parce que la résolution du conflit nécessite une
belaran@999:       intervention humaine) ou si ils sont absents, le script tente
belaran@999:       d'exécuter certains outils graphiques de fusion.</para>
belaran@999: 
belaran@999:     <para id="x_34f">Il est aussi possible de demander à Mercurial d'exécuter
belaran@999:       un autre programme ou un autre script en définissant la variable
belaran@999:       d'environnement <envar>HGMERGE</envar> avec le nom
belaran@999:       du programme de votre choix.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Utiliser un outil graphique de fusion</title>
belaran@999: 
belaran@999:       <para id="x_350">Mon outil de fusion préféré est
belaran@999:       <command moreinfo="none">kdiff3</command>, que j'utilise ici pour illustrer les
belaran@999:         fonctionnalités classiques des outils graphiques de fusion. Vous pouvez
belaran@999:         voir une capture d'écran de l'utilisation de <command moreinfo="none">kdiff3</command>
belaran@999:         dans la figure <xref linkend="fig:tour-merge:kdiff3"/>. Cet outil
belaran@999:         effectue une <emphasis>fusion \textit{three-way</emphasis>}, car il y a
belaran@999:         trois différentes versions du fichier qui nous intéresse. Le fichier
belaran@999:         découpe la partie supérieure de la fenêtre en trois panneaux:</para>
belaran@999:       <itemizedlist>
belaran@999:         <listitem><para id="x_351">A gauche on la version de
belaran@999:           <emphasis>base</emphasis> du fichier, soit la plus récente version
belaran@999:           des deux versions qu'on souhaite fusionner.</para></listitem>
belaran@999:         <listitem><para id="x_352">Au centre, il y a <quote>notre</quote>
belaran@999:           version du fichier, avec le contenu que nous avons modifié.</para></listitem>
belaran@999:         <listitem><para id="x_353">Sur la droite, on trouve
belaran@999:         <quote>leur</quote> version du fichier, celui qui contient la
belaran@999:         révision que nous souhaitons intégré.</para>
belaran@999:         </listitem></itemizedlist>
belaran@999:       <para id="x_354">Dans le panneau en dessous, on trouve le
belaran@999:         <emphasis>résultat</emphasis> actuel de notre fusion. Notre tâche
belaran@999:         consiste donc à remplacement tous les textes en rouges,
belaran@999:         qui indiquent des conflits non résolus, avec une fusion manuelle et 
belaran@999:         pertinente de <quote>notre</quote> version et de la <quote>leur</quote>.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_355">Tous les quatre panneaux sont <emphasis>accrochés ensemble</emphasis>, 
belaran@999:         si nous déroulons les ascenseurs verticalement ou horizontalement dans chacun 
belaran@999:         d'entre eux, les autres sont mis à jour avec la section correspondante dans leurs 
belaran@999:         fichiers respectifs.</para>
belaran@999: 
belaran@999:       <figure id="fig:tour-merge:kdiff3" float="0">
belaran@999:         <title>Utiliser <command moreinfo="none">kdiff3</command> pour fusionner les
belaran@999:           différentes version d'un fichier.</title>
belaran@999:         <mediaobject>
belaran@999:           <imageobject>
belaran@999:             <imagedata width="100%" fileref="figs/kdiff3.png"/></imageobject>
belaran@999:             <textobject>
belaran@999:               <phrase>XXX ajoute texte</phrase>
belaran@999:             </textobject>
belaran@999:           </mediaobject>
belaran@999:        </figure>
belaran@999: 
belaran@999:        <para id="x_357">Pour chaque portion de fichier posant problème, nous
belaran@999:          pouvons choisir de résoudre le conflit en utilisant une combinaison de
belaran@999:          texte depuis la version de base, la notre, ou la leur. Nous pouvons
belaran@999:          aussi éditer manuellement les fichiers à tout moment, si c'est nécessaire.</para>
belaran@999: 
belaran@999:        <para id="x_358">Il y a <emphasis>beaucoup</emphasis> d'outils de
belaran@999:          fusion disponibles, bien trop pour en parler de tous ici. Leurs
belaran@999:          disponibilités varient selon les plate formes  ainsi que leurs
belaran@999:          avantages et inconvénients. La plupart sont optimisé pour
belaran@999:          la fusion de fichier contenant un texte plat, certains sont spécialisé
belaran@999:          dans un format de fichier précis (généralement XML).</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Un exemple concret</title>
belaran@999: 
belaran@999:       <para id="x_359">Dans cet exemple, nous allons reproduire la
belaran@999:         modification de l'historique du fichier de la figure <xref linkend="fig:tour-merge:conflict"/> ci dessus. Commençons par créer
belaran@999:         un dépôt avec une version de base de notre document.</para>
belaran@999: 
belaran@999:       <!-- BEGIN tour-merge-conflict.wife -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat &gt; letter.txt &lt;&lt;EOF</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Greetings!</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">I am Mariam Abacha, the wife of former</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Nigerian dictator Sani Abacha.</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">EOF</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add letter.txt</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m '419 scam, first draft'</userinput>
belaran@999: </screen>
belaran@999: <!-- END tour-merge-conflict.wife -->
belaran@999:  
belaran@999: 
belaran@999:       <para id="x_35a">Créons un clone de ce dépôt et faisons une
belaran@999:         modification dans le fichier.</para>
belaran@999: 
belaran@999:       <!-- BEGIN tour-merge-conflict.cousin -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone scam scam-cousin</userinput>
belaran@999: updating working directory
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd scam-cousin</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat &gt; letter.txt &lt;&lt;EOF</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Greetings!</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">I am Shehu Musa Abacha, cousin to the former</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Nigerian dictator Sani Abacha.</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">EOF</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m '419 scam, with cousin'</userinput>
belaran@999: </screen>
belaran@999: <!-- END tour-merge-conflict.cousin -->
belaran@999: 
belaran@999:       
belaran@999:       <para id="x_35b">Et un autre clone, pour simuler que quelqu'un d'autre effectue une
belaran@999:         modification sur le fichier. (Ceci pour suggérer qu'il n'est pas rare
belaran@999:         de devoir effectuer des fusions (merges) avec vos propres travaux quand
belaran@999:         vous isolez les tâches dans des dépôts distincts. En effet, vous
belaran@999:         aurez alors à trouver et résoudre certains conflits).</para>
belaran@999: 
belaran@999:       <!-- BEGIN tour-merge-conflict.son -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone scam scam-son</userinput>
belaran@999: updating working directory
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd scam-son</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat &gt; letter.txt &lt;&lt;EOF</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Greetings!</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">I am Alhaji Abba Abacha, son of the former</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Nigerian dictator Sani Abacha.</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">EOF</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m '419 scam, with son'</userinput>
belaran@999: </screen>
belaran@999: <!-- END tour-merge-conflict.son -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_35c">Maintenant que ces deux versions différentes du même fichier sont
belaran@999:         créées, nous allons configurer l'environnement de manière appropriée pour
belaran@999:         exécuter notre fusion (merge).</para>
belaran@999: 
belaran@999:       <!-- BEGIN tour-merge-conflict.pull -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone scam-cousin scam-merge</userinput>
belaran@999: updating working directory
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd scam-merge</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull -u ../scam-son</userinput>
belaran@999: pulling from ../scam-son
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 1 changes to 1 files (+1 heads)
belaran@999: not updating, since new heads added
belaran@999: (run 'hg heads' to see heads, 'hg merge' to merge)
belaran@999: </screen>
belaran@999: <!-- END tour-merge-conflict.pull -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_35d">Dans cette exemple, je n'utiliserais pas la commande Mercurial
belaran@999:         habituelle <command moreinfo="none">hgmerge</command> pour effectuer le
belaran@999:         fusion (merge), car il me faudrait abandonner ce joli petit exemple automatisé
belaran@999:         pour utiliser un outil graphique. À la place, je vais définir la
belaran@999:         variable d'environnement <envar>HGMERGE</envar> pour indiquer à
belaran@999:         Mercurial d'utiliser la commande non-interactive <command moreinfo="none">merge</command>.
belaran@999:         Cette dernière est embarquée par de nombreux systèmes <quote>à la Unix</quote>.
belaran@999:         Si vous exécutez cet exemple depuis votre ordinateur, ne vous
belaran@999:         occupez pas de définir <envar>HGMERGE</envar>.</para>
belaran@999: 
belaran@999:      <!-- BEGIN tour-merge-conflict.merge -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">export HGMERGE=merge</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
belaran@999: merging letter.txt
belaran@999: merge: warning: conflicts during merge
belaran@999: merging letter.txt failed!
belaran@999: 0 files updated, 0 files merged, 0 files removed, 1 files unresolved
belaran@999: use 'hg resolve' to retry unresolved file merges or 'hg up --clean' to abandon
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat letter.txt</userinput>
belaran@999: Greetings!
belaran@999: &lt;&lt;&lt;&lt;&lt;&lt;&lt; /tmp/tour-merge-conflictk3twLJ/scam-merge/letter.txt
belaran@999: I am Shehu Musa Abacha, cousin to the former
belaran@999: =======
belaran@999: I am Alhaji Abba Abacha, son of the former
belaran@999: &gt;&gt;&gt;&gt;&gt;&gt;&gt; /tmp/letter.txt~other.4O623C
belaran@999: Nigerian dictator Sani Abacha.
belaran@999: </screen>
belaran@999: <!-- END tour-merge-conflict.merge -->
belaran@999:  
belaran@999: 
belaran@999: 
belaran@999:      <para id="x_35f">Parce que <command moreinfo="none">merge</command> ne peut pas résoudre
belaran@999:        les modifications conflictuelles, il laisse des <emphasis>marqueurs de
belaran@999:        différences</emphasis> à l'intérieur du fichier qui a des conflits,
belaran@999:        indiquant clairement quelles lignes sont en conflits, et si elles
belaran@999:        viennent de notre fichier ou du fichier externe.
belaran@999:      </para>
belaran@999: 
belaran@999:      <para id="x_360">Mercurial peut distinguer, à la manière dont la
belaran@999:        commande <command moreinfo="none">merge</command> se termine, qu'elle n'a pas été
belaran@999:        capable d'effectuer la fusion (merge), alors il nous indique que nous
belaran@999:        devons effectuer de nouveau cette opération. Ceci peut être très utile
belaran@999:        si, par exemple, nous exécutons un outil graphique de fusion et que
belaran@999:        nous le quittons sans nous rendre compte qu'il reste des conflits ou 
belaran@999:        simplement par erreur.</para>
belaran@999: 
belaran@999:      <para id="x_361">Si la fusion (merge) automatique ou manuelle échoue, 
belaran@999:        il n'y a rien pour nous empêcher de <quote>corriger le tir</quote> en
belaran@999:        modifiant nous même les fichiers, et enfin effectuer le "commit" du 
belaran@999:        fichier:</para>
belaran@999: 
belaran@999:      <!-- BEGIN tour-merge-conflict.commit -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat &gt; letter.txt &lt;&lt;EOF</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Greetings!</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">I am Bryan O'Sullivan, no relation of the former</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">Nigerian dictator Sani Abacha.</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">EOF</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg resolve -m letter.txt</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Send me your money'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
belaran@999: changeset:   3:0954bda76c6b
belaran@999: tag:         tip
belaran@999: parent:      1:1ac156b6e708
belaran@999: parent:      2:7ee20631b33b
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:34 2009 +0000
belaran@999: summary:     Send me your money
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tour-merge-conflict.commit -->
belaran@999: 
belaran@999: 
belaran@999:      <note>
belaran@999:        <title>Où est la <command moreinfo="none">hg resolve</command> ?</title>
belaran@999:        
belaran@999:        <para id="x_724">La commande <command moreinfo="none">hg resolve</command> a été
belaran@999:          introduit dans la version 1.1 de Mercurial, qui a été publié en
belaran@999:          décembre 2008. Si vous utilisez une version plus anciennne de
belaran@999:          Mercurial (exécutez la command <command moreinfo="none">hg version</command> pour en
belaran@999:          avoir le coeur net), cette commande ne sera pas disponible. Si votre
belaran@999:          version de Mercurial est plus ancienne que la 1.1, vous devriez très
belaran@999:          fortement considérer une mise à jour à une version plus récente avant
belaran@999:          d'essayer de régler des fusions complexes.</para>
belaran@999:        </note>
belaran@999:      </sect2>
belaran@999:    </sect1>
belaran@999: 
belaran@999:    <sect1 id="sec:tour-merge:fetch">
belaran@999:      <title>Simplification de la séquence pull-merge-commit</title>
belaran@999: 
belaran@999:      <para id="x_362">La procédure pour effectuer la fusion indiquée
belaran@999:        ci-dessus est simple, mais requiert le lancement de trois commandes à la
belaran@999:        suite.</para>
belaran@999: 
belaran@999:      <programlisting format="linespecific">hg pull -u
belaran@999: hg merge
belaran@999: hg commit -m 'Merged remote changes'</programlisting>
belaran@999: 
belaran@999:      <para id="x_363">Lors du "commit" final, vous devez également saisir un
belaran@999:        message, qui aura vraisemblablement assez peu d'intérêt.</para>
belaran@999: 
belaran@999:      <para id="x_364">Il serait assez sympathique de pouvoir réduire le
belaran@999:        nombre d'opérations nécessaire, si possible. De fait Mercurial est
belaran@999:        fourni avec une extension appelé <literal role="hg-ext" moreinfo="none">fetch</literal>
belaran@999:        qui fait justement cela.</para>
belaran@999: 
belaran@999:      <para id="x_365">Mercurial fourni un mécanisme d'extension flexible qui permet à chacun
belaran@999:        d'étendre ces fonctionnalités, tout en conservant le cœur de Mercurial
belaran@999:        léger et facile à utiliser. Certains extensions ajoutent de nouvelles
belaran@999:        commandes que vous pouvez utiliser en ligne de commande, alors que
belaran@999:        d'autres travaillent <quote>en coulisse,</quote> par exemple en ajoutant des
belaran@999:        possibilités au serveur.</para>
belaran@999: 
belaran@999:      <para id="x_366">L'extension <literal role="hg-ext" moreinfo="none">fetch</literal>
belaran@999:        ajoute une nouvelle commande nommée, sans surprise, <command role="hg-cmd" moreinfo="none">hg fetch</command>. Cette extension résulte en une
belaran@999:        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
belaran@999:        merge</command>. Elle commence par récupérer les modifications d'un
belaran@999:        autre dépôt dans le dépôt courant. Si elle trouve que les
belaran@999:        modifications ajoutent une nouvelle "head", elle effectue un "merge",
belaran@999:        et ensuite "commit" le résultat du "merge" avec un message généré
belaran@999:        automatiquement. Si aucune "head" n'ont été ajouté, elle met à jour le
belaran@999:        répertoire de travail au niveau de la nouvelle révision tip.</para>
belaran@999:      
belaran@999:      <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
belaran@999:        <literal role="rc-extensions" moreinfo="none">extensions</literal>. Ensuite ajoutez
belaran@999:        une ligne qui consiste simplement en <quote>\Verb+fetch =</quote>.</para>
belaran@999: 
belaran@999:      <programlisting format="linespecific">[extensions]
belaran@999: fetch =</programlisting>
belaran@999: 
belaran@999:     <para id="x_368">(Normalement, sur la partie droite de
belaran@999:       <quote><literal moreinfo="none">=</literal></quote> devrait apparaître le chemin de
belaran@999:       l'extension, mais étant donné que l'extension <literal role="hg-ext" moreinfo="none">fetch</literal> fait partie de la distribution standard,
belaran@999:       Mercurial sait où la trouver.) </para>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   
belaran@999:   <sect1>
belaran@999:     <title>Renommer, copier, et fusionner (merge)</title>
belaran@999: 
belaran@999:     <para id="x_729">En cours de la vie d'un projet, nous allons souvent 
belaran@999:       vouloir changer la disposition de ses fichiers et de ses répertoires. 
belaran@999:       Ceci peut être aussi simple que de changer le nom d'un seul fichier, 
belaran@999:       et aussi compliqué que de restructurer une hiérarchie entiere de fichier
belaran@999:       au sein du projet.</para>
belaran@999: 
belaran@999:     <para id="x_72a">Mercurial permet de faire ce genre de modification de
belaran@999:       manière fluide, à condition de l'informer de ce que nous faisons. Si 
belaran@999:       vous voulez renommenr un ficher, vous devriez utiliser les commande
belaran@999:       <command moreinfo="none">hg rename</command><footnote>
belaran@999:         <para id="x_72b">Si vous un utilisateur de Unix, vous serez content
belaran@999:           de savoir que la commande  <command moreinfo="none">hg rename</command> command 
belaran@999:           peut être abrégée en <command moreinfo="none">hg mv</command>.</para>
belaran@999:       </footnote> pour changer son nom, ainsi Mercurial peut ensuite prendre
belaran@999:       la bonne décision, plus tard, en cas de fusionv (merge).</para>
belaran@999: 
belaran@999:     <para id="x_72c">Nous étudierojns en détail l'utilisation de ces commandes, 
belaran@999:       en détail, dans le chapitre <xref linkend="chap:daily.copy"/>.</para>
belaran@999:   </sect1>
belaran@999: </chapter>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "chapter")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN ch04 -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <chapter id="chap:concepts">
belaran@999:   <?dbhtml filename="behind-the-scenes.html"?>
belaran@999:   <title>Derrière le décor</title>
belaran@999:   
belaran@999:   <para id="x_2e8">À la différence de beaucoup d'outils de gestion de versions,
belaran@999:     les concepts sur lesquels se base Mercurial sont assez simples pour
belaran@999:     qu'il soit facile de comprendre comment le logiciel fonctionne.
belaran@999:     Bien que leur connaissance ne soit pas nécéssaire, je trouve utile
belaran@999:     d'avoir un <quote>modèle mental</quote> de ce qui se passe.</para>
belaran@999: 
belaran@999:   <para id="x_2e9">En effet, cette compréhension m'apporte la confiance que
belaran@999:     Mercurial a été développé avec soin pour être à la fois
belaran@999:     <emphasis>sûr</emphasis> et <emphasis>efficace</emphasis>. De surcroît,
belaran@999:     si il m'est facile de garder en tête ce que le logiciel fait lorsque
belaran@999:     j'accompli des tâches de révision, j'aurai moins de risques d'être
belaran@999:     surpris par son comportement.</para>
belaran@999: 
belaran@999:   <para id="x_2ea">Dans ce chapitre, nous décrirons tout d'abord les concepts
belaran@999:     essentiels de l'architecture de Mercurial, pour ensuite discuter quelques
belaran@999:     uns des détails intéressants de son implémentation.</para>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Conservation de l'historique sous Mercurial</title>
belaran@999:     <sect2>
belaran@999:       <title>Suivi de l'historique pour un seul fichier</title>
belaran@999:       
belaran@999:       <para id="x_2eb">Lorsque Mercurial effectue un suivi des modifications
belaran@999:         faites à un fichier, il conserve l'historique pour ce fichier dans un
belaran@999:         <emphasis>filelog</emphasis> sous forme de métadonnées. Chaque entrée
belaran@999:         dans le filelog contient assez d'informations pour reconstituer une
belaran@999:         révision du fichier correspondant. Les filelogs sont des fichiers
belaran@999:         stockés dans le répertoire  <filename role="special" class="directory" moreinfo="none">.hg/store/data</filename>. Un filelog contient
belaran@999:         des informations de deux types: les données de révision, et un index
belaran@999:         pour permettre à Mercurial une recherche efficace d'une révision
belaran@999:         donnée.</para>
belaran@999: 
belaran@999:       <para id="x_2ec">Lorsqu'un fichier devient trop gros ou a un long
belaran@999:         historique, son filelog se voit stocker dans un fichier de données
belaran@999:         (avec un suffixe <quote><literal moreinfo="none">.d</literal></quote>) et un fichier
belaran@999:         index (avec un suffixe<quote><literal moreinfo="none">.i</literal></quote>)
belaran@999:         distincts. La relation entre un fichier dans le répertoire de travail
belaran@999:         et le  filelog couvrant le suivi de son historique dans le dépôt est
belaran@999:         illustré à la figure <xref linkend="fig:concepts:filelog"/>.</para>
belaran@999: 
belaran@999:       <figure id="fig:concepts:filelog" float="0">
belaran@999:         <title>Relations entre les fichiers dans le répertoire de travail et
belaran@999:         leurs filelogs dans le dépôt</title> 
belaran@999:         <mediaobject> <imageobject><imagedata fileref="figs/filelog.png"/></imageobject>
belaran@999:           <textobject><phrase>XXX add text</phrase></textobject>
belaran@999:         </mediaobject> </figure>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Gestion des fichiers suivis</title>
belaran@999:       
belaran@999:       <para id="x_2ee">Mercurial a recours à une structure nommée
belaran@999:         <emphasis>manifest</emphasis> pour rassembler les informations sur
belaran@999:         les fichiers dont il gère le suivi. Chaque entrée dans ce manifest
belaran@999:         contient des informations sur les fichiers présents dans une révision
belaran@999:         donnée. Une entrée store la liste des fichiers faisant partie de la
belaran@999:         révision, la version de chaque fichier, et quelques autres
belaran@999:         métadonnées sur ces fichiers.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Recording changeset information</title>
belaran@999: 
belaran@999:       <para id="x_2ef">The <emphasis>changelog</emphasis> contains
belaran@999:         information about each changeset.  Each revision records who
belaran@999:         committed a change, the changeset comment, other pieces of
belaran@999:         changeset-related information, and the revision of the manifest to
belaran@999:         use.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Relationships between revisions</title>
belaran@999: 
belaran@999:       <para id="x_2f0">Within a changelog, a manifest, or a filelog, each
belaran@999: 	revision stores a pointer to its immediate parent (or to its
belaran@999: 	two parents, if it's a merge revision).  As I mentioned above,
belaran@999: 	there are also relationships between revisions
belaran@999: 	<emphasis>across</emphasis> these structures, and they are
belaran@999: 	hierarchical in nature.</para>
belaran@999: 
belaran@999:       <para id="x_2f1">For every changeset in a repository, there is exactly one
belaran@999: 	revision stored in the changelog.  Each revision of the
belaran@999: 	changelog contains a pointer to a single revision of the
belaran@999: 	manifest.  A revision of the manifest stores a pointer to a
belaran@999: 	single revision of each filelog tracked when that changeset
belaran@999: 	was created.  These relationships are illustrated in
belaran@999: 	<xref linkend="fig:concepts:metadata"/>.</para>
belaran@999: 
belaran@999:       <figure id="fig:concepts:metadata" float="0">
belaran@999: 	<title>Metadata relationships</title>
belaran@999: 	<mediaobject>
belaran@999: 	  <imageobject><imagedata fileref="figs/metadata.png"/></imageobject>
belaran@999: 	  <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	</mediaobject>
belaran@999:       </figure>
belaran@999: 
belaran@999:       <para id="x_2f3">As the illustration shows, there is
belaran@999: 	<emphasis>not</emphasis> a <quote>one to one</quote>
belaran@999: 	relationship between revisions in the changelog, manifest, or
belaran@999: 	filelog. If a file that
belaran@999: 	Mercurial tracks hasn't changed between two changesets, the
belaran@999: 	entry for that file in the two revisions of the manifest will
belaran@999: 	point to the same revision of its filelog<footnote>
belaran@999: 	  <para id="x_725">It is possible (though unusual) for the manifest to
belaran@999: 	    remain the same between two changesets, in which case the
belaran@999: 	    changelog entries for those changesets will point to the
belaran@999: 	    same revision of the manifest.</para>
belaran@999: 	</footnote>.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Safe, efficient storage</title>
belaran@999: 
belaran@999:     <para id="x_2f4">The underpinnings of changelogs, manifests, and filelogs are
belaran@999:       provided by a single structure called the
belaran@999:       <emphasis>revlog</emphasis>.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Efficient storage</title>
belaran@999: 
belaran@999:       <para id="x_2f5">The revlog provides efficient storage of revisions using a
belaran@999: 	<emphasis>delta</emphasis> mechanism.  Instead of storing a
belaran@999: 	complete copy of a file for each revision, it stores the
belaran@999: 	changes needed to transform an older revision into the new
belaran@999: 	revision.  For many kinds of file data, these deltas are
belaran@999: 	typically a fraction of a percent of the size of a full copy
belaran@999: 	of a file.</para>
belaran@999: 
belaran@999:       <para id="x_2f6">Some obsolete revision control systems can only work with
belaran@999: 	deltas of text files.  They must either store binary files as
belaran@999: 	complete snapshots or encoded into a text representation, both
belaran@999: 	of which are wasteful approaches.  Mercurial can efficiently
belaran@999: 	handle deltas of files with arbitrary binary contents; it
belaran@999: 	doesn't need to treat text as special.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2 id="sec:concepts:txn">
belaran@999:       <title>Safe operation</title>
belaran@999: 
belaran@999:       <para id="x_2f7">Mercurial only ever <emphasis>appends</emphasis> data to
belaran@999: 	the end of a revlog file. It never modifies a section of a
belaran@999: 	file after it has written it.  This is both more robust and
belaran@999: 	efficient than schemes that need to modify or rewrite
belaran@999: 	data.</para>
belaran@999: 
belaran@999:       <para id="x_2f8">In addition, Mercurial treats every write as part of a
belaran@999: 	<emphasis>transaction</emphasis> that can span a number of
belaran@999: 	files.  A transaction is <emphasis>atomic</emphasis>: either
belaran@999: 	the entire transaction succeeds and its effects are all
belaran@999: 	visible to readers in one go, or the whole thing is undone.
belaran@999: 	This guarantee of atomicity means that if you're running two
belaran@999: 	copies of Mercurial, where one is reading data and one is
belaran@999: 	writing it, the reader will never see a partially written
belaran@999: 	result that might confuse it.</para>
belaran@999: 
belaran@999:       <para id="x_2f9">The fact that Mercurial only appends to files makes it
belaran@999: 	easier to provide this transactional guarantee.  The easier it
belaran@999: 	is to do stuff like this, the more confident you should be
belaran@999: 	that it's done correctly.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Fast retrieval</title>
belaran@999: 
belaran@999:       <para id="x_2fa">Mercurial cleverly avoids a pitfall common to
belaran@999: 	all earlier revision control systems: the problem of
belaran@999: 	<emphasis>inefficient retrieval</emphasis>. Most revision
belaran@999: 	control systems store the contents of a revision as an
belaran@999: 	incremental series of modifications against a
belaran@999: 	<quote>snapshot</quote>.  (Some base the snapshot on the
belaran@999: 	oldest revision, others on the newest.)  To reconstruct a
belaran@999: 	specific revision, you must first read the snapshot, and then
belaran@999: 	every one of the revisions between the snapshot and your
belaran@999: 	target revision.  The more history that a file accumulates,
belaran@999: 	the more revisions you must read, hence the longer it takes to
belaran@999: 	reconstruct a particular revision.</para>
belaran@999: 
belaran@999:       <figure id="fig:concepts:snapshot" float="0">
belaran@999: 	<title>Snapshot of a revlog, with incremental deltas</title>
belaran@999: 	<mediaobject>
belaran@999: 	  <imageobject><imagedata fileref="figs/snapshot.png"/></imageobject>
belaran@999: 	  <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	</mediaobject>
belaran@999:       </figure>
belaran@999: 
belaran@999:       <para id="x_2fc">The innovation that Mercurial applies to this problem is
belaran@999: 	simple but effective.  Once the cumulative amount of delta
belaran@999: 	information stored since the last snapshot exceeds a fixed
belaran@999: 	threshold, it stores a new snapshot (compressed, of course),
belaran@999: 	instead of another delta.  This makes it possible to
belaran@999: 	reconstruct <emphasis>any</emphasis> revision of a file
belaran@999: 	quickly.  This approach works so well that it has since been
belaran@999: 	copied by several other revision control systems.</para>
belaran@999: 
belaran@999:       <para id="x_2fd"><xref linkend="fig:concepts:snapshot"/> illustrates
belaran@999: 	the idea.  In an entry in a revlog's index file, Mercurial
belaran@999: 	stores the range of entries from the data file that it must
belaran@999: 	read to reconstruct a particular revision.</para>
belaran@999: 
belaran@999:       <sect3>
belaran@999: 	<title>Aside: the influence of video compression</title>
belaran@999: 
belaran@999: 	<para id="x_2fe">If you're familiar with video compression or
belaran@999: 	  have ever watched a TV feed through a digital cable or
belaran@999: 	  satellite service, you may know that most video compression
belaran@999: 	  schemes store each frame of video as a delta against its
belaran@999: 	  predecessor frame.</para>
belaran@999: 
belaran@999: 	<para id="x_2ff">Mercurial borrows this idea to make it
belaran@999: 	  possible to reconstruct a revision from a snapshot and a
belaran@999: 	  small number of deltas.</para>
belaran@999: 
belaran@999:       </sect3>
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Identification and strong integrity</title>
belaran@999: 
belaran@999:       <para id="x_300">Along with delta or snapshot information, a revlog entry
belaran@999: 	contains a cryptographic hash of the data that it represents.
belaran@999: 	This makes it difficult to forge the contents of a revision,
belaran@999: 	and easy to detect accidental corruption.</para>
belaran@999: 
belaran@999:       <para id="x_301">Hashes provide more than a mere check against corruption;
belaran@999: 	they are used as the identifiers for revisions.  The changeset
belaran@999: 	identification hashes that you see as an end user are from
belaran@999: 	revisions of the changelog.  Although filelogs and the
belaran@999: 	manifest also use hashes, Mercurial only uses these behind the
belaran@999: 	scenes.</para>
belaran@999: 
belaran@999:       <para id="x_302">Mercurial verifies that hashes are correct when it
belaran@999: 	retrieves file revisions and when it pulls changes from
belaran@999: 	another repository.  If it encounters an integrity problem, it
belaran@999: 	will complain and stop whatever it's doing.</para>
belaran@999: 
belaran@999:       <para id="x_303">In addition to the effect it has on retrieval efficiency,
belaran@999: 	Mercurial's use of periodic snapshots makes it more robust
belaran@999: 	against partial data corruption.  If a revlog becomes partly
belaran@999: 	corrupted due to a hardware error or system bug, it's often
belaran@999: 	possible to reconstruct some or most revisions from the
belaran@999: 	uncorrupted sections of the revlog, both before and after the
belaran@999: 	corrupted section.  This would not be possible with a
belaran@999: 	delta-only storage model.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Revision history, branching, and merging</title>
belaran@999: 
belaran@999:     <para id="x_304">Every entry in a Mercurial revlog knows the identity of its
belaran@999:       immediate ancestor revision, usually referred to as its
belaran@999:       <emphasis>parent</emphasis>.  In fact, a revision contains room
belaran@999:       for not one parent, but two.  Mercurial uses a special hash,
belaran@999:       called the <quote>null ID</quote>, to represent the idea
belaran@999:       <quote>there is no parent here</quote>.  This hash is simply a
belaran@999:       string of zeroes.</para>
belaran@999: 
belaran@999:     <para id="x_305">In <xref linkend="fig:concepts:revlog"/>, you can see
belaran@999:       an example of the conceptual structure of a revlog.  Filelogs,
belaran@999:       manifests, and changelogs all have this same structure; they
belaran@999:       differ only in the kind of data stored in each delta or
belaran@999:       snapshot.</para>
belaran@999: 
belaran@999:     <para id="x_306">The first revision in a revlog (at the bottom of the image)
belaran@999:       has the null ID in both of its parent slots.  For a
belaran@999:       <quote>normal</quote> revision, its first parent slot contains
belaran@999:       the ID of its parent revision, and its second contains the null
belaran@999:       ID, indicating that the revision has only one real parent.  Any
belaran@999:       two revisions that have the same parent ID are branches.  A
belaran@999:       revision that represents a merge between branches has two normal
belaran@999:       revision IDs in its parent slots.</para>
belaran@999: 
belaran@999:     <figure id="fig:concepts:revlog" float="0">
belaran@999:       <title>The conceptual structure of a revlog</title>
belaran@999:       <mediaobject>
belaran@999: 	<imageobject><imagedata fileref="figs/revlog.png"/></imageobject>
belaran@999: 	<textobject><phrase>XXX add text</phrase></textobject>
belaran@999:       </mediaobject>
belaran@999:     </figure>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>The working directory</title>
belaran@999: 
belaran@999:     <para id="x_307">In the working directory, Mercurial stores a snapshot of the
belaran@999:       files from the repository as of a particular changeset.</para>
belaran@999: 
belaran@999:     <para id="x_308">The working directory <quote>knows</quote> which changeset
belaran@999:       it contains.  When you update the working directory to contain a
belaran@999:       particular changeset, Mercurial looks up the appropriate
belaran@999:       revision of the manifest to find out which files it was tracking
belaran@999:       at the time that changeset was committed, and which revision of
belaran@999:       each file was then current.  It then recreates a copy of each of
belaran@999:       those files, with the same contents it had when the changeset
belaran@999:       was committed.</para>
belaran@999: 
belaran@999:     <para id="x_309">The <emphasis>dirstate</emphasis> is a special
belaran@999:       structure that contains Mercurial's knowledge of the working
belaran@999:       directory.  It is maintained as a file named
belaran@999:       <filename moreinfo="none">.hg/dirstate</filename> inside a repository.  The
belaran@999:       dirstate details which changeset the working directory is
belaran@999:       updated to, and all of the files that Mercurial is tracking in
belaran@999:       the working directory. It also lets Mercurial quickly notice
belaran@999:       changed files, by recording their checkout times and
belaran@999:       sizes.</para>
belaran@999: 
belaran@999:     <para id="x_30a">Just as a revision of a revlog has room for two parents, so
belaran@999:       that it can represent either a normal revision (with one parent)
belaran@999:       or a merge of two earlier revisions, the dirstate has slots for
belaran@999:       two parents.  When you use the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	update</command> command, the changeset that you update to is
belaran@999:       stored in the <quote>first parent</quote> slot, and the null ID
belaran@999:       in the second. When you <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	merge</command> with another changeset, the first parent
belaran@999:       remains unchanged, and the second parent is filled in with the
belaran@999:       changeset you're merging with.  The <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	parents</command> command tells you what the parents of the
belaran@999:       dirstate are.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>What happens when you commit</title>
belaran@999: 
belaran@999:       <para id="x_30b">The dirstate stores parent information for more than just
belaran@999: 	book-keeping purposes.  Mercurial uses the parents of the
belaran@999: 	dirstate as <emphasis>the parents of a new
belaran@999: 	  changeset</emphasis> when you perform a commit.</para>
belaran@999: 
belaran@999:       <figure id="fig:concepts:wdir" float="0">
belaran@999: 	<title>The working directory can have two parents</title>
belaran@999: 	<mediaobject>
belaran@999: 	  <imageobject><imagedata fileref="figs/wdir.png"/></imageobject>
belaran@999: 	  <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	</mediaobject>
belaran@999:       </figure>
belaran@999: 
belaran@999:       <para id="x_30d"><xref linkend="fig:concepts:wdir"/> shows the
belaran@999: 	normal state of the working directory, where it has a single
belaran@999: 	changeset as parent.  That changeset is the
belaran@999: 	<emphasis>tip</emphasis>, the newest changeset in the
belaran@999: 	repository that has no children.</para>
belaran@999: 
belaran@999:       <figure id="fig:concepts:wdir-after-commit" float="0">
belaran@999: 	<title>The working directory gains new parents after a
belaran@999: 	  commit</title>
belaran@999: 	<mediaobject>
belaran@999: 	  <imageobject><imagedata fileref="figs/wdir-after-commit.png"/></imageobject>
belaran@999: 	  <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	</mediaobject>
belaran@999:       </figure>
belaran@999: 
belaran@999:       <para id="x_30f">It's useful to think of the working directory as
belaran@999: 	<quote>the changeset I'm about to commit</quote>.  Any files
belaran@999: 	that you tell Mercurial that you've added, removed, renamed,
belaran@999: 	or copied will be reflected in that changeset, as will
belaran@999: 	modifications to any files that Mercurial is already tracking;
belaran@999: 	the new changeset will have the parents of the working
belaran@999: 	directory as its parents.</para>
belaran@999: 
belaran@999:       <para id="x_310">After a commit, Mercurial will update the
belaran@999: 	parents of the working directory, so that the first parent is
belaran@999: 	the ID of the new changeset, and the second is the null ID.
belaran@999: 	This is shown in <xref linkend="fig:concepts:wdir-after-commit"/>. Mercurial
belaran@999: 	doesn't touch any of the files in the working directory when
belaran@999: 	you commit; it just modifies the dirstate to note its new
belaran@999: 	parents.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Creating a new head</title>
belaran@999: 
belaran@999:       <para id="x_311">It's perfectly normal to update the working directory to a
belaran@999: 	changeset other than the current tip.  For example, you might
belaran@999: 	want to know what your project looked like last Tuesday, or
belaran@999: 	you could be looking through changesets to see which one
belaran@999: 	introduced a bug.  In cases like this, the natural thing to do
belaran@999: 	is update the working directory to the changeset you're
belaran@999: 	interested in, and then examine the files in the working
belaran@999: 	directory directly to see their contents as they were when you
belaran@999: 	committed that changeset.  The effect of this is shown in
belaran@999: 	<xref linkend="fig:concepts:wdir-pre-branch"/>.</para>
belaran@999: 
belaran@999:       <figure id="fig:concepts:wdir-pre-branch" float="0">
belaran@999: 	<title>The working directory, updated to an older
belaran@999: 	  changeset</title>
belaran@999: 	<mediaobject>
belaran@999: 	  <imageobject><imagedata fileref="figs/wdir-pre-branch.png"/></imageobject>
belaran@999: 	  <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	</mediaobject>
belaran@999:       </figure>
belaran@999: 
belaran@999:       <para id="x_313">Having updated the working directory to an
belaran@999: 	older changeset, what happens if you make some changes, and
belaran@999: 	then commit?  Mercurial behaves in the same way as I outlined
belaran@999: 	above.  The parents of the working directory become the
belaran@999: 	parents of the new changeset.  This new changeset has no
belaran@999: 	children, so it becomes the new tip.  And the repository now
belaran@999: 	contains two changesets that have no children; we call these
belaran@999: 	<emphasis>heads</emphasis>.  You can see the structure that
belaran@999: 	this creates in <xref linkend="fig:concepts:wdir-branch"/>.</para>
belaran@999: 
belaran@999:       <figure id="fig:concepts:wdir-branch" float="0">
belaran@999: 	<title>After a commit made while synced to an older
belaran@999: 	  changeset</title>
belaran@999: 	<mediaobject>
belaran@999: 	  <imageobject><imagedata fileref="figs/wdir-branch.png"/></imageobject>
belaran@999: 	  <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	</mediaobject>
belaran@999:       </figure>
belaran@999: 
belaran@999:       <note>
belaran@999: 	<para id="x_315">If you're new to Mercurial, you should keep
belaran@999: 	  in mind a common <quote>error</quote>, which is to use the
belaran@999: 	  <command role="hg-cmd" moreinfo="none">hg pull</command> command without any
belaran@999: 	  options.  By default, the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	    pull</command> command <emphasis>does not</emphasis>
belaran@999: 	  update the working directory, so you'll bring new changesets
belaran@999: 	  into your repository, but the working directory will stay
belaran@999: 	  synced at the same changeset as before the pull.  If you
belaran@999: 	  make some changes and commit afterwards, you'll thus create
belaran@999: 	  a new head, because your working directory isn't synced to
belaran@999: 	  whatever the current tip is.  To combine the operation of a
belaran@999: 	  pull, followed by an update, run <command moreinfo="none">hg pull
belaran@999: 	    -u</command>.</para>
belaran@999: 
belaran@999: 	<para id="x_316">I put the word <quote>error</quote> in quotes
belaran@999: 	  because all that you need to do to rectify the situation
belaran@999: 	  where you created a new head by accident is
belaran@999: 	  <command role="hg-cmd" moreinfo="none">hg merge</command>, then <command role="hg-cmd" moreinfo="none">hg commit</command>.  In other words, this
belaran@999: 	  almost never has negative consequences; it's just something
belaran@999: 	  of a surprise for newcomers.  I'll discuss other ways to
belaran@999: 	  avoid this behavior, and why Mercurial behaves in this
belaran@999: 	  initially surprising way, later on.</para>
belaran@999:       </note>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Merging changes</title>
belaran@999: 
belaran@999:       <para id="x_317">When you run the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  merge</command> command, Mercurial leaves the first parent
belaran@999: 	of the working directory unchanged, and sets the second parent
belaran@999: 	to the changeset you're merging with, as shown in <xref linkend="fig:concepts:wdir-merge"/>.</para>
belaran@999: 
belaran@999:       <figure id="fig:concepts:wdir-merge" float="0">
belaran@999: 	<title>Merging two heads</title>
belaran@999: 	<mediaobject>
belaran@999: 	  <imageobject>
belaran@999: 	    <imagedata fileref="figs/wdir-merge.png"/>
belaran@999: 	  </imageobject>
belaran@999: 	  <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	</mediaobject>
belaran@999:       </figure>
belaran@999: 
belaran@999:       <para id="x_319">Mercurial also has to modify the working directory, to
belaran@999: 	merge the files managed in the two changesets.  Simplified a
belaran@999: 	little, the merging process goes like this, for every file in
belaran@999: 	the manifests of both changesets.</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_31a">If neither changeset has modified a file, do
belaran@999: 	    nothing with that file.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_31b">If one changeset has modified a file, and the
belaran@999: 	    other hasn't, create the modified copy of the file in the
belaran@999: 	    working directory.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_31c">If one changeset has removed a file, and the
belaran@999: 	    other hasn't (or has also deleted it), delete the file
belaran@999: 	    from the working directory.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_31d">If one changeset has removed a file, but the
belaran@999: 	    other has modified the file, ask the user what to do: keep
belaran@999: 	    the modified file, or remove it?</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_31e">If both changesets have modified a file,
belaran@999: 	    invoke an external merge program to choose the new
belaran@999: 	    contents for the merged file.  This may require input from
belaran@999: 	    the user.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_31f">If one changeset has modified a file, and the
belaran@999: 	    other has renamed or copied the file, make sure that the
belaran@999: 	    changes follow the new name of the file.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999:       <para id="x_320">There are more details—merging has plenty of corner
belaran@999: 	cases—but these are the most common choices that are
belaran@999: 	involved in a merge.  As you can see, most cases are
belaran@999: 	completely automatic, and indeed most merges finish
belaran@999: 	automatically, without requiring your input to resolve any
belaran@999: 	conflicts.</para>
belaran@999: 
belaran@999:       <para id="x_321">When you're thinking about what happens when you commit
belaran@999: 	after a merge, once again the working directory is <quote>the
belaran@999: 	  changeset I'm about to commit</quote>.  After the <command role="hg-cmd" moreinfo="none">hg merge</command> command completes, the
belaran@999: 	working directory has two parents; these will become the
belaran@999: 	parents of the new changeset.</para>
belaran@999: 
belaran@999:       <para id="x_322">Mercurial lets you perform multiple merges, but
belaran@999: 	you must commit the results of each individual merge as you
belaran@999: 	go.  This is necessary because Mercurial only tracks two
belaran@999: 	parents for both revisions and the working directory.  While
belaran@999: 	it would be technically feasible to merge multiple changesets
belaran@999: 	at once, Mercurial avoids this for simplicity.  With multi-way
belaran@999: 	merges, the risks of user confusion, nasty conflict
belaran@999: 	resolution, and making a terrible mess of a merge would grow
belaran@999: 	intolerable.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Merging and renames</title>
belaran@999: 
belaran@999:       <para id="x_69a">A surprising number of revision control systems pay little
belaran@999: 	or no attention to a file's <emphasis>name</emphasis> over
belaran@999: 	time.  For instance, it used to be common that if a file got
belaran@999: 	renamed on one side of a merge, the changes from the other
belaran@999: 	side would be silently dropped.</para>
belaran@999: 
belaran@999:       <para id="x_69b">Mercurial records metadata when you tell it to perform a
belaran@999: 	rename or copy. It uses this metadata during a merge to do the
belaran@999: 	right thing in the case of a merge.  For instance, if I rename
belaran@999: 	a file, and you edit it without renaming it, when we merge our
belaran@999: 	work the file will be renamed and have your edits
belaran@999: 	applied.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Other interesting design features</title>
belaran@999: 
belaran@999:     <para id="x_323">In the sections above, I've tried to highlight some of the
belaran@999:       most important aspects of Mercurial's design, to illustrate that
belaran@999:       it pays careful attention to reliability and performance.
belaran@999:       However, the attention to detail doesn't stop there.  There are
belaran@999:       a number of other aspects of Mercurial's construction that I
belaran@999:       personally find interesting.  I'll detail a few of them here,
belaran@999:       separate from the <quote>big ticket</quote> items above, so that
belaran@999:       if you're interested, you can gain a better idea of the amount
belaran@999:       of thinking that goes into a well-designed system.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Clever compression</title>
belaran@999: 
belaran@999:       <para id="x_324">When appropriate, Mercurial will store both snapshots and
belaran@999: 	deltas in compressed form.  It does this by always
belaran@999: 	<emphasis>trying to</emphasis> compress a snapshot or delta,
belaran@999: 	but only storing the compressed version if it's smaller than
belaran@999: 	the uncompressed version.</para>
belaran@999: 
belaran@999:       <para id="x_325">This means that Mercurial does <quote>the right
belaran@999: 	  thing</quote> when storing a file whose native form is
belaran@999: 	compressed, such as a <literal moreinfo="none">zip</literal> archive or a JPEG
belaran@999: 	image.  When these types of files are compressed a second
belaran@999: 	time, the resulting file is usually bigger than the
belaran@999: 	once-compressed form, and so Mercurial will store the plain
belaran@999: 	<literal moreinfo="none">zip</literal> or JPEG.</para>
belaran@999: 
belaran@999:       <para id="x_326">Deltas between revisions of a compressed file are usually
belaran@999: 	larger than snapshots of the file, and Mercurial again does
belaran@999: 	<quote>the right thing</quote> in these cases.  It finds that
belaran@999: 	such a delta exceeds the threshold at which it should store a
belaran@999: 	complete snapshot of the file, so it stores the snapshot,
belaran@999: 	again saving space compared to a naive delta-only
belaran@999: 	approach.</para>
belaran@999: 
belaran@999:       <sect3>
belaran@999: 	<title>Network recompression</title>
belaran@999: 
belaran@999: 	<para id="x_327">When storing revisions on disk, Mercurial uses the
belaran@999: 	  <quote>deflate</quote> compression algorithm (the same one
belaran@999: 	  used by the popular <literal moreinfo="none">zip</literal> archive format),
belaran@999: 	  which balances good speed with a respectable compression
belaran@999: 	  ratio.  However, when transmitting revision data over a
belaran@999: 	  network connection, Mercurial uncompresses the compressed
belaran@999: 	  revision data.</para>
belaran@999: 
belaran@999: 	<para id="x_328">If the connection is over HTTP, Mercurial recompresses
belaran@999: 	  the entire stream of data using a compression algorithm that
belaran@999: 	  gives a better compression ratio (the Burrows-Wheeler
belaran@999: 	  algorithm from the widely used <literal moreinfo="none">bzip2</literal>
belaran@999: 	  compression package).  This combination of algorithm and
belaran@999: 	  compression of the entire stream (instead of a revision at a
belaran@999: 	  time) substantially reduces the number of bytes to be
belaran@999: 	  transferred, yielding better network performance over most
belaran@999: 	  kinds of network.</para>
belaran@999: 
belaran@999: 	<para id="x_329">If the connection is over
belaran@999: 	  <command moreinfo="none">ssh</command>, Mercurial
belaran@999: 	  <emphasis>doesn't</emphasis> recompress the stream, because
belaran@999: 	  <command moreinfo="none">ssh</command> can already do this itself.  You can
belaran@999: 	  tell Mercurial to always use <command moreinfo="none">ssh</command>'s
belaran@999: 	  compression feature by editing the
belaran@999: 	  <filename moreinfo="none">.hgrc</filename> file in your home directory as
belaran@999: 	  follows.</para>
belaran@999: 
belaran@999: 	<programlisting format="linespecific">[ui]
belaran@999: ssh = ssh -C</programlisting>
belaran@999: 
belaran@999:       </sect3>
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Read/write ordering and atomicity</title>
belaran@999: 
belaran@999:       <para id="x_32a">Appending to files isn't the whole story when
belaran@999: 	it comes to guaranteeing that a reader won't see a partial
belaran@999: 	write.  If you recall <xref linkend="fig:concepts:metadata"/>,
belaran@999: 	revisions in the changelog point to revisions in the manifest,
belaran@999: 	and revisions in the manifest point to revisions in filelogs.
belaran@999: 	This hierarchy is deliberate.</para>
belaran@999: 
belaran@999:       <para id="x_32b">A writer starts a transaction by writing filelog and
belaran@999: 	manifest data, and doesn't write any changelog data until
belaran@999: 	those are finished.  A reader starts by reading changelog
belaran@999: 	data, then manifest data, followed by filelog data.</para>
belaran@999: 
belaran@999:       <para id="x_32c">Since the writer has always finished writing filelog and
belaran@999: 	manifest data before it writes to the changelog, a reader will
belaran@999: 	never read a pointer to a partially written manifest revision
belaran@999: 	from the changelog, and it will never read a pointer to a
belaran@999: 	partially written filelog revision from the manifest.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Concurrent access</title>
belaran@999: 
belaran@999:       <para id="x_32d">The read/write ordering and atomicity guarantees mean that
belaran@999: 	Mercurial never needs to <emphasis>lock</emphasis> a
belaran@999: 	repository when it's reading data, even if the repository is
belaran@999: 	being written to while the read is occurring. This has a big
belaran@999: 	effect on scalability; you can have an arbitrary number of
belaran@999: 	Mercurial processes safely reading data from a repository
belaran@999: 	all at once, no matter whether it's being written to or
belaran@999: 	not.</para>
belaran@999: 
belaran@999:       <para id="x_32e">The lockless nature of reading means that if you're
belaran@999: 	sharing a repository on a multi-user system, you don't need to
belaran@999: 	grant other local users permission to
belaran@999: 	<emphasis>write</emphasis> to your repository in order for
belaran@999: 	them to be able to clone it or pull changes from it; they only
belaran@999: 	need <emphasis>read</emphasis> permission.  (This is
belaran@999: 	<emphasis>not</emphasis> a common feature among revision
belaran@999: 	control systems, so don't take it for granted!  Most require
belaran@999: 	readers to be able to lock a repository to access it safely,
belaran@999: 	and this requires write permission on at least one directory,
belaran@999: 	which of course makes for all kinds of nasty and annoying
belaran@999: 	security and administrative problems.)</para>
belaran@999: 
belaran@999:       <para id="x_32f">Mercurial uses locks to ensure that only one process can
belaran@999: 	write to a repository at a time (the locking mechanism is safe
belaran@999: 	even over filesystems that are notoriously hostile to locking,
belaran@999: 	such as NFS).  If a repository is locked, a writer will wait
belaran@999: 	for a while to retry if the repository becomes unlocked, but
belaran@999: 	if the repository remains locked for too long, the process
belaran@999: 	attempting to write will time out after a while. This means
belaran@999: 	that your daily automated scripts won't get stuck forever and
belaran@999: 	pile up if a system crashes unnoticed, for example.  (Yes, the
belaran@999: 	timeout is configurable, from zero to infinity.)</para>
belaran@999: 
belaran@999:       <sect3>
belaran@999: 	<title>Safe dirstate access</title>
belaran@999: 
belaran@999: 	<para id="x_330">As with revision data, Mercurial doesn't take a lock to
belaran@999: 	  read the dirstate file; it does acquire a lock to write it.
belaran@999: 	  To avoid the possibility of reading a partially written copy
belaran@999: 	  of the dirstate file, Mercurial writes to a file with a
belaran@999: 	  unique name in the same directory as the dirstate file, then
belaran@999: 	  renames the temporary file atomically to
belaran@999: 	  <filename moreinfo="none">dirstate</filename>.  The file named
belaran@999: 	  <filename moreinfo="none">dirstate</filename> is thus guaranteed to be
belaran@999: 	  complete, not partially written.</para>
belaran@999: 
belaran@999:       </sect3>
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Avoiding seeks</title>
belaran@999: 
belaran@999:       <para id="x_331">Critical to Mercurial's performance is the avoidance of
belaran@999: 	seeks of the disk head, since any seek is far more expensive
belaran@999: 	than even a comparatively large read operation.</para>
belaran@999: 
belaran@999:       <para id="x_332">This is why, for example, the dirstate is stored in a
belaran@999: 	single file.  If there were a dirstate file per directory that
belaran@999: 	Mercurial tracked, the disk would seek once per directory.
belaran@999: 	Instead, Mercurial reads the entire single dirstate file in
belaran@999: 	one step.</para>
belaran@999: 
belaran@999:       <para id="x_333">Mercurial also uses a <quote>copy on write</quote> scheme
belaran@999: 	when cloning a repository on local storage.  Instead of
belaran@999: 	copying every revlog file from the old repository into the new
belaran@999: 	repository, it makes a <quote>hard link</quote>, which is a
belaran@999: 	shorthand way to say <quote>these two names point to the same
belaran@999: 	  file</quote>.  When Mercurial is about to write to one of a
belaran@999: 	revlog's files, it checks to see if the number of names
belaran@999: 	pointing at the file is greater than one.  If it is, more than
belaran@999: 	one repository is using the file, so Mercurial makes a new
belaran@999: 	copy of the file that is private to this repository.</para>
belaran@999: 
belaran@999:       <para id="x_334">A few revision control developers have pointed out that
belaran@999: 	this idea of making a complete private copy of a file is not
belaran@999: 	very efficient in its use of storage.  While this is true,
belaran@999: 	storage is cheap, and this method gives the highest
belaran@999: 	performance while deferring most book-keeping to the operating
belaran@999: 	system.  An alternative scheme would most likely reduce
belaran@999: 	performance and increase the complexity of the software, but
belaran@999: 	speed and simplicity are key to the <quote>feel</quote> of
belaran@999: 	day-to-day use.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Other contents of the dirstate</title>
belaran@999: 
belaran@999:       <para id="x_335">Because Mercurial doesn't force you to tell it when you're
belaran@999: 	modifying a file, it uses the dirstate to store some extra
belaran@999: 	information so it can determine efficiently whether you have
belaran@999: 	modified a file.  For each file in the working directory, it
belaran@999: 	stores the time that it last modified the file itself, and the
belaran@999: 	size of the file at that time.</para>
belaran@999: 
belaran@999:       <para id="x_336">When you explicitly <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  add</command>, <command role="hg-cmd" moreinfo="none">hg remove</command>,
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg rename</command> or <command role="hg-cmd" moreinfo="none">hg copy</command> files, Mercurial updates the
belaran@999: 	dirstate so that it knows what to do with those files when you
belaran@999: 	commit.</para>
belaran@999: 
belaran@999:       <para id="x_337">The dirstate helps Mercurial to efficiently
belaran@999: 	  check the status of files in a repository.</para>
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999: 	<listitem>
belaran@999: 	  <para id="x_726">When Mercurial checks the state of a file in the
belaran@999: 	    working directory, it first checks a file's modification
belaran@999: 	    time against the time in the dirstate that records when
belaran@999: 	    Mercurial last wrote the file. If the last modified time
belaran@999: 	    is the same as the time when Mercurial wrote the file, the
belaran@999: 	    file must not have been modified, so Mercurial does not
belaran@999: 	    need to check any further.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem>
belaran@999: 	  <para id="x_727">If the file's size has changed, the file must have
belaran@999: 	    been modified.  If the modification time has changed, but
belaran@999: 	    the size has not, only then does Mercurial need to
belaran@999: 	    actually read the contents of the file to see if it has
belaran@999: 	    changed.</para>
belaran@999: 	</listitem>
belaran@999:       </itemizedlist>
belaran@999: 
belaran@999:       <para id="x_728">Storing the modification time and size dramatically
belaran@999: 	reduces the number of read operations that Mercurial needs to
belaran@999: 	perform when we run commands like <command moreinfo="none">hg status</command>.
belaran@999: 	This results in large performance improvements.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: </chapter>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "chapter")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN ch05 -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <chapter id="chap:daily">
belaran@999:   <?dbhtml filename="mercurial-in-daily-use.html"?>
belaran@999:   <title>Mercurial pour une utilisation de tous les jours</title>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Informer Mercurial des fichier à suivre</title>
belaran@999: 
belaran@999:     <para id="x_1a3">Mercurial ne suit pas les fichiers de votre dépôt tant
belaran@999:       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
belaran@999:       inconnus de Mercurial. Il utilise un
belaran@999:       <quote><literal moreinfo="none">?</literal></quote> pour montrer ces fichiers.</para>
belaran@999: 
belaran@999:     <para id="x_1a4">Pour informer Mercurial de suivre un fichier, utilisez
belaran@999:       la commande <command role="hg-cmd" moreinfo="none">hg add</command>. Une fois que vous
belaran@999:       avez ajouté un fichier, la ligne correspondante à ce fichier dans la
belaran@999:       sortie de <command role="hg-cmd" moreinfo="none">hg status</command> change de
belaran@999:       <quote><literal moreinfo="none">?</literal></quote> à
belaran@999:       <quote><literal moreinfo="none">A</literal></quote>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN daily.files.add -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init add-example</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd add-example</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; myfile.txt</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: ? myfile.txt
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add myfile.txt</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: A myfile.txt
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Added one file'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: </screen>
belaran@999: <!-- END daily.files.add -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_1a5">Après avoir exécuté un <command role="hg-cmd" moreinfo="none">hg
belaran@999:         commit</command>, les fichiers que vous avez ajoutés avant le commit
belaran@999:       ne seront plus listés dans la sortie de <command role="hg-cmd" moreinfo="none">hg
belaran@999:         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
belaran@999:       <quote>intéressants</quote> —ceux que vous avez (par exemple)
belaran@999:       modifiés, supprimés ou renommés. Si vous aviez un dépôt qui contient un
belaran@999:       millier de fichiers, vous ne voudriez certainement que rarement entendre
belaran@999:       parler des fichiers que Mercurial suit, mais qui n'ont pas changés.
belaran@999:       (Vous pouvez quand même avoir cette information, nous y reviendrons
belaran@999:       plus tard.)</para>
belaran@999: 
belaran@999:     <para id="x_1a6">Une fois que vous ajoutez un fichier, Mercurial ne fait
belaran@999:       rien du tout avec celui-ci immédiatement. Au lieu de ça, il va prendre
belaran@999:       un "snapshot" de l'état du fichier la prochaine fois que vous
belaran@999:       exécuterez un commit. Il continuera ensuite à suivre les changements
belaran@999:       que vous avez fait au fichier chaque fois que vous committerez, et ce,
belaran@999:       jusqu'à ce que vous supprimiez le fichier.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Nommage des fichiers explicite versus implicite</title>
belaran@999: 
belaran@999:       <para id="x_1a7">Un comportement utile que Mercurial possède est que si
belaran@999:         vous passez le nom d'un répertoire à une commande, toute commande
belaran@999:         Mercurial la traitera comme : <quote>Je veux opérer sur chaque fichier
belaran@999:           dans ce répertoire et ses sous-répertoires</quote>.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.files.add-dir -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir b</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b &gt; b/somefile.txt</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo c &gt; b/source.cpp</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir b/d</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo d &gt; b/d/test.h</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add b</userinput>
belaran@999: adding b/d/test.h
belaran@999: adding b/somefile.txt
belaran@999: adding b/source.cpp
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Added all files in subdirectory'</userinput>
belaran@999: </screen>
belaran@999: <!-- END daily.files.add-dir -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1a8">Remarquez que dans cet exemple, Mercurial affiche le
belaran@999:         nom des fichiers qu'il a ajouté, alors qu'il ne l'a pas fait lorsque
belaran@999:         nous avons ajouté le fichier nommé <filename moreinfo="none">myfile.txt</filename>
belaran@999:         dans l'exemple précédent.</para>
belaran@999: 
belaran@999:       <para id="x_1a9">Ce qu'il se passe est que dans le premier cas, nous
belaran@999:         avons nommé explicitement le fichier à ajouter sur la ligne de
belaran@999:         commande. Ce que Mercurial suppose dans ce cas est que nous savons ce
belaran@999:         que nous faisons, il n'affiche donc rien en sortie.</para>
belaran@999: 
belaran@999:       <para id="x_1aa">Cependant, lorsque nous avons
belaran@999:         <emphasis>implicitement</emphasis> donné les fichiers à l'aide du nom
belaran@999:         d'un répertoire, Mercurial prend l'initiative d'afficher le nom de
belaran@999:         chaque fichier avec lequel il fait quelque chose. Ceci clarifie ce
belaran@999:         qu'il se passe et réduit la probabilité d'une mauvaise surprise
belaran@999:         restée silencieuse. Ce comportement est commun à la plupart des
belaran@999:         commandes Mercurial.</para>
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Mercurial suit les fichiers, pas les répertoires</title>
belaran@999: 
belaran@999:       <para id="x_1ab">Mercurial ne suit pas les informations sur les
belaran@999:         répertoires. En contrepartie, il suit le chemin vers un fichier. Avant
belaran@999:         de créer un fichier, il crée au préalable les répertoires manquants
belaran@999:         dans le chemin. Après avoir supprimé un fichier, il supprime chaque
belaran@999:         répertoire vide qui apparaît dans le chemin du fichier. Ceci apparaît
belaran@999:         comme une distinction triviale, cependant, cela a une conséquence
belaran@999:         pratique mineure : il n'est pas possible de représenter un répertoire
belaran@999:         totalement vide dans Mercurial.</para>
belaran@999: 
belaran@999:       <para id="x_1ac">Les répertoires vides sont rarement utiles. Il existe
belaran@999:         cependant des solutions alternatives et non intrusives que vous
belaran@999:         pouvez utiliser pour obtenir l'effet approprié. Les développeurs de
belaran@999:         Mercurial ont ainsi pensé que la complexité requise pour gérer les
belaran@999:         répertoires n'était pas aussi importante que le bénéfice que cette
belaran@999:         fonctionnalité apporterait.</para>
belaran@999: 
belaran@999:       <para id="x_1ad">Si vous avez besoin d'un répertoire vide dans votre
belaran@999:         dépôt, il existe quelques façons d'y arriver. L'une d'elles est de
belaran@999:         créer un répertoire et ensuite, de faire un <command role="hg-cmd" moreinfo="none">hg
belaran@999:           add</command> sur un fichier <quote>caché</quote> dans ce
belaran@999:         répertoire. Sur les systèmes de type Unix, tout fichier dont le nom
belaran@999:         commence avec un point (<quote><literal moreinfo="none">.</literal></quote>) est
belaran@999:         considéré comme caché par la plupart des commandes et outils
belaran@999:         graphiques. Cette approche est illustrée ci-après.</para>
belaran@999:       
belaran@999:       <!-- BEGIN daily.files.hidden -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init hidden-example</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd hidden-example</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir empty</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">touch empty/.hidden</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add empty/.hidden</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Manage an empty-looking directory'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls empty</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone hidden-example tmp</userinput>
belaran@999: updating working directory
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls tmp</userinput>
belaran@999: empty
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls tmp/empty</userinput>
belaran@999: </screen>
belaran@999: <!-- END daily.files.hidden -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1ae">Une autre façon de s'attaquer au besoin d'un
belaran@999:         répertoire vide est de simplement d'en créer un dans vos scripts
belaran@999:         de construction avant qu'ils n'en aient le besoin.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Comment arrêter de suivre un fichier</title>
belaran@999: 
belaran@999:     <para id="x_1af">Une fois que vous décidez qu'un fichier n'appartient
belaran@999:       plus à votre dépôt, utilisez la commande <command role="hg-cmd" moreinfo="none">hg
belaran@999:         remove</command>. Ceci supprime le fichier et informe Mercurial
belaran@999:       d'arrêter de le suivre (ce qui prendra effet lors du prochain commit).
belaran@999:       Un fichier supprimé est représenté dans la sortie de la commande
belaran@999:       <command role="hg-cmd" moreinfo="none">hg status</command> par un
belaran@999:       <quote><literal moreinfo="none">R</literal></quote>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN daily.files.remove -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init remove-example</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd remove-example</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir b</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b &gt; b/b</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a b</userinput>
belaran@999: adding b/b
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Small example for file removal'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg remove a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: R a
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg remove b</userinput>
belaran@999: removing b/b
belaran@999: </screen>
belaran@999: <!-- END daily.files.remove -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_1b0">Après avoir fait un <command role="hg-cmd" moreinfo="none">hg
belaran@999:         remove</command> sur un fichier, Mercurial ne suivra plus aucun
belaran@999:       changement sur ce fichier, même si vous recréez un fichier avec le même
belaran@999:       nom dans votre répertoire de travail. Si vous recréez un fichier avec le
belaran@999:       même nom et que vous désirez que Mercurial suive ce dernier, faite
belaran@999:       simplement un <command role="hg-cmd" moreinfo="none">hg add</command> sur celui-ci.
belaran@999:       Mercurial saura alors que le nouveau fichier ne fait pas référence à
belaran@999:       l'ancien fichier qui portait le même nom.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Supprimer un fichier n'affecte pas son historique</title>
belaran@999: 
belaran@999:       <para id="x_1b1">Il est important de comprendre que supprimer un fichier
belaran@999:         n'a que deux effets.</para>
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999:         <listitem><para id="x_1b2">Il supprime la version actuelle de ce
belaran@999:             fichier du répertoire de travail.</para>
belaran@999:         </listitem>
belaran@999:         <listitem><para id="x_1b3">Il arrête, à partir du prochain commit, le
belaran@999:             suivi de Mercurial sur les changements qui ont lieu sur ce
belaran@999:             fichier.</para>
belaran@999:         </listitem></itemizedlist>
belaran@999:         
belaran@999:       <para id="x_1b4">Supprimer un fichier <emphasis>n'</emphasis>affecte en
belaran@999:         <emphasis>aucun</emphasis> cas l'<emphasis>historique</emphasis> du
belaran@999:         fichier.</para>
belaran@999: 
belaran@999:       <para id="x_1b5">Si vous mettez à jour le répertoire de travail à un
belaran@999:         changeset qui a été committé alors que le fichier que vous venez de
belaran@999:         supprimer était encore suivi, ce fichier réapparaîtra dans le
belaran@999:         répertoire de travail, avec le contenu qu'il avait lorsque vous aviez
belaran@999:         committé ce changeset. Si vous mettez à jour (update) le répertoire de
belaran@999:         travail à un changeset ultérieur dans lequel le fichier a été
belaran@999:         supprimé, Mercurial supprimera une nouvelle fois le fichier du
belaran@999:         répertoire de travail.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Fichiers manquants</title>
belaran@999: 
belaran@999:       <para id="x_1b6">Mercurial considère qu'un fichier que vous avez
belaran@999:         supprimé sans utiliser<command role="hg-cmd" moreinfo="none">hg remove</command>
belaran@999:         comme étant <emphasis>manquant</emphasis>.  Un fichier manquant est
belaran@999:         représenté avec un <quote><literal moreinfo="none">!</literal></quote> en sortie de
belaran@999:         <command role="hg-cmd" moreinfo="none">hg status</command>.
belaran@999:         Les commandes Mercurial ne feront rien avec les fichiers
belaran@999:         manquants.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.files.missing -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init missing-example</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd missing-example</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'File about to be missing'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">rm a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: ! a
belaran@999: </screen>
belaran@999: <!-- END daily.files.missing -->
belaran@999: 
belaran@999: 
belaran@999:       <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
belaran@999:         vous voulez que ce fichier reste supprimé, vous pouvez exécuter
belaran@999:         <command role="hg-cmd" moreinfo="none">hg remove <option role="hg-opt-remove">--after</option></command> à tout moment
belaran@999:         pour dire à Mercurial que vous aviez bien voulu supprimer ce
belaran@999:         fichier.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.files.remove-after -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg remove --after a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: R a
belaran@999: </screen>
belaran@999: <!-- END daily.files.remove-after -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1b8">D'un autre coté, si vous avez supprimé le fichier
belaran@999:         manquant par accident, donnez à la commande <command role="hg-cmd" moreinfo="none">hg
belaran@999:           revert</command> le nom du fichier à retrouver. Il réapparaitra dans
belaran@999:         sa forme non modifiée.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.files.recover-missing -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat a</userinput>
belaran@999: a
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: </screen>
belaran@999: <!-- END daily.files.recover-missing -->
belaran@999: 
belaran@999:     
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Entre nous : Pourquoi dire explicitement à Mercurial de supprimer un
belaran@999:       fichier ?</title>
belaran@999: 
belaran@999:       <para id="x_1b9">Vous pourriez vous demander pourquoi il est nécessaire
belaran@999:         de dire explicitement à Mercurial que vous souhaitez supprimer un
belaran@999:         fichier. Au début du développement de Mercurial, celui ci vous
belaran@999:         laissait pourtant supprimer un fichier sans soucis ; Mercurial vous
belaran@999:         aurait automatiquement informé de l'absence du fichier lorsque vous
belaran@999:         auriez lancé un <command role="hg-cmd" moreinfo="none">hg commit</command> et arrêté
belaran@999:         de le suivre. En pratique, ceci a montré qu'il était trop facile de
belaran@999:         supprimer accidentellement un fichier sans le remarquer.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Raccourci utile—ajouter et supprimer des fichiers en une
belaran@999:       seule étape.</title>
belaran@999: 
belaran@999:       <para id="x_1ba">Mercurial offre une commande combinée, <command role="hg-cmd" moreinfo="none">hg addremove</command>, qui ajoute les fichiers non
belaran@999:         suivis et marque les fichiers manquants comme supprimés.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.files.addremove -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init addremove-example</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd addremove-example</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b &gt; b</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg addremove</userinput>
belaran@999: adding a
belaran@999: adding b
belaran@999: </screen>
belaran@999: <!-- END daily.files.addremove -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1bb">La commande <command role="hg-cmd" moreinfo="none">hg commit</command>
belaran@999:         fournit aussi une option <option role="hg-opt-commit">-A</option> qui
belaran@999:         exécute le même ajouter-et-supprimer, immédiatement suivi d'un
belaran@999:         commit.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.files.commit-addremove -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo c &gt; c</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'Commit with addremove'</userinput>
belaran@999: adding c
belaran@999: </screen>
belaran@999: <!-- END daily.files.commit-addremove -->
belaran@999: 
belaran@999:     
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="chap:daily.copy">
belaran@999:     <title>Copier des fichiers</title>
belaran@999: 
belaran@999:     <para id="x_1bc">Mercurial fournit une commande <command role="hg-cmd" moreinfo="none">hg
belaran@999:         copy</command> qui vous permet de faire une nouvelle copie d'un
belaran@999:       fichier. Lorsque vous copiez un fichier en utilisant cette commande,
belaran@999:       Mercurial crée un enregistrement du fait que ce nouveau fichier est une
belaran@999:       copie du fichier originel. Il traite ces fichiers copiés spécialement
belaran@999:       lorsque vous fusionnez (merge) votre travail avec quelqu'un
belaran@999:       d'autre.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Les résultats d'une copie durant une fusion (merge)</title>
belaran@999: 
belaran@999:       <para id="x_1bd">Ce qu'il se passe durant une fusion (merge) est que
belaran@999:         les changements <quote>suivent</quote> une copie. Pour illustrer ce
belaran@999:         que cela veut dire de la meilleure façon, créons un exemple. Nous
belaran@999:         allons commencer avec le mini dépôt usuel qui contient un simple
belaran@999:         fichier.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.copy.init -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init my-copy</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-copy</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo line &gt; file</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add file</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Added a file'</userinput>
belaran@999: </screen>
belaran@999: <!-- END daily.copy.init -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1be">Nous devons faire du travail en parallèle, ainsi,
belaran@999:         nous aurons quelque chose à fusionner (merge). Donc clonons notre
belaran@999:         dépôt.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.copy.clone -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone my-copy your-copy</userinput>
belaran@999: updating working directory
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: </screen>
belaran@999: <!-- END daily.copy.clone -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1bf">De retour dans notre dépôt initial, utilisons la
belaran@999:         commande <command role="hg-cmd" moreinfo="none">hg copy</command> pour faire une
belaran@999:         copie du premier fichier que nous avons créé.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.copy.copy -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-copy</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy file new-file</userinput>
belaran@999: </screen>
belaran@999: <!-- END daily.copy.copy -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1c0">Si nous regardons ensuite à la sortie de la commande
belaran@999:         <command role="hg-cmd" moreinfo="none">hg status</command>, les fichiers copiés
belaran@999:         ont l'air de fichiers normalement ajoutés.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.copy.status -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: A new-file
belaran@999: </screen>
belaran@999: <!-- END daily.copy.status -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1c1">Mais si nous passons l'option <option role="hg-opt-status">-C</option> à <command role="hg-cmd" moreinfo="none">hg
belaran@999:           status</command>, il affiche une autre ligne de sortie : il s'agit
belaran@999:         du fichier <emphasis>source</emphasis> pour notre copie.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.copy.status-copy -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status -C</userinput>
belaran@999: A new-file
belaran@999:   file
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Copied file'</userinput>
belaran@999: </screen>
belaran@999: <!-- END daily.copy.status-copy -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1c2">Maintenant, de retour dans le dépôt que nous avons
belaran@999:         cloné, créons un changement en parallèle. Nous allons ajouter une
belaran@999:         ligne de contenu au fichier original qui a été créé.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.copy.other -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../your-copy</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'new contents' &gt;&gt; file</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Changed file'</userinput>
belaran@999: </screen>
belaran@999: <!-- END daily.copy.other -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1c3">Nous avons alors un fichier <filename moreinfo="none">file</filename>
belaran@999:         modifié dans ce dépôt. Lorsque nous récupérons (pull) les changements
belaran@999:         depuis le premier répertoire et fusionnons (merge) les deux "heads",
belaran@999:         Mercurial propagera les changements que nous avons faits localement
belaran@999:         au fichier <filename moreinfo="none">file</filename> dans sa copie
belaran@999:         <filename moreinfo="none">new-file</filename>.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.copy.merge -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../my-copy</userinput>
belaran@999: pulling from ../my-copy
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 1 changes to 1 files (+1 heads)
belaran@999: (run 'hg heads' to see heads, 'hg merge' to merge)
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
belaran@999: merging file and new-file to new-file
belaran@999: 0 files updated, 1 files merged, 0 files removed, 0 files unresolved
belaran@999: (branch merge, don't forget to commit)
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat new-file</userinput>
belaran@999: line
belaran@999: new contents
belaran@999: </screen>
belaran@999: <!-- END daily.copy.merge -->
belaran@999: 
belaran@999:     
belaran@999:     </sect2>
belaran@999:     <sect2 id="sec:daily:why-copy">
belaran@999:       <title>Pourquoi est-ce que les changements devraient suivre les copies
belaran@999:         ?</title>
belaran@999: 
belaran@999:       <para id="x_1c4">Ce comportement—des changements d'un fichiers
belaran@999:         qui se propagent aux copies de ce fichier—peut sembler
belaran@999:         ésotérique, mais, dans la plupart des cas, c'est hautement
belaran@999:         désirable.</para>
belaran@999: 
belaran@999:       <para id="x_1c5">Pour commencer, souvenez vous que cette propagation
belaran@999:         a lieue <emphasis>seulement</emphasis> lors des fusions (merge).
belaran@999:         Donc, si vous faites un	<command role="hg-cmd" moreinfo="none">hg copy</command> sur
belaran@999:         un fichier, et par la suite modifiez le fichier original durant le
belaran@999:         cours normal de votre travail, rien n'a lieu.</para>
belaran@999: 
belaran@999:       <para id="x_1c6">La deuxième chose à savoir c'est que les modifications
belaran@999:         ne se propageront à travers une copie que si le changeset à partir
belaran@999:         duquel vous faites une fusion (merge) <emphasis>n'a pas encore
belaran@999:           vu</emphasis> la copie.</para>
belaran@999:           
belaran@999:       <para id="x_1c7">La raison pour laquelle Mercurial fait ainsi est une
belaran@999:         règle. Imaginons que je corrige un important bug dans un fichier source
belaran@999:         et que je commit mes changements. Pendant ce temps, vous avez décidé de
belaran@999:         faire un <command role="hg-cmd" moreinfo="none">hg copy</command> du fichier dans
belaran@999:         votre dépôt, sans rien savoir au sujet du bug ou à propos de la
belaran@999:         correction. Vous avez alors commencé à "hacker" sur votre copie du
belaran@999:         fichier.</para>
belaran@999: 
belaran@999:       <para id="x_1c8">Si vous aviez récupéré (pull) et fusionné (merge) mes
belaran@999:         changements, et que Mercurial <emphasis>n'avait pas</emphasis>
belaran@999:         propagé les changements à travers les copies, votre nouveau fichier
belaran@999:         source contiendrait maintenant le bug, et à moins que vous ne sachiez
belaran@999:         qu'il faille propager la correction du bug à la main, le bug aurait
belaran@999:         <emphasis>subsisté</emphasis> dans votre copie du fichier.</para>
belaran@999: 
belaran@999:       <para id="x_1c9">En propageant automatiquement les changements qui
belaran@999:         fixent les bugs à partir du fichier original vers les copies,
belaran@999:         Mercurial prévient ce type de problèmes. A ma connaissance, Mercurial
belaran@999:         est le <emphasis>seul</emphasis> système de gestion de révisions qui
belaran@999:         propage les changements à travers les copies comme ceci.</para>
belaran@999: 
belaran@999:       <para id="x_1ca">Une fois que votre historique des changements a un
belaran@999:         enregistrement concernant une copie et qu'une fusion postérieure a
belaran@999:         eu lieue, il n'y a d'habitude pas d'autre besoin de propager les
belaran@999:         changements du fichier originel vers le fichier copié. C'est pourquoi
belaran@999:         Mercurial ne propage les changements à travers les copies qu'à la
belaran@999:         première fusion, et pas d'avantage.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Comment faire des changements qui <emphasis>ne</emphasis>
belaran@999:       suivent <emphasis>pas</emphasis> une copie</title>
belaran@999: 
belaran@999:       <para id="x_1cb">Si pour une raison ou une autre, vous décidez que
belaran@999:         cette fonctionnalité de propager automatiquement les changements à
belaran@999:         travers les copies n'est pas pour vous, utilisez simplement la
belaran@999:         commande normale de copie de votre système (sur les systèmes de type
belaran@999:         Unix, il s'agit de <command moreinfo="none">cp</command>) pour faire une copie d'un
belaran@999:         fichier. Utilisez ensuite <command role="hg-cmd" moreinfo="none">hg add</command>
belaran@999:         pour ajouter les nouveaux fichiers à la main. Cependant, avant d'en
belaran@999:         faire ainsi, relisez <xref linkend="sec:daily:why-copy"/>, et faites
belaran@999:         un choix en connaissance de cause comme quoi cette fonctionnalité
belaran@999:         n'est pas appropriée à votre cas spécifique.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Comportement de la commande <command role="hg-cmd" moreinfo="none">hg copy</command></title>
belaran@999: 
belaran@999:       <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
belaran@999:         fichier source tel qu'il est actuellement dans le répertoire de
belaran@999:         travail. Cela signifie que si vous effectuez des modifications sur un
belaran@999:         fichier, puis faites un <command role="hg-cmd" moreinfo="none">hg copy</command> sur
belaran@999:         celui-ci sans avoir au préalable committé ces changements, la nouvelle
belaran@999:         copie contiendra aussi les modifications que vous avez fait jusqu'à
belaran@999:         ce point.	(Je trouve ce comportement quelque peu contre intuitif,
belaran@999:         c'est pourquoi j'en fais mention ici.)</para>
belaran@999:       <!-- Vérifier que je n'ai pas fait de contre sens en relisant la
belaran@999:       version anglaise, ce que je comprend ici me paraît un peu bizarre -->
belaran@999: 
belaran@999:       <para id="x_1cd">La commande <command role="hg-cmd" moreinfo="none">hg copy</command>
belaran@999:         agit comme la commande Unix <command moreinfo="none">cp</command> (vous pouvez
belaran@999:         utilisez l'alias <command role="hg-cmd" moreinfo="none">hg cp</command> si vous
belaran@999:         préférez).  Nous devons lui donner deux ou plus arguments où le
belaran@999:         dernier est considéré comme la <emphasis>destination</emphasis>, et
belaran@999:         les autres comme les <emphasis>sources</emphasis>.</para>
belaran@999: 
belaran@999:       <para id="x_685">Si vous passez à <command role="hg-cmd" moreinfo="none">hg
belaran@999:           copy</command> un seul fichier source, et que la destination
belaran@999:         n'existe pas, ceci créera un nouveau fichier avec ce nom.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.copy.simple -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir k</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy a k</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls k</userinput>
belaran@999: a
belaran@999: </screen>
belaran@999: <!-- END daily.copy.simple -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1ce">Si la destination est un répertoire, Mercurial copie
belaran@999:         les sources dans ce répertoire.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.copy.dir-dest -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir d</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy a b d</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls d</userinput>
belaran@999: a  b
belaran@999: </screen>
belaran@999: <!-- END daily.copy.dir-dest -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1cf">La copie de répertoire est récursive et préserve la
belaran@999:         structure du répertoire source.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.copy.dir-src -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy z e</userinput>
belaran@999: copying z/a/c to e/a/c
belaran@999: </screen>
belaran@999: <!-- END daily.copy.dir-src -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1d0">Si la source et la destination sont tous deux des
belaran@999:         répertoires, l'arborescence de la source est recréée dans le
belaran@999:         répertoire destination.</para>
belaran@999:     
belaran@999:       <!-- BEGIN daily.copy.dir-src-dest -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy z d</userinput>
belaran@999: copying z/a/c to d/z/a/c
belaran@999: </screen>
belaran@999: <!-- END daily.copy.dir-src-dest -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1d1">Comme avec la commande <command role="hg-cmd" moreinfo="none">hg
belaran@999:           remove</command>, si vous copiez un fichier manuellement et voulez
belaran@999:         que Mercurial sache qu'il s'agit d'une copie, utilisez simplement
belaran@999:         l'option <option role="hg-opt-copy">--after</option> avec <command role="hg-cmd" moreinfo="none">hg copy</command>.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.copy.after -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cp a n</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy --after a n</userinput>
belaran@999: </screen>
belaran@999: <!-- END daily.copy.after -->
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Renommer les fichiers</title>
belaran@999: 
belaran@999:     <para id="x_1d2">Il est plus commun d'avoir besoin de renommer un
belaran@999:       fichier que d'en faire une copie. La raison pour laquelle j'ai discuté
belaran@999:       de la commande <command role="hg-cmd" moreinfo="none">hg copy</command> avant de parler
belaran@999:       de renommage des fichiers est que Mercurial traite les renommages
belaran@999:       essentiellement comme une copie. Ainsi, savoir comment Mercurial traite
belaran@999:       les copies de fichiers vous informe sur ce que vous êtes en droit
belaran@999:       d'attendre lorsque vous renommez un fichier.</para>
belaran@999: 
belaran@999:     <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
belaran@999:       les fichiers sources, les supprime et marque ces fichiers comme étant
belaran@999:       supprimés.</para>
belaran@999: 
belaran@999:     <!-- BEGIN daily.rename.rename -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rename a b</userinput>
belaran@999: </screen>
belaran@999: <!-- END daily.rename.rename -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_1d4">La commande <command role="hg-cmd" moreinfo="none">hg status</command>
belaran@999:       montre les nouveaux fichiers comme ajoutés et les fichiers originaux
belaran@999:       comme supprimés.</para>
belaran@999: 
belaran@999:     <!-- BEGIN daily.rename.status -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: A b
belaran@999: R a
belaran@999: </screen>
belaran@999: <!-- END daily.rename.status -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_1d5">A cause du <command role="hg-cmd" moreinfo="none">hg	copy</command>,
belaran@999:       nous devons utiliser l'option <option role="hg-opt-status">-C</option>
belaran@999:       pour la commande <command role="hg-cmd" moreinfo="none">hg status</command> afin
belaran@999:       d'observer que le fichier ajouté est bien suivi par Mercurial comme
belaran@999:       étant une copie de l'original maintenant supprimé.</para>
belaran@999: 
belaran@999:     <!-- BEGIN daily.rename.status-copy -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status -C</userinput>
belaran@999: A b
belaran@999:   a
belaran@999: R a
belaran@999: </screen>
belaran@999: <!-- END daily.rename.status-copy -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_1d6">Comme avec <command role="hg-cmd" moreinfo="none">hg remove</command> et
belaran@999:       <command role="hg-cmd" moreinfo="none">hg copy</command>, vous pouvez informer
belaran@999:       Mercurial au sujet d'un renommage après coup en utilisant l'option
belaran@999:       <option role="hg-opt-rename">--after</option>. Dans le plus grand
belaran@999:       respect, le comportement de la commande <command role="hg-cmd" moreinfo="none">hg
belaran@999:         rename</command>, et les options qu'il accepte sont similaires à la
belaran@999:       commande <command role="hg-cmd" moreinfo="none">hg copy</command>.</para>
belaran@999: 
belaran@999:     <para id="x_686">Si vous êtes familier avec la ligne de commande Unix,
belaran@999:       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>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Renommer les fichiers et fusionner (merge) les changements</title>
belaran@999: 
belaran@999:       <para id="x_1d7">Puise que le "rename" de Mercurial est implanté comme un
belaran@999:         "copy-and-remove", la même propagation des changements a lieue après
belaran@999:         un "rename" qu'après un "copy" lorsque vous fusionnez (merge).</para>
belaran@999: 
belaran@999:       <para id="x_1d8">Si je modifie un fichier et que vous le renommez, si
belaran@999:         ensuite nous fusionnons nos changements respectifs, mes modifications
belaran@999:         sur le fichier sous son nom originel seront propagés vers le même
belaran@999:         fichier sous son nouveau nom. (C'est quelque chose que vous pourriez
belaran@999:         espérer voir <quote>fonctionner simplement</quote>, mais tous les
belaran@999:         systèmes de gestion de version ne le font pas.)</para>
belaran@999: 
belaran@999:       <para id="x_1d9">Tandis qu'avoir des changements qui suivent une copie
belaran@999:         est une fonctionnalité où vous hocheriez sûrement la tête en disant
belaran@999:         <quote>oui, cela pourrait être utile</quote>, il est clair que les
belaran@999:         voir suivre un renommage est définitivement important. Sans cette
belaran@999:         aptitude, il serait vraiment trop facile d'avoir des changements
belaran@999:         qui deviennent orphelins lorsque des fichiers sont renommés.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Renommages divergeants et fusion (merge)</title>
belaran@999: 
belaran@999:       <para id="x_1da">Le cas de noms divergeants a lieu lorsque deux
belaran@999:         développeurs commencent avec un fichier—appelons le
belaran@999:         <filename moreinfo="none">foo</filename>—dans leurs dépôts respectifs.</para>
belaran@999: 
belaran@999:       <!-- BEGIN rename.divergent.clone -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone orig anne</userinput>
belaran@999: updating working directory
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone orig bob</userinput>
belaran@999: updating working directory
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: </screen>
belaran@999: <!-- END rename.divergent.clone -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1db">Anne renomme le fichier en
belaran@999:         <filename moreinfo="none">bar</filename>.</para>
belaran@999: 
belaran@999:       <!-- BEGIN rename.divergent.rename.anne -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd anne</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rename foo bar</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -m 'Rename foo to bar'</userinput>
belaran@999: </screen>
belaran@999: <!-- END rename.divergent.rename.anne -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1dc">Pendant ce temps, Bob le renomme en
belaran@999:         <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>
belaran@999:     
belaran@999:       <!-- BEGIN rename.divergent.rename.bob -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../bob</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg mv foo quux</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -m 'Rename foo to quux'</userinput>
belaran@999: </screen>
belaran@999: <!-- END rename.divergent.rename.bob -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1dd">J'aime à penser qu'il s'agit d'un conflit puisque
belaran@999:         chaque développeur a exprimé différentes intentions au sujet de ce
belaran@999:         que le nom de ce fichier aurait du être.</para>
belaran@999: 
belaran@999:       <para id="x_1de">Que pensez vous qu'il devrait se produire lorsqu'ils
belaran@999:         fusionnent (merge) leurs travaux ? Le comportement actuel de
belaran@999:         Mercurial est qu'il préserve toujours les <emphasis>deux</emphasis>
belaran@999:         noms lorsqu'il fusionne (merge) des changesets qui contiennent des
belaran@999:         renommages divergeants.</para>
belaran@999: 
belaran@999:       <!-- BEGIN rename.divergent.merge -->
belaran@999: <screen format="linespecific"># See http://www.selenic.com/mercurial/bts/issue455
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../orig</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull -u ../anne</userinput>
belaran@999: pulling from ../anne
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 1 changes to 1 files
belaran@999: 1 files updated, 0 files merged, 1 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../bob</userinput>
belaran@999: pulling from ../bob
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 1 changes to 1 files (+1 heads)
belaran@999: (run 'hg heads' to see heads, 'hg merge' to merge)
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
belaran@999: warning: detected divergent renames of foo to:
belaran@999:  bar
belaran@999:  quux
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: (branch merge, don't forget to commit)
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls</userinput>
belaran@999: bar  quux
belaran@999: </screen>
belaran@999: <!-- END rename.divergent.merge -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_1df">Remarquez que bien que Mercurial vous avertisse au
belaran@999:         sujet de la divergeance des renommages, il vous laisse faire quelque
belaran@999:         chose au sujet de la divergeance après la fusion (merge).</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Renommages et fusion convergeants</title>
belaran@999: 
belaran@999:       <para id="x_1e0">Un autre type de conflit de renommage intervient
belaran@999:         lorsque deux personne choisissent de renommer différents fichiers
belaran@999:         <emphasis>source</emphasis> vers la même
belaran@999:         <emphasis>destination</emphasis>. Dans ce cas, Mercurial exécute la
belaran@999:         machinerie normale de fusion (merge) et vous guide vers une
belaran@999:         solution convenable.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Autres cas anguleux relatifs aux noms</title>
belaran@999: 
belaran@999:       <para id="x_1e1">Mercurial possède un bug de longue date dans lequel il
belaran@999:         échoue à traiter une fusion (merge) où un coté a un fichier avec un
belaran@999:         nom donné, alors que l'autre coté possède un répertoire avec le même nom.
belaran@999:         Ceci est documenté dans l'<ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue29">issue
belaran@999:           29</ulink>.</para>
belaran@999: 
belaran@999:       <!-- BEGIN issue29.go -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init issue29</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd issue29</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -Ama</userinput>
belaran@999: adding a
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b &gt; b</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -Amb</userinput>
belaran@999: adding b
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg up 0</userinput>
belaran@999: 0 files updated, 0 files merged, 1 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir b</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b &gt; b/b</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -Amc</userinput>
belaran@999: adding b/b
belaran@999: created new head
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
belaran@999: abort: Is a directory: /tmp/issue29vhrzWD/issue29/b
belaran@999: </screen>
belaran@999: <!-- END issue29.go -->
belaran@999: 
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Récupération d'erreurs</title>
belaran@999: 
belaran@999:     <para id="x_1e2">Mercurial possède certaines commandes utiles qui vont
belaran@999:       vous aider à récupérer de certaines erreurs communes.</para>
belaran@999: 
belaran@999:     <para id="x_1e3">La commande <command role="hg-cmd" moreinfo="none">hg revert</command>
belaran@999:       vous permet d'annuler les changements que vous avez faits dans votre
belaran@999:       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
belaran@999:       juste <command role="hg-cmd" moreinfo="none">hg	revert</command> avec le nom du fichier
belaran@999:       que vous avez ajouté et tandis que le fichier ne sera touché d'une
belaran@999:       quelconque manière, il ne sera plus suivi comme ajouté par Mercurial.
belaran@999:       Vous pouvez aussi utiliser la commande <command role="hg-cmd" moreinfo="none">hg
belaran@999:         revert</command> pour vous débarrasser de modifications erronés
belaran@999:       apportées à un fichier.</para>
belaran@999: 
belaran@999:     <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
belaran@999:       qui n'ont pas encore été committées. Une fois que vous avez committé un
belaran@999:       changement, si vous décidez qu'il s'agissait d'une erreur, vous pouvez
belaran@999:       toujours faire quelque chose à ce sujet, bien que vos options soient
belaran@999:       un peu plus limitées.</para>
belaran@999: 
belaran@999:     <para id="x_1e5">Pour plus d'informations au sujet de la commande
belaran@999:       <command role="hg-cmd" moreinfo="none">hg revert</command>, et des détails sur comment
belaran@999:       traiter les modifications que vous avez déjà committées, référez vous à
belaran@999:       <xref linkend="chap:undo"/>.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Traiter avec les fusions (merge) malicieuses</title>
belaran@999: 
belaran@999:     <para id="x_687">Dans des projets compliqués ou conséquents, il n'est pas
belaran@999:       rare qu'une fusion (merge) de deux changesets finisse par une migraine.
belaran@999:       Supposez qu'il y ait un gros fichier source qui ait été largement édité de
belaran@999:       chaque coté de la fusion (merge) : ceci va inévitablement résulter en
belaran@999:       conflits, dont certains peuvent prendre plusieurs essais pour s'en
belaran@999:       sortir.</para>
belaran@999: 
belaran@999:     <para id="x_688">Développons en un cas simple pour voir comment le gérer.
belaran@999:       Nous allons commencer avec un dépôt contenant un fichier, et le
belaran@999:       cloner deux fois.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch04/resolve.init -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init conflict</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd conflict</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo first &gt; myfile.txt</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -A -m first</userinput>
belaran@999: adding myfile.txt
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone conflict left</userinput>
belaran@999: updating working directory
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone conflict right</userinput>
belaran@999: updating working directory
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: </screen>
belaran@999: <!-- END ch04/resolve.init -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_689">Dans un des clones, nous allons modifier le fichier
belaran@999:       d'une façon.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch04/resolve.left -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd left</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo left &gt;&gt; myfile.txt</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -m left</userinput>
belaran@999: </screen>
belaran@999: <!-- END ch04/resolve.left -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_68a">Dans un autre, nous allons modifier le fichier
belaran@999:       différemment.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch04/resolve.right -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../right</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo right &gt;&gt; myfile.txt</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -m right</userinput>
belaran@999: </screen>
belaran@999: <!-- END ch04/resolve.right -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_68b">Ensuite, nous allons récupérer (pull) chaque ensemble de
belaran@999:       changement dans notre dépôt original.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch04/resolve.pull -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../conflict</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull -u ../left</userinput>
belaran@999: pulling from ../left
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 1 changes to 1 files
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull -u ../right</userinput>
belaran@999: pulling from ../right
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 1 changes to 1 files (+1 heads)
belaran@999: not updating, since new heads added
belaran@999: (run 'hg heads' to see heads, 'hg merge' to merge)
belaran@999: </screen>
belaran@999: <!-- END ch04/resolve.pull -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_68c">Nous nous attendons à ce que notre dépôt contienne deux
belaran@999:       "heads".</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch04/resolve.heads -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg heads</userinput>
belaran@999: changeset:   2:85f1afc84c33
belaran@999: tag:         tip
belaran@999: parent:      0:14a820f81f48
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:51 2009 +0000
belaran@999: summary:     right
belaran@999: 
belaran@999: changeset:   1:085ebbf44348
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:51 2009 +0000
belaran@999: summary:     left
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END ch04/resolve.heads -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_68d">Normalement, si nous lançons <command role="hg-cmd" moreinfo="none">hg
belaran@999:         merge</command> à ce point, il nous renverra vers une interface
belaran@999:       utilisateur qui nous permettra de résoudre manuellement les éditions
belaran@999:       conflictuelles sur le fichier <filename moreinfo="none">myfile.txt</filename>.
belaran@999:       Cependant, pour simplifier ici les choses dans la présentation, nous
belaran@999:       aimerions plutôt que la fusion (merge) échoue immédiatement. Voici une
belaran@999:       façon de le faire.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch04/resolve.export -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">export HGMERGE=false</userinput>
belaran@999: </screen>
belaran@999: <!-- END ch04/resolve.export -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_68e">Nous avons dit au processus de fusion de Mercurial
belaran@999:       d'exécuter la commande <command moreinfo="none">false</command> (qui échoue
belaran@999:       immédiatement, à la demande) s'il détecte une fusion (merge) qu'il ne
belaran@999:       peut pas arranger automatiquement.</para>
belaran@999: 
belaran@999:     <para id="x_68f">Si nous appelons maintenant <command role="hg-cmd" moreinfo="none">hg
belaran@999:         merge</command>, il devrait échouer et reporter une erreur.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch04/resolve.merge -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
belaran@999: merging myfile.txt
belaran@999: merging myfile.txt failed!
belaran@999: 0 files updated, 0 files merged, 0 files removed, 1 files unresolved
belaran@999: use 'hg resolve' to retry unresolved file merges or 'hg up --clean' to abandon
belaran@999: </screen>
belaran@999: <!-- END ch04/resolve.merge -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_690">Même si nous ne remarquons pas qu'une fusion (merge) a
belaran@999:       échoué, Mercurial nous empêchera de committer le résultat d'une fusion
belaran@999:       ratée.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch04/resolve.cifail -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Attempt to commit a failed merge'</userinput>
belaran@999: abort: unresolved merge conflicts (see hg resolve)
belaran@999: </screen>
belaran@999: <!-- END ch04/resolve.cifail -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_691">Lorsque <command role="hg-cmd" moreinfo="none">hg commit</command>
belaran@999:       échoue dans ce cas, il suggère que nous utilisons la commande peu
belaran@999:       connue <command role="hg-cmd" moreinfo="none">hg resolve</command>.  Comme d'habitude,
belaran@999:       <command role="hg-cmd" moreinfo="none">hg help resolve</command> affichera une aide
belaran@999:       sommaire.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>États de résolution des fichiers</title>
belaran@999:       <!-- TODO Vérifier traduction : File resolution states -->
belaran@999: 
belaran@999:       <para id="x_692">Lorsqu'une fusion intervient, la plupart des fichiers
belaran@999:         vont, la plupart du temps, rester sans modification. Pour chaque
belaran@999:         fichier sur lequel Mercurial doit faire quelque chose, il suit l'état
belaran@999:         de celui-ci.</para>
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999:         <listitem><para id="x_693">Un fichier
belaran@999:             <quote><emphasis>resolved</emphasis></quote> a été fusionné
belaran@999:             (merge) avec succès, que ce soit automatiquement par Mercurial ou
belaran@999:             manuellement par une intervention humaine.</para></listitem>
belaran@999:         <listitem><para id="x_694">Un fichier
belaran@999:             <quote><emphasis>unresolved</emphasis></quote> n'a pas été
belaran@999:             fusionné (merge) correctement et a besoin de plus
belaran@999:             d'attention.</para>
belaran@999:         </listitem>
belaran@999:       </itemizedlist>
belaran@999: 
belaran@999:       <para id="x_695">Si Mercurial voit un fichier
belaran@999:         <emphasis>quelconque</emphasis> dans un état
belaran@999:         <quote>unresolved</quote> après une fusion (merge), il considère que
belaran@999:         la fusion (merge) a échoué. Heureusement, nous n'avons pas à
belaran@999:         recommencer la procédure à partir du début.</para>
belaran@999: 
belaran@999:       <para id="x_696">L'option <option role="hg-opt-resolve">--list</option>
belaran@999:         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
belaran@999:         fusionné (merge).</para>
belaran@999: 
belaran@999:       <!-- BEGIN ch04/resolve.list -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg resolve -l</userinput>
belaran@999: U myfile.txt
belaran@999: </screen>
belaran@999: <!-- END ch04/resolve.list -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_697">En sortie de <command role="hg-cmd" moreinfo="none">hg
belaran@999:           resolve</command>, un fichier "resolved" est marqué avec un
belaran@999:         <literal moreinfo="none">R</literal>, alors qu'un fichier "unresolved" est marqué
belaran@999:         d'un <literal moreinfo="none">U</literal>.  S'il existe un fichier listé avec un
belaran@999:         <literal moreinfo="none">U</literal>, nous savons qu'essayer de committer le résultat
belaran@999:         de la fusion (merge) échouera.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Résoudre une fusion de fichier</title>
belaran@999: 
belaran@999:       <para id="x_698">Nous avons plusieurs options pour changer l'état d'un
belaran@999:         fichier de "unresolved" à "resolved". Le plus commun est de relancer
belaran@999:         <command role="hg-cmd" moreinfo="none">hg resolve</command>. Si nous passons les noms
belaran@999:         des fichiers individuels ou des répertoires, ceci retentera la fusion
belaran@999:         de tous les fichiers présents à cet endroit. Nous pouvons aussi
belaran@999:         passer l'option <option role="hg-opt-resolve">--all</option> ou
belaran@999:         <option role="hg-opt-resolve">-a</option> qui tentera de fusionner
belaran@999:         <emphasis>tous</emphasis> les fichiers "unresolved".</para>
belaran@999: 
belaran@999:       <para id="x_699">Mercurial nous laisse aussi modifier la résolution
belaran@999:         d'un fichier directement. Nous pouvons marquer un fichier "resolved"
belaran@999:         en utilisant l'option <option role="hg-opt-resolve">--mark</option>,
belaran@999:         ou "unresolved" en utilisant l'option <option role="hg-opt-resolve">--unmark</option>. Ceci nous autorise à
belaran@999:         nettoyer une fusion particulièrement compliquée à la main, et de
belaran@999:         garder un suivi de nos progrès avec chaque fichier pendant que nous
belaran@999:         procédons.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Des "diffs" plus utiles</title>
belaran@999: 
belaran@999:     <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
belaran@999:       la commande régulière <command moreinfo="none">diff</command>, mais ceci a quelques
belaran@999:       inconvénients.</para>
belaran@999: 
belaran@999:     <para id="x_6c8">Considérez le cas où nous utilisons <command role="hg-cmd" moreinfo="none">hg
belaran@999:         rename</command> pour renommer un fichier.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch04/diff.rename.basic -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rename a b</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
belaran@999: diff -r f5deb7868663 a
belaran@999: --- a/a	Sun Aug 16 14:04:49 2009 +0000
belaran@999: +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
belaran@999: @@ -1,1 +0,0 @@
belaran@999: -a
belaran@999: diff -r f5deb7868663 b
belaran@999: --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
belaran@999: +++ b/b	Sun Aug 16 14:04:49 2009 +0000
belaran@999: @@ -0,0 +1,1 @@
belaran@999: +a
belaran@999: </screen>
belaran@999: <!-- END ch04/diff.rename.basic -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_6c9">La sortie de <command role="hg-cmd" moreinfo="none">hg diff</command>
belaran@999:       ci-dessus cache le fait que nous avons simplement renommé un fichier.
belaran@999:       La commande <command role="hg-cmd" moreinfo="none">hg diff</command> accepte l'option
belaran@999:       <option>--git</option> ou <option>-g</option> pour utiliser un nouveau
belaran@999:       format de diff qui montre ces informations sous une forme plus
belaran@999:       expressive.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch04/diff.rename.git -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff -g</userinput>
belaran@999: diff --git a/a b/b
belaran@999: rename from a
belaran@999: rename to b
belaran@999: </screen>
belaran@999: <!-- END ch04/diff.rename.git -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_6ca">Cette option peut aussi aider avec le cas autrement
belaran@999:       confus : un fichier qui apparaît comme étant modifié en accord avec
belaran@999:       <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
belaran@999:       survenir si nous changeons les permissions d'exécution du
belaran@999:       fichier.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch04/diff.chmod -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">chmod +x a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg st</userinput>
belaran@999: M a
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
belaran@999: </screen>
belaran@999: <!-- END ch04/diff.chmod -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_6cb">La commande normale <command moreinfo="none">diff</command> ne fait pas
belaran@999:       attention aux permissions des fichiers, ce qui explique pourquoi
belaran@999:       <command role="hg-cmd" moreinfo="none">hg diff</command> n'affiche rien du tout par
belaran@999:       défaut. Si nous lui passons l'option <option>-g</option>, ceci nous
belaran@999:       informe de ce qu'il s'est vraiment passé.</para>
belaran@999: 
belaran@999:     <!-- BEGIN ch04/diff.chmod.git -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff -g</userinput>
belaran@999: diff --git a/a b/a
belaran@999: old mode 100644
belaran@999: new mode 100755
belaran@999: </screen>
belaran@999: <!-- END ch04/diff.chmod.git -->
belaran@999: 
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Quels fichiers suivre et lesquels éviter</title>
belaran@999: 
belaran@999:     <para id="x_6cc">Les systèmes de gestion de révisions sont en général
belaran@999:       meilleurs pour gérer les fichiers textes qui sont écrits par les
belaran@999:       humains, comme le code source, où les fichiers ne changent pas
belaran@999:       énormément d'une révision à l'autre. Certains systèmes de gestion de
belaran@999:       révisions centralisés peuvent aussi traiter très convenablement les
belaran@999:       fichiers binaires, tels que les images bitmap.</para>
belaran@999: 
belaran@999:     <para id="x_6cd">Par exemple, une équipe de développement de jeux va
belaran@999:       probablement gérer les deux types : ses codes source et tous ses binaires
belaran@999:       (ex. données géométriques, textures, schémas de cartes) dans un système
belaran@999:       de contrôle de révisions.</para>
belaran@999:     <!-- Vérifier la traduction de map layouts que j'ai traduit par schémas
belaran@999:     de cartes -->
belaran@999: 
belaran@999:     <para id="x_6ce">Puisqu'il est d'habitude impossible de fusionner (merge)
belaran@999:       deux modifications conflictuelles sur un fichier binaire, les systèmes
belaran@999:       de version centralisés offrent souvent un mécanisme de verrou (lock) qui
belaran@999:       permet à un utilisateur de dire <quote>Je suis la seule personne qui
belaran@999:         peut éditer ce fichier</quote>.</para>
belaran@999: 
belaran@999:     <para id="x_6cf">En comparaison avec un système centralisé, un système
belaran@999:       décentralisé de gestion de révision change certains facteurs qui
belaran@999:       guident les décisions sur quels fichiers gérer et comment.</para>
belaran@999: 
belaran@999:     <para id="x_6d0">Par exemple, un système distribué de gestion de révisions
belaran@999:       ne peut pas, par sa nature, offrir un système de véroux (lock) sur les
belaran@999:       fichiers. Il n'y a donc pas de mécanisme inclus pour empêcher deux
belaran@999:       personnes de faire des modifications conflictuelles sur un fichier
belaran@999:       binaire. Si vous avez une équipe où plusieurs personnes peuvent souvent
belaran@999:       éditer un fichier binaire, cela ne serait pas une très bonne idée
belaran@999:       d'utiliser Mercurial —ou tout autre système distribué de gestion
belaran@999:       de révisions—pour gérer ces fichiers.</para>
belaran@999: 
belaran@999:     <para id="x_6d1">Lorsque vous sauvegardez les modifications sur un
belaran@999:       fichier, Mercurial ne sauvegarde d'habitude que les différences entre
belaran@999:       la version précédente et la version actuelle d'un fichier. Pour la
belaran@999:       plupart des fichiers texte, ceci est très efficace. Cependant, certains
belaran@999:       fichiers (en particulier les fichiers binaires) sont construits d'une
belaran@999:       façon que même un petit changement sur un contenu logique résulte sur
belaran@999:       un changement de la plupart des octets du fichier. Par exemple, les
belaran@999:       fichiers compressés sont particulièrement sujets à ce comportement. Si
belaran@999:       les différences entre deux versions successives d'un fichier sont
belaran@999:       toujours très grandes, Mercurial ne sera pas capable de sauvegarder
belaran@999:       l'historique des révisions sur le fichier très efficacement. Ceci peut
belaran@999:       affecter aussi bien les besoins pour la sauvegarde locale que le temps
belaran@999:       nécessaire à cloner le dépôt.</para>
belaran@999: 
belaran@999:     <para id="x_6d2">Pour avoir une idée de comment ceci pourrait vous
belaran@999:       affecter en pratique, supposez que nous voulions que Mercurial gère des
belaran@999:       documents OpenOffice. OpenOffice sauvegarde les documents sur le disque
belaran@999:       comme des fichiers compressés zip. Même le fait d'éditer ces fichiers
belaran@999:       d'une seule lettre, changera les bits de la quasi totalité du fichier
belaran@999:       lorsque vous le sauvegarderez. Maintenant, supposez que ce fichier
belaran@999:       fasse une taille de 2Mo. Puisque la plupart du fichier change à chaque
belaran@999:       fois que vous sauvegardez, Mercurial aura à sauvegarder tous les 2Mo du
belaran@999:       fichier à chaque commit, alors que de votre point de vue, il n'y a
belaran@999:       que peu de mots qui changent à chaque fois. Un seul fichier
belaran@999:       souvent édité qui n'est pas bien traité par les hypothèses que Mercurial
belaran@999:       fait sur les sauvegardes peut facilement avoir un effet colossal sur la
belaran@999:       taille du dépôt.</para>
belaran@999: 
belaran@999:     <para id="x_6d3">Même pire, si vous et quelqu'un d'autre éditez le même
belaran@999:       document OpenOffice sur lequel vous travaillez, il n'y a pas de façon
belaran@999:       utile pour fusionner votre travail. En fait, il n'y a pas de moyen
belaran@999:       utile de montrer que les différences sont faites à partir de votre
belaran@999:       vision des modifications.</para>
belaran@999: 
belaran@999:     <para id="x_6d4">Il y a ainsi quelques recommandations claires sur les
belaran@999:       types de fichiers spécifiques avec lesquels faire très
belaran@999:       attention.</para>
belaran@999: 
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_6d5">Les fichier qui sont très gros et
belaran@999:           incompressibles, comme les images ISO de CD-ROM, sont, par
belaran@999:           construction très gros et les cloner à travers un réseau sera très
belaran@999:           long.</para></listitem>
belaran@999:      <!-- TODO : Trouver une meilleure traduction pour : ISO CD-ROM images, will by
belaran@999:      virtue of sheer size make clones over a network very slow. -->
belaran@999:       <listitem><para id="x_6d6">Les fichiers qui changent beaucoup d'une
belaran@999:           révision à l'autre peuvent être très chers à sauvegarder si vous
belaran@999:           les éditez fréquemment, de même que les conflits entre deux éditions
belaran@999:           concurrentes peuvent être difficiles à résoudre.</para>
belaran@999:       </listitem>
belaran@999:     </itemizedlist>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Sauvegardes et miroirs</title>
belaran@999: 
belaran@999:     <para id="x_6d7">Puisque Mercurial maintient une copie complète de
belaran@999:       l'historique de chaque clone, toute personne qui utilise Mercurial pour
belaran@999:       collaborer à un projet peut potentiellement agir comme une source de
belaran@999:       sauvegarde si une catastrophe survenait. Si un dépôt central devient
belaran@999:       indisponible, vous pouvez construire un remplaçant en clonant une copie
belaran@999:       du dépôt à partir d'un des contributeurs en récupérant (pull) tous les
belaran@999:       changements qui n'auraient pas été vus par les autres.</para>
belaran@999: 
belaran@999:     <para id="x_6d8">Il est simple d'utiliser Mercurial pour construire des
belaran@999:       serveurs hors site de sauvegarde et des miroirs distants. Initiez une
belaran@999:       tâche périodique (ex. via la commande <command moreinfo="none">cron</command>) sur un
belaran@999:       serveur distant pour récupérer (pull) les changements de votre dépôt
belaran@999:       distant chaque heure. Ceci sera difficile seulement dans le cas
belaran@999:       improbable où le nombre des dépôts maîtres que vous maintenez change
belaran@999:       souvent, auquel cas vous aurez besoin de faire un peu de scripting pour
belaran@999:       rafraichir la liste des dépôt à sauvegarder.</para>
belaran@999: 
belaran@999:     <para id="x_6d9">Si vous exécutez des sauvegardes traditionnelles de
belaran@999:       votre dépôt maître sur bande ou disque, et que vous voulez sauvegarder
belaran@999:       un dépôt nommé <filename moreinfo="none">myrepo</filename>, utilisez la commande
belaran@999:       <command moreinfo="none">hg clone -U myrepo myrepo.bak</command> pour créer un clone de
belaran@999:       <filename moreinfo="none">myrepo</filename> avant de commencer vos backups.
belaran@999:       L'option <option>-U</option> ne crée pas de répertoire de travail après
belaran@999:       que le clone soit accompli, puisque ceci serait superflu et ferait que
belaran@999:       la sauvegarde prenne plus de temps.</para>
belaran@999: 
belaran@999:     <para id="x_6da">Si vous voulez ensuite sauvegarder
belaran@999:       <filename moreinfo="none">myrepo.bak</filename> au lieu de <filename moreinfo="none">myrepo</filename>,
belaran@999:       vous aurez la garantie d'avoir une image (snapshot) consistante de
belaran@999:       votre dépôt sur lequel un développeur insomniaque n'enverra (push) pas de
belaran@999:       changements en milieu de sauvegarde.</para>
belaran@999:   </sect1>
belaran@999: </chapter>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "chapter")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN ch06 -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <chapter id="cha:collab">
belaran@999:   <?dbhtml filename="collaborating-with-other-people.html"?>
belaran@999:   <title>Collaborating with other people</title>
belaran@999: 
belaran@999:   <para id="x_44a">As a completely decentralised tool, Mercurial doesn't impose
belaran@999:     any policy on how people ought to work with each other.  However,
belaran@999:     if you're new to distributed revision control, it helps to have
belaran@999:     some tools and examples in mind when you're thinking about
belaran@999:     possible workflow models.</para>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Mercurial's web interface</title>
belaran@999: 
belaran@999:     <para id="x_44b">Mercurial has a powerful web interface that provides several
belaran@999:       useful capabilities.</para>
belaran@999: 
belaran@999:     <para id="x_44c">For interactive use, the web interface lets you browse a
belaran@999:       single repository or a collection of repositories.  You can view
belaran@999:       the history of a repository, examine each change (comments and
belaran@999:       diffs), and view the contents of each directory and file.  You
belaran@999:       can even get a view of history that gives a graphical view of
belaran@999:       the relationships between individual changes and merges.</para>
belaran@999: 
belaran@999:     <para id="x_44d">Also for human consumption, the web interface provides
belaran@999:       Atom and RSS feeds of the changes in a repository.  This lets you
belaran@999:       <quote>subscribe</quote> to a repository using your favorite
belaran@999:       feed reader, and be automatically notified of activity in that
belaran@999:       repository as soon as it happens.  I find this capability much
belaran@999:       more convenient than the model of subscribing to a mailing list
belaran@999:       to which notifications are sent, as it requires no additional
belaran@999:       configuration on the part of whoever is serving the
belaran@999:       repository.</para>
belaran@999: 
belaran@999:     <para id="x_44e">The web interface also lets remote users clone a repository,
belaran@999:       pull changes from it, and (when the server is configured to
belaran@999:       permit it) push changes back to it.  Mercurial's HTTP tunneling
belaran@999:       protocol aggressively compresses data, so that it works
belaran@999:       efficiently even over low-bandwidth network connections.</para>
belaran@999: 
belaran@999:     <para id="x_44f">The easiest way to get started with the web interface is to
belaran@999:       use your web browser to visit an existing repository, such as
belaran@999:       the master Mercurial repository at <ulink url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para>
belaran@999: 
belaran@999:     <para id="x_450">If you're interested in providing a web interface
belaran@999:       to your own repositories, there are several good ways to do
belaran@999:       this.</para>
belaran@999: 
belaran@999:     <para id="x_69d">The easiest and fastest way to get started in an informal
belaran@999:       environment is to use the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	serve</command> command, which is best suited to short-term
belaran@999:       <quote>lightweight</quote> serving.  See <xref linkend="sec:collab:serve"/> below for details of how to use
belaran@999:       this command.</para>
belaran@999: 
belaran@999:     <para id="x_69e">For longer-lived repositories that you'd like to
belaran@999:       have permanently available, there are several public hosting
belaran@999:       services available.  Some are free to open source projects,
belaran@999:       while others offer paid commercial hosting.  An up-to-date list
belaran@999:       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>
belaran@999: 
belaran@999:     <para id="x_6a0">If you would prefer to host your own repositories, Mercurial
belaran@999:       has built-in support for several popular hosting technologies,
belaran@999:       most notably CGI (Common Gateway Interface), and WSGI (Web
belaran@999:       Services Gateway Interface).  See <xref linkend="sec:collab:cgi"/> for details of CGI and WSGI
belaran@999:       configuration.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Collaboration models</title>
belaran@999: 
belaran@999:     <para id="x_451">With a suitably flexible tool, making decisions about
belaran@999:       workflow is much more of a social engineering challenge than a
belaran@999:       technical one. Mercurial imposes few limitations on how you can
belaran@999:       structure the flow of work in a project, so it's up to you and
belaran@999:       your group to set up and live with a model that matches your own
belaran@999:       particular needs.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Factors to keep in mind</title>
belaran@999: 
belaran@999:       <para id="x_452">The most important aspect of any model that you must keep
belaran@999: 	in mind is how well it matches the needs and capabilities of
belaran@999: 	the people who will be using it.  This might seem
belaran@999: 	self-evident; even so, you still can't afford to forget it for
belaran@999: 	a moment.</para>
belaran@999: 
belaran@999:       <para id="x_453">I once put together a workflow model that seemed to make
belaran@999: 	perfect sense to me, but that caused a considerable amount of
belaran@999: 	consternation and strife within my development team.  In spite
belaran@999: 	of my attempts to explain why we needed a complex set of
belaran@999: 	branches, and how changes ought to flow between them, a few
belaran@999: 	team members revolted.  Even though they were smart people,
belaran@999: 	they didn't want to pay attention to the constraints we were
belaran@999: 	operating under, or face the consequences of those constraints
belaran@999: 	in the details of the model that I was advocating.</para>
belaran@999: 
belaran@999:       <para id="x_454">Don't sweep foreseeable social or technical problems under
belaran@999: 	the rug. Whatever scheme you put into effect, you should plan
belaran@999: 	for mistakes and problem scenarios.  Consider adding automated
belaran@999: 	machinery to prevent, or quickly recover from, trouble that
belaran@999: 	you can anticipate.  As an example, if you intend to have a
belaran@999: 	branch with not-for-release changes in it, you'd do well to
belaran@999: 	think early about the possibility that someone might
belaran@999: 	accidentally merge those changes into a release branch.  You
belaran@999: 	could avoid this particular problem by writing a hook that
belaran@999: 	prevents changes from being merged from an inappropriate
belaran@999: 	branch.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Informal anarchy</title>
belaran@999: 
belaran@999:       <para id="x_455">I wouldn't suggest an <quote>anything goes</quote>
belaran@999: 	approach as something sustainable, but it's a model that's
belaran@999: 	easy to grasp, and it works perfectly well in a few unusual
belaran@999: 	situations.</para>
belaran@999: 
belaran@999:       <para id="x_456">As one example, many projects have a loose-knit group of
belaran@999: 	collaborators who rarely physically meet each other.  Some
belaran@999: 	groups like to overcome the isolation of working at a distance
belaran@999: 	by organizing occasional <quote>sprints</quote>.  In a sprint,
belaran@999: 	a number of people get together in a single location (a
belaran@999: 	company's conference room, a hotel meeting room, that kind of
belaran@999: 	place) and spend several days more or less locked in there,
belaran@999: 	hacking intensely on a handful of projects.</para>
belaran@999: 
belaran@999:       <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg serve</command> command, since
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg serve</command> does not require any
belaran@999: 	fancy server infrastructure.  You can get started with
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg serve</command> in moments, by
belaran@999: 	reading <xref linkend="sec:collab:serve"/> below.  Then simply
belaran@999: 	tell the person next to you that you're running a server, send
belaran@999: 	the URL to them in an instant message, and you immediately
belaran@999: 	have a quick-turnaround way to work together.  They can type
belaran@999: 	your URL into their web browser and quickly review your
belaran@999: 	changes; or they can pull a bugfix from you and verify it; or
belaran@999: 	they can clone a branch containing a new feature and try it
belaran@999: 	out.</para>
belaran@999: 
belaran@999:       <para id="x_458">The charm, and the problem, with doing things
belaran@999: 	in an ad hoc fashion like this is that only people who know
belaran@999: 	about your changes, and where they are, can see them.  Such an
belaran@999: 	informal approach simply doesn't scale beyond a handful
belaran@999: 	people, because each individual needs to know about
belaran@999: 	<emphasis>n</emphasis> different repositories to pull
belaran@999: 	from.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>A single central repository</title>
belaran@999: 
belaran@999:       <para id="x_459">For smaller projects migrating from a centralised revision
belaran@999: 	control tool, perhaps the easiest way to get started is to
belaran@999: 	have changes flow through a single shared central repository.
belaran@999: 	This is also the most common <quote>building block</quote> for
belaran@999: 	more ambitious workflow schemes.</para>
belaran@999: 
belaran@999:       <para id="x_45a">Contributors start by cloning a copy of this repository.
belaran@999: 	They can pull changes from it whenever they need to, and some
belaran@999: 	(perhaps all) developers have permission to push a change back
belaran@999: 	when they're ready for other people to see it.</para>
belaran@999: 
belaran@999:       <para id="x_45b">Under this model, it can still often make sense for people
belaran@999: 	to pull changes directly from each other, without going
belaran@999: 	through the central repository.  Consider a case in which I
belaran@999: 	have a tentative bug fix, but I am worried that if I were to
belaran@999: 	publish it to the central repository, it might subsequently
belaran@999: 	break everyone else's trees as they pull it.  To reduce the
belaran@999: 	potential for damage, I can ask you to clone my repository
belaran@999: 	into a temporary repository of your own and test it.  This
belaran@999: 	lets us put off publishing the potentially unsafe change until
belaran@999: 	it has had a little testing.</para>
belaran@999: 
belaran@999:       <para id="x_45c">If a team is hosting its own repository in this
belaran@999: 	kind of scenario, people will usually use the
belaran@999: 	<command moreinfo="none">ssh</command> protocol to securely push changes to
belaran@999: 	the central repository, as documented in <xref linkend="sec:collab:ssh"/>.  It's also usual to publish a
belaran@999: 	read-only copy of the repository over HTTP, as in
belaran@999: 	<xref linkend="sec:collab:cgi"/>. Publishing over HTTP
belaran@999: 	satisfies the needs of people who don't have push access, and
belaran@999: 	those who want to use web browsers to browse the repository's
belaran@999: 	history.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>A hosted central repository</title>
belaran@999: 
belaran@999:       <para id="x_6a1">A wonderful thing about public hosting services like
belaran@999: 	<ulink url="http://bitbucket.org/">Bitbucket</ulink> is that
belaran@999: 	not only do they handle the fiddly server configuration
belaran@999: 	details, such as user accounts, authentication, and secure
belaran@999: 	wire protocols, they provide additional infrastructure to make
belaran@999: 	this model work well.</para>
belaran@999: 
belaran@999:       <para id="x_6a2">For instance, a well-engineered hosting service will let
belaran@999: 	people clone their own copies of a repository with a single
belaran@999: 	click.  This lets people work in separate spaces and share
belaran@999: 	their changes when they're ready.</para>
belaran@999: 
belaran@999:       <para id="x_6a3">In addition, a good hosting service will let people
belaran@999: 	communicate with each other, for instance to say <quote>there
belaran@999: 	  are changes ready for you to review in this
belaran@999: 	  tree</quote>.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Working with multiple branches</title>
belaran@999: 
belaran@999:       <para id="x_45d">Projects of any significant size naturally tend to make
belaran@999: 	progress on several fronts simultaneously.  In the case of
belaran@999: 	software, it's common for a project to go through periodic
belaran@999: 	official releases.  A release might then go into
belaran@999: 	<quote>maintenance mode</quote> for a while after its first
belaran@999: 	publication; maintenance releases tend to contain only bug
belaran@999: 	fixes, not new features.  In parallel with these maintenance
belaran@999: 	releases, one or more future releases may be under
belaran@999: 	development.  People normally use the word
belaran@999: 	<quote>branch</quote> to refer to one of these many slightly
belaran@999: 	different directions in which development is
belaran@999: 	proceeding.</para>
belaran@999: 
belaran@999:       <para id="x_45e">Mercurial is particularly well suited to managing a number
belaran@999: 	of simultaneous, but not identical, branches.  Each
belaran@999: 	<quote>development direction</quote> can live in its own
belaran@999: 	central repository, and you can merge changes from one to
belaran@999: 	another as the need arises.  Because repositories are
belaran@999: 	independent of each other, unstable changes in a development
belaran@999: 	branch will never affect a stable branch unless someone
belaran@999: 	explicitly merges those changes into the stable branch.</para>
belaran@999: 
belaran@999:       <para id="x_45f">Here's an example of how this can work in practice.  Let's
belaran@999: 	say you have one <quote>main branch</quote> on a central
belaran@999: 	server.</para>
belaran@999: 
belaran@999:       <!-- BEGIN branching.init -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init main</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd main</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'This is a boring feature.' &gt; myfile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'We have reached an important milestone!'</userinput>
belaran@999: adding myfile
belaran@999: </screen>
belaran@999: <!-- END branching.init -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_460">People clone it, make changes locally, test them, and push
belaran@999: 	them back.</para>
belaran@999: 
belaran@999:       <para id="x_461">Once the main branch reaches a release milestone, you can
belaran@999: 	use the <command role="hg-cmd" moreinfo="none">hg tag</command> command to
belaran@999: 	give a permanent name to the milestone revision.</para>
belaran@999: 
belaran@999: 	<!-- BEGIN branching.tag -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag v1.0</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
belaran@999: changeset:   1:5e447fdaf941
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:47 2009 +0000
belaran@999: summary:     Added tag v1.0 for changeset 6412b791fd06
belaran@999: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tags</userinput>
belaran@999: tip                                1:5e447fdaf941
belaran@999: v1.0                               0:6412b791fd06
belaran@999: </screen>
belaran@999: <!-- END branching.tag -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_462">Let's say some ongoing
belaran@999: 	development occurs on the main branch.</para>
belaran@999: 
belaran@999:       <!-- BEGIN branching.main -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../main</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'This is exciting and new!' &gt;&gt; myfile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Add a new feature'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
belaran@999: This is a boring feature.
belaran@999: This is exciting and new!
belaran@999: </screen>
belaran@999: <!-- END branching.main -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_463">Using the tag that was recorded at the milestone, people
belaran@999: 	who clone that repository at any time in the future can use
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg update</command> to get a copy of
belaran@999: 	the working directory exactly as it was when that tagged
belaran@999: 	revision was committed.</para>
belaran@999: 
belaran@999:       <!-- BEGIN branching.update -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone -U main main-old</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd main-old</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update v1.0</userinput>
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
belaran@999: This is a boring feature.
belaran@999: </screen>
belaran@999: <!-- END branching.update -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_464">In addition, immediately after the main branch is tagged,
belaran@999: 	we can then clone the main branch on the server to a new
belaran@999: 	<quote>stable</quote> branch, also on the server.</para>
belaran@999: 
belaran@999:       <!-- BEGIN branching.clone -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone -rv1.0 main stable</userinput>
belaran@999: requesting all changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 1 changes to 1 files
belaran@999: updating working directory
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: </screen>
belaran@999: <!-- END branching.clone -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_465">If we need to make a change to the stable
belaran@999: 	branch, we can then clone <emphasis>that</emphasis>
belaran@999: 	repository, make our changes, commit, and push our changes
belaran@999: 	back there.</para>
belaran@999: 
belaran@999:       <!-- BEGIN branching.stable -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone stable stable-fix</userinput>
belaran@999: updating working directory
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd stable-fix</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'This is a fix to a boring feature.' &gt; myfile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Fix a bug'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push</userinput>
belaran@999: pushing to /tmp/branchingPsTziR/stable
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 1 changes to 1 files
belaran@999: </screen>
belaran@999: <!-- END branching.stable -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_466">Because Mercurial repositories are independent, and
belaran@999: 	Mercurial doesn't move changes around automatically, the
belaran@999: 	stable and main branches are <emphasis>isolated</emphasis>
belaran@999: 	from each other.  The changes that we made on the main branch
belaran@999: 	don't <quote>leak</quote> to the stable branch, and vice
belaran@999: 	versa.</para>
belaran@999: 
belaran@999:       <para id="x_467">We'll often want all of our bugfixes on the stable
belaran@999: 	branch to show up on the main branch, too.  Rather than
belaran@999: 	rewrite a bugfix on the main branch, we can simply pull and
belaran@999: 	merge changes from the stable to the main branch, and
belaran@999: 	Mercurial will bring those bugfixes in for us.</para>
belaran@999: 
belaran@999:       <!-- BEGIN branching.merge -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../main</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../stable</userinput>
belaran@999: pulling from ../stable
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 1 changes to 1 files (+1 heads)
belaran@999: (run 'hg heads' to see heads, 'hg merge' to merge)
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
belaran@999: merging myfile
belaran@999: 0 files updated, 1 files merged, 0 files removed, 0 files unresolved
belaran@999: (branch merge, don't forget to commit)
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Bring in bugfix from stable branch'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
belaran@999: This is a fix to a boring feature.
belaran@999: This is exciting and new!
belaran@999: </screen>
belaran@999: <!-- END branching.merge -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_468">The main branch will still contain changes that
belaran@999: 	are not on the stable branch, but it will also contain all of
belaran@999: 	the bugfixes from the stable branch.  The stable branch
belaran@999: 	remains unaffected by these changes, since changes are only
belaran@999: 	flowing from the stable to the main branch, and not the other
belaran@999: 	way.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Feature branches</title>
belaran@999: 
belaran@999:       <para id="x_469">For larger projects, an effective way to manage change is
belaran@999: 	to break up a team into smaller groups.  Each group has a
belaran@999: 	shared branch of its own, cloned from a single
belaran@999: 	<quote>master</quote> branch used by the entire project.
belaran@999: 	People working on an individual branch are typically quite
belaran@999: 	isolated from developments on other branches.</para>
belaran@999: 
belaran@999:       <figure id="fig:collab:feature-branches" float="0">
belaran@999: 	<title>Feature branches</title>
belaran@999: 	<mediaobject>
belaran@999: 	  <imageobject><imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject>
belaran@999: 	  <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	</mediaobject>
belaran@999:       </figure>
belaran@999: 
belaran@999:       <para id="x_46b">When a particular feature is deemed to be in suitable
belaran@999: 	shape, someone on that feature team pulls and merges from the
belaran@999: 	master branch into the feature branch, then pushes back up to
belaran@999: 	the master branch.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>The release train</title>
belaran@999: 
belaran@999:       <para id="x_46c">Some projects are organized on a <quote>train</quote>
belaran@999: 	basis: a release is scheduled to happen every few months, and
belaran@999: 	whatever features are ready when the <quote>train</quote> is
belaran@999: 	ready to leave are allowed in.</para>
belaran@999: 
belaran@999:       <para id="x_46d">This model resembles working with feature branches.  The
belaran@999: 	difference is that when a feature branch misses a train,
belaran@999: 	someone on the feature team pulls and merges the changes that
belaran@999: 	went out on that train release into the feature branch, and
belaran@999: 	the team continues its work on top of that release so that
belaran@999: 	their feature can make the next release.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>The Linux kernel model</title>
belaran@999: 
belaran@999:       <para id="x_46e">The development of the Linux kernel has a shallow
belaran@999: 	hierarchical structure, surrounded by a cloud of apparent
belaran@999: 	chaos.  Because most Linux developers use
belaran@999: 	<command moreinfo="none">git</command>, a distributed revision control tool
belaran@999: 	with capabilities similar to Mercurial, it's useful to
belaran@999: 	describe the way work flows in that environment; if you like
belaran@999: 	the ideas, the approach translates well across tools.</para>
belaran@999: 
belaran@999:       <para id="x_46f">At the center of the community sits Linus Torvalds, the
belaran@999: 	creator of Linux.  He publishes a single source repository
belaran@999: 	that is considered the <quote>authoritative</quote> current
belaran@999: 	tree by the entire developer community. Anyone can clone
belaran@999: 	Linus's tree, but he is very choosy about whose trees he pulls
belaran@999: 	from.</para>
belaran@999: 
belaran@999:       <para id="x_470">Linus has a number of <quote>trusted lieutenants</quote>.
belaran@999: 	As a general rule, he pulls whatever changes they publish, in
belaran@999: 	most cases without even reviewing those changes.  Some of
belaran@999: 	those lieutenants are generally agreed to be
belaran@999: 	<quote>maintainers</quote>, responsible for specific
belaran@999: 	subsystems within the kernel.  If a random kernel hacker wants
belaran@999: 	to make a change to a subsystem that they want to end up in
belaran@999: 	Linus's tree, they must find out who the subsystem's
belaran@999: 	maintainer is, and ask that maintainer to take their change.
belaran@999: 	If the maintainer reviews their changes and agrees to take
belaran@999: 	them, they'll pass them along to Linus in due course.</para>
belaran@999: 
belaran@999:       <para id="x_471">Individual lieutenants have their own approaches to
belaran@999: 	reviewing, accepting, and publishing changes; and for deciding
belaran@999: 	when to feed them to Linus.  In addition, there are several
belaran@999: 	well known branches that people use for different purposes.
belaran@999: 	For example, a few people maintain <quote>stable</quote>
belaran@999: 	repositories of older versions of the kernel, to which they
belaran@999: 	apply critical fixes as needed.  Some maintainers publish
belaran@999: 	multiple trees: one for experimental changes; one for changes
belaran@999: 	that they are about to feed upstream; and so on.  Others just
belaran@999: 	publish a single tree.</para>
belaran@999: 
belaran@999:       <para id="x_472">This model has two notable features.  The first is that
belaran@999: 	it's <quote>pull only</quote>.  You have to ask, convince, or
belaran@999: 	beg another developer to take a change from you, because there
belaran@999: 	are almost no trees to which more than one person can push,
belaran@999: 	and there's no way to push changes into a tree that someone
belaran@999: 	else controls.</para>
belaran@999: 
belaran@999:       <para id="x_473">The second is that it's based on reputation and acclaim.
belaran@999: 	If you're an unknown, Linus will probably ignore changes from
belaran@999: 	you without even responding.  But a subsystem maintainer will
belaran@999: 	probably review them, and will likely take them if they pass
belaran@999: 	their criteria for suitability. The more <quote>good</quote>
belaran@999: 	changes you contribute to a maintainer, the more likely they
belaran@999: 	are to trust your judgment and accept your changes.  If you're
belaran@999: 	well-known and maintain a long-lived branch for something
belaran@999: 	Linus hasn't yet accepted, people with similar interests may
belaran@999: 	pull your changes regularly to keep up with your work.</para>
belaran@999: 
belaran@999:       <para id="x_474">Reputation and acclaim don't necessarily cross subsystem
belaran@999: 	or <quote>people</quote> boundaries.  If you're a respected
belaran@999: 	but specialised storage hacker, and you try to fix a
belaran@999: 	networking bug, that change will receive a level of scrutiny
belaran@999: 	from a network maintainer comparable to a change from a
belaran@999: 	complete stranger.</para>
belaran@999: 
belaran@999:       <para id="x_475">To people who come from more orderly project backgrounds,
belaran@999: 	the comparatively chaotic Linux kernel development process
belaran@999: 	often seems completely insane.  It's subject to the whims of
belaran@999: 	individuals; people make sweeping changes whenever they deem
belaran@999: 	it appropriate; and the pace of development is astounding.
belaran@999: 	And yet Linux is a highly successful, well-regarded piece of
belaran@999: 	software.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Pull-only versus shared-push collaboration</title>
belaran@999: 
belaran@999:       <para id="x_476">A perpetual source of heat in the open source community is
belaran@999: 	whether a development model in which people only ever pull
belaran@999: 	changes from others is <quote>better than</quote> one in which
belaran@999: 	multiple people can push changes to a shared
belaran@999: 	repository.</para>
belaran@999: 
belaran@999:       <para id="x_477">Typically, the backers of the shared-push model use tools
belaran@999: 	that actively enforce this approach.  If you're using a
belaran@999: 	centralised revision control tool such as Subversion, there's
belaran@999: 	no way to make a choice over which model you'll use: the tool
belaran@999: 	gives you shared-push, and if you want to do anything else,
belaran@999: 	you'll have to roll your own approach on top (such as applying
belaran@999: 	a patch by hand).</para>
belaran@999: 
belaran@999:       <para id="x_478">A good distributed revision control tool will
belaran@999: 	support both models.  You and your collaborators can then
belaran@999: 	structure how you work together based on your own needs and
belaran@999: 	preferences, not on what contortions your tools force you
belaran@999: 	into.</para>
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Where collaboration meets branch management</title>
belaran@999: 
belaran@999:       <para id="x_479">Once you and your team set up some shared
belaran@999: 	repositories and start propagating changes back and forth
belaran@999: 	between local and shared repos, you begin to face a related,
belaran@999: 	but slightly different challenge: that of managing the
belaran@999: 	multiple directions in which your team may be moving at once.
belaran@999: 	Even though this subject is intimately related to how your
belaran@999: 	team collaborates, it's dense enough to merit treatment of its
belaran@999: 	own, in <xref linkend="chap:branch"/>.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>The technical side of sharing</title>
belaran@999: 
belaran@999:     <para id="x_47a">The remainder of this chapter is devoted to the question of
belaran@999:       sharing changes with your collaborators.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="sec:collab:serve">
belaran@999:     <title>Informal sharing with <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	serve</command></title>
belaran@999: 
belaran@999:     <para id="x_47b">Mercurial's <command role="hg-cmd" moreinfo="none">hg serve</command>
belaran@999:       command is wonderfully suited to small, tight-knit, and
belaran@999:       fast-paced group environments.  It also provides a great way to
belaran@999:       get a feel for using Mercurial commands over a network.</para>
belaran@999: 
belaran@999:     <para id="x_47c">Run <command role="hg-cmd" moreinfo="none">hg serve</command> inside a
belaran@999:       repository, and in under a second it will bring up a specialised
belaran@999:       HTTP server; this will accept connections from any client, and
belaran@999:       serve up data for that repository until you terminate it.
belaran@999:       Anyone who knows the URL of the server you just started, and can
belaran@999:       talk to your computer over the network, can then use a web
belaran@999:       browser or Mercurial to read data from that repository.  A URL
belaran@999:       for a <command role="hg-cmd" moreinfo="none">hg serve</command> instance running
belaran@999:       on a laptop is likely to look something like
belaran@999:       <literal moreinfo="none">http://my-laptop.local:8000/</literal>.</para>
belaran@999: 
belaran@999:     <para id="x_47d">The <command role="hg-cmd" moreinfo="none">hg serve</command> command is
belaran@999:       <emphasis>not</emphasis> a general-purpose web server. It can do
belaran@999:       only two things:</para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_47e">Allow people to browse the history of the
belaran@999: 	  repository it's serving, from their normal web
belaran@999: 	  browsers.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people
belaran@999: 	  can <command role="hg-cmd" moreinfo="none">hg clone</command> or <command role="hg-cmd" moreinfo="none">hg pull</command> changes from that
belaran@999: 	  repository.</para>
belaran@999:       </listitem></itemizedlist>
belaran@999:     <para id="x_480">In particular, <command role="hg-cmd" moreinfo="none">hg serve</command>
belaran@999:       won't allow remote users to <emphasis>modify</emphasis> your
belaran@999:       repository.  It's intended for read-only use.</para>
belaran@999: 
belaran@999:     <para id="x_481">If you're getting started with Mercurial, there's nothing to
belaran@999:       prevent you from using <command role="hg-cmd" moreinfo="none">hg serve</command>
belaran@999:       to serve up a repository on your own computer, then use commands
belaran@999:       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
belaran@999:       server as if the repository was hosted remotely. This can help
belaran@999:       you to quickly get acquainted with using commands on
belaran@999:       network-hosted repositories.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>A few things to keep in mind</title>
belaran@999: 
belaran@999:       <para id="x_482">Because it provides unauthenticated read access to all
belaran@999: 	clients, you should only use <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  serve</command> in an environment where you either don't
belaran@999: 	care, or have complete control over, who can access your
belaran@999: 	network and pull data from your repository.</para>
belaran@999: 
belaran@999:       <para id="x_483">The <command role="hg-cmd" moreinfo="none">hg serve</command> command
belaran@999: 	knows nothing about any firewall software you might have
belaran@999: 	installed on your system or network.  It cannot detect or
belaran@999: 	control your firewall software.  If other people are unable to
belaran@999: 	talk to a running <command role="hg-cmd" moreinfo="none">hg serve</command>
belaran@999: 	instance, the second thing you should do
belaran@999: 	(<emphasis>after</emphasis> you make sure that they're using
belaran@999: 	the correct URL) is check your firewall configuration.</para>
belaran@999: 
belaran@999:       <para id="x_484">By default, <command role="hg-cmd" moreinfo="none">hg serve</command>
belaran@999: 	listens for incoming connections on port 8000.  If another
belaran@999: 	process is already listening on the port you want to use, you
belaran@999: 	can specify a different port to listen on using the <option role="hg-opt-serve">-p</option> option.</para>
belaran@999: 
belaran@999:       <para id="x_485">Normally, when <command role="hg-cmd" moreinfo="none">hg serve</command>
belaran@999: 	starts, it prints no output, which can be a bit unnerving.  If
belaran@999: 	you'd like to confirm that it is indeed running correctly, and
belaran@999: 	find out what URL you should send to your collaborators, start
belaran@999: 	it with the <option role="hg-opt-global">-v</option>
belaran@999: 	option.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="sec:collab:ssh">
belaran@999:     <title>Using the Secure Shell (ssh) protocol</title>
belaran@999: 
belaran@999:     <para id="x_486">You can pull and push changes securely over a network
belaran@999:       connection using the Secure Shell (<literal moreinfo="none">ssh</literal>)
belaran@999:       protocol.  To use this successfully, you may have to do a little
belaran@999:       bit of configuration on the client or server sides.</para>
belaran@999: 
belaran@999:     <para id="x_487">If you're not familiar with ssh, it's the name of
belaran@999:       both a command and a network protocol that let you securely
belaran@999:       communicate with another computer.  To use it with Mercurial,
belaran@999:       you'll be setting up one or more user accounts on a server so
belaran@999:       that remote users can log in and execute commands.</para>
belaran@999: 
belaran@999:     <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll
belaran@999:       probably find some of the material that follows to be elementary
belaran@999:       in nature.)</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>How to read and write ssh URLs</title>
belaran@999: 
belaran@999:       <para id="x_489">An ssh URL tends to look like this:</para>
belaran@999:       <programlisting format="linespecific">ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting>
belaran@999:       <orderedlist inheritnum="ignore" continuation="restarts">
belaran@999: 	<listitem><para id="x_48a">The <quote><literal moreinfo="none">ssh://</literal></quote>
belaran@999: 	    part tells Mercurial to use the ssh protocol.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_48b">The <quote><literal moreinfo="none">bos@</literal></quote>
belaran@999: 	    component indicates what username to log into the server
belaran@999: 	    as.  You can leave this out if the remote username is the
belaran@999: 	    same as your local username.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_48c">The
belaran@999: 	    <quote><literal moreinfo="none">hg.serpentine.com</literal></quote> gives
belaran@999: 	    the hostname of the server to log into.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_48d">The <quote>:22</quote> identifies the port
belaran@999: 	    number to connect to the server on.  The default port is
belaran@999: 	    22, so you only need to specify a colon and port number if
belaran@999: 	    you're <emphasis>not</emphasis> using port 22.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_48e">The remainder of the URL is the local path to
belaran@999: 	    the repository on the server.</para>
belaran@999: 	</listitem></orderedlist>
belaran@999: 
belaran@999:       <para id="x_48f">There's plenty of scope for confusion with the path
belaran@999: 	component of ssh URLs, as there is no standard way for tools
belaran@999: 	to interpret it.  Some programs behave differently than others
belaran@999: 	when dealing with these paths. This isn't an ideal situation,
belaran@999: 	but it's unlikely to change.  Please read the following
belaran@999: 	paragraphs carefully.</para>
belaran@999: 
belaran@999:       <para id="x_490">Mercurial treats the path to a repository on the server as
belaran@999: 	relative to the remote user's home directory.  For example, if
belaran@999: 	user <literal moreinfo="none">foo</literal> on the server has a home directory
belaran@999: 	of <filename class="directory" moreinfo="none">/home/foo</filename>, then an
belaran@999: 	ssh URL that contains a path component of <filename class="directory" moreinfo="none">bar</filename> <emphasis>really</emphasis>
belaran@999: 	refers to the directory <filename class="directory" moreinfo="none">/home/foo/bar</filename>.</para>
belaran@999: 
belaran@999:       <para id="x_491">If you want to specify a path relative to another user's
belaran@999: 	home directory, you can use a path that starts with a tilde
belaran@999: 	character followed by the user's name (let's call them
belaran@999: 	<literal moreinfo="none">otheruser</literal>), like this.</para>
belaran@999:       <programlisting format="linespecific">ssh://server/~otheruser/hg/repo</programlisting>
belaran@999: 
belaran@999:       <para id="x_492">And if you really want to specify an
belaran@999: 	<emphasis>absolute</emphasis> path on the server, begin the
belaran@999: 	path component with two slashes, as in this example.</para>
belaran@999:       <programlisting format="linespecific">ssh://server//absolute/path</programlisting>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Finding an ssh client for your system</title>
belaran@999: 
belaran@999:       <para id="x_493">Almost every Unix-like system comes with OpenSSH
belaran@999: 	preinstalled.  If you're using such a system, run
belaran@999: 	<literal moreinfo="none">which ssh</literal> to find out if the
belaran@999: 	<command moreinfo="none">ssh</command> command is installed (it's usually in
belaran@999: 	<filename class="directory" moreinfo="none">/usr/bin</filename>).  In the
belaran@999: 	unlikely event that it isn't present, take a look at your
belaran@999: 	system documentation to figure out how to install it.</para>
belaran@999: 
belaran@999:       <para id="x_494">On Windows, the TortoiseHg package is bundled
belaran@999: 	with a version of Simon Tatham's excellent
belaran@999: 	<command moreinfo="none">plink</command> command, and you should not need to
belaran@999: 	do any further configuration.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Generating a key pair</title>
belaran@999: 
belaran@999:       <para id="x_499">To avoid the need to repetitively type a
belaran@999: 	password every time you need to use your ssh client, I
belaran@999: 	recommend generating a key pair.</para>
belaran@999: 
belaran@999:       <tip>
belaran@999: 	<title>Key pairs are not mandatory</title>
belaran@999: 
belaran@999: 	<para id="x_6a4">Mercurial knows nothing about ssh authentication or key
belaran@999: 	  pairs.  You can, if you like, safely ignore this section and
belaran@999: 	  the one that follows until you grow tired of repeatedly
belaran@999: 	  typing ssh passwords.</para>
belaran@999:       </tip>
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999: 	<listitem>
belaran@999: 	  <para id="x_6a5">On a Unix-like system, the
belaran@999: 	    <command moreinfo="none">ssh-keygen</command> command will do the
belaran@999: 	    trick.</para>
belaran@999: 	  <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need
belaran@999: 	    to download a command named <command moreinfo="none">puttygen</command>
belaran@999: 	    from <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the 
belaran@999: 	      PuTTY web site</ulink> to generate a key pair.  See
belaran@999: 	    <ulink url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the 
belaran@999: 	      <command moreinfo="none">puttygen</command> documentation</ulink> for
belaran@999: 	    details of how use the command.</para>
belaran@999: 	</listitem>
belaran@999:       </itemizedlist>
belaran@999: 
belaran@999:       <para id="x_49a">When you generate a key pair, it's usually
belaran@999: 	<emphasis>highly</emphasis> advisable to protect it with a
belaran@999: 	passphrase.  (The only time that you might not want to do this
belaran@999: 	is when you're using the ssh protocol for automated tasks on a
belaran@999: 	secure network.)</para>
belaran@999: 
belaran@999:       <para id="x_49b">Simply generating a key pair isn't enough, however.
belaran@999: 	You'll need to add the public key to the set of authorised
belaran@999: 	keys for whatever user you're logging in remotely as.  For
belaran@999: 	servers using OpenSSH (the vast majority), this will mean
belaran@999: 	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>
belaran@999: 	directory.</para>
belaran@999: 
belaran@999:       <para id="x_49c">On a Unix-like system, your public key will have a
belaran@999: 	<filename moreinfo="none">.pub</filename> extension.  If you're using
belaran@999: 	<command moreinfo="none">puttygen</command> on Windows, you can save the
belaran@999: 	public key to a file of your choosing, or paste it from the
belaran@999: 	window it's displayed in straight into the <filename role="special" moreinfo="none">authorized_keys</filename> file.</para>
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Using an authentication agent</title>
belaran@999: 
belaran@999:       <para id="x_49d">An authentication agent is a daemon that stores
belaran@999: 	passphrases in memory (so it will forget passphrases if you
belaran@999: 	log out and log back in again). An ssh client will notice if
belaran@999: 	it's running, and query it for a passphrase.  If there's no
belaran@999: 	authentication agent running, or the agent doesn't store the
belaran@999: 	necessary passphrase, you'll have to type your passphrase
belaran@999: 	every time Mercurial tries to communicate with a server on
belaran@999: 	your behalf (e.g. whenever you pull or push changes).</para>
belaran@999: 
belaran@999:       <para id="x_49e">The downside of storing passphrases in an agent is that
belaran@999: 	it's possible for a well-prepared attacker to recover the
belaran@999: 	plain text of your passphrases, in some cases even if your
belaran@999: 	system has been power-cycled. You should make your own
belaran@999: 	judgment as to whether this is an acceptable risk.  It
belaran@999: 	certainly saves a lot of repeated typing.</para>
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999: 	<listitem>
belaran@999: 	  <para id="x_49f">On Unix-like systems, the agent is called
belaran@999: 	    <command moreinfo="none">ssh-agent</command>, and it's often run
belaran@999: 	    automatically for you when you log in.  You'll need to use
belaran@999: 	    the <command moreinfo="none">ssh-add</command> command to add passphrases
belaran@999: 	    to the agent's store.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem>
belaran@999: 	  <para id="x_6a7">On Windows, if you're using TortoiseHg, the
belaran@999: 	    <command moreinfo="none">pageant</command> command acts as the agent.  As
belaran@999: 	    with <command moreinfo="none">puttygen</command>, you'll need to <ulink url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download 
belaran@999: 	      <command moreinfo="none">pageant</command></ulink> from the PuTTY web
belaran@999: 	    site and read <ulink url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its 
belaran@999: 	      documentation</ulink>.  The <command moreinfo="none">pageant</command>
belaran@999: 	    command adds an icon to your system tray that will let you
belaran@999: 	    manage stored passphrases.</para>
belaran@999: 	</listitem>
belaran@999:       </itemizedlist>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Configuring the server side properly</title>
belaran@999: 
belaran@999:       <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
belaran@999: 	a variety of things can go wrong.  Add Mercurial
belaran@999: 	on top, and there's plenty more scope for head-scratching.
belaran@999: 	Most of these potential problems occur on the server side, not
belaran@999: 	the client side.  The good news is that once you've gotten a
belaran@999: 	configuration working, it will usually continue to work
belaran@999: 	indefinitely.</para>
belaran@999: 
belaran@999:       <para id="x_4a1">Before you try using Mercurial to talk to an ssh server,
belaran@999: 	it's best to make sure that you can use the normal
belaran@999: 	<command moreinfo="none">ssh</command> or <command moreinfo="none">putty</command> command to
belaran@999: 	talk to the server first.  If you run into problems with using
belaran@999: 	these commands directly, Mercurial surely won't work.  Worse,
belaran@999: 	it will obscure the underlying problem.  Any time you want to
belaran@999: 	debug ssh-related Mercurial problems, you should drop back to
belaran@999: 	making sure that plain ssh client commands work first,
belaran@999: 	<emphasis>before</emphasis> you worry about whether there's a
belaran@999: 	problem with Mercurial.</para>
belaran@999: 
belaran@999:       <para id="x_4a2">The first thing to be sure of on the server side is that
belaran@999: 	you can actually log in from another machine at all.  If you
belaran@999: 	can't use <command moreinfo="none">ssh</command> or <command moreinfo="none">putty</command>
belaran@999: 	to log in, the error message you get may give you a few hints
belaran@999: 	as to what's wrong.  The most common problems are as
belaran@999: 	follows.</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_4a3">If you get a <quote>connection refused</quote>
belaran@999: 	    error, either there isn't an SSH daemon running on the
belaran@999: 	    server at all, or it's inaccessible due to firewall
belaran@999: 	    configuration.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4a4">If you get a <quote>no route to host</quote>
belaran@999: 	    error, you either have an incorrect address for the server
belaran@999: 	    or a seriously locked down firewall that won't admit its
belaran@999: 	    existence at all.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4a5">If you get a <quote>permission denied</quote>
belaran@999: 	    error, you may have mistyped the username on the server,
belaran@999: 	    or you could have mistyped your key's passphrase or the
belaran@999: 	    remote user's password.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999:       <para id="x_4a6">In summary, if you're having trouble talking to the
belaran@999: 	server's ssh daemon, first make sure that one is running at
belaran@999: 	all.  On many systems it will be installed, but disabled, by
belaran@999: 	default.  Once you're done with this step, you should then
belaran@999: 	check that the server's firewall is configured to allow
belaran@999: 	incoming connections on the port the ssh daemon is listening
belaran@999: 	on (usually 22).  Don't worry about more exotic possibilities
belaran@999: 	for misconfiguration until you've checked these two
belaran@999: 	first.</para>
belaran@999: 
belaran@999:       <para id="x_4a7">If you're using an authentication agent on the client side
belaran@999: 	to store passphrases for your keys, you ought to be able to
belaran@999: 	log into the server without being prompted for a passphrase or
belaran@999: 	a password.  If you're prompted for a passphrase, there are a
belaran@999: 	few possible culprits.</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_4a8">You might have forgotten to use
belaran@999: 	    <command moreinfo="none">ssh-add</command> or <command moreinfo="none">pageant</command>
belaran@999: 	    to store the passphrase.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4a9">You might have stored the passphrase for the
belaran@999: 	    wrong key.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999:       <para id="x_4aa">If you're being prompted for the remote user's password,
belaran@999: 	there are another few possible problems to check.</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_4ab">Either the user's home directory or their
belaran@999: 	    <filename role="special" class="directory" moreinfo="none">.ssh</filename>
belaran@999: 	    directory might have excessively liberal permissions.  As
belaran@999: 	    a result, the ssh daemon will not trust or read their
belaran@999: 	    <filename role="special" moreinfo="none">authorized_keys</filename> file.
belaran@999: 	    For example, a group-writable home or <filename role="special" class="directory" moreinfo="none">.ssh</filename>
belaran@999: 	    directory will often cause this symptom.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4ac">The user's <filename role="special" moreinfo="none">authorized_keys</filename> file may have
belaran@999: 	    a problem. If anyone other than the user owns or can write
belaran@999: 	    to that file, the ssh daemon will not trust or read
belaran@999: 	    it.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_4ad">In the ideal world, you should be able to run the
belaran@999: 	following command successfully, and it should print exactly
belaran@999: 	one line of output, the current date and time.</para>
belaran@999:       <programlisting format="linespecific">ssh myserver date</programlisting>
belaran@999: 
belaran@999:       <para id="x_4ae">If, on your server, you have login scripts that print
belaran@999: 	banners or other junk even when running non-interactive
belaran@999: 	commands like this, you should fix them before you continue,
belaran@999: 	so that they only print output if they're run interactively.
belaran@999: 	Otherwise these banners will at least clutter up Mercurial's
belaran@999: 	output.  Worse, they could potentially cause problems with
belaran@999: 	running Mercurial commands remotely.  Mercurial tries to
belaran@999: 	detect and ignore banners in non-interactive
belaran@999: 	<command moreinfo="none">ssh</command> sessions, but it is not foolproof.  (If
belaran@999: 	you're editing your login scripts on your server, the usual
belaran@999: 	way to see if a login script is running in an interactive
belaran@999: 	shell is to check the return code from the command
belaran@999: 	<literal moreinfo="none">tty -s</literal>.)</para>
belaran@999: 
belaran@999:       <para id="x_4af">Once you've verified that plain old ssh is working with
belaran@999: 	your server, the next step is to ensure that Mercurial runs on
belaran@999: 	the server.  The following command should run
belaran@999: 	successfully:</para>
belaran@999: 
belaran@999:       <programlisting format="linespecific">ssh myserver hg version</programlisting>
belaran@999: 
belaran@999:       <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
belaran@999: 	because you haven't installed Mercurial to <filename class="directory" moreinfo="none">/usr/bin</filename>.  Don't worry if this
belaran@999: 	is the case; you don't need to do that.  But you should check
belaran@999: 	for a few possible problems.</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_4b1">Is Mercurial really installed on the server at
belaran@999: 	    all?  I know this sounds trivial, but it's worth
belaran@999: 	    checking!</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4b2">Maybe your shell's search path (usually set
belaran@999: 	    via the <envar>PATH</envar> environment variable) is
belaran@999: 	    simply misconfigured.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment
belaran@999: 	    variable is only being set to point to the location of the
belaran@999: 	    <command moreinfo="none">hg</command> executable if the login session is
belaran@999: 	    interactive.  This can happen if you're setting the path
belaran@999: 	    in the wrong shell login script.  See your shell's
belaran@999: 	    documentation for details.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment
belaran@999: 	    variable may need to contain the path to the Mercurial
belaran@999: 	    Python modules.  It might not be set at all; it could be
belaran@999: 	    incorrect; or it may be set only if the login is
belaran@999: 	    interactive.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_4b5">If you can run <command role="hg-cmd" moreinfo="none">hg version</command>
belaran@999: 	over an ssh connection, well done! You've got the server and
belaran@999: 	client sorted out.  You should now be able to use Mercurial to
belaran@999: 	access repositories hosted by that username on that server.
belaran@999: 	If you run into problems with Mercurial and ssh at this point,
belaran@999: 	try using the <option role="hg-opt-global">--debug</option>
belaran@999: 	option to get a clearer picture of what's going on.</para>
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Using compression with ssh</title>
belaran@999: 
belaran@999:       <para id="x_4b6">Mercurial does not compress data when it uses the ssh
belaran@999: 	protocol, because the ssh protocol can transparently compress
belaran@999: 	data.  However, the default behavior of ssh clients is
belaran@999: 	<emphasis>not</emphasis> to request compression.</para>
belaran@999: 
belaran@999:       <para id="x_4b7">Over any network other than a fast LAN (even a wireless
belaran@999: 	network), using compression is likely to significantly speed
belaran@999: 	up Mercurial's network operations.  For example, over a WAN,
belaran@999: 	someone measured compression as reducing the amount of time
belaran@999: 	required to clone a particularly large repository from 51
belaran@999: 	minutes to 17 minutes.</para>
belaran@999: 
belaran@999:       <para id="x_4b8">Both <command moreinfo="none">ssh</command> and <command moreinfo="none">plink</command>
belaran@999: 	accept a <option role="cmd-opt-ssh">-C</option> option which
belaran@999: 	turns on compression.  You can easily edit your <filename role="special" moreinfo="none">~/.hgrc</filename> to enable compression for
belaran@999: 	all of Mercurial's uses of the ssh protocol.  Here is how to
belaran@999: 	do so for regular <command moreinfo="none">ssh</command> on Unix-like systems,
belaran@999: 	for example.</para>
belaran@999:       <programlisting format="linespecific">[ui]
belaran@999: ssh = ssh -C</programlisting>
belaran@999: 
belaran@999:       <para id="x_4b9">If you use <command moreinfo="none">ssh</command> on a
belaran@999: 	Unix-like system, you can configure it to always use
belaran@999: 	compression when talking to your server.  To do this, edit
belaran@999: 	your <filename role="special" moreinfo="none">.ssh/config</filename> file
belaran@999: 	(which may not yet exist), as follows.</para>
belaran@999: 
belaran@999:       <programlisting format="linespecific">Host hg
belaran@999:   Compression yes
belaran@999:   HostName hg.example.com</programlisting>
belaran@999: 
belaran@999:       <para id="x_4ba">This defines a hostname alias,
belaran@999: 	<literal moreinfo="none">hg</literal>.  When you use that hostname on the
belaran@999: 	<command moreinfo="none">ssh</command> command line or in a Mercurial
belaran@999: 	<literal moreinfo="none">ssh</literal>-protocol URL, it will cause
belaran@999: 	<command moreinfo="none">ssh</command> to connect to
belaran@999: 	<literal moreinfo="none">hg.example.com</literal> and use compression.  This
belaran@999: 	gives you both a shorter name to type and compression, each of
belaran@999: 	which is a good thing in its own right.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="sec:collab:cgi">
belaran@999:     <title>Serving over HTTP using CGI</title>
belaran@999: 
belaran@999:     <para id="x_6a8">The simplest way to host one or more repositories in a
belaran@999:       permanent way is to use a web server and Mercurial's CGI
belaran@999:       support.</para>
belaran@999: 
belaran@999:     <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
belaran@999:       CGI interface can take anything from a few moments to several
belaran@999:       hours.</para>
belaran@999: 
belaran@999:     <para id="x_4bc">We'll begin with the simplest of examples, and work our way
belaran@999:       towards a more complex configuration.  Even for the most basic
belaran@999:       case, you're almost certainly going to need to read and modify
belaran@999:       your web server's configuration.</para>
belaran@999: 
belaran@999:     <note>
belaran@999:       <title>High pain tolerance required</title>
belaran@999: 
belaran@999:       <para id="x_4bd">Configuring a web server is a complex, fiddly,
belaran@999: 	and highly system-dependent activity.  I can't possibly give
belaran@999: 	you instructions that will cover anything like all of the
belaran@999: 	cases you will encounter. Please use your discretion and
belaran@999: 	judgment in following the sections below.  Be prepared to make
belaran@999: 	plenty of mistakes, and to spend a lot of time reading your
belaran@999: 	server's error logs.</para>
belaran@999: 
belaran@999:       <para id="x_6a9">If you don't have a strong stomach for tweaking
belaran@999: 	configurations over and over, or a compelling need to host
belaran@999: 	your own services, you might want to try one of the public
belaran@999: 	hosting services that I mentioned earlier.</para>
belaran@999:     </note>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Web server configuration checklist</title>
belaran@999: 
belaran@999:       <para id="x_4be">Before you continue, do take a few moments to check a few
belaran@999: 	aspects of your system's setup.</para>
belaran@999: 
belaran@999:       <orderedlist inheritnum="ignore" continuation="restarts">
belaran@999: 	<listitem><para id="x_4bf">Do you have a web server installed
belaran@999: 	    at all? Mac OS X and some Linux distributions ship with
belaran@999: 	    Apache, but many other systems may not have a web server
belaran@999: 	    installed.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4c0">If you have a web server installed, is it
belaran@999: 	    actually running?  On most systems, even if one is
belaran@999: 	    present, it will be disabled by default.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4c1">Is your server configured to allow you to run
belaran@999: 	    CGI programs in the directory where you plan to do so?
belaran@999: 	    Most servers default to explicitly disabling the ability
belaran@999: 	    to run CGI programs.</para>
belaran@999: 	</listitem></orderedlist>
belaran@999: 
belaran@999:       <para id="x_4c2">If you don't have a web server installed, and don't have
belaran@999: 	substantial experience configuring Apache, you should consider
belaran@999: 	using the <literal moreinfo="none">lighttpd</literal> web server instead of
belaran@999: 	Apache.  Apache has a well-deserved reputation for baroque and
belaran@999: 	confusing configuration. While <literal moreinfo="none">lighttpd</literal> is
belaran@999: 	less capable in some ways than Apache, most of these
belaran@999: 	capabilities are not relevant to serving Mercurial
belaran@999: 	repositories.  And <literal moreinfo="none">lighttpd</literal> is undeniably
belaran@999: 	<emphasis>much</emphasis> easier to get started with than
belaran@999: 	Apache.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Basic CGI configuration</title>
belaran@999: 
belaran@999:       <para id="x_4c3">On Unix-like systems, it's common for users to have a
belaran@999: 	subdirectory named something like <filename class="directory" moreinfo="none">public_html</filename> in their home
belaran@999: 	directory, from which they can serve up web pages.  A file
belaran@999: 	named <filename moreinfo="none">foo</filename> in this directory will be
belaran@999: 	accessible at a URL of the form
belaran@999: 	<literal moreinfo="none">http://www.example.com/username/foo</literal>.</para>
belaran@999: 
belaran@999:       <para id="x_4c4">To get started, find the <filename role="special" moreinfo="none">hgweb.cgi</filename> script that should be
belaran@999: 	present in your Mercurial installation.  If you can't quickly
belaran@999: 	find a local copy on your system, simply download one from the
belaran@999: 	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>
belaran@999: 
belaran@999:       <para id="x_4c5">You'll need to copy this script into your <filename class="directory" moreinfo="none">public_html</filename> directory, and
belaran@999: 	ensure that it's executable.</para>
belaran@999:       <programlisting format="linespecific">cp .../hgweb.cgi ~/public_html
belaran@999: chmod 755 ~/public_html/hgweb.cgi</programlisting>
belaran@999:       <para id="x_4c6">The <literal moreinfo="none">755</literal> argument to
belaran@999: 	<command moreinfo="none">chmod</command> is a little more general than just
belaran@999: 	making the script executable: it ensures that the script is
belaran@999: 	executable by anyone, and that <quote>group</quote> and
belaran@999: 	<quote>other</quote> write permissions are
belaran@999: 	<emphasis>not</emphasis> set.  If you were to leave those
belaran@999: 	write permissions enabled, Apache's <literal moreinfo="none">suexec</literal>
belaran@999: 	subsystem would likely refuse to execute the script.  In fact,
belaran@999: 	<literal moreinfo="none">suexec</literal> also insists that the
belaran@999: 	<emphasis>directory</emphasis> in which the script resides
belaran@999: 	must not be writable by others.</para>
belaran@999:       <programlisting format="linespecific">chmod 755 ~/public_html</programlisting>
belaran@999: 
belaran@999:       <sect3 id="sec:collab:wtf">
belaran@999: 	<title>What could <emphasis>possibly</emphasis> go
belaran@999: 	  wrong?</title>
belaran@999: 
belaran@999: 	<para id="x_4c7">Once you've copied the CGI script into place,
belaran@999: 	  go into a web browser, and try to open the URL
belaran@999: 	  <literal moreinfo="none">http://myhostname/~myuser/hgweb.cgi</literal>,
belaran@999: 	  <emphasis>but</emphasis> brace yourself for instant failure.
belaran@999: 	  There's a high probability that trying to visit this URL
belaran@999: 	  will fail, and there are many possible reasons for this.  In
belaran@999: 	  fact, you're likely to stumble over almost every one of the
belaran@999: 	  possible errors below, so please read carefully.  The
belaran@999: 	  following are all of the problems I ran into on a system
belaran@999: 	  running Fedora 7, with a fresh installation of Apache, and a
belaran@999: 	  user account that I created specially to perform this
belaran@999: 	  exercise.</para>
belaran@999: 
belaran@999: 	<para id="x_4c8">Your web server may have per-user directories disabled.
belaran@999: 	  If you're using Apache, search your config file for a
belaran@999: 	  <literal moreinfo="none">UserDir</literal> directive.  If there's none
belaran@999: 	  present, per-user directories will be disabled.  If one
belaran@999: 	  exists, but its value is <literal moreinfo="none">disabled</literal>, then
belaran@999: 	  per-user directories will be disabled.  Otherwise, the
belaran@999: 	  string after <literal moreinfo="none">UserDir</literal> gives the name of
belaran@999: 	  the subdirectory that Apache will look in under your home
belaran@999: 	  directory, for example <filename class="directory" moreinfo="none">public_html</filename>.</para>
belaran@999: 
belaran@999: 	<para id="x_4c9">Your file access permissions may be too restrictive.
belaran@999: 	  The web server must be able to traverse your home directory
belaran@999: 	  and directories under your <filename class="directory" moreinfo="none">public_html</filename> directory, and
belaran@999: 	  read files under the latter too.  Here's a quick recipe to
belaran@999: 	  help you to make your permissions more appropriate.</para>
belaran@999: 	<programlisting format="linespecific">chmod 755 ~
belaran@999: find ~/public_html -type d -print0 | xargs -0r chmod 755
belaran@999: find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting>
belaran@999: 
belaran@999: 	<para id="x_4ca">The other possibility with permissions is that you might
belaran@999: 	  get a completely empty window when you try to load the
belaran@999: 	  script.  In this case, it's likely that your access
belaran@999: 	  permissions are <emphasis>too permissive</emphasis>.  Apache's
belaran@999: 	  <literal moreinfo="none">suexec</literal> subsystem won't execute a script
belaran@999: 	  that's group- or world-writable, for example.</para>
belaran@999: 
belaran@999: 	<para id="x_4cb">Your web server may be configured to disallow execution
belaran@999: 	  of CGI programs in your per-user web directory.  Here's
belaran@999: 	  Apache's default per-user configuration from my Fedora
belaran@999: 	  system.</para>
belaran@999: 
belaran@999: 	<!-- BEGIN ch06/apache-config.lst -->
belaran@999: <programlisting format="linespecific">&lt;Directory /home/*/public_html&gt;
belaran@999:   AllowOverride FileInfo AuthConfig Limit
belaran@999:   Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
belaran@999:   &lt;Limit GET POST OPTIONS&gt;
belaran@999:     Order allow,deny
belaran@999:     Allow from all
belaran@999:   &lt;/Limit&gt;
belaran@999:   &lt;LimitExcept GET POST OPTIONS&gt;
belaran@999:     Order deny,allow Deny from all
belaran@999:   &lt;/LimitExcept&gt;
belaran@999: &lt;/Directory&gt;</programlisting>
belaran@999: <!-- END ch06/apache-config.lst -->
belaran@999: 
belaran@999: 
belaran@999: 	<para id="x_4cc">If you find a similar-looking
belaran@999: 	  <literal moreinfo="none">Directory</literal> group in your Apache
belaran@999: 	  configuration, the directive to look at inside it is
belaran@999: 	  <literal moreinfo="none">Options</literal>. Add <literal moreinfo="none">ExecCGI</literal>
belaran@999: 	  to the end of this list if it's missing, and restart the web
belaran@999: 	  server.</para>
belaran@999: 
belaran@999: 	<para id="x_4cd">If you find that Apache serves you the text of the CGI
belaran@999: 	  script instead of executing it, you may need to either
belaran@999: 	  uncomment (if already present) or add a directive like
belaran@999: 	  this.</para>
belaran@999: 	<programlisting format="linespecific">AddHandler cgi-script .cgi</programlisting>
belaran@999: 
belaran@999: 	<para id="x_4ce">The next possibility is that you might be served with a
belaran@999: 	  colourful Python backtrace claiming that it can't import a
belaran@999: 	  <literal moreinfo="none">mercurial</literal>-related module.  This is
belaran@999: 	  actually progress!  The server is now capable of executing
belaran@999: 	  your CGI script.  This error is only likely to occur if
belaran@999: 	  you're running a private installation of Mercurial, instead
belaran@999: 	  of a system-wide version.  Remember that the web server runs
belaran@999: 	  the CGI program without any of the environment variables
belaran@999: 	  that you take for granted in an interactive session.  If
belaran@999: 	  this error happens to you, edit your copy of <filename role="special" moreinfo="none">hgweb.cgi</filename> and follow the
belaran@999: 	  directions inside it to correctly set your
belaran@999: 	  <envar>PYTHONPATH</envar> environment variable.</para>
belaran@999: 
belaran@999: 	<para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be
belaran@999: 	  served with another colourful Python backtrace: this one
belaran@999: 	  will complain that it can't find <filename class="directory" moreinfo="none">/path/to/repository</filename>.  Edit
belaran@999: 	  your <filename role="special" moreinfo="none">hgweb.cgi</filename> script
belaran@999: 	  and replace the <filename class="directory" moreinfo="none">/path/to/repository</filename> string
belaran@999: 	  with the complete path to the repository you want to serve
belaran@999: 	  up.</para>
belaran@999: 
belaran@999: 	<para id="x_4d0">At this point, when you try to reload the page, you
belaran@999: 	  should be presented with a nice HTML view of your
belaran@999: 	  repository's history.  Whew!</para>
belaran@999:       </sect3>
belaran@999: 
belaran@999:       <sect3>
belaran@999: 	<title>Configuring lighttpd</title>
belaran@999: 
belaran@999: 	<para id="x_4d1">To be exhaustive in my experiments, I tried configuring
belaran@999: 	  the increasingly popular <literal moreinfo="none">lighttpd</literal> web
belaran@999: 	  server to serve the same repository as I described with
belaran@999: 	  Apache above.  I had already overcome all of the problems I
belaran@999: 	  outlined with Apache, many of which are not server-specific.
belaran@999: 	  As a result, I was fairly sure that my file and directory
belaran@999: 	  permissions were good, and that my <filename role="special" moreinfo="none">hgweb.cgi</filename> script was properly
belaran@999: 	  edited.</para>
belaran@999: 
belaran@999: 	<para id="x_4d2">Once I had Apache running, getting
belaran@999: 	  <literal moreinfo="none">lighttpd</literal> to serve the repository was a
belaran@999: 	  snap (in other words, even if you're trying to use
belaran@999: 	  <literal moreinfo="none">lighttpd</literal>, you should read the Apache
belaran@999: 	  section).  I first had to edit the
belaran@999: 	  <literal moreinfo="none">mod_access</literal> section of its config file to
belaran@999: 	  enable <literal moreinfo="none">mod_cgi</literal> and
belaran@999: 	  <literal moreinfo="none">mod_userdir</literal>, both of which were disabled
belaran@999: 	  by default on my system.  I then added a few lines to the
belaran@999: 	  end of the config file, to configure these modules.</para>
belaran@999: 	<programlisting format="linespecific">userdir.path = "public_html"
belaran@999: cgi.assign = (".cgi" =&gt; "" )</programlisting>
belaran@999: 	<para id="x_4d3">With this done, <literal moreinfo="none">lighttpd</literal> ran
belaran@999: 	  immediately for me.  If I had configured
belaran@999: 	  <literal moreinfo="none">lighttpd</literal> before Apache, I'd almost
belaran@999: 	  certainly have run into many of the same system-level
belaran@999: 	  configuration problems as I did with Apache.  However, I
belaran@999: 	  found <literal moreinfo="none">lighttpd</literal> to be noticeably easier to
belaran@999: 	  configure than Apache, even though I've used Apache for over
belaran@999: 	  a decade, and this was my first exposure to
belaran@999: 	  <literal moreinfo="none">lighttpd</literal>.</para>
belaran@999:       </sect3>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Sharing multiple repositories with one CGI script</title>
belaran@999: 
belaran@999:       <para id="x_4d4">The <filename role="special" moreinfo="none">hgweb.cgi</filename> script
belaran@999: 	only lets you publish a single repository, which is an
belaran@999: 	annoying restriction.  If you want to publish more than one
belaran@999: 	without wracking yourself with multiple copies of the same
belaran@999: 	script, each with different names, a better choice is to use
belaran@999: 	the <filename role="special" moreinfo="none">hgwebdir.cgi</filename>
belaran@999: 	script.</para>
belaran@999: 
belaran@999:       <para id="x_4d5">The procedure to configure <filename role="special" moreinfo="none">hgwebdir.cgi</filename> is only a little more
belaran@999: 	involved than for <filename role="special" moreinfo="none">hgweb.cgi</filename>.  First, you must obtain
belaran@999: 	a copy of the script.  If you don't have one handy, you can
belaran@999: 	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>
belaran@999: 
belaran@999:       <para id="x_4d6">You'll need to copy this script into your <filename class="directory" moreinfo="none">public_html</filename> directory, and
belaran@999: 	ensure that it's executable.</para>
belaran@999: 
belaran@999:       <programlisting format="linespecific">cp .../hgwebdir.cgi ~/public_html
belaran@999: chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
belaran@999: 
belaran@999:       <para id="x_4d7">With basic configuration out of the way, try to
belaran@999: 	visit <literal moreinfo="none">http://myhostname/~myuser/hgwebdir.cgi</literal>
belaran@999: 	in your	browser.  It should
belaran@999: 	display an empty list of repositories.  If you get a blank
belaran@999: 	window or error message, try walking through the list of
belaran@999: 	potential problems in <xref linkend="sec:collab:wtf"/>.</para>
belaran@999: 
belaran@999:       <para id="x_4d8">The <filename role="special" moreinfo="none">hgwebdir.cgi</filename>
belaran@999: 	script relies on an external configuration file.  By default,
belaran@999: 	it searches for a file named <filename role="special" moreinfo="none">hgweb.config</filename> in the same directory
belaran@999: 	as itself.  You'll need to create this file, and make it
belaran@999: 	world-readable.  The format of the file is similar to a
belaran@999: 	Windows <quote>ini</quote> file, as understood by Python's
belaran@999: 	<literal moreinfo="none">ConfigParser</literal>
belaran@999: 	<citation>web:configparser</citation> module.</para>
belaran@999: 
belaran@999:       <para id="x_4d9">The easiest way to configure <filename role="special" moreinfo="none">hgwebdir.cgi</filename> is with a section
belaran@999: 	named <literal moreinfo="none">collections</literal>.  This will automatically
belaran@999: 	publish <emphasis>every</emphasis> repository under the
belaran@999: 	directories you name.  The section should look like
belaran@999: 	this:</para>
belaran@999:       <programlisting format="linespecific">[collections]
belaran@999: /my/root = /my/root</programlisting>
belaran@999:       <para id="x_4da">Mercurial interprets this by looking at the directory name
belaran@999: 	on the <emphasis>right</emphasis> hand side of the
belaran@999: 	<quote><literal moreinfo="none">=</literal></quote> sign; finding repositories
belaran@999: 	in that directory hierarchy; and using the text on the
belaran@999: 	<emphasis>left</emphasis> to strip off matching text from the
belaran@999: 	names it will actually list in the web interface.  The
belaran@999: 	remaining component of a path after this stripping has
belaran@999: 	occurred is called a <quote>virtual path</quote>.</para>
belaran@999: 
belaran@999:       <para id="x_4db">Given the example above, if we have a
belaran@999: 	repository whose local path is <filename class="directory" moreinfo="none">/my/root/this/repo</filename>, the CGI
belaran@999: 	script will strip the leading <filename class="directory" moreinfo="none">/my/root</filename> from the name, and
belaran@999: 	publish the repository with a virtual path of <filename class="directory" moreinfo="none">this/repo</filename>.  If the base URL for
belaran@999: 	our CGI script is
belaran@999: 	<literal moreinfo="none">http://myhostname/~myuser/hgwebdir.cgi</literal>, the
belaran@999: 	complete URL for that repository will be
belaran@999: 	<literal moreinfo="none">http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para>
belaran@999: 
belaran@999:       <para id="x_4dc">If we replace <filename class="directory" moreinfo="none">/my/root</filename> on the left hand side
belaran@999: 	of this example with <filename class="directory" moreinfo="none">/my</filename>, then <filename role="special" moreinfo="none">hgwebdir.cgi</filename> will only strip off
belaran@999: 	<filename class="directory" moreinfo="none">/my</filename> from the repository
belaran@999: 	name, and will give us a virtual path of <filename class="directory" moreinfo="none">root/this/repo</filename> instead of
belaran@999: 	<filename class="directory" moreinfo="none">this/repo</filename>.</para>
belaran@999: 
belaran@999:       <para id="x_4dd">The <filename role="special" moreinfo="none">hgwebdir.cgi</filename>
belaran@999: 	script will recursively search each directory listed in the
belaran@999: 	<literal moreinfo="none">collections</literal> section of its configuration
belaran@999: 	file, but it will <literal moreinfo="none">not</literal> recurse into the
belaran@999: 	repositories it finds.</para>
belaran@999: 
belaran@999:       <para id="x_4de">The <literal moreinfo="none">collections</literal> mechanism makes it easy
belaran@999: 	to publish many repositories in a <quote>fire and
belaran@999: 	  forget</quote> manner.  You only need to set up the CGI
belaran@999: 	script and configuration file one time.  Afterwards, you can
belaran@999: 	publish or unpublish a repository at any time by simply moving
belaran@999: 	it into, or out of, the directory hierarchy in which you've
belaran@999: 	configured <filename role="special" moreinfo="none">hgwebdir.cgi</filename> to
belaran@999: 	look.</para>
belaran@999: 
belaran@999:       <sect3>
belaran@999: 	<title>Explicitly specifying which repositories to
belaran@999: 	  publish</title>
belaran@999: 
belaran@999: 	<para id="x_4df">In addition to the <literal moreinfo="none">collections</literal>
belaran@999: 	  mechanism, the <filename role="special" moreinfo="none">hgwebdir.cgi</filename> script allows you
belaran@999: 	  to publish a specific list of repositories.  To do so,
belaran@999: 	  create a <literal moreinfo="none">paths</literal> section, with contents of
belaran@999: 	  the following form.</para>
belaran@999: 	<programlisting format="linespecific">[paths]
belaran@999: repo1 = /my/path/to/some/repo
belaran@999: repo2 = /some/path/to/another</programlisting>
belaran@999: 	<para id="x_4e0">In this case, the virtual path (the component that will
belaran@999: 	  appear in a URL) is on the left hand side of each
belaran@999: 	  definition, while the path to the repository is on the
belaran@999: 	  right.  Notice that there does not need to be any
belaran@999: 	  relationship between the virtual path you choose and the
belaran@999: 	  location of a repository in your filesystem.</para>
belaran@999: 
belaran@999: 	<para id="x_4e1">If you wish, you can use both the
belaran@999: 	  <literal moreinfo="none">collections</literal> and <literal moreinfo="none">paths</literal>
belaran@999: 	  mechanisms simultaneously in a single configuration
belaran@999: 	  file.</para>
belaran@999: 
belaran@999: 	<note>
belaran@999: 	  <title>Beware duplicate virtual paths</title>
belaran@999: 
belaran@999: 	  <para id="x_4e2">  If several repositories have the same
belaran@999: 	    virtual path, <filename role="special" moreinfo="none">hgwebdir.cgi</filename> will not report
belaran@999: 	    an error.  Instead, it will behave unpredictably.</para>
belaran@999: 	</note>
belaran@999:       </sect3>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Downloading source archives</title>
belaran@999: 
belaran@999:       <para id="x_4e3">Mercurial's web interface lets users download an archive
belaran@999: 	of any revision.  This archive will contain a snapshot of the
belaran@999: 	working directory as of that revision, but it will not contain
belaran@999: 	a copy of the repository data.</para>
belaran@999: 
belaran@999:       <para id="x_4e4">By default, this feature is not enabled.  To enable it,
belaran@999: 	you'll need to add an <envar role="rc-item-web">allow_archive</envar> item to the
belaran@999: 	<literal role="rc-web" moreinfo="none">web</literal> section of your <filename role="special" moreinfo="none">~/.hgrc</filename>; see below for details.</para>
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Web configuration options</title>
belaran@999: 
belaran@999:       <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  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
belaran@999: 	number of configuration options that you can set.  These
belaran@999: 	belong in a section named <literal role="rc-web" moreinfo="none">web</literal>.</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_4e6"><envar role="rc-item-web">allow_archive</envar>: Determines
belaran@999: 	    which (if any) archive download mechanisms Mercurial
belaran@999: 	    supports.  If you enable this feature, users of the web
belaran@999: 	    interface will be able to download an archive of whatever
belaran@999: 	    revision of a repository they are viewing. To enable the
belaran@999: 	    archive feature, this item must take the form of a
belaran@999: 	    sequence of words drawn from the list below.</para>
belaran@999: 	  <itemizedlist>
belaran@999: 	    <listitem><para id="x_4e7"><literal moreinfo="none">bz2</literal>: A
belaran@999: 		<command moreinfo="none">tar</command> archive, compressed using
belaran@999: 		<literal moreinfo="none">bzip2</literal> compression.  This has the
belaran@999: 		best compression ratio, but uses the most CPU time on
belaran@999: 		the server.</para>
belaran@999: 	    </listitem>
belaran@999: 	    <listitem><para id="x_4e8"><literal moreinfo="none">gz</literal>: A
belaran@999: 		<command moreinfo="none">tar</command> archive, compressed using
belaran@999: 		<literal moreinfo="none">gzip</literal> compression.</para>
belaran@999: 	    </listitem>
belaran@999: 	    <listitem><para id="x_4e9"><literal moreinfo="none">zip</literal>: A
belaran@999: 		<command moreinfo="none">zip</command> archive, compressed using LZW
belaran@999: 		compression.  This format has the worst compression
belaran@999: 		ratio, but is widely used in the Windows world.</para>
belaran@999: 	    </listitem>
belaran@999: 	  </itemizedlist>
belaran@999: 	  <para id="x_4ea">  If you provide an empty list, or don't have an
belaran@999: 	    <envar role="rc-item-web">allow_archive</envar> entry at
belaran@999: 	    all, this feature will be disabled.  Here is an example of
belaran@999: 	    how to enable all three supported formats.</para>
belaran@999: 	  <programlisting format="linespecific">[web]
belaran@999: allow_archive = bz2 gz zip</programlisting>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>:
belaran@999: 	    Boolean.  Determines whether the web interface allows
belaran@999: 	    remote users to <command role="hg-cmd" moreinfo="none">hg pull</command>
belaran@999: 	    and <command role="hg-cmd" moreinfo="none">hg clone</command> this
belaran@999: 	    repository over HTTP.  If set to <literal moreinfo="none">no</literal> or
belaran@999: 	    <literal moreinfo="none">false</literal>, only the
belaran@999: 	    <quote>human-oriented</quote> portion of the web interface
belaran@999: 	    is available.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>:
belaran@999: 	    String.  A free-form (but preferably brief) string
belaran@999: 	    identifying the person or group in charge of the
belaran@999: 	    repository.  This often contains the name and email
belaran@999: 	    address of a person or mailing list.  It often makes sense
belaran@999: 	    to place this entry in a repository's own <filename role="special" moreinfo="none">.hg/hgrc</filename> file, but it can make
belaran@999: 	    sense to use in a global <filename role="special" moreinfo="none">~/.hgrc</filename> if every repository
belaran@999: 	    has a single maintainer.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>:
belaran@999: 	    Integer.  The default maximum number of changesets to
belaran@999: 	    display in a single page of output.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>:
belaran@999: 	    Integer.  The default maximum number of modified files to
belaran@999: 	    display in a single page of output.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>:
belaran@999: 	    Integer.  If the web interface displays alternating
belaran@999: 	    <quote>stripes</quote> to make it easier to visually align
belaran@999: 	    rows when you are looking at a table, this number controls
belaran@999: 	    the number of rows in each stripe.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4f0"><envar role="rc-item-web">style</envar>: Controls the template
belaran@999: 	    Mercurial uses to display the web interface.  Mercurial
belaran@999: 	    ships with several web templates.</para>
belaran@999: 	  <itemizedlist>
belaran@999: 	    <listitem>
belaran@999: 	      <para id="x_6aa"><literal moreinfo="none">coal</literal> is monochromatic.</para>
belaran@999: 	    </listitem>
belaran@999: 	    <listitem>
belaran@999: 	      <para id="x_6ab"><literal moreinfo="none">gitweb</literal> emulates the visual
belaran@999: 		style of git's web interface.</para>
belaran@999: 	    </listitem>
belaran@999: 	    <listitem>
belaran@999: 	      <para id="x_6ac"><literal moreinfo="none">monoblue</literal> uses solid blues and
belaran@999: 		greys.</para>
belaran@999: 	    </listitem>
belaran@999: 	    <listitem>
belaran@999: 	      <para id="x_6ad"><literal moreinfo="none">paper</literal> is the default.</para>
belaran@999: 	    </listitem>
belaran@999: 	    <listitem>
belaran@999: 	      <para id="x_6ae"><literal moreinfo="none">spartan</literal> was the default for a
belaran@999: 		long time.</para>
belaran@999: 	    </listitem>
belaran@999: 	  </itemizedlist>
belaran@999: 	  <para id="x_6af">You can
belaran@999: 	    also specify a custom template of your own; see 
belaran@999: 	    <xref linkend="chap:template"/> for details. Here, you can
belaran@999: 	    see how to enable the <literal moreinfo="none">gitweb</literal>
belaran@999: 	    style.</para>
belaran@999: 	  <programlisting format="linespecific">[web]
belaran@999: style = gitweb</programlisting>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>:
belaran@999: 	    Path.  The directory in which to search for template
belaran@999: 	    files.  By default, Mercurial searches in the directory in
belaran@999: 	    which it was installed.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999:       <para id="x_4f2">If you are using <filename role="special" moreinfo="none">hgwebdir.cgi</filename>, you can place a few
belaran@999: 	configuration items in a <literal role="rc-web" moreinfo="none">web</literal>
belaran@999: 	section of the <filename role="special" moreinfo="none">hgweb.config</filename> file instead of a
belaran@999: 	<filename role="special" moreinfo="none">~/.hgrc</filename> file, for
belaran@999: 	convenience.  These items are <envar role="rc-item-web">motd</envar> and <envar role="rc-item-web">style</envar>.</para>
belaran@999: 
belaran@999:       <sect3>
belaran@999: 	<title>Options specific to an individual repository</title>
belaran@999: 
belaran@999: 	<para id="x_4f3">A few <literal role="rc-web" moreinfo="none">web</literal> configuration
belaran@999: 	  items ought to be placed in a repository's local <filename role="special" moreinfo="none">.hg/hgrc</filename>, rather than a user's
belaran@999: 	  or global <filename role="special" moreinfo="none">~/.hgrc</filename>.</para>
belaran@999: 	<itemizedlist>
belaran@999: 	  <listitem><para id="x_4f4"><envar role="rc-item-web">description</envar>: String.  A
belaran@999: 	      free-form (but preferably brief) string that describes
belaran@999: 	      the contents or purpose of the repository.</para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>:
belaran@999: 	      String.  The name to use for the repository in the web
belaran@999: 	      interface.  This overrides the default name, which is
belaran@999: 	      the last component of the repository's path.</para>
belaran@999: 	  </listitem></itemizedlist>
belaran@999:       </sect3>
belaran@999: 
belaran@999:       <sect3>
belaran@999: 	<title>Options specific to the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	    serve</command> command</title>
belaran@999: 
belaran@999: 	<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
belaran@999: 	  with the <command role="hg-cmd" moreinfo="none">hg serve</command>
belaran@999: 	  command.</para>
belaran@999: 	<itemizedlist>
belaran@999: 	  <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>:
belaran@999: 	      Path.  The name of a file into which to write an access
belaran@999: 	      log.  By default, the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 		serve</command> command writes this information to
belaran@999: 	      standard output, not to a file.  Log entries are written
belaran@999: 	      in the standard <quote>combined</quote> file format used
belaran@999: 	      by almost all web servers.</para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>:
belaran@999: 	      String.  The local address on which the server should
belaran@999: 	      listen for incoming connections.  By default, the server
belaran@999: 	      listens on all addresses.</para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>:
belaran@999: 	      Path.  The name of a file into which to write an error
belaran@999: 	      log.  By default, the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 		serve</command> command writes this information to
belaran@999: 	      standard error, not to a file.</para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>:
belaran@999: 	      Boolean.  Whether to use the IPv6 protocol. By default,
belaran@999: 	      IPv6 is not used.</para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>:
belaran@999: 	      Integer.  The TCP port number on which the server should
belaran@999: 	      listen.  The default port number used is 8000.</para>
belaran@999: 	  </listitem></itemizedlist>
belaran@999:       </sect3>
belaran@999: 
belaran@999:       <sect3>
belaran@999: 	<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>
belaran@999: 
belaran@999: 	<para id="x_4fc">It is important to remember that a web server like
belaran@999: 	  Apache or <literal moreinfo="none">lighttpd</literal> will run under a user
belaran@999: 	  ID that is different to yours. CGI scripts run by your
belaran@999: 	  server, such as <filename role="special" moreinfo="none">hgweb.cgi</filename>, will usually also run
belaran@999: 	  under that user ID.</para>
belaran@999: 
belaran@999: 	<para id="x_4fd">If you add <literal role="rc-web" moreinfo="none">web</literal> items to
belaran@999: 	  your own personal <filename role="special" moreinfo="none">~/.hgrc</filename> file, CGI scripts won't read that
belaran@999: 	  <filename role="special" moreinfo="none">~/.hgrc</filename> file.  Those
belaran@999: 	  settings will thus only affect the behavior of the <command role="hg-cmd" moreinfo="none">hg serve</command> command when you run it.
belaran@999: 	  To cause CGI scripts to see your settings, either create a
belaran@999: 	  <filename role="special" moreinfo="none">~/.hgrc</filename> file in the
belaran@999: 	  home directory of the user ID that runs your web server, or
belaran@999: 	  add those settings to a system-wide <filename role="special" moreinfo="none">hgrc</filename> file.</para>
belaran@999:       </sect3>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>System-wide configuration</title>
belaran@999: 
belaran@999:     <para id="x_6b0">On Unix-like systems shared by multiple users (such as a
belaran@999:       server to which people publish changes), it often makes sense to
belaran@999:       set up some global default behaviors, such as what theme to use
belaran@999:       in web interfaces.</para>
belaran@999: 
belaran@999:     <para id="x_6b1">If a file named <filename moreinfo="none">/etc/mercurial/hgrc</filename>
belaran@999:       exists, Mercurial will read it at startup time and apply any
belaran@999:       configuration settings it finds in that file.  It will also look
belaran@999:       for files ending in a <literal moreinfo="none">.rc</literal> extension in a
belaran@999:       directory named <filename moreinfo="none">/etc/mercurial/hgrc.d</filename>, and
belaran@999:       apply any configuration settings it finds in each of those
belaran@999:       files.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Making Mercurial more trusting</title>
belaran@999: 
belaran@999:       <para id="x_6b2">One situation in which a global <filename moreinfo="none">hgrc</filename>
belaran@999: 	can be useful is if users are pulling changes owned by other
belaran@999: 	users.  By default, Mercurial will not trust most of the
belaran@999: 	configuration items in a <filename moreinfo="none">.hg/hgrc</filename> file
belaran@999: 	inside a repository that is owned by a different user. If we
belaran@999: 	clone or pull changes from such a repository, Mercurial will
belaran@999: 	print a warning stating that it does not trust their
belaran@999: 	<filename moreinfo="none">.hg/hgrc</filename>.</para>
belaran@999: 
belaran@999:       <para id="x_6b3">If everyone in a particular Unix group is on the same team
belaran@999: 	and <emphasis>should</emphasis> trust each other's
belaran@999: 	configuration settings, or we want to trust particular users,
belaran@999: 	we can override Mercurial's skeptical defaults by creating a
belaran@999: 	system-wide <filename moreinfo="none">hgrc</filename> file such as the
belaran@999: 	following:</para>
belaran@999: 
belaran@999:     <programlisting format="linespecific"># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
belaran@999: [trusted]
belaran@999: # Trust all entries in any hgrc file owned by the "editors" or
belaran@999: # "www-data" groups.
belaran@999: groups = editors, www-data
belaran@999: 
belaran@999: # Trust entries in hgrc files owned by the following users.
belaran@999: users = apache, bobo
belaran@999: </programlisting>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: </chapter>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "chapter")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN ch07 -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <chapter id="chap:names">
belaran@999:   <?dbhtml filename="file-names-and-pattern-matching.html"?>
belaran@999:   <title>File names and pattern matching</title>
belaran@999: 
belaran@999:   <para id="x_543">Mercurial provides mechanisms that let you work with file
belaran@999:     names in a consistent and expressive way.</para>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Simple file naming</title>
belaran@999: 
belaran@999:     <para id="x_544">Mercurial uses a unified piece of machinery <quote>under the
belaran@999: 	hood</quote> to handle file names.  Every command behaves
belaran@999:       uniformly with respect to file names.  The way in which commands
belaran@999:       work with file names is as follows.</para>
belaran@999: 
belaran@999:     <para id="x_545">If you explicitly name real files on the command line,
belaran@999:       Mercurial works with exactly those files, as you would expect.
belaran@999:       <!-- BEGIN filenames.files -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add COPYING README examples/simple.py</userinput>
belaran@999: </screen>
belaran@999: <!-- END filenames.files -->
belaran@999: </para>
belaran@999: 
belaran@999:     <para id="x_546">When you provide a directory name, Mercurial will interpret
belaran@999:       this as <quote>operate on every file in this directory and its
belaran@999: 	subdirectories</quote>. Mercurial traverses the files and
belaran@999:       subdirectories in a directory in alphabetical order.  When it
belaran@999:       encounters a subdirectory, it will traverse that subdirectory
belaran@999:       before continuing with the current directory.</para>
belaran@999: 
belaran@999:       <!-- BEGIN filenames.dirs -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status src</userinput>
belaran@999: ? src/main.py
belaran@999: ? src/watcher/_watcher.c
belaran@999: ? src/watcher/watcher.py
belaran@999: ? src/xyzzy.txt
belaran@999: </screen>
belaran@999: <!-- END filenames.dirs -->
belaran@999: 
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Running commands without any file names</title>
belaran@999: 
belaran@999:     <para id="x_547">Mercurial's commands that work with file names have useful
belaran@999:       default behaviors when you invoke them without providing any
belaran@999:       file names or patterns.  What kind of behavior you should
belaran@999:       expect depends on what the command does.  Here are a few rules
belaran@999:       of thumb you can use to predict what a command is likely to do
belaran@999:       if you don't give it any names to work with.</para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_548">Most commands will operate on the entire working
belaran@999: 	  directory. This is what the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	    add</command> command does, for example.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_549">If the command has effects that are difficult or
belaran@999: 	  impossible to reverse, it will force you to explicitly
belaran@999: 	  provide at least one name or pattern (see below).  This
belaran@999: 	  protects you from accidentally deleting files by running
belaran@999: 	  <command role="hg-cmd" moreinfo="none">hg remove</command> with no
belaran@999: 	  arguments, for example.</para>
belaran@999:       </listitem></itemizedlist>
belaran@999: 
belaran@999:     <para id="x_54a">It's easy to work around these default behaviors if they
belaran@999:       don't suit you.  If a command normally operates on the whole
belaran@999:       working directory, you can invoke it on just the current
belaran@999:       directory and its subdirectories by giving it the name
belaran@999:       <quote><filename class="directory" moreinfo="none">.</filename></quote>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN filenames.wdir-subdir -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd src</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add -n</userinput>
belaran@999: adding ../MANIFEST.in
belaran@999: adding ../examples/performant.py
belaran@999: adding ../setup.py
belaran@999: adding main.py
belaran@999: adding watcher/_watcher.c
belaran@999: adding watcher/watcher.py
belaran@999: adding xyzzy.txt
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add -n .</userinput>
belaran@999: adding main.py
belaran@999: adding watcher/_watcher.c
belaran@999: adding watcher/watcher.py
belaran@999: adding xyzzy.txt
belaran@999: </screen>
belaran@999: <!-- END filenames.wdir-subdir -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_54b">Along the same lines, some commands normally print file
belaran@999:       names relative to the root of the repository, even if you're
belaran@999:       invoking them from a subdirectory.  Such a command will print
belaran@999:       file names relative to your subdirectory if you give it explicit
belaran@999:       names.  Here, we're going to run <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	status</command> from a subdirectory, and get it to operate on
belaran@999:       the entire working directory while printing file names relative
belaran@999:       to our subdirectory, by passing it the output of the <command role="hg-cmd" moreinfo="none">hg root</command> command.</para>
belaran@999: 
belaran@999:       <!-- BEGIN filenames.wdir-relname -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: A COPYING
belaran@999: A README
belaran@999: A examples/simple.py
belaran@999: ? MANIFEST.in
belaran@999: ? examples/performant.py
belaran@999: ? setup.py
belaran@999: ? src/main.py
belaran@999: ? src/watcher/_watcher.c
belaran@999: ? src/watcher/watcher.py
belaran@999: ? src/xyzzy.txt
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status `hg root`</userinput>
belaran@999: A ../COPYING
belaran@999: A ../README
belaran@999: A ../examples/simple.py
belaran@999: ? ../MANIFEST.in
belaran@999: ? ../examples/performant.py
belaran@999: ? ../setup.py
belaran@999: ? main.py
belaran@999: ? watcher/_watcher.c
belaran@999: ? watcher/watcher.py
belaran@999: ? xyzzy.txt
belaran@999: </screen>
belaran@999: <!-- END filenames.wdir-relname -->
belaran@999: 
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Telling you what's going on</title>
belaran@999: 
belaran@999:     <para id="x_54c">The <command role="hg-cmd" moreinfo="none">hg add</command> example in the
belaran@999:       preceding section illustrates something else that's helpful
belaran@999:       about Mercurial commands.  If a command operates on a file that
belaran@999:       you didn't name explicitly on the command line, it will usually
belaran@999:       print the name of the file, so that you will not be surprised
belaran@999:       what's going on.</para>
belaran@999: 
belaran@999:     <para id="x_54d">The principle here is of <emphasis>least
belaran@999: 	surprise</emphasis>.  If you've exactly named a file on the
belaran@999:       command line, there's no point in repeating it back at you.  If
belaran@999:       Mercurial is acting on a file <emphasis>implicitly</emphasis>, e.g.
belaran@999:       because you provided no names, or a directory, or a pattern (see
belaran@999:       below), it is safest to tell you what files it's operating on.</para>
belaran@999: 
belaran@999:     <para id="x_54e">For commands that behave this way, you can silence them
belaran@999:       using the <option role="hg-opt-global">-q</option> option.  You
belaran@999:       can also get them to print the name of every file, even those
belaran@999:       you've named explicitly, using the <option role="hg-opt-global">-v</option> option.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Using patterns to identify files</title>
belaran@999: 
belaran@999:     <para id="x_54f">In addition to working with file and directory names,
belaran@999:       Mercurial lets you use <emphasis>patterns</emphasis> to identify
belaran@999:       files.  Mercurial's pattern handling is expressive.</para>
belaran@999: 
belaran@999:     <para id="x_550">On Unix-like systems (Linux, MacOS, etc.), the job of
belaran@999:       matching file names to patterns normally falls to the shell.  On
belaran@999:       these systems, you must explicitly tell Mercurial that a name is
belaran@999:       a pattern.  On Windows, the shell does not expand patterns, so
belaran@999:       Mercurial will automatically identify names that are patterns,
belaran@999:       and expand them for you.</para>
belaran@999: 
belaran@999:     <para id="x_551">To provide a pattern in place of a regular name on the
belaran@999:       command line, the mechanism is simple:</para>
belaran@999:     <programlisting format="linespecific">syntax:patternbody</programlisting>
belaran@999:     <para id="x_552">That is, a pattern is identified by a short text string that
belaran@999:       says what kind of pattern this is, followed by a colon, followed
belaran@999:       by the actual pattern.</para>
belaran@999: 
belaran@999:     <para id="x_553">Mercurial supports two kinds of pattern syntax.  The most
belaran@999:       frequently used is called <literal moreinfo="none">glob</literal>; this is the
belaran@999:       same kind of pattern matching used by the Unix shell, and should
belaran@999:       be familiar to Windows command prompt users, too.</para>
belaran@999: 
belaran@999:     <para id="x_554">When Mercurial does automatic pattern matching on Windows,
belaran@999:       it uses <literal moreinfo="none">glob</literal> syntax.  You can thus omit the
belaran@999:       <quote><literal moreinfo="none">glob:</literal></quote> prefix on Windows, but
belaran@999:       it's safe to use it, too.</para>
belaran@999: 
belaran@999:     <para id="x_555">The <literal moreinfo="none">re</literal> syntax is more powerful; it lets
belaran@999:       you specify patterns using regular expressions, also known as
belaran@999:       regexps.</para>
belaran@999: 
belaran@999:     <para id="x_556">By the way, in the examples that follow, notice that I'm
belaran@999:       careful to wrap all of my patterns in quote characters, so that
belaran@999:       they won't get expanded by the shell before Mercurial sees
belaran@999:       them.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Shell-style <literal moreinfo="none">glob</literal> patterns</title>
belaran@999: 
belaran@999:       <para id="x_557">This is an overview of the kinds of patterns you can use
belaran@999: 	when you're matching on glob patterns.</para>
belaran@999: 
belaran@999:       <para id="x_558">The <quote><literal moreinfo="none">*</literal></quote> character matches
belaran@999: 	any string, within a single directory.</para>
belaran@999: 
belaran@999:       <!-- BEGIN filenames.glob.star -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add 'glob:*.py'</userinput>
belaran@999: adding main.py
belaran@999: </screen>
belaran@999: <!-- END filenames.glob.star -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_559">The <quote><literal moreinfo="none">**</literal></quote> pattern matches
belaran@999: 	any string, and crosses directory boundaries.  It's not a
belaran@999: 	standard Unix glob token, but it's accepted by several popular
belaran@999: 	Unix shells, and is very useful.</para>
belaran@999: 
belaran@999:       <!-- BEGIN filenames.glob.starstar -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:**.py'</userinput>
belaran@999: A examples/simple.py
belaran@999: A src/main.py
belaran@999: ? examples/performant.py
belaran@999: ? setup.py
belaran@999: ? src/watcher/watcher.py
belaran@999: </screen>
belaran@999: <!-- END filenames.glob.starstar -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_55a">The <quote><literal moreinfo="none">?</literal></quote> pattern matches
belaran@999: 	any single character.</para>
belaran@999: 
belaran@999:       <!-- BEGIN filenames.glob.question -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:**.?'</userinput>
belaran@999: ? src/watcher/_watcher.c
belaran@999: </screen>
belaran@999: <!-- END filenames.glob.question -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_55b">The <quote><literal moreinfo="none">[</literal></quote> character begins a
belaran@999: 	<emphasis>character class</emphasis>.  This matches any single
belaran@999: 	character within the class.  The class ends with a
belaran@999: 	<quote><literal moreinfo="none">]</literal></quote> character.  A class may
belaran@999: 	contain multiple <emphasis>range</emphasis>s of the form
belaran@999: 	<quote><literal moreinfo="none">a-f</literal></quote>, which is shorthand for
belaran@999: 	<quote><literal moreinfo="none">abcdef</literal></quote>.</para>
belaran@999: 
belaran@999: 	<!-- BEGIN filenames.glob.range -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:**[nr-t]'</userinput>
belaran@999: ? MANIFEST.in
belaran@999: ? src/xyzzy.txt
belaran@999: </screen>
belaran@999: <!-- END filenames.glob.range -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_55c">If the first character after the
belaran@999: 	<quote><literal moreinfo="none">[</literal></quote> in a character class is a
belaran@999: 	<quote><literal moreinfo="none">!</literal></quote>, it
belaran@999: 	<emphasis>negates</emphasis> the class, making it match any
belaran@999: 	single character not in the class.</para>
belaran@999: 
belaran@999:       <para id="x_55d">A <quote><literal moreinfo="none">{</literal></quote> begins a group of
belaran@999: 	subpatterns, where the whole group matches if any subpattern
belaran@999: 	in the group matches.  The <quote><literal moreinfo="none">,</literal></quote>
belaran@999: 	character separates subpatterns, and
belaran@999: 	<quote><literal moreinfo="none">}</literal></quote> ends the group.</para>
belaran@999: 
belaran@999:       <!-- BEGIN filenames.glob.group -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:*.{in,py}'</userinput>
belaran@999: ? MANIFEST.in
belaran@999: ? setup.py
belaran@999: </screen>
belaran@999: <!-- END filenames.glob.group -->
belaran@999: 
belaran@999: 
belaran@999:       <sect3>
belaran@999: 	<title>Watch out!</title>
belaran@999: 
belaran@999: 	<para id="x_55e">Don't forget that if you want to match a pattern in any
belaran@999: 	  directory, you should not be using the
belaran@999: 	  <quote><literal moreinfo="none">*</literal></quote> match-any token, as this
belaran@999: 	  will only match within one directory.  Instead, use the
belaran@999: 	  <quote><literal moreinfo="none">**</literal></quote> token.  This small
belaran@999: 	  example illustrates the difference between the two.</para>
belaran@999: 
belaran@999: 	  <!-- BEGIN filenames.glob.star-starstar -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:*.py'</userinput>
belaran@999: ? setup.py
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:**.py'</userinput>
belaran@999: A examples/simple.py
belaran@999: A src/main.py
belaran@999: ? examples/performant.py
belaran@999: ? setup.py
belaran@999: ? src/watcher/watcher.py
belaran@999: </screen>
belaran@999: <!-- END filenames.glob.star-starstar -->
belaran@999: 
belaran@999:       </sect3>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Regular expression matching with <literal moreinfo="none">re</literal>
belaran@999: 	patterns</title>
belaran@999: 
belaran@999:       <para id="x_55f">Mercurial accepts the same regular expression syntax as
belaran@999: 	the Python programming language (it uses Python's regexp
belaran@999: 	engine internally). This is based on the Perl language's
belaran@999: 	regexp syntax, which is the most popular dialect in use (it's
belaran@999: 	also used in Java, for example).</para>
belaran@999: 
belaran@999:       <para id="x_560">I won't discuss Mercurial's regexp dialect in any detail
belaran@999: 	here, as regexps are not often used.  Perl-style regexps are
belaran@999: 	in any case already exhaustively documented on a multitude of
belaran@999: 	web sites, and in many books.  Instead, I will focus here on a
belaran@999: 	few things you should know if you find yourself needing to use
belaran@999: 	regexps with Mercurial.</para>
belaran@999: 
belaran@999:       <para id="x_561">A regexp is matched against an entire file name, relative
belaran@999: 	to the root of the repository.  In other words, even if you're
belaran@999: 	already in subbdirectory <filename class="directory" moreinfo="none">foo</filename>, if you want to match files
belaran@999: 	under this directory, your pattern must start with
belaran@999: 	<quote><literal moreinfo="none">foo/</literal></quote>.</para>
belaran@999: 
belaran@999:       <para id="x_562">One thing to note, if you're familiar with Perl-style
belaran@999: 	regexps, is that Mercurial's are <emphasis>rooted</emphasis>.
belaran@999: 	That is, a regexp starts matching against the beginning of a
belaran@999: 	string; it doesn't look for a match anywhere within the
belaran@999: 	string.  To match anywhere in a string, start your pattern
belaran@999: 	with <quote><literal moreinfo="none">.*</literal></quote>.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Filtering files</title>
belaran@999: 
belaran@999:     <para id="x_563">Not only does Mercurial give you a variety of ways to
belaran@999:       specify files; it lets you further winnow those files using
belaran@999:       <emphasis>filters</emphasis>.  Commands that work with file
belaran@999:       names accept two filtering options.</para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_564"><option role="hg-opt-global">-I</option>, or
belaran@999: 	  <option role="hg-opt-global">--include</option>, lets you
belaran@999: 	  specify a pattern that file names must match in order to be
belaran@999: 	  processed.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_565"><option role="hg-opt-global">-X</option>, or
belaran@999: 	  <option role="hg-opt-global">--exclude</option>, gives you a
belaran@999: 	  way to <emphasis>avoid</emphasis> processing files, if they
belaran@999: 	  match this pattern.</para>
belaran@999:       </listitem></itemizedlist>
belaran@999:     <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,
belaran@999:       and intermix them as you please.  Mercurial interprets the
belaran@999:       patterns you provide using glob syntax by default (but you can
belaran@999:       use regexps if you need to).</para>
belaran@999: 
belaran@999:     <para id="x_567">You can read a <option role="hg-opt-global">-I</option>
belaran@999:       filter as <quote>process only the files that match this
belaran@999: 	filter</quote>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN filenames.filter.include -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status -I '*.in'</userinput>
belaran@999: ? MANIFEST.in
belaran@999: </screen>
belaran@999: <!-- END filenames.filter.include -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_568">The <option role="hg-opt-global">-X</option> filter is best
belaran@999:       read as <quote>process only the files that don't match this
belaran@999: 	pattern</quote>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN filenames.filter.exclude -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status -X '**.py' src</userinput>
belaran@999: ? src/watcher/_watcher.c
belaran@999: ? src/xyzzy.txt
belaran@999: </screen>
belaran@999: <!-- END filenames.filter.exclude -->
belaran@999: 
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Permanently ignoring unwanted files and directories</title>
belaran@999: 
belaran@999:     <para id="x_569">When you create a new repository, the chances are
belaran@999:       that over time it will grow to contain files that ought to
belaran@999:       <emphasis>not</emphasis> be managed by Mercurial, but which you
belaran@999:       don't want to see listed every time you run <command moreinfo="none">hg
belaran@999: 	status</command>.  For instance, <quote>build products</quote>
belaran@999:       are files that are created as part of a build but which should
belaran@999:       not be managed by a revision control system.  The most common
belaran@999:       build products are output files produced by software tools such
belaran@999:       as compilers.  As another example, many text editors litter a
belaran@999:       directory with lock files, temporary working files, and backup
belaran@999:       files, which it also makes no sense to manage.</para>
belaran@999: 
belaran@999:     <para id="x_6b4">To have Mercurial permanently ignore such files, create a
belaran@999:       file named <filename moreinfo="none">.hgignore</filename> in the root of your
belaran@999:       repository.  You <emphasis>should</emphasis> <command moreinfo="none">hg
belaran@999:       add</command> this file so that it gets tracked with the rest of
belaran@999:       your repository contents, since your collaborators will probably
belaran@999:       find it useful too.</para>
belaran@999: 
belaran@999:     <para id="x_6b5">By default, the <filename moreinfo="none">.hgignore</filename> file should
belaran@999:       contain a list of regular expressions, one per line.  Empty
belaran@999:       lines are skipped. Most people prefer to describe the files they
belaran@999:       want to ignore using the <quote>glob</quote> syntax that we
belaran@999:       described above, so a typical <filename moreinfo="none">.hgignore</filename>
belaran@999:       file will start with this directive:</para>
belaran@999: 
belaran@999:     <programlisting format="linespecific">syntax: glob</programlisting>
belaran@999: 
belaran@999:     <para id="x_6b6">This tells Mercurial to interpret the lines that follow as
belaran@999:       glob patterns, not regular expressions.</para>
belaran@999: 
belaran@999:     <para id="x_6b7">Here is a typical-looking <filename moreinfo="none">.hgignore</filename>
belaran@999:       file.</para>
belaran@999: 
belaran@999:     <programlisting format="linespecific">syntax: glob
belaran@999: # This line is a comment, and will be skipped.
belaran@999: # Empty lines are skipped too.
belaran@999: 
belaran@999: # Backup files left behind by the Emacs editor.
belaran@999: *~
belaran@999: 
belaran@999: # Lock files used by the Emacs editor.
belaran@999: # Notice that the "#" character is quoted with a backslash.
belaran@999: # This prevents it from being interpreted as starting a comment.
belaran@999: .\#*
belaran@999: 
belaran@999: # Temporary files used by the vim editor.
belaran@999: .*.swp
belaran@999: 
belaran@999: # A hidden file created by the Mac OS X Finder.
belaran@999: .DS_Store
belaran@999: </programlisting>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="sec:names:case">
belaran@999:     <title>Case sensitivity</title>
belaran@999: 
belaran@999:     <para id="x_56a">If you're working in a mixed development environment that
belaran@999:       contains both Linux (or other Unix) systems and Macs or Windows
belaran@999:       systems, you should keep in the back of your mind the knowledge
belaran@999:       that they treat the case (<quote>N</quote> versus
belaran@999:       <quote>n</quote>) of file names in incompatible ways.  This is
belaran@999:       not very likely to affect you, and it's easy to deal with if it
belaran@999:       does, but it could surprise you if you don't know about
belaran@999:       it.</para>
belaran@999: 
belaran@999:     <para id="x_56b">Operating systems and filesystems differ in the way they
belaran@999:       handle the <emphasis>case</emphasis> of characters in file and
belaran@999:       directory names.  There are three common ways to handle case in
belaran@999:       names.</para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_56c">Completely case insensitive.  Uppercase and
belaran@999: 	  lowercase versions of a letter are treated as identical,
belaran@999: 	  both when creating a file and during subsequent accesses.
belaran@999: 	  This is common on older DOS-based systems.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_56d">Case preserving, but insensitive.  When a file
belaran@999: 	  or directory is created, the case of its name is stored, and
belaran@999: 	  can be retrieved and displayed by the operating system.
belaran@999: 	  When an existing file is being looked up, its case is
belaran@999: 	  ignored.  This is the standard arrangement on Windows and
belaran@999: 	  MacOS.  The names <filename moreinfo="none">foo</filename> and
belaran@999: 	  <filename moreinfo="none">FoO</filename> identify the same file.  This
belaran@999: 	  treatment of uppercase and lowercase letters as
belaran@999: 	  interchangeable is also referred to as <emphasis>case
belaran@999: 	    folding</emphasis>.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_56e">Case sensitive.  The case of a name
belaran@999: 	  is significant at all times. The names
belaran@999: 	  <filename moreinfo="none">foo</filename> and <filename moreinfo="none">FoO</filename>
belaran@999: 	  identify different files.  This is the way Linux and Unix
belaran@999: 	  systems normally work.</para>
belaran@999:       </listitem></itemizedlist>
belaran@999: 
belaran@999:     <para id="x_56f">On Unix-like systems, it is possible to have any or all of
belaran@999:       the above ways of handling case in action at once.  For example,
belaran@999:       if you use a USB thumb drive formatted with a FAT32 filesystem
belaran@999:       on a Linux system, Linux will handle names on that filesystem in
belaran@999:       a case preserving, but insensitive, way.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Safe, portable repository storage</title>
belaran@999: 
belaran@999:       <para id="x_570">Mercurial's repository storage mechanism is <emphasis>case
belaran@999: 	  safe</emphasis>.  It translates file names so that they can
belaran@999: 	be safely stored on both case sensitive and case insensitive
belaran@999: 	filesystems.  This means that you can use normal file copying
belaran@999: 	tools to transfer a Mercurial repository onto, for example, a
belaran@999: 	USB thumb drive, and safely move that drive and repository
belaran@999: 	back and forth between a Mac, a PC running Windows, and a
belaran@999: 	Linux box.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Detecting case conflicts</title>
belaran@999: 
belaran@999:       <para id="x_571">When operating in the working directory, Mercurial honours
belaran@999: 	the naming policy of the filesystem where the working
belaran@999: 	directory is located.  If the filesystem is case preserving,
belaran@999: 	but insensitive, Mercurial will treat names that differ only
belaran@999: 	in case as the same.</para>
belaran@999: 
belaran@999:       <para id="x_572">An important aspect of this approach is that it is
belaran@999: 	possible to commit a changeset on a case sensitive (typically
belaran@999: 	Linux or Unix) filesystem that will cause trouble for users on
belaran@999: 	case insensitive (usually Windows and MacOS) users.  If a
belaran@999: 	Linux user commits changes to two files, one named
belaran@999: 	<filename moreinfo="none">myfile.c</filename> and the other named
belaran@999: 	<filename moreinfo="none">MyFile.C</filename>, they will be stored correctly
belaran@999: 	in the repository.  And in the working directories of other
belaran@999: 	Linux users, they will be correctly represented as separate
belaran@999: 	files.</para>
belaran@999: 
belaran@999:       <para id="x_573">If a Windows or Mac user pulls this change, they will not
belaran@999: 	initially have a problem, because Mercurial's repository
belaran@999: 	storage mechanism is case safe.  However, once they try to
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg update</command> the working
belaran@999: 	directory to that changeset, or <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  merge</command> with that changeset, Mercurial will spot the
belaran@999: 	conflict between the two file names that the filesystem would
belaran@999: 	treat as the same, and forbid the update or merge from
belaran@999: 	occurring.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Fixing a case conflict</title>
belaran@999: 
belaran@999:       <para id="x_574">If you are using Windows or a Mac in a mixed environment
belaran@999: 	where some of your collaborators are using Linux or Unix, and
belaran@999: 	Mercurial reports a case folding conflict when you try to
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg update</command> or <command role="hg-cmd" moreinfo="none">hg merge</command>, the procedure to fix the
belaran@999: 	problem is simple.</para>
belaran@999: 
belaran@999:       <para id="x_575">Just find a nearby Linux or Unix box, clone the problem
belaran@999: 	repository onto it, and use Mercurial's <command role="hg-cmd" moreinfo="none">hg rename</command> command to change the
belaran@999: 	names of any offending files or directories so that they will
belaran@999: 	no longer cause case folding conflicts.  Commit this change,
belaran@999: 	<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
belaran@999: 	MacOS system, and <command role="hg-cmd" moreinfo="none">hg update</command>
belaran@999: 	to the revision with the non-conflicting names.</para>
belaran@999: 
belaran@999:       <para id="x_576">The changeset with case-conflicting names will remain in
belaran@999: 	your project's history, and you still won't be able to
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg update</command> your working
belaran@999: 	directory to that changeset on a Windows or MacOS system, but
belaran@999: 	you can continue development unimpeded.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: </chapter>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "chapter")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN ch08 -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <chapter id="chap:branch">
belaran@999:   <?dbhtml filename="managing-releases-and-branchy-development.html"?>
belaran@999:   <title>Managing releases and branchy development</title>
belaran@999: 
belaran@999:   <para id="x_369">Mercurial provides several mechanisms for you to manage a
belaran@999:     project that is making progress on multiple fronts at once.  To
belaran@999:     understand these mechanisms, let's first take a brief look at a
belaran@999:     fairly normal software project structure.</para>
belaran@999: 
belaran@999:   <para id="x_36a">Many software projects issue periodic <quote>major</quote>
belaran@999:     releases that contain substantial new features.  In parallel, they
belaran@999:     may issue <quote>minor</quote> releases.  These are usually
belaran@999:     identical to the major releases off which they're based, but with
belaran@999:     a few bugs fixed.</para>
belaran@999: 
belaran@999:   <para id="x_36b">In this chapter, we'll start by talking about how to keep
belaran@999:     records of project milestones such as releases.  We'll then
belaran@999:     continue on to talk about the flow of work between different
belaran@999:     phases of a project, and how Mercurial can help you to isolate and
belaran@999:     manage this work.</para>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Giving a persistent name to a revision</title>
belaran@999: 
belaran@999:     <para id="x_36c">Once you decide that you'd like to call a particular
belaran@999:       revision a <quote>release</quote>, it's a good idea to record
belaran@999:       the identity of that revision. This will let you reproduce that
belaran@999:       release at a later date, for whatever purpose you might need at
belaran@999:       the time (reproducing a bug, porting to a new platform, etc).
belaran@999:       <!-- BEGIN tag.init -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init mytag</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd mytag</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo hello &gt; myfile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'Initial commit'</userinput>
belaran@999: adding myfile
belaran@999: </screen>
belaran@999: <!-- END tag.init -->
belaran@999: </para>
belaran@999: 
belaran@999:     <para id="x_36d">Mercurial lets you give a permanent name to any revision
belaran@999:       using the <command role="hg-cmd" moreinfo="none">hg tag</command> command.  Not
belaran@999:       surprisingly, these names are called <quote>tags</quote>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN tag.tag -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag v1.0</userinput>
belaran@999: </screen>
belaran@999: <!-- END tag.tag -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_36e">A tag is nothing more than a <quote>symbolic name</quote>
belaran@999:       for a revision.  Tags exist purely for your convenience, so that
belaran@999:       you have a handy permanent way to refer to a revision; Mercurial
belaran@999:       doesn't interpret the tag names you use in any way.  Neither
belaran@999:       does Mercurial place any restrictions on the name of a tag,
belaran@999:       beyond a few that are necessary to ensure that a tag can be
belaran@999:       parsed unambiguously.  A tag name cannot contain any of the
belaran@999:       following characters:</para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_36f">Colon (ASCII 58,
belaran@999: 	  <quote><literal moreinfo="none">:</literal></quote>)</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_370">Carriage return (ASCII 13,
belaran@999: 	  <quote><literal moreinfo="none">\r</literal></quote>)</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_371">Newline (ASCII 10,
belaran@999: 	  <quote><literal moreinfo="none">\n</literal></quote>)</para>
belaran@999:       </listitem></itemizedlist>
belaran@999: 
belaran@999:     <para id="x_372">You can use the <command role="hg-cmd" moreinfo="none">hg tags</command>
belaran@999:       command to display the tags present in your repository.  In the
belaran@999:       output, each tagged revision is identified first by its name,
belaran@999:       then by revision number, and finally by the unique hash of the
belaran@999:       revision.</para>
belaran@999: 
belaran@999:     <!-- BEGIN tag.tags -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tags</userinput>
belaran@999: tip                                1:f283c2669b38
belaran@999: v1.0                               0:0c957785065f
belaran@999: </screen>
belaran@999: <!-- END tag.tags -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_373">Notice that <literal moreinfo="none">tip</literal> is listed in the output
belaran@999:       of <command role="hg-cmd" moreinfo="none">hg tags</command>.  The
belaran@999:       <literal moreinfo="none">tip</literal> tag is a special <quote>floating</quote>
belaran@999:       tag, which always identifies the newest revision in the
belaran@999:       repository.</para>
belaran@999: 
belaran@999:     <para id="x_374">In the output of the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	tags</command> command, tags are listed in reverse order, by
belaran@999:       revision number.  This usually means that recent tags are listed
belaran@999:       before older tags.  It also means that <literal moreinfo="none">tip</literal> is
belaran@999:       always going to be the first tag listed in the output of
belaran@999:       <command role="hg-cmd" moreinfo="none">hg tags</command>.</para>
belaran@999: 
belaran@999:     <para id="x_375">When you run <command role="hg-cmd" moreinfo="none">hg log</command>, if it
belaran@999:       displays a revision that has tags associated with it, it will
belaran@999:       print those tags.</para>
belaran@999: 
belaran@999:     <!-- BEGIN tag.log -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log</userinput>
belaran@999: changeset:   1:f283c2669b38
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:16 2009 +0000
belaran@999: summary:     Added tag v1.0 for changeset 0c957785065f
belaran@999: 
belaran@999: changeset:   0:0c957785065f
belaran@999: tag:         v1.0
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:15 2009 +0000
belaran@999: summary:     Initial commit
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tag.log -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_376">Any time you need to provide a revision ID to a Mercurial
belaran@999:       command, the command will accept a tag name in its place.
belaran@999:       Internally, Mercurial will translate your tag name into the
belaran@999:       corresponding revision ID, then use that.</para>
belaran@999: 
belaran@999:     <!-- BEGIN tag.log.v1.0 -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo goodbye &gt; myfile2</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'Second commit'</userinput>
belaran@999: adding myfile2
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r v1.0</userinput>
belaran@999: changeset:   0:0c957785065f
belaran@999: tag:         v1.0
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:15 2009 +0000
belaran@999: summary:     Initial commit
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tag.log.v1.0 -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_377">There's no limit on the number of tags you can have in a
belaran@999:       repository, or on the number of tags that a single revision can
belaran@999:       have.  As a practical matter, it's not a great idea to have
belaran@999:       <quote>too many</quote> (a number which will vary from project
belaran@999:       to project), simply because tags are supposed to help you to
belaran@999:       find revisions.  If you have lots of tags, the ease of using
belaran@999:       them to identify revisions diminishes rapidly.</para>
belaran@999: 
belaran@999:     <para id="x_378">For example, if your project has milestones as frequent as
belaran@999:       every few days, it's perfectly reasonable to tag each one of
belaran@999:       those.  But if you have a continuous build system that makes
belaran@999:       sure every revision can be built cleanly, you'd be introducing a
belaran@999:       lot of noise if you were to tag every clean build.  Instead, you
belaran@999:       could tag failed builds (on the assumption that they're rare!),
belaran@999:       or simply not use tags to track buildability.</para>
belaran@999: 
belaran@999:     <para id="x_379">If you want to remove a tag that you no longer want, use
belaran@999:       <command role="hg-cmd" moreinfo="none">hg tag --remove</command>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN tag.remove -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag --remove v1.0</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tags</userinput>
belaran@999: tip                                3:0f446f1d1f7f
belaran@999: </screen>
belaran@999: <!-- END tag.remove -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_37a">You can also modify a tag at any time, so that it identifies
belaran@999:       a different revision, by simply issuing a new <command role="hg-cmd" moreinfo="none">hg tag</command> command. You'll have to use the
belaran@999:       <option role="hg-opt-tag">-f</option> option to tell Mercurial
belaran@999:       that you <emphasis>really</emphasis> want to update the
belaran@999:       tag.</para>
belaran@999: 
belaran@999:     <!-- BEGIN tag.replace -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag -r 1 v1.1</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tags</userinput>
belaran@999: tip                                4:12fc7bf92915
belaran@999: v1.1                               1:f283c2669b38
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag -r 2 v1.1</userinput>
belaran@999: abort: tag 'v1.1' already exists (use -f to force)
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag -f -r 2 v1.1</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tags</userinput>
belaran@999: tip                                5:17e25cf010af
belaran@999: v1.1                               2:737882b3cc76
belaran@999: </screen>
belaran@999: <!-- END tag.replace -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_37b">There will still be a permanent record of the previous
belaran@999:       identity of the tag, but Mercurial will no longer use it.
belaran@999:       There's thus no penalty to tagging the wrong revision; all you
belaran@999:       have to do is turn around and tag the correct revision once you
belaran@999:       discover your error.</para>
belaran@999: 
belaran@999:     <para id="x_37c">Mercurial stores tags in a normal revision-controlled file
belaran@999:       in your repository.  If you've created any tags, you'll find
belaran@999:       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
belaran@999:       this file, then automatically commits the change to it.  This
belaran@999:       means that every time you run <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	tag</command>, you'll see a corresponding changeset in the
belaran@999:       output of <command role="hg-cmd" moreinfo="none">hg log</command>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN tag.tip -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
belaran@999: changeset:   5:17e25cf010af
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:16 2009 +0000
belaran@999: summary:     Added tag v1.1 for changeset 737882b3cc76
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END tag.tip -->
belaran@999: 
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Handling tag conflicts during a merge</title>
belaran@999: 
belaran@999:       <para id="x_37d">You won't often need to care about the <filename role="special" moreinfo="none">.hgtags</filename> file, but it sometimes
belaran@999: 	makes its presence known during a merge.  The format of the
belaran@999: 	file is simple: it consists of a series of lines.  Each line
belaran@999: 	starts with a changeset hash, followed by a space, followed by
belaran@999: 	the name of a tag.</para>
belaran@999: 
belaran@999:       <para id="x_37e">If you're resolving a conflict in the <filename role="special" moreinfo="none">.hgtags</filename> file during a merge,
belaran@999: 	there's one twist to modifying the <filename role="special" moreinfo="none">.hgtags</filename> file: when Mercurial is
belaran@999: 	parsing the tags in a repository, it
belaran@999: 	<emphasis>never</emphasis> reads the working copy of the
belaran@999: 	<filename role="special" moreinfo="none">.hgtags</filename> file.  Instead, it
belaran@999: 	reads the <emphasis>most recently committed</emphasis>
belaran@999: 	revision of the file.</para>
belaran@999: 
belaran@999:       <para id="x_37f">An unfortunate consequence of this design is that you
belaran@999: 	can't actually verify that your merged <filename role="special" moreinfo="none">.hgtags</filename> file is correct until
belaran@999: 	<emphasis>after</emphasis> you've committed a change.  So if
belaran@999: 	you find yourself resolving a conflict on <filename role="special" moreinfo="none">.hgtags</filename> during a merge, be sure to
belaran@999: 	run <command role="hg-cmd" moreinfo="none">hg tags</command> after you commit.
belaran@999: 	If it finds an error in the <filename role="special" moreinfo="none">.hgtags</filename> file, it will report the
belaran@999: 	location of the error, which you can then fix and commit.  You
belaran@999: 	should then run <command role="hg-cmd" moreinfo="none">hg tags</command>
belaran@999: 	again, just to be sure that your fix is correct.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Tags and cloning</title>
belaran@999: 
belaran@999:       <para id="x_380">You may have noticed that the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  clone</command> command has a <option role="hg-opt-clone">-r</option> option that lets you clone
belaran@999: 	an exact copy of the repository as of a particular changeset.
belaran@999: 	The new clone will not contain any project history that comes
belaran@999: 	after the revision you specified.  This has an interaction
belaran@999: 	with tags that can surprise the unwary.</para>
belaran@999: 
belaran@999:       <para id="x_381">Recall that a tag is stored as a revision to
belaran@999: 	the <filename role="special" moreinfo="none">.hgtags</filename> file. When you
belaran@999: 	create a tag, the changeset in which its recorded refers to an
belaran@999: 	older changeset.  When you run <command role="hg-cmd" moreinfo="none">hg clone
belaran@999: 	  -r foo</command> to clone a repository as of tag
belaran@999: 	<literal moreinfo="none">foo</literal>, the new clone <emphasis>will not
belaran@999: 	  contain any revision newer than the one the tag refers to,
belaran@999: 	  including the revision where the tag was created</emphasis>.
belaran@999: 	The result is that you'll get exactly the right subset of the
belaran@999: 	project's history in the new repository, but
belaran@999: 	<emphasis>not</emphasis> the tag you might have
belaran@999: 	expected.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>When permanent tags are too much</title>
belaran@999: 
belaran@999:       <para id="x_382">Since Mercurial's tags are revision controlled and carried
belaran@999: 	around with a project's history, everyone you work with will
belaran@999: 	see the tags you create.  But giving names to revisions has
belaran@999: 	uses beyond simply noting that revision
belaran@999: 	<literal moreinfo="none">4237e45506ee</literal> is really
belaran@999: 	<literal moreinfo="none">v2.0.2</literal>.  If you're trying to track down a
belaran@999: 	subtle bug, you might want a tag to remind you of something
belaran@999: 	like <quote>Anne saw the symptoms with this
belaran@999: 	  revision</quote>.</para>
belaran@999: 
belaran@999:       <para id="x_383">For cases like this, what you might want to use are
belaran@999: 	<emphasis>local</emphasis> tags. You can create a local tag
belaran@999: 	with the <option role="hg-opt-tag">-l</option> option to the
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg tag</command> command.  This will
belaran@999: 	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
belaran@999: 	controlled.  Any tags you create using <option role="hg-opt-tag">-l</option> remain strictly local to the
belaran@999: 	repository you're currently working in.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>The flow of changes—big picture vs. little</title>
belaran@999: 
belaran@999:     <para id="x_384">To return to the outline I sketched at the
belaran@999:       beginning of the chapter, let's think about a project that has
belaran@999:       multiple concurrent pieces of work under development at
belaran@999:       once.</para>
belaran@999: 
belaran@999:     <para id="x_385">There might be a push for a new <quote>main</quote> release;
belaran@999:       a new minor bugfix release to the last main release; and an
belaran@999:       unexpected <quote>hot fix</quote> to an old release that is now
belaran@999:       in maintenance mode.</para>
belaran@999: 
belaran@999:     <para id="x_386">The usual way people refer to these different concurrent
belaran@999:       directions of development is as <quote>branches</quote>.
belaran@999:       However, we've already seen numerous times that Mercurial treats
belaran@999:       <emphasis>all of history</emphasis> as a series of branches and
belaran@999:       merges.  Really, what we have here is two ideas that are
belaran@999:       peripherally related, but which happen to share a name.</para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_387"><quote>Big picture</quote> branches represent
belaran@999: 	  the sweep of a project's evolution; people give them names,
belaran@999: 	  and talk about them in conversation.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_388"><quote>Little picture</quote> branches are
belaran@999: 	  artefacts of the day-to-day activity of developing and
belaran@999: 	  merging changes.  They expose the narrative of how the code
belaran@999: 	  was developed.</para>
belaran@999:       </listitem></itemizedlist>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Managing big-picture branches in repositories</title>
belaran@999: 
belaran@999:     <para id="x_389">The easiest way to isolate a <quote>big picture</quote>
belaran@999:       branch in Mercurial is in a dedicated repository.  If you have
belaran@999:       an existing shared repository—let's call it
belaran@999:       <literal moreinfo="none">myproject</literal>—that reaches a
belaran@999:       <quote>1.0</quote> milestone, you can start to prepare for
belaran@999:       future maintenance releases on top of version 1.0 by tagging the
belaran@999:       revision from which you prepared the 1.0 release.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-repo.tag -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd myproject</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag v1.0</userinput>
belaran@999: </screen>
belaran@999: <!-- END branch-repo.tag -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_38a">You can then clone a new shared
belaran@999:       <literal moreinfo="none">myproject-1.0.1</literal> repository as of that
belaran@999:       tag.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-repo.clone -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone myproject myproject-1.0.1</userinput>
belaran@999: updating working directory
belaran@999: 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: </screen>
belaran@999: <!-- END branch-repo.clone -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_38b">Afterwards, if someone needs to work on a bug fix that ought
belaran@999:       to go into an upcoming 1.0.1 minor release, they clone the
belaran@999:       <literal moreinfo="none">myproject-1.0.1</literal> repository, make their
belaran@999:       changes, and push them back.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-repo.bugfix -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone myproject-1.0.1 my-1.0.1-bugfix</userinput>
belaran@999: updating working directory
belaran@999: 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-1.0.1-bugfix</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'I fixed a bug using only echo!' &gt;&gt; myfile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Important fix for 1.0.1'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push</userinput>
belaran@999: pushing to /tmp/branch-repo3rVLLS/myproject-1.0.1
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 1 changes to 1 files
belaran@999: </screen>
belaran@999: <!-- END branch-repo.bugfix -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_38c">Meanwhile, development for
belaran@999:       the next major release can continue, isolated and unabated, in
belaran@999:       the <literal moreinfo="none">myproject</literal> repository.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-repo.new -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone myproject my-feature</userinput>
belaran@999: updating working directory
belaran@999: 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-feature</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'This sure is an exciting new feature!' &gt; mynewfile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'New feature'</userinput>
belaran@999: adding mynewfile
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push</userinput>
belaran@999: pushing to /tmp/branch-repo3rVLLS/myproject
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 1 changes to 1 files
belaran@999: </screen>
belaran@999: <!-- END branch-repo.new -->
belaran@999: 
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Don't repeat yourself: merging across branches</title>
belaran@999: 
belaran@999:     <para id="x_38d">In many cases, if you have a bug to fix on a maintenance
belaran@999:       branch, the chances are good that the bug exists on your
belaran@999:       project's main branch (and possibly other maintenance branches,
belaran@999:       too).  It's a rare developer who wants to fix the same bug
belaran@999:       multiple times, so let's look at a few ways that Mercurial can
belaran@999:       help you to manage these bugfixes without duplicating your
belaran@999:       work.</para>
belaran@999: 
belaran@999:     <para id="x_38e">In the simplest instance, all you need to do is pull changes
belaran@999:       from your maintenance branch into your local clone of the target
belaran@999:       branch.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-repo.pull -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone myproject myproject-merge</userinput>
belaran@999: updating working directory
belaran@999: 3 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd myproject-merge</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../myproject-1.0.1</userinput>
belaran@999: pulling from ../myproject-1.0.1
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 1 changes to 1 files (+1 heads)
belaran@999: (run 'hg heads' to see heads, 'hg merge' to merge)
belaran@999: </screen>
belaran@999: <!-- END branch-repo.pull -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_38f">You'll then need to merge the heads of the two branches, and
belaran@999:       push back to the main branch.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-repo.merge -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: (branch merge, don't forget to commit)
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Merge bugfix from 1.0.1 branch'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push</userinput>
belaran@999: pushing to /tmp/branch-repo3rVLLS/myproject
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 2 changesets with 1 changes to 1 files
belaran@999: </screen>
belaran@999: <!-- END branch-repo.merge -->
belaran@999: 
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Naming branches within one repository</title>
belaran@999: 
belaran@999:     <para id="x_390">In most instances, isolating branches in repositories is the
belaran@999:       right approach.  Its simplicity makes it easy to understand; and
belaran@999:       so it's hard to make mistakes.  There's a one-to-one
belaran@999:       relationship between branches you're working in and directories
belaran@999:       on your system.  This lets you use normal (non-Mercurial-aware)
belaran@999:       tools to work on files within a branch/repository.</para>
belaran@999: 
belaran@999:     <para id="x_391">If you're more in the <quote>power user</quote> category
belaran@999:       (<emphasis>and</emphasis> your collaborators are too), there is
belaran@999:       an alternative way of handling branches that you can consider.
belaran@999:       I've already mentioned the human-level distinction between
belaran@999:       <quote>small picture</quote> and <quote>big picture</quote>
belaran@999:       branches.  While Mercurial works with multiple <quote>small
belaran@999: 	picture</quote> branches in a repository all the time (for
belaran@999:       example after you pull changes in, but before you merge them),
belaran@999:       it can <emphasis>also</emphasis> work with multiple <quote>big
belaran@999: 	picture</quote> branches.</para>
belaran@999: 
belaran@999:     <para id="x_392">The key to working this way is that Mercurial lets you
belaran@999:       assign a persistent <emphasis>name</emphasis> to a branch.
belaran@999:       There always exists a branch named <literal moreinfo="none">default</literal>.
belaran@999:       Even before you start naming branches yourself, you can find
belaran@999:       traces of the <literal moreinfo="none">default</literal> branch if you look for
belaran@999:       them.</para>
belaran@999: 
belaran@999:     <para id="x_393">As an example, when you run the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	commit</command> command, and it pops up your editor so that
belaran@999:       you can enter a commit message, look for a line that contains
belaran@999:       the text <quote><literal moreinfo="none">HG: branch default</literal></quote> at
belaran@999:       the bottom. This is telling you that your commit will occur on
belaran@999:       the branch named <literal moreinfo="none">default</literal>.</para>
belaran@999: 
belaran@999:     <para id="x_394">To start working with named branches, use the <command role="hg-cmd" moreinfo="none">hg branches</command> command.  This command
belaran@999:       lists the named branches already present in your repository,
belaran@999:       telling you which changeset is the tip of each.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-named.branches -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
belaran@999: changeset:   0:90897f9e54e3
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:42 2009 +0000
belaran@999: summary:     Initial commit
belaran@999: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branches</userinput>
belaran@999: default                        0:90897f9e54e3
belaran@999: </screen>
belaran@999: <!-- END branch-named.branches -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_395">Since you haven't created any named branches yet, the only
belaran@999:       one that exists is <literal moreinfo="none">default</literal>.</para>
belaran@999: 
belaran@999:     <para id="x_396">To find out what the <quote>current</quote> branch is, run
belaran@999:       the <command role="hg-cmd" moreinfo="none">hg branch</command> command, giving
belaran@999:       it no arguments.  This tells you what branch the parent of the
belaran@999:       current changeset is on.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-named.branch -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch</userinput>
belaran@999: default
belaran@999: </screen>
belaran@999: <!-- END branch-named.branch -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_397">To create a new branch, run the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	branch</command> command again.  This time, give it one
belaran@999:       argument: the name of the branch you want to create.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-named.create -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch foo</userinput>
belaran@999: marked working directory as branch foo
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch</userinput>
belaran@999: foo
belaran@999: </screen>
belaran@999: <!-- END branch-named.create -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_398">After you've created a branch, you might wonder what effect
belaran@999:       the <command role="hg-cmd" moreinfo="none">hg branch</command> command has had.
belaran@999:       What do the <command role="hg-cmd" moreinfo="none">hg status</command> and
belaran@999:       <command role="hg-cmd" moreinfo="none">hg tip</command> commands report?</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-named.status -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
belaran@999: changeset:   0:90897f9e54e3
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:42 2009 +0000
belaran@999: summary:     Initial commit
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END branch-named.status -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_399">Nothing has changed in the
belaran@999:       working directory, and there's been no new history created.  As
belaran@999:       this suggests, running the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	branch</command> command has no permanent effect; it only
belaran@999:       tells Mercurial what branch name to use the
belaran@999:       <emphasis>next</emphasis> time you commit a changeset.</para>
belaran@999: 
belaran@999:     <para id="x_39a">When you commit a change, Mercurial records the name of the
belaran@999:       branch on which you committed.  Once you've switched from the
belaran@999:       <literal moreinfo="none">default</literal> branch to another and committed,
belaran@999:       you'll see the name of the new branch show up in the output of
belaran@999:       <command role="hg-cmd" moreinfo="none">hg log</command>, <command role="hg-cmd" moreinfo="none">hg tip</command>, and other commands that
belaran@999:       display the same kind of output.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-named.commit -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'hello again' &gt;&gt; myfile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Second commit'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
belaran@999: changeset:   1:5656f8ffdd49
belaran@999: branch:      foo
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:42 2009 +0000
belaran@999: summary:     Second commit
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END branch-named.commit -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_39b">The <command role="hg-cmd" moreinfo="none">hg log</command>-like commands
belaran@999:       will print the branch name of every changeset that's not on the
belaran@999:       <literal moreinfo="none">default</literal> branch.  As a result, if you never
belaran@999:       use named branches, you'll never see this information.</para>
belaran@999: 
belaran@999:     <para id="x_39c">Once you've named a branch and committed a change with that
belaran@999:       name, every subsequent commit that descends from that change
belaran@999:       will inherit the same branch name.  You can change the name of a
belaran@999:       branch at any time, using the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	branch</command> command.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-named.rebranch -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch</userinput>
belaran@999: foo
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch bar</userinput>
belaran@999: marked working directory as branch bar
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo new file &gt; newfile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'Third commit'</userinput>
belaran@999: adding newfile
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
belaran@999: changeset:   2:c59d680fc2ec
belaran@999: branch:      bar
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:42 2009 +0000
belaran@999: summary:     Third commit
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END branch-named.rebranch -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_39d">In practice, this is something you won't do very often, as
belaran@999:       branch names tend to have fairly long lifetimes.  (This isn't a
belaran@999:       rule, just an observation.)</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Dealing with multiple named branches in a
belaran@999:       repository</title>
belaran@999: 
belaran@999:     <para id="x_39e">If you have more than one named branch in a repository,
belaran@999:       Mercurial will remember the branch that your working directory
belaran@999:       is on when you start a command like <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	update</command> or <command role="hg-cmd" moreinfo="none">hg pull
belaran@999: 	-u</command>.  It will update the working directory to the tip
belaran@999:       of this branch, no matter what the <quote>repo-wide</quote> tip
belaran@999:       is.  To update to a revision that's on a different named branch,
belaran@999:       you may need to use the <option role="hg-opt-update">-C</option>
belaran@999:       option to <command role="hg-cmd" moreinfo="none">hg update</command>.</para>
belaran@999: 
belaran@999:     <para id="x_39f">This behavior is a little subtle, so let's see it in
belaran@999:       action.  First, let's remind ourselves what branch we're
belaran@999:       currently on, and what branches are in our repository.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-named.parents -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
belaran@999: changeset:   2:c59d680fc2ec
belaran@999: branch:      bar
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:42 2009 +0000
belaran@999: summary:     Third commit
belaran@999: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branches</userinput>
belaran@999: bar                            2:c59d680fc2ec
belaran@999: foo                            1:5656f8ffdd49 (inactive)
belaran@999: default                        0:90897f9e54e3 (inactive)
belaran@999: </screen>
belaran@999: <!-- END branch-named.parents -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_3a0">We're on the <literal moreinfo="none">bar</literal> branch, but there also
belaran@999:       exists an older <command role="hg-cmd" moreinfo="none">hg foo</command>
belaran@999:       branch.</para>
belaran@999: 
belaran@999:     <para id="x_3a1">We can <command role="hg-cmd" moreinfo="none">hg update</command> back and
belaran@999:       forth between the tips of the <literal moreinfo="none">foo</literal> and
belaran@999:       <literal moreinfo="none">bar</literal> branches without needing to use the
belaran@999:       <option role="hg-opt-update">-C</option> option, because this
belaran@999:       only involves going backwards and forwards linearly through our
belaran@999:       change history.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-named.update-switchy -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update foo</userinput>
belaran@999: 0 files updated, 0 files merged, 1 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
belaran@999: changeset:   1:5656f8ffdd49
belaran@999: branch:      foo
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:42 2009 +0000
belaran@999: summary:     Second commit
belaran@999: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update bar</userinput>
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
belaran@999: changeset:   2:c59d680fc2ec
belaran@999: branch:      bar
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:42 2009 +0000
belaran@999: summary:     Third commit
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END branch-named.update-switchy -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_3a2">If we go back to the <literal moreinfo="none">foo</literal> branch and then
belaran@999:       run <command role="hg-cmd" moreinfo="none">hg update</command>, it will keep us
belaran@999:       on <literal moreinfo="none">foo</literal>, not move us to the tip of
belaran@999:       <literal moreinfo="none">bar</literal>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-named.update-nothing -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update foo</userinput>
belaran@999: 0 files updated, 0 files merged, 1 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update</userinput>
belaran@999: 0 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: </screen>
belaran@999: <!-- END branch-named.update-nothing -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_3a3">Committing a new change on the <literal moreinfo="none">foo</literal> branch
belaran@999:       introduces a new head.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-named.foo-commit -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo something &gt; somefile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'New file'</userinput>
belaran@999: adding somefile
belaran@999: created new head
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg heads</userinput>
belaran@999: changeset:   3:4dd2f7a37288
belaran@999: branch:      foo
belaran@999: tag:         tip
belaran@999: parent:      1:5656f8ffdd49
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:43 2009 +0000
belaran@999: summary:     New file
belaran@999: 
belaran@999: changeset:   2:c59d680fc2ec
belaran@999: branch:      bar
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:42 2009 +0000
belaran@999: summary:     Third commit
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END branch-named.foo-commit -->
belaran@999: 
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Branch names and merging</title>
belaran@999: 
belaran@999:     <para id="x_3a4">As you've probably noticed, merges in Mercurial are not
belaran@999:       symmetrical. Let's say our repository has two heads, 17 and 23.
belaran@999:       If I <command role="hg-cmd" moreinfo="none">hg update</command> to 17 and then
belaran@999:       <command role="hg-cmd" moreinfo="none">hg merge</command> with 23, Mercurial
belaran@999:       records 17 as the first parent of the merge, and 23 as the
belaran@999:       second.  Whereas if I <command role="hg-cmd" moreinfo="none">hg update</command>
belaran@999:       to 23 and then <command role="hg-cmd" moreinfo="none">hg merge</command> with
belaran@999:       17, it records 23 as the first parent, and 17 as the
belaran@999:       second.</para>
belaran@999: 
belaran@999:     <para id="x_3a5">This affects Mercurial's choice of branch name when you
belaran@999:       merge.  After a merge, Mercurial will retain the branch name of
belaran@999:       the first parent when you commit the result of the merge.  If
belaran@999:       your first parent's branch name is <literal moreinfo="none">foo</literal>, and
belaran@999:       you merge with <literal moreinfo="none">bar</literal>, the branch name will
belaran@999:       still be <literal moreinfo="none">foo</literal> after you merge.</para>
belaran@999: 
belaran@999:     <para id="x_3a6">It's not unusual for a repository to contain multiple heads,
belaran@999:       each with the same branch name.  Let's say I'm working on the
belaran@999:       <literal moreinfo="none">foo</literal> branch, and so are you.  We commit
belaran@999:       different changes; I pull your changes; I now have two heads,
belaran@999:       each claiming to be on the <literal moreinfo="none">foo</literal> branch.  The
belaran@999:       result of a merge will be a single head on the
belaran@999:       <literal moreinfo="none">foo</literal> branch, as you might hope.</para>
belaran@999: 
belaran@999:     <para id="x_3a7">But if I'm working on the <literal moreinfo="none">bar</literal> branch, and
belaran@999:       I merge work from the <literal moreinfo="none">foo</literal> branch, the result
belaran@999:       will remain on the <literal moreinfo="none">bar</literal> branch.</para>
belaran@999: 
belaran@999:     <!-- BEGIN branch-named.merge -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch</userinput>
belaran@999: bar
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge foo</userinput>
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: (branch merge, don't forget to commit)
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Merge'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
belaran@999: changeset:   4:9f05d4ef3efe
belaran@999: branch:      bar
belaran@999: tag:         tip
belaran@999: parent:      2:c59d680fc2ec
belaran@999: parent:      3:4dd2f7a37288
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:44 2009 +0000
belaran@999: summary:     Merge
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END branch-named.merge -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_3a8">To give a more concrete example, if I'm working on the
belaran@999:       <literal moreinfo="none">bleeding-edge</literal> branch, and I want to bring in
belaran@999:       the latest fixes from the <literal moreinfo="none">stable</literal> branch,
belaran@999:       Mercurial will choose the <quote>right</quote>
belaran@999:       (<literal moreinfo="none">bleeding-edge</literal>) branch name when I pull and
belaran@999:       merge from <literal moreinfo="none">stable</literal>.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Branch naming is generally useful</title>
belaran@999: 
belaran@999:     <para id="x_3a9">You shouldn't think of named branches as applicable only to
belaran@999:       situations where you have multiple long-lived branches
belaran@999:       cohabiting in a single repository.  They're very useful even in
belaran@999:       the one-branch-per-repository case.</para>
belaran@999: 
belaran@999:     <para id="x_3aa">In the simplest case, giving a name to each branch gives you
belaran@999:       a permanent record of which branch a changeset originated on.
belaran@999:       This gives you more context when you're trying to follow the
belaran@999:       history of a long-lived branchy project.</para>
belaran@999: 
belaran@999:     <para id="x_3ab">If you're working with shared repositories, you can set up a
belaran@999:       <literal role="hook" moreinfo="none">pretxnchangegroup</literal> hook on each
belaran@999:       that will block incoming changes that have the
belaran@999:       <quote>wrong</quote> branch name.  This provides a simple, but
belaran@999:       effective, defence against people accidentally pushing changes
belaran@999:       from a <quote>bleeding edge</quote> branch to a
belaran@999:       <quote>stable</quote> branch.  Such a hook might look like this
belaran@999:       inside the shared repo's <filename role="special" moreinfo="none">
belaran@999: 	/.hgrc</filename>.</para>
belaran@999:     <programlisting format="linespecific">[hooks]
belaran@999: pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting>
belaran@999:   </sect1>
belaran@999: </chapter>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "chapter")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN ch09 -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <chapter id="chap:undo">
belaran@999:   <?dbhtml filename="finding-and-fixing-mistakes.html"?>
belaran@999:   <title>Finding and fixing mistakes</title>
belaran@999: 
belaran@999:   <para id="x_d2">To err might be human, but to really handle the consequences
belaran@999:     well takes a top-notch revision control system.  In this chapter,
belaran@999:     we'll discuss some of the techniques you can use when you find
belaran@999:     that a problem has crept into your project.  Mercurial has some
belaran@999:     highly capable features that will help you to isolate the sources
belaran@999:     of problems, and to handle them appropriately.</para>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Erasing local history</title>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>The accidental commit</title>
belaran@999: 
belaran@999:       <para id="x_d3">I have the occasional but persistent problem of typing
belaran@999: 	rather more quickly than I can think, which sometimes results
belaran@999: 	in me committing a changeset that is either incomplete or
belaran@999: 	plain wrong.  In my case, the usual kind of incomplete
belaran@999: 	changeset is one in which I've created a new source file, but
belaran@999: 	forgotten to <command role="hg-cmd" moreinfo="none">hg add</command> it.  A
belaran@999: 	<quote>plain wrong</quote> changeset is not as common, but no
belaran@999: 	less annoying.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2 id="sec:undo:rollback">
belaran@999:       <title>Rolling back a transaction</title>
belaran@999: 
belaran@999:       <para id="x_d4">In <xref linkend="sec:concepts:txn"/>, I
belaran@999: 	mentioned that Mercurial treats each modification of a
belaran@999: 	repository as a <emphasis>transaction</emphasis>.  Every time
belaran@999: 	you commit a changeset or pull changes from another
belaran@999: 	repository, Mercurial remembers what you did.  You can undo,
belaran@999: 	or <emphasis>roll back</emphasis>, exactly one of these
belaran@999: 	actions using the <command role="hg-cmd" moreinfo="none">hg rollback</command>
belaran@999: 	command.  (See <xref linkend="sec:undo:rollback-after-push"/>
belaran@999: 	for an important caveat about the use of this command.)</para>
belaran@999: 
belaran@999:       <para id="x_d5">Here's a mistake that I often find myself making:
belaran@999: 	committing a change in which I've created a new file, but
belaran@999: 	forgotten to <command role="hg-cmd" moreinfo="none">hg add</command>
belaran@999: 	it.</para>
belaran@999: 
belaran@999:       <!-- BEGIN rollback.commit -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: M a
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b &gt; b</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Add file b'</userinput>
belaran@999: </screen>
belaran@999: <!-- END rollback.commit -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_d6">Looking at the output of <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  status</command> after the commit immediately confirms the
belaran@999: 	error.</para>
belaran@999: 
belaran@999:       <!-- BEGIN rollback.status -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: ? b
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
belaran@999: changeset:   1:246e2aada1c5
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:14 2009 +0000
belaran@999: summary:     Add file b
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END rollback.status -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_d7">The commit captured the changes to the file
belaran@999: 	<filename moreinfo="none">a</filename>, but not the new file
belaran@999: 	<filename moreinfo="none">b</filename>.  If I were to push this changeset to a
belaran@999: 	repository that I shared with a colleague, the chances are
belaran@999: 	high that something in <filename moreinfo="none">a</filename> would refer to
belaran@999: 	<filename moreinfo="none">b</filename>, which would not be present in their
belaran@999: 	repository when they pulled my changes.  I would thus become
belaran@999: 	the object of some indignation.</para>
belaran@999: 
belaran@999:       <para id="x_d8">However, luck is with me—I've caught my error
belaran@999: 	before I pushed the changeset.  I use the <command role="hg-cmd" moreinfo="none">hg rollback</command> command, and Mercurial
belaran@999: 	makes that last changeset vanish.</para>
belaran@999: 
belaran@999:       <!-- BEGIN rollback.rollback -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rollback</userinput>
belaran@999: rolling back last transaction
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
belaran@999: changeset:   0:c37ce4157509
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:14 2009 +0000
belaran@999: summary:     First commit
belaran@999: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: M a
belaran@999: ? b
belaran@999: </screen>
belaran@999: <!-- END rollback.rollback -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_d9">Notice that the changeset is no longer present in the
belaran@999: 	repository's history, and the working directory once again
belaran@999: 	thinks that the file <filename moreinfo="none">a</filename> is modified.  The
belaran@999: 	commit and rollback have left the working directory exactly as
belaran@999: 	it was prior to the commit; the changeset has been completely
belaran@999: 	erased.  I can now safely <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  add</command> the file <filename moreinfo="none">b</filename>, and rerun my
belaran@999: 	commit.</para>
belaran@999: 
belaran@999:       <!-- BEGIN rollback.add -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add b</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Add file b, this time for real'</userinput>
belaran@999: </screen>
belaran@999: <!-- END rollback.add -->
belaran@999: 
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>The erroneous pull</title>
belaran@999: 
belaran@999:       <para id="x_da">It's common practice with Mercurial to maintain separate
belaran@999: 	development branches of a project in different repositories.
belaran@999: 	Your development team might have one shared repository for
belaran@999: 	your project's <quote>0.9</quote> release, and another,
belaran@999: 	containing different changes, for the <quote>1.0</quote>
belaran@999: 	release.</para>
belaran@999: 
belaran@999:       <para id="x_db">Given this, you can imagine that the consequences could be
belaran@999: 	messy if you had a local <quote>0.9</quote> repository, and
belaran@999: 	accidentally pulled changes from the shared <quote>1.0</quote>
belaran@999: 	repository into it.  At worst, you could be paying
belaran@999: 	insufficient attention, and push those changes into the shared
belaran@999: 	<quote>0.9</quote> tree, confusing your entire team (but don't
belaran@999: 	worry, we'll return to this horror scenario later).  However,
belaran@999: 	it's more likely that you'll notice immediately, because
belaran@999: 	Mercurial will display the URL it's pulling from, or you will
belaran@999: 	see it pull a suspiciously large number of changes into the
belaran@999: 	repository.</para>
belaran@999: 
belaran@999:       <para id="x_dc">The <command role="hg-cmd" moreinfo="none">hg rollback</command> command
belaran@999: 	will work nicely to expunge all of the changesets that you
belaran@999: 	just pulled.  Mercurial groups all changes from one <command role="hg-cmd" moreinfo="none">hg pull</command> into a single transaction,
belaran@999: 	so one <command role="hg-cmd" moreinfo="none">hg rollback</command> is all you
belaran@999: 	need to undo this mistake.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2 id="sec:undo:rollback-after-push">
belaran@999:       <title>Rolling back is useless once you've pushed</title>
belaran@999: 
belaran@999:       <para id="x_dd">The value of the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  rollback</command> command drops to zero once you've pushed
belaran@999: 	your changes to another repository.  Rolling back a change
belaran@999: 	makes it disappear entirely, but <emphasis>only</emphasis> in
belaran@999: 	the repository in which you perform the <command role="hg-cmd" moreinfo="none">hg rollback</command>.  Because a rollback
belaran@999: 	eliminates history, there's no way for the disappearance of a
belaran@999: 	change to propagate between repositories.</para>
belaran@999: 
belaran@999:       <para id="x_de">If you've pushed a change to another
belaran@999: 	repository—particularly if it's a shared
belaran@999: 	repository—it has essentially <quote>escaped into the
belaran@999: 	  wild,</quote> and you'll have to recover from your mistake
belaran@999: 	in a different way.  If you push a changeset somewhere, then
belaran@999: 	roll it back, then pull from the repository you pushed to, the
belaran@999: 	changeset you thought you'd gotten rid of will simply reappear
belaran@999: 	in your repository.</para>
belaran@999: 
belaran@999:       <para id="x_df">(If you absolutely know for sure that the change
belaran@999: 	you want to roll back is the most recent change in the
belaran@999: 	repository that you pushed to, <emphasis>and</emphasis> you
belaran@999: 	know that nobody else could have pulled it from that
belaran@999: 	repository, you can roll back the changeset there, too, but
belaran@999: 	you really should not expect this to work reliably.  Sooner or
belaran@999: 	later a change really will make it into a repository that you
belaran@999: 	don't directly control (or have forgotten about), and come
belaran@999: 	back to bite you.)</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>You can only roll back once</title>
belaran@999: 
belaran@999:       <para id="x_e0">Mercurial stores exactly one transaction in its
belaran@999: 	transaction log; that transaction is the most recent one that
belaran@999: 	occurred in the repository. This means that you can only roll
belaran@999: 	back one transaction.  If you expect to be able to roll back
belaran@999: 	one transaction, then its predecessor, this is not the
belaran@999: 	behavior you will get.</para>
belaran@999: 
belaran@999:       <!-- BEGIN rollback.twice -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rollback</userinput>
belaran@999: rolling back last transaction
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rollback</userinput>
belaran@999: no rollback information available
belaran@999: </screen>
belaran@999: <!-- END rollback.twice -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_e1">Once you've rolled back one transaction in a repository,
belaran@999: 	you can't roll back again in that repository until you perform
belaran@999: 	another commit or pull.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Reverting the mistaken change</title>
belaran@999: 
belaran@999:     <para id="x_e2">If you make a modification to a file, and decide that you
belaran@999:       really didn't want to change the file at all, and you haven't
belaran@999:       yet committed your changes, the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	revert</command> command is the one you'll need.  It looks at
belaran@999:       the changeset that's the parent of the working directory, and
belaran@999:       restores the contents of the file to their state as of that
belaran@999:       changeset. (That's a long-winded way of saying that, in the
belaran@999:       normal case, it undoes your modifications.)</para>
belaran@999: 
belaran@999:     <para id="x_e3">Let's illustrate how the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	revert</command> command works with yet another small example.
belaran@999:       We'll begin by modifying a file that Mercurial is already
belaran@999:       tracking.</para>
belaran@999: 
belaran@999:     <!-- BEGIN daily.revert.modify -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat file</userinput>
belaran@999: original content
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo unwanted change &gt;&gt; file</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff file</userinput>
belaran@999: diff -r 2eacf948d309 file
belaran@999: --- a/file	Sun Aug 16 14:05:00 2009 +0000
belaran@999: +++ b/file	Sun Aug 16 14:05:00 2009 +0000
belaran@999: @@ -1,1 +1,2 @@
belaran@999:  original content
belaran@999: +unwanted change
belaran@999: </screen>
belaran@999: <!-- END daily.revert.modify -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_e4">If we don't
belaran@999:       want that change, we can simply <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	revert</command> the file.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.revert.unmodify -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: M file
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert file</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat file</userinput>
belaran@999: original content
belaran@999: </screen>
belaran@999: <!-- END daily.revert.unmodify -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_e5">The <command role="hg-cmd" moreinfo="none">hg revert</command> command
belaran@999:       provides us with an extra degree of safety by saving our
belaran@999:       modified file with a <filename moreinfo="none">.orig</filename>
belaran@999:       extension.</para>
belaran@999: 
belaran@999:     <!-- BEGIN daily.revert.status -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: ? file.orig
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat file.orig</userinput>
belaran@999: original content
belaran@999: unwanted change
belaran@999: </screen>
belaran@999: <!-- END daily.revert.status -->
belaran@999: 
belaran@999: 
belaran@999:     <tip>
belaran@999:       <title>Be careful with <filename moreinfo="none">.orig</filename> files</title>
belaran@999: 
belaran@999:       <para id="x_6b8">It's extremely unlikely that you are either using
belaran@999: 	Mercurial to manage files with <filename moreinfo="none">.orig</filename>
belaran@999: 	extensions or that you even care about the contents of such
belaran@999: 	files.  Just in case, though, it's useful to remember that
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg revert</command> will
belaran@999: 	unconditionally overwrite an existing file with a
belaran@999: 	<filename moreinfo="none">.orig</filename> extension. For instance, if you
belaran@999: 	already have a file named <filename moreinfo="none">foo.orig</filename> when
belaran@999: 	you revert <filename moreinfo="none">foo</filename>, the contents of
belaran@999: 	<filename moreinfo="none">foo.orig</filename> will be clobbered.</para>
belaran@999:     </tip>
belaran@999: 
belaran@999:     <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
belaran@999:       will describe each of these in more detail in the section that
belaran@999:       follows.</para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_e7">If you modify a file, it will restore the file
belaran@999: 	  to its unmodified state.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_e8">If you <command role="hg-cmd" moreinfo="none">hg add</command> a
belaran@999: 	  file, it will undo the <quote>added</quote> state of the
belaran@999: 	  file, but leave the file itself untouched.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_e9">If you delete a file without telling Mercurial,
belaran@999: 	  it will restore the file to its unmodified contents.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_ea">If you use the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	    remove</command> command to remove a file, it will undo
belaran@999: 	  the <quote>removed</quote> state of the file, and restore
belaran@999: 	  the file to its unmodified contents.</para>
belaran@999:       </listitem></itemizedlist>
belaran@999: 
belaran@999:     <sect2 id="sec:undo:mgmt">
belaran@999:       <title>File management errors</title>
belaran@999: 
belaran@999:       <para id="x_eb">The <command role="hg-cmd" moreinfo="none">hg revert</command> command is
belaran@999: 	useful for more than just modified files.  It lets you reverse
belaran@999: 	the results of all of Mercurial's file management
belaran@999: 	commands—<command role="hg-cmd" moreinfo="none">hg add</command>,
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg remove</command>, and so on.</para>
belaran@999: 
belaran@999:       <para id="x_ec">If you <command role="hg-cmd" moreinfo="none">hg add</command> a file,
belaran@999: 	then decide that in fact you don't want Mercurial to track it,
belaran@999: 	use <command role="hg-cmd" moreinfo="none">hg revert</command> to undo the
belaran@999: 	add.  Don't worry; Mercurial will not modify the file in any
belaran@999: 	way.  It will just <quote>unmark</quote> the file.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.revert.add -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo oops &gt; oops</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add oops</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status oops</userinput>
belaran@999: A oops
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert oops</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: ? oops
belaran@999: </screen>
belaran@999: <!-- END daily.revert.add -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_ed">Similarly, if you ask Mercurial to <command role="hg-cmd" moreinfo="none">hg remove</command> a file, you can use
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg revert</command> to restore it to
belaran@999: 	the contents it had as of the parent of the working directory.
belaran@999: 	<!-- BEGIN daily.revert.remove -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg remove file</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: R file
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert file</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls file</userinput>
belaran@999: file
belaran@999: </screen>
belaran@999: <!-- END daily.revert.remove -->
belaran@999:  This works just as
belaran@999: 	well for a file that you deleted by hand, without telling
belaran@999: 	Mercurial (recall that in Mercurial terminology, this kind of
belaran@999: 	file is called <quote>missing</quote>).</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.revert.missing -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">rm file</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: ! file
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert file</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls file</userinput>
belaran@999: file
belaran@999: </screen>
belaran@999: <!-- END daily.revert.missing -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_ee">If you revert a <command role="hg-cmd" moreinfo="none">hg copy</command>,
belaran@999: 	the copied-to file remains in your working directory
belaran@999: 	afterwards, untracked.  Since a copy doesn't affect the
belaran@999: 	copied-from file in any way, Mercurial doesn't do anything
belaran@999: 	with the copied-from file.</para>
belaran@999: 
belaran@999:       <!-- BEGIN daily.revert.copy -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy file new-file</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert new-file</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: ? new-file
belaran@999: </screen>
belaran@999: <!-- END daily.revert.copy -->
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Dealing with committed changes</title>
belaran@999: 
belaran@999:     <para id="x_f5">Consider a case where you have committed a change
belaran@999:       <emphasis>a</emphasis>, and another change
belaran@999:       <emphasis>b</emphasis> on top of it; you then realise that
belaran@999:       change <emphasis>a</emphasis> was incorrect.  Mercurial lets you
belaran@999:       <quote>back out</quote> an entire changeset automatically, and
belaran@999:       building blocks that let you reverse part of a changeset by
belaran@999:       hand.</para>
belaran@999: 
belaran@999:     <para id="x_f6">Before you read this section, here's something to
belaran@999:       keep in mind: the <command role="hg-cmd" moreinfo="none">hg backout</command>
belaran@999:       command undoes the effect of a change by
belaran@999:       <emphasis>adding</emphasis> to your repository's history, not by
belaran@999:       modifying or erasing it.  It's the right tool to use if you're
belaran@999:       fixing bugs, but not if you're trying to undo some change that
belaran@999:       has catastrophic consequences.  To deal with those, see
belaran@999:       <xref linkend="sec:undo:aaaiiieee"/>.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Backing out a changeset</title>
belaran@999: 
belaran@999:       <para id="x_f7">The <command role="hg-cmd" moreinfo="none">hg backout</command> command
belaran@999: 	lets you <quote>undo</quote> the effects of an entire
belaran@999: 	changeset in an automated fashion.  Because Mercurial's
belaran@999: 	history is immutable, this command <emphasis>does
belaran@999: 	  not</emphasis> get rid of the changeset you want to undo.
belaran@999: 	Instead, it creates a new changeset that
belaran@999: 	<emphasis>reverses</emphasis> the effect of the to-be-undone
belaran@999: 	changeset.</para>
belaran@999: 
belaran@999:       <para id="x_f8">The operation of the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  backout</command> command is a little intricate, so let's
belaran@999: 	illustrate it with some examples.  First, we'll create a
belaran@999: 	repository with some simple changes.</para>
belaran@999: 
belaran@999:       <!-- BEGIN backout.init -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init myrepo</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd myrepo</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo first change &gt;&gt; myfile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add myfile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'first change'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo second change &gt;&gt; myfile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'second change'</userinput>
belaran@999: </screen>
belaran@999: <!-- END backout.init -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_f9">The <command role="hg-cmd" moreinfo="none">hg backout</command> command
belaran@999: 	takes a single changeset ID as its argument; this is the
belaran@999: 	changeset to back out.  Normally, <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  backout</command> will drop you into a text editor to write
belaran@999: 	a commit message, so you can record why you're backing the
belaran@999: 	change out.  In this example, we provide a commit message on
belaran@999: 	the command line using the <option role="hg-opt-backout">-m</option> option.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Backing out the tip changeset</title>
belaran@999: 
belaran@999:       <para id="x_fa">We're going to start by backing out the last changeset we
belaran@999: 	committed.</para>
belaran@999: 
belaran@999:       <!-- BEGIN backout.simple -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg backout -m 'back out second change' tip</userinput>
belaran@999: reverting myfile
belaran@999: changeset 2:611a0cae251c backs out changeset 1:43700a9b3ec8
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
belaran@999: first change
belaran@999: </screen>
belaran@999: <!-- END backout.simple -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_fb">You can see that the second line from
belaran@999: 	<filename moreinfo="none">myfile</filename> is no longer present.  Taking a
belaran@999: 	look at the output of <command role="hg-cmd" moreinfo="none">hg log</command>
belaran@999: 	gives us an idea of what the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  backout</command> command has done.
belaran@999: 	<!-- BEGIN backout.simple.log -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style compact</userinput>
belaran@999: 2[tip]   611a0cae251c   2009-08-16 14:04 +0000   bos
belaran@999:   back out second change
belaran@999: 
belaran@999: 1   43700a9b3ec8   2009-08-16 14:04 +0000   bos
belaran@999:   second change
belaran@999: 
belaran@999: 0   f2ef23d503fd   2009-08-16 14:04 +0000   bos
belaran@999:   first change
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END backout.simple.log -->
belaran@999:  Notice that the new changeset
belaran@999: 	that <command role="hg-cmd" moreinfo="none">hg backout</command> has created
belaran@999: 	is a child of the changeset we backed out.  It's easier to see
belaran@999: 	this in <xref linkend="fig:undo:backout"/>, which presents a
belaran@999: 	graphical view of the change history.  As you can see, the
belaran@999: 	history is nice and linear.</para>
belaran@999: 
belaran@999:       <figure id="fig:undo:backout" float="0">
belaran@999: 	<title>Backing out a change using the <command role="hg-cmd" moreinfo="none">hg backout</command> command</title>
belaran@999: 	<mediaobject>
belaran@999: 	  <imageobject><imagedata fileref="figs/undo-simple.png"/></imageobject>
belaran@999: 	  <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	</mediaobject>
belaran@999:       </figure>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Backing out a non-tip change</title>
belaran@999: 
belaran@999:       <para id="x_fd">If you want to back out a change other than the last one
belaran@999: 	you committed, pass the <option role="hg-opt-backout">--merge</option> option to the
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg backout</command> command.</para>
belaran@999: 
belaran@999:       <!-- BEGIN backout.non-tip.clone -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone -r1 myrepo non-tip-repo</userinput>
belaran@999: requesting all changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 2 changesets with 2 changes to 1 files
belaran@999: updating working directory
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd non-tip-repo</userinput>
belaran@999: </screen>
belaran@999: <!-- END backout.non-tip.clone -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_fe">This makes backing out any changeset a
belaran@999: 	<quote>one-shot</quote> operation that's usually simple and
belaran@999: 	fast.</para>
belaran@999: 
belaran@999:       <!-- BEGIN backout.non-tip.backout -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo third change &gt;&gt; myfile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'third change'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg backout --merge -m 'back out second change' 1</userinput>
belaran@999: reverting myfile
belaran@999: created new head
belaran@999: changeset 3:611a0cae251c backs out changeset 1:43700a9b3ec8
belaran@999: merging with changeset 3:611a0cae251c
belaran@999: merging myfile
belaran@999: 0 files updated, 1 files merged, 0 files removed, 0 files unresolved
belaran@999: (branch merge, don't forget to commit)
belaran@999: </screen>
belaran@999: <!-- END backout.non-tip.backout -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_ff">If you take a look at the contents of
belaran@999: 	<filename moreinfo="none">myfile</filename> after the backout finishes, you'll
belaran@999: 	see that the first and third changes are present, but not the
belaran@999: 	second.</para>
belaran@999: 
belaran@999:       <!-- BEGIN backout.non-tip.cat -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
belaran@999: first change
belaran@999: third change
belaran@999: </screen>
belaran@999: <!-- END backout.non-tip.cat -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_100">As the graphical history in <xref linkend="fig:undo:backout-non-tip"/> illustrates, Mercurial
belaran@999: 	still commits one change in this kind of situation (the
belaran@999: 	box-shaped node is the ones that Mercurial commits
belaran@999: 	automatically), but the revision graph now looks different.
belaran@999: 	Before Mercurial begins the backout process, it first
belaran@999: 	remembers what the current parent of the working directory is.
belaran@999: 	It then backs out the target changeset, and commits that as a
belaran@999: 	changeset.  Finally, it merges back to the previous parent of
belaran@999: 	the working directory, but notice that it <emphasis>does not
belaran@999: 	  commit</emphasis> the result of the merge.  The repository
belaran@999: 	now contains two heads, and the working directory is in a
belaran@999: 	merge state.</para>
belaran@999: 
belaran@999:       <figure id="fig:undo:backout-non-tip" float="0">
belaran@999: 	<title>Automated backout of a non-tip change using the
belaran@999: 	  <command role="hg-cmd" moreinfo="none">hg backout</command> command</title>
belaran@999: 	<mediaobject>
belaran@999: 	  <imageobject><imagedata fileref="figs/undo-non-tip.png"/></imageobject>
belaran@999: 	  <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	</mediaobject>
belaran@999:       </figure>
belaran@999: 
belaran@999:       <para id="x_103">The result is that you end up <quote>back where you
belaran@999: 	  were</quote>, only with some extra history that undoes the
belaran@999: 	effect of the changeset you wanted to back out.</para>
belaran@999: 
belaran@999:       <para id="x_6b9">You might wonder why Mercurial does not commit the result
belaran@999: 	of the merge that it performed.  The reason lies in Mercurial
belaran@999: 	behaving conservatively: a merge naturally has more scope for
belaran@999: 	error than simply undoing the effect of the tip changeset,
belaran@999: 	so your work will be safest if you first inspect (and test!)
belaran@999: 	the result of the merge, <emphasis>then</emphasis> commit
belaran@999: 	it.</para>
belaran@999: 
belaran@999:       <sect3>
belaran@999: 	<title>Always use the <option role="hg-opt-backout">--merge</option> option</title>
belaran@999: 
belaran@999: 	<para id="x_104">In fact, since the <option role="hg-opt-backout">--merge</option> option will do the
belaran@999: 	  <quote>right thing</quote> whether or not the changeset
belaran@999: 	  you're backing out is the tip (i.e. it won't try to merge if
belaran@999: 	  it's backing out the tip, since there's no need), you should
belaran@999: 	  <emphasis>always</emphasis> use this option when you run the
belaran@999: 	  <command role="hg-cmd" moreinfo="none">hg backout</command> command.</para>
belaran@999: 
belaran@999:       </sect3>
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Gaining more control of the backout process</title>
belaran@999: 
belaran@999:       <para id="x_105">While I've recommended that you always use the <option role="hg-opt-backout">--merge</option> option when backing
belaran@999: 	out a change, the <command role="hg-cmd" moreinfo="none">hg backout</command>
belaran@999: 	command lets you decide how to merge a backout changeset.
belaran@999: 	Taking control of the backout process by hand is something you
belaran@999: 	will rarely need to do, but it can be useful to understand
belaran@999: 	what the <command role="hg-cmd" moreinfo="none">hg backout</command> command
belaran@999: 	is doing for you automatically.  To illustrate this, let's
belaran@999: 	clone our first repository, but omit the backout change that
belaran@999: 	it contains.</para>
belaran@999: 
belaran@999:       <!-- BEGIN backout.manual.clone -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone -r1 myrepo newrepo</userinput>
belaran@999: requesting all changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 2 changesets with 2 changes to 1 files
belaran@999: updating working directory
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd newrepo</userinput>
belaran@999: </screen>
belaran@999: <!-- END backout.manual.clone -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_106">As with our
belaran@999: 	earlier example, We'll commit a third changeset, then back out
belaran@999: 	its parent, and see what happens.</para>
belaran@999: 
belaran@999:       <!-- BEGIN backout.manual.backout -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo third change &gt;&gt; myfile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'third change'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg backout -m 'back out second change' 1</userinput>
belaran@999: reverting myfile
belaran@999: created new head
belaran@999: changeset 3:bf906ee0baae backs out changeset 1:43700a9b3ec8
belaran@999: the backout changeset is a new head - do not forget to merge
belaran@999: (use "backout --merge" if you want to auto-merge)
belaran@999: </screen>
belaran@999: <!-- END backout.manual.backout -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_107">Our new changeset is again a descendant of the changeset
belaran@999: 	we backout out; it's thus a new head, <emphasis>not</emphasis>
belaran@999: 	a descendant of the changeset that was the tip.  The <command role="hg-cmd" moreinfo="none">hg backout</command> command was quite
belaran@999: 	explicit in telling us this.</para>
belaran@999: 
belaran@999:       <!-- BEGIN backout.manual.log -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style compact</userinput>
belaran@999: 3[tip]:1   bf906ee0baae   2009-08-16 14:04 +0000   bos
belaran@999:   back out second change
belaran@999: 
belaran@999: 2   2521379001ad   2009-08-16 14:04 +0000   bos
belaran@999:   third change
belaran@999: 
belaran@999: 1   43700a9b3ec8   2009-08-16 14:04 +0000   bos
belaran@999:   second change
belaran@999: 
belaran@999: 0   f2ef23d503fd   2009-08-16 14:04 +0000   bos
belaran@999:   first change
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END backout.manual.log -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_108">Again, it's easier to see what has happened by looking at
belaran@999: 	a graph of the revision history, in <xref linkend="fig:undo:backout-manual"/>.  This makes it clear
belaran@999: 	that when we use <command role="hg-cmd" moreinfo="none">hg backout</command>
belaran@999: 	to back out a change other than the tip, Mercurial adds a new
belaran@999: 	head to the repository (the change it committed is
belaran@999: 	box-shaped).</para>
belaran@999: 
belaran@999:       <figure id="fig:undo:backout-manual" float="0">
belaran@999: 	<title>Backing out a change using the <command role="hg-cmd" moreinfo="none">hg backout</command> command</title>
belaran@999: 	<mediaobject>
belaran@999: 	  <imageobject><imagedata fileref="figs/undo-manual.png"/></imageobject>
belaran@999: 	  <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	</mediaobject>
belaran@999:       </figure>
belaran@999: 
belaran@999:       <para id="x_10a">After the <command role="hg-cmd" moreinfo="none">hg backout</command>
belaran@999: 	command has completed, it leaves the new
belaran@999: 	<quote>backout</quote> changeset as the parent of the working
belaran@999: 	directory.</para>
belaran@999: 
belaran@999:       <!-- BEGIN backout.manual.parents -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
belaran@999: changeset:   2:2521379001ad
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:37 2009 +0000
belaran@999: summary:     third change
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END backout.manual.parents -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_10b">Now we have two isolated sets of changes.</para>
belaran@999: 
belaran@999:       <!-- BEGIN backout.manual.heads -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg heads</userinput>
belaran@999: changeset:   3:bf906ee0baae
belaran@999: tag:         tip
belaran@999: parent:      1:43700a9b3ec8
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:37 2009 +0000
belaran@999: summary:     back out second change
belaran@999: 
belaran@999: changeset:   2:2521379001ad
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:37 2009 +0000
belaran@999: summary:     third change
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END backout.manual.heads -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_10c">Let's think about what we expect to see as the contents of
belaran@999: 	<filename moreinfo="none">myfile</filename> now.  The first change should be
belaran@999: 	present, because we've never backed it out.  The second change
belaran@999: 	should be missing, as that's the change we backed out.  Since
belaran@999: 	the history graph shows the third change as a separate head,
belaran@999: 	we <emphasis>don't</emphasis> expect to see the third change
belaran@999: 	present in <filename moreinfo="none">myfile</filename>.</para>
belaran@999: 
belaran@999:       <!-- BEGIN backout.manual.cat -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
belaran@999: first change
belaran@999: </screen>
belaran@999: <!-- END backout.manual.cat -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_10d">To get the third change back into the file, we just do a
belaran@999: 	normal merge of our two heads.</para>
belaran@999: 
belaran@999:       <!-- BEGIN backout.manual.merge -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
belaran@999: abort: outstanding uncommitted changes
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'merged backout with previous tip'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
belaran@999: first change
belaran@999: </screen>
belaran@999: <!-- END backout.manual.merge -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_10e">Afterwards, the graphical history of our
belaran@999: 	repository looks like
belaran@999: 	<xref linkend="fig:undo:backout-manual-merge"/>.</para>
belaran@999: 
belaran@999:       <figure id="fig:undo:backout-manual-merge" float="0">
belaran@999: 	<title>Manually merging a backout change</title>
belaran@999: 	<mediaobject>
belaran@999: 	  <imageobject><imagedata fileref="figs/undo-manual-merge.png"/></imageobject>
belaran@999: 	  <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	</mediaobject>
belaran@999:       </figure>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Why <command role="hg-cmd" moreinfo="none">hg backout</command> works as
belaran@999: 	it does</title>
belaran@999: 
belaran@999:       <para id="x_110">Here's a brief description of how the <command role="hg-cmd" moreinfo="none">hg backout</command> command works.</para>
belaran@999:       <orderedlist inheritnum="ignore" continuation="restarts">
belaran@999: 	<listitem><para id="x_111">It ensures that the working directory is
belaran@999: 	    <quote>clean</quote>, i.e. that the output of <command role="hg-cmd" moreinfo="none">hg status</command> would be empty.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_112">It remembers the current parent of the working
belaran@999: 	    directory.  Let's call this changeset
belaran@999: 	    <literal moreinfo="none">orig</literal>.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_113">It does the equivalent of a <command role="hg-cmd" moreinfo="none">hg update</command> to sync the working
belaran@999: 	    directory to the changeset you want to back out.  Let's
belaran@999: 	    call this changeset <literal moreinfo="none">backout</literal>.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_114">It finds the parent of that changeset.  Let's
belaran@999: 	    call that changeset <literal moreinfo="none">parent</literal>.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_115">For each file that the
belaran@999: 	    <literal moreinfo="none">backout</literal> changeset affected, it does the
belaran@999: 	    equivalent of a <command role="hg-cmd" moreinfo="none">hg revert -r
belaran@999: 	      parent</command> on that file, to restore it to the
belaran@999: 	    contents it had before that changeset was
belaran@999: 	    committed.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_116">It commits the result as a new changeset.
belaran@999: 	    This changeset has <literal moreinfo="none">backout</literal> as its
belaran@999: 	    parent.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_117">If you specify <option role="hg-opt-backout">--merge</option> on the command
belaran@999: 	    line, it merges with <literal moreinfo="none">orig</literal>, and commits
belaran@999: 	    the result of the merge.</para>
belaran@999: 	</listitem></orderedlist>
belaran@999: 
belaran@999:       <para id="x_118">An alternative way to implement the <command role="hg-cmd" moreinfo="none">hg backout</command> command would be to
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg export</command> the
belaran@999: 	to-be-backed-out changeset as a diff, then use the <option role="cmd-opt-patch">--reverse</option> option to the
belaran@999: 	<command moreinfo="none">patch</command> command to reverse the effect of the
belaran@999: 	change without fiddling with the working directory.  This
belaran@999: 	sounds much simpler, but it would not work nearly as
belaran@999: 	well.</para>
belaran@999: 
belaran@999:       <para id="x_119">The reason that <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  backout</command> does an update, a commit, a merge, and
belaran@999: 	another commit is to give the merge machinery the best chance
belaran@999: 	to do a good job when dealing with all the changes
belaran@999: 	<emphasis>between</emphasis> the change you're backing out and
belaran@999: 	the current tip.</para>
belaran@999: 
belaran@999:       <para id="x_11a">If you're backing out a changeset that's 100 revisions
belaran@999: 	back in your project's history, the chances that the
belaran@999: 	<command moreinfo="none">patch</command> command will be able to apply a
belaran@999: 	reverse diff cleanly are not good, because intervening changes
belaran@999: 	are likely to have <quote>broken the context</quote> that
belaran@999: 	<command moreinfo="none">patch</command> uses to determine whether it can
belaran@999: 	apply a patch (if this sounds like gibberish, see <xref linkend="sec:mq:patch"/> for a
belaran@999: 	discussion of the <command moreinfo="none">patch</command> command).  Also,
belaran@999: 	Mercurial's merge machinery will handle files and directories
belaran@999: 	being renamed, permission changes, and modifications to binary
belaran@999: 	files, none of which <command moreinfo="none">patch</command> can deal
belaran@999: 	with.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1 id="sec:undo:aaaiiieee">
belaran@999:     <title>Changes that should never have been</title>
belaran@999: 
belaran@999:     <para id="x_11b">Most of the time, the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	backout</command> command is exactly what you need if you want
belaran@999:       to undo the effects of a change.  It leaves a permanent record
belaran@999:       of exactly what you did, both when committing the original
belaran@999:       changeset and when you cleaned up after it.</para>
belaran@999: 
belaran@999:     <para id="x_11c">On rare occasions, though, you may find that you've
belaran@999:       committed a change that really should not be present in the
belaran@999:       repository at all.  For example, it would be very unusual, and
belaran@999:       usually considered a mistake, to commit a software project's
belaran@999:       object files as well as its source files.  Object files have
belaran@999:       almost no intrinsic value, and they're <emphasis>big</emphasis>,
belaran@999:       so they increase the size of the repository and the amount of
belaran@999:       time it takes to clone or pull changes.</para>
belaran@999: 
belaran@999:     <para id="x_11d">Before I discuss the options that you have if you commit a
belaran@999:       <quote>brown paper bag</quote> change (the kind that's so bad
belaran@999:       that you want to pull a brown paper bag over your head), let me
belaran@999:       first discuss some approaches that probably won't work.</para>
belaran@999: 
belaran@999:     <para id="x_11e">Since Mercurial treats history as
belaran@999:       accumulative—every change builds on top of all changes
belaran@999:       that preceded it—you generally can't just make disastrous
belaran@999:       changes disappear.  The one exception is when you've just
belaran@999:       committed a change, and it hasn't been pushed or pulled into
belaran@999:       another repository.  That's when you can safely use the <command role="hg-cmd" moreinfo="none">hg rollback</command> command, as I detailed in
belaran@999:       <xref linkend="sec:undo:rollback"/>.</para>
belaran@999: 
belaran@999:     <para id="x_11f">After you've pushed a bad change to another repository, you
belaran@999:       <emphasis>could</emphasis> still use <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	rollback</command> to make your local copy of the change
belaran@999:       disappear, but it won't have the consequences you want.  The
belaran@999:       change will still be present in the remote repository, so it
belaran@999:       will reappear in your local repository the next time you
belaran@999:       pull.</para>
belaran@999: 
belaran@999:     <para id="x_120">If a situation like this arises, and you know which
belaran@999:       repositories your bad change has propagated into, you can
belaran@999:       <emphasis>try</emphasis> to get rid of the change from
belaran@999:       <emphasis>every</emphasis> one of those repositories.  This is,
belaran@999:       of course, not a satisfactory solution: if you miss even a
belaran@999:       single repository while you're expunging, the change is still
belaran@999:       <quote>in the wild</quote>, and could propagate further.</para>
belaran@999: 
belaran@999:     <para id="x_121">If you've committed one or more changes
belaran@999:       <emphasis>after</emphasis> the change that you'd like to see
belaran@999:       disappear, your options are further reduced. Mercurial doesn't
belaran@999:       provide a way to <quote>punch a hole</quote> in history, leaving
belaran@999:       changesets intact.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Backing out a merge</title>
belaran@999: 
belaran@999:       <para id="x_6ba">Since merges are often complicated, it is not unheard of
belaran@999: 	for a merge to be mangled badly, but committed erroneously.
belaran@999: 	Mercurial provides an important safeguard against bad merges
belaran@999: 	by refusing to commit unresolved files, but human ingenuity
belaran@999: 	guarantees that it is still possible to mess a merge up and
belaran@999: 	commit it.</para>
belaran@999: 
belaran@999:       <para id="x_6bb">Given a bad merge that has been committed, usually the
belaran@999: 	best way to approach it is to simply try to repair the damage
belaran@999: 	by hand.  A complete disaster that cannot be easily fixed up
belaran@999: 	by hand ought to be very rare, but the <command role="hg-cmd" moreinfo="none">hg backout</command> command may help in
belaran@999: 	making the cleanup easier. It offers a <option role="hg-opt-backout">--parent</option> option, which lets
belaran@999: 	you specify which parent to revert to when backing out a
belaran@999: 	merge.</para>
belaran@999: 
belaran@999:       <figure id="fig:undo:bad-merge-1" float="0">
belaran@999: 	<title>A bad merge</title>
belaran@999: 	<mediaobject>
belaran@999: 	  <imageobject><imagedata fileref="figs/bad-merge-1.png"/></imageobject>
belaran@999: 	  <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	</mediaobject>
belaran@999:       </figure>
belaran@999: 
belaran@999:       <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
belaran@999: 	<emphasis>redo</emphasis> the merge of revisions 2 and
belaran@999: 	3.</para>
belaran@999: 
belaran@999:       <para id="x_6bd">One way to do so would be as follows.</para>
belaran@999: 
belaran@999:       <orderedlist inheritnum="ignore" continuation="restarts">
belaran@999: 	<listitem>
belaran@999: 	  <para id="x_6be">Call <command role="hg-cmd" moreinfo="none">hg backout --rev=4
belaran@999: 	      --parent=2</command>.  This tells <command role="hg-cmd" moreinfo="none">hg backout</command> to back out revision
belaran@999: 	    4, which is the bad merge, and to when deciding which
belaran@999: 	    revision to prefer, to choose parent 2, one of the parents
belaran@999: 	    of the merge.  The effect can be seen in <xref linkend="fig:undo:bad-merge-2"/>.</para>
belaran@999: 	  <figure id="fig:undo:bad-merge-2" float="0">
belaran@999: 	    <title>Backing out the merge, favoring one parent</title>
belaran@999: 	    <mediaobject>
belaran@999: 	      <imageobject><imagedata fileref="figs/bad-merge-2.png"/></imageobject>
belaran@999: 	      <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	    </mediaobject>
belaran@999: 	  </figure>
belaran@999: 	</listitem>
belaran@999: 
belaran@999: 	<listitem>
belaran@999: 	  <para id="x_6bf">Call <command role="hg-cmd" moreinfo="none">hg backout --rev=4
belaran@999: 	      --parent=3</command>.  This tells <command role="hg-cmd" moreinfo="none">hg backout</command> to back out revision
belaran@999: 	    4 again, but this time to choose parent 3, the other
belaran@999: 	    parent of the merge.  The result is visible in <xref linkend="fig:undo:bad-merge-3"/>, in which the repository
belaran@999: 	    now contains three heads.</para>
belaran@999: 	  <figure id="fig:undo:bad-merge-3" float="0">
belaran@999: 	    <title>Backing out the merge, favoring the other
belaran@999: 	      parent</title>
belaran@999: 	    <mediaobject>
belaran@999: 	      <imageobject><imagedata fileref="figs/bad-merge-3.png"/></imageobject>
belaran@999: 	      <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	    </mediaobject>
belaran@999: 	  </figure>
belaran@999: 	</listitem>
belaran@999: 
belaran@999: 	<listitem>
belaran@999: 	  <para id="x_6c0">Redo the bad merge by merging the two backout heads,
belaran@999: 	    which reduces the number of heads in the repository to
belaran@999: 	    two, as can be seen in <xref linkend="fig:undo:bad-merge-4"/>.</para>
belaran@999: 	  <figure id="fig:undo:bad-merge-4" float="0">
belaran@999: 	    <title>Merging the backouts</title>
belaran@999: 	    <mediaobject>
belaran@999: 	      <imageobject><imagedata fileref="figs/bad-merge-4.png"/></imageobject>
belaran@999: 	      <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	    </mediaobject>
belaran@999: 	  </figure>
belaran@999: 	</listitem>
belaran@999: 
belaran@999: 	<listitem>
belaran@999: 	  <para id="x_6c1">Merge with the commit that was made after the bad
belaran@999: 	    merge, as shown in <xref linkend="fig:undo:bad-merge-5"/>.</para>
belaran@999: 	  <figure id="fig:undo:bad-merge-5" float="0">
belaran@999: 	    <title>Merging the backouts</title>
belaran@999: 	    <mediaobject>
belaran@999: 	      <imageobject><imagedata fileref="figs/bad-merge-5.png"/></imageobject>
belaran@999: 	      <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	    </mediaobject>
belaran@999: 	  </figure>
belaran@999: 	</listitem>
belaran@999:       </orderedlist>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Protect yourself from <quote>escaped</quote>
belaran@999: 	changes</title>
belaran@999: 
belaran@999:       <para id="x_123">If you've committed some changes to your local repository
belaran@999: 	and they've been pushed or pulled somewhere else, this isn't
belaran@999: 	necessarily a disaster.  You can protect yourself ahead of
belaran@999: 	time against some classes of bad changeset.  This is
belaran@999: 	particularly easy if your team usually pulls changes from a
belaran@999: 	central repository.</para>
belaran@999: 
belaran@999:       <para id="x_124">By configuring some hooks on that repository to validate
belaran@999: 	incoming changesets (see chapter <xref linkend="chap:hook"/>),
belaran@999: 	you can
belaran@999: 	automatically prevent some kinds of bad changeset from being
belaran@999: 	pushed to the central repository at all.  With such a
belaran@999: 	configuration in place, some kinds of bad changeset will
belaran@999: 	naturally tend to <quote>die out</quote> because they can't
belaran@999: 	propagate into the central repository.  Better yet, this
belaran@999: 	happens without any need for explicit intervention.</para>
belaran@999: 
belaran@999:       <para id="x_125">For instance, an incoming change hook that
belaran@999: 	verifies that a changeset will actually compile can prevent
belaran@999: 	people from inadvertently <quote>breaking the
belaran@999: 	  build</quote>.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>What to do about sensitive changes that escape</title>
belaran@999: 
belaran@999:       <para id="x_6c2">Even a carefully run project can suffer an unfortunate
belaran@999: 	event such as the committing and uncontrolled propagation of a
belaran@999: 	file that contains important passwords.</para>
belaran@999: 
belaran@999:       <para id="x_6c3">If something like this happens to you, and the information
belaran@999: 	that gets accidentally propagated is truly sensitive, your
belaran@999: 	first step should be to mitigate the effect of the leak
belaran@999: 	without trying to control the leak itself. If you are not 100%
belaran@999: 	certain that you know exactly who could have seen the changes,
belaran@999: 	you should immediately change passwords, cancel credit cards,
belaran@999: 	or find some other way to make sure that the information that
belaran@999: 	has leaked is no longer useful.  In other words, assume that
belaran@999: 	the change has propagated far and wide, and that there's
belaran@999: 	nothing more you can do.</para>
belaran@999: 
belaran@999:       <para id="x_6c4">You might hope that there would be mechanisms you could
belaran@999: 	use to either figure out who has seen a change or to erase the
belaran@999: 	change permanently everywhere, but there are good reasons why
belaran@999: 	these are not possible.</para>
belaran@999: 
belaran@999:       <para id="x_6c5">Mercurial does not provide an audit trail of who has
belaran@999: 	pulled changes from a repository, because it is usually either
belaran@999: 	impossible to record such information or trivial to spoof it.
belaran@999: 	In a multi-user or networked environment, you should thus be
belaran@999: 	extremely skeptical of yourself if you think that you have
belaran@999: 	identified every place that a sensitive changeset has
belaran@999: 	propagated to.  Don't forget that people can and will send
belaran@999: 	bundles by email, have their backup software save data
belaran@999: 	offsite, carry repositories on USB sticks, and find other
belaran@999: 	completely innocent ways to confound your attempts to track
belaran@999: 	down every copy of a problematic change.</para>
belaran@999: 
belaran@999:       <para id="x_6c6">Mercurial also does not provide a way to make a file or
belaran@999: 	changeset completely disappear from history, because there is
belaran@999: 	no way to enforce its disappearance; someone could easily
belaran@999: 	modify their copy of Mercurial to ignore such directives. In
belaran@999: 	addition, even if Mercurial provided such a capability,
belaran@999: 	someone who simply hadn't pulled a <quote>make this file
belaran@999: 	  disappear</quote> changeset wouldn't be affected by it, nor
belaran@999: 	would web crawlers visiting at the wrong time, disk backups,
belaran@999: 	or other mechanisms.  Indeed, no distributed revision control
belaran@999: 	system can make data reliably vanish. Providing the illusion
belaran@999: 	of such control could easily give a false sense of security,
belaran@999: 	and be worse than not providing it at all.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="sec:undo:bisect">
belaran@999:     <title>Finding the source of a bug</title>
belaran@999: 
belaran@999:     <para id="x_126">While it's all very well to be able to back out a changeset
belaran@999:       that introduced a bug, this requires that you know which
belaran@999:       changeset to back out.  Mercurial provides an invaluable
belaran@999:       command, called <command role="hg-cmd" moreinfo="none">hg bisect</command>, that
belaran@999:       helps you to automate this process and accomplish it very
belaran@999:       efficiently.</para>
belaran@999: 
belaran@999:     <para id="x_127">The idea behind the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	bisect</command> command is that a changeset has introduced
belaran@999:       some change of behavior that you can identify with a simple
belaran@999:       pass/fail test.  You don't know which piece of code introduced the
belaran@999:       change, but you know how to test for the presence of the bug.
belaran@999:       The <command role="hg-cmd" moreinfo="none">hg bisect</command> command uses your
belaran@999:       test to direct its search for the changeset that introduced the
belaran@999:       code that caused the bug.</para>
belaran@999: 
belaran@999:     <para id="x_128">Here are a few scenarios to help you understand how you
belaran@999:       might apply this command.</para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_129">The most recent version of your software has a
belaran@999: 	  bug that you remember wasn't present a few weeks ago, but
belaran@999: 	  you don't know when it was introduced.  Here, your binary
belaran@999: 	  test checks for the presence of that bug.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_12a">You fixed a bug in a rush, and now it's time to
belaran@999: 	  close the entry in your team's bug database.  The bug
belaran@999: 	  database requires a changeset ID when you close an entry,
belaran@999: 	  but you don't remember which changeset you fixed the bug in.
belaran@999: 	  Once again, your binary test checks for the presence of the
belaran@999: 	  bug.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_12b">Your software works correctly, but runs 15%
belaran@999: 	  slower than the last time you measured it.  You want to know
belaran@999: 	  which changeset introduced the performance regression.  In
belaran@999: 	  this case, your binary test measures the performance of your
belaran@999: 	  software, to see whether it's <quote>fast</quote> or
belaran@999: 	  <quote>slow</quote>.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_12c">The sizes of the components of your project that
belaran@999: 	  you ship exploded recently, and you suspect that something
belaran@999: 	  changed in the way you build your project.</para>
belaran@999:       </listitem></itemizedlist>
belaran@999: 
belaran@999:     <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
belaran@999:       for finding the sources of bugs.  You can use it to find any
belaran@999:       <quote>emergent property</quote> of a repository (anything that
belaran@999:       you can't find from a simple text search of the files in the
belaran@999:       tree) for which you can write a binary test.</para>
belaran@999: 
belaran@999:     <para id="x_12e">We'll introduce a little bit of terminology here, just to
belaran@999:       make it clear which parts of the search process are your
belaran@999:       responsibility, and which are Mercurial's.  A
belaran@999:       <emphasis>test</emphasis> is something that
belaran@999:       <emphasis>you</emphasis> run when <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	bisect</command> chooses a changeset.  A
belaran@999:       <emphasis>probe</emphasis> is what <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	bisect</command> runs to tell whether a revision is good.
belaran@999:       Finally, we'll use the word <quote>bisect</quote>, as both a
belaran@999:       noun and a verb, to stand in for the phrase <quote>search using
belaran@999: 	the <command role="hg-cmd" moreinfo="none">hg bisect</command>
belaran@999: 	command</quote>.</para>
belaran@999: 
belaran@999:     <para id="x_12f">One simple way to automate the searching process would be
belaran@999:       simply to probe every changeset.  However, this scales poorly.
belaran@999:       If it took ten minutes to test a single changeset, and you had
belaran@999:       10,000 changesets in your repository, the exhaustive approach
belaran@999:       would take on average 35 <emphasis>days</emphasis> to find the
belaran@999:       changeset that introduced a bug.  Even if you knew that the bug
belaran@999:       was introduced by one of the last 500 changesets, and limited
belaran@999:       your search to those, you'd still be looking at over 40 hours to
belaran@999:       find the changeset that introduced your bug.</para>
belaran@999: 
belaran@999:     <para id="x_130">What the <command role="hg-cmd" moreinfo="none">hg bisect</command> command
belaran@999:       does is use its knowledge of the <quote>shape</quote> of your
belaran@999:       project's revision history to perform a search in time
belaran@999:       proportional to the <emphasis>logarithm</emphasis> of the number
belaran@999:       of changesets to check (the kind of search it performs is called
belaran@999:       a dichotomic search).  With this approach, searching through
belaran@999:       10,000 changesets will take less than three hours, even at ten
belaran@999:       minutes per test (the search will require about 14 tests).
belaran@999:       Limit your search to the last hundred changesets, and it will
belaran@999:       take only about an hour (roughly seven tests).</para>
belaran@999: 
belaran@999:     <para id="x_131">The <command role="hg-cmd" moreinfo="none">hg bisect</command> command is
belaran@999:       aware of the <quote>branchy</quote> nature of a Mercurial
belaran@999:       project's revision history, so it has no problems dealing with
belaran@999:       branches, merges, or multiple heads in a repository.  It can
belaran@999:       prune entire branches of history with a single probe, which is
belaran@999:       how it operates so efficiently.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Using the <command role="hg-cmd" moreinfo="none">hg bisect</command>
belaran@999: 	command</title>
belaran@999: 
belaran@999:       <para id="x_132">Here's an example of <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  bisect</command> in action.</para>
belaran@999: 
belaran@999:       <note>
belaran@999: 	<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:
belaran@999: 	  it was distributed with Mercurial as an extension. This
belaran@999: 	  section describes the built-in command, not the old
belaran@999: 	  extension.</para>
belaran@999:       </note>
belaran@999: 
belaran@999:       <para id="x_134">Now let's create a repository, so that we can try out the
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg bisect</command> command in
belaran@999: 	isolation.</para>
belaran@999: 
belaran@999:       <!-- BEGIN bisect.init -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init mybug</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd mybug</userinput>
belaran@999: </screen>
belaran@999: <!-- END bisect.init -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_135">We'll simulate a project that has a bug in it in a
belaran@999: 	simple-minded way: create trivial changes in a loop, and
belaran@999: 	nominate one specific change that will have the
belaran@999: 	<quote>bug</quote>.  This loop creates 35 changesets, each
belaran@999: 	adding a single file to the repository. We'll represent our
belaran@999: 	<quote>bug</quote> with a file that contains the text <quote>i
belaran@999: 	  have a gub</quote>.</para>
belaran@999: 
belaran@999:       <!-- BEGIN bisect.commits -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">buggy_change=22</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">for (( i = 0; i &lt; 35; i++ )); do</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  if [[ $i = $buggy_change ]]; then</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">    echo 'i have a gub' &gt; myfile$i</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">    hg commit -q -A -m 'buggy changeset'</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  else</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">    echo 'nothing to see here, move along' &gt; myfile$i</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">    hg commit -q -A -m 'normal changeset'</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  fi</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">done</userinput>
belaran@999: </screen>
belaran@999: <!-- END bisect.commits -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_136">The next thing that we'd like to do is figure out how to
belaran@999: 	use the <command role="hg-cmd" moreinfo="none">hg bisect</command> command.
belaran@999: 	We can use Mercurial's normal built-in help mechanism for
belaran@999: 	this.</para>
belaran@999: 
belaran@999:       <!-- BEGIN bisect.help -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg help bisect</userinput>
belaran@999: hg bisect [-gbsr] [-c CMD] [REV]
belaran@999: 
belaran@999: subdivision search of changesets
belaran@999: 
belaran@999:     This command helps to find changesets which introduce problems.
belaran@999:     To use, mark the earliest changeset you know exhibits the problem
belaran@999:     as bad, then mark the latest changeset which is free from the
belaran@999:     problem as good. Bisect will update your working directory to a
belaran@999:     revision for testing (unless the --noupdate option is specified).
belaran@999:     Once you have performed tests, mark the working directory as bad
belaran@999:     or good and bisect will either update to another candidate changeset
belaran@999:     or announce that it has found the bad revision.
belaran@999: 
belaran@999:     As a shortcut, you can also use the revision argument to mark a
belaran@999:     revision as good or bad without checking it out first.
belaran@999: 
belaran@999:     If you supply a command it will be used for automatic bisection. Its exit
belaran@999:     status will be used as flag to mark revision as bad or good. In case exit
belaran@999:     status is 0 the revision is marked as good, 125 - skipped, 127 (command not
belaran@999:     found) - bisection will be aborted; any other status bigger than 0 will
belaran@999:     mark revision as bad.
belaran@999: 
belaran@999: options:
belaran@999: 
belaran@999:  -r --reset     reset bisect state
belaran@999:  -g --good      mark changeset good
belaran@999:  -b --bad       mark changeset bad
belaran@999:  -s --skip      skip testing changeset
belaran@999:  -c --command   use command to check changeset state
belaran@999:  -U --noupdate  do not update to target
belaran@999: 
belaran@999: use "hg -v help bisect" to show global options
belaran@999: </screen>
belaran@999: <!-- END bisect.help -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_137">The <command role="hg-cmd" moreinfo="none">hg bisect</command> command
belaran@999: 	works in steps.  Each step proceeds as follows.</para>
belaran@999:       <orderedlist inheritnum="ignore" continuation="restarts">
belaran@999: 	<listitem><para id="x_138">You run your binary test.</para>
belaran@999: 	  <itemizedlist>
belaran@999: 	    <listitem><para id="x_139">If the test succeeded, you tell <command role="hg-cmd" moreinfo="none">hg bisect</command> by running the
belaran@999: 		<command role="hg-cmd" moreinfo="none">hg bisect --good</command>
belaran@999: 		command.</para>
belaran@999: 	    </listitem>
belaran@999: 	    <listitem><para id="x_13a">If it failed, run the <command role="hg-cmd" moreinfo="none">hg bisect --bad</command>
belaran@999: 		command.</para></listitem></itemizedlist>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_13b">The command uses your information to decide
belaran@999: 	    which changeset to test next.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_13c">It updates the working directory to that
belaran@999: 	    changeset, and the process begins again.</para>
belaran@999: 	</listitem></orderedlist>
belaran@999:       <para id="x_13d">The process ends when <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  bisect</command> identifies a unique changeset that marks
belaran@999: 	the point where your test transitioned from
belaran@999: 	<quote>succeeding</quote> to <quote>failing</quote>.</para>
belaran@999: 
belaran@999:       <para id="x_13e">To start the search, we must run the <command role="hg-cmd" moreinfo="none">hg bisect --reset</command> command.</para>
belaran@999: 
belaran@999:       <!-- BEGIN bisect.search.init -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg bisect --reset</userinput>
belaran@999: </screen>
belaran@999: <!-- END bisect.search.init -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_13f">In our case, the binary test we use is simple: we check to
belaran@999: 	see if any file in the repository contains the string <quote>i
belaran@999: 	  have a gub</quote>.  If it does, this changeset contains the
belaran@999: 	change that <quote>caused the bug</quote>.  By convention, a
belaran@999: 	changeset that has the property we're searching for is
belaran@999: 	<quote>bad</quote>, while one that doesn't is
belaran@999: 	<quote>good</quote>.</para>
belaran@999: 
belaran@999:       <para id="x_140">Most of the time, the revision to which the working
belaran@999: 	directory is synced (usually the tip) already exhibits the
belaran@999: 	problem introduced by the buggy change, so we'll mark it as
belaran@999: 	<quote>bad</quote>.</para>
belaran@999: 
belaran@999:       <!-- BEGIN bisect.search.bad-init -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg bisect --bad</userinput>
belaran@999: </screen>
belaran@999: <!-- END bisect.search.bad-init -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_141">Our next task is to nominate a changeset that we know
belaran@999: 	<emphasis>doesn't</emphasis> have the bug; the <command role="hg-cmd" moreinfo="none">hg bisect</command> command will
belaran@999: 	<quote>bracket</quote> its search between the first pair of
belaran@999: 	good and bad changesets.  In our case, we know that revision
belaran@999: 	10 didn't have the bug.  (I'll have more words about choosing
belaran@999: 	the first <quote>good</quote> changeset later.)</para>
belaran@999: 
belaran@999:       <!-- BEGIN bisect.search.good-init -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg bisect --good 10</userinput>
belaran@999: Testing changeset 22:69f52b967ab8 (24 changesets remaining, ~4 tests)
belaran@999: 0 files updated, 0 files merged, 12 files removed, 0 files unresolved
belaran@999: </screen>
belaran@999: <!-- END bisect.search.good-init -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_142">Notice that this command printed some output.</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_143">It told us how many changesets it must
belaran@999: 	    consider before it can identify the one that introduced
belaran@999: 	    the bug, and how many tests that will require.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_144">It updated the working directory to the next
belaran@999: 	    changeset to test, and told us which changeset it's
belaran@999: 	    testing.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_145">We now run our test in the working directory.  We use the
belaran@999: 	<command moreinfo="none">grep</command> command to see if our
belaran@999: 	<quote>bad</quote> file is present in the working directory.
belaran@999: 	If it is, this revision is bad; if not, this revision is good.
belaran@999: 	<!-- BEGIN bisect.search.step1 -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">if grep -q 'i have a gub' *</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">then</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  result=bad</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">else</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  result=good</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">fi</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo this revision is $result</userinput>
belaran@999: this revision is bad
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg bisect --$result</userinput>
belaran@999: Testing changeset 16:f1dd8bc690ae (12 changesets remaining, ~3 tests)
belaran@999: 0 files updated, 0 files merged, 6 files removed, 0 files unresolved
belaran@999: </screen>
belaran@999: <!-- END bisect.search.step1 -->
belaran@999: </para>
belaran@999: 
belaran@999:       <para id="x_146">This test looks like a perfect candidate for automation,
belaran@999: 	so let's turn it into a shell function.</para>
belaran@999:       <!-- BEGIN bisect.search.mytest -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mytest() {</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  if grep -q 'i have a gub' *</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  then</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">    result=bad</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  else</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">    result=good</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  fi</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  echo this revision is $result</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">  hg bisect --$result</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">}</userinput>
belaran@999: </screen>
belaran@999: <!-- END bisect.search.mytest -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_147">We can now run an entire test step with a single command,
belaran@999: 	<literal moreinfo="none">mytest</literal>.</para>
belaran@999: 
belaran@999:       <!-- BEGIN bisect.search.step2 -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mytest</userinput>
belaran@999: this revision is good
belaran@999: Testing changeset 19:88d99d97058a (6 changesets remaining, ~2 tests)
belaran@999: 3 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: </screen>
belaran@999: <!-- END bisect.search.step2 -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_148">A few more invocations of our canned test step command,
belaran@999: 	and we're done.</para>
belaran@999: 
belaran@999:       <!-- BEGIN bisect.search.rest -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mytest</userinput>
belaran@999: this revision is good
belaran@999: Testing changeset 20:32a195a31d51 (3 changesets remaining, ~1 tests)
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mytest</userinput>
belaran@999: this revision is good
belaran@999: Testing changeset 21:a2efe8e4f624 (2 changesets remaining, ~1 tests)
belaran@999: 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mytest</userinput>
belaran@999: this revision is good
belaran@999: The first bad revision is:
belaran@999: changeset:   22:69f52b967ab8
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:04:39 2009 +0000
belaran@999: summary:     buggy changeset
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END bisect.search.rest -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_149">Even though we had 40 changesets to search through, the
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg bisect</command> command let us find
belaran@999: 	the changeset that introduced our <quote>bug</quote> with only
belaran@999: 	five tests.  Because the number of tests that the <command role="hg-cmd" moreinfo="none">hg bisect</command> command performs grows
belaran@999: 	logarithmically with the number of changesets to search, the
belaran@999: 	advantage that it has over the <quote>brute force</quote>
belaran@999: 	search approach increases with every changeset you add.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Cleaning up after your search</title>
belaran@999: 
belaran@999:       <para id="x_14a">When you're finished using the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  bisect</command> command in a repository, you can use the
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg bisect --reset</command> command to
belaran@999: 	drop the information it was using to drive your search.  The
belaran@999: 	command doesn't use much space, so it doesn't matter if you
belaran@999: 	forget to run this command.  However, <command role="hg-cmd" moreinfo="none">hg bisect</command> won't let you start a new
belaran@999: 	search in that repository until you do a <command role="hg-cmd" moreinfo="none">hg bisect --reset</command>.</para>
belaran@999: 
belaran@999:       <!-- BEGIN bisect.search.reset -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg bisect --reset</userinput>
belaran@999: </screen>
belaran@999: <!-- END bisect.search.reset -->
belaran@999: 
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Tips for finding bugs effectively</title>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Give consistent input</title>
belaran@999: 
belaran@999:       <para id="x_14b">The <command role="hg-cmd" moreinfo="none">hg bisect</command> command
belaran@999: 	requires that you correctly report the result of every test
belaran@999: 	you perform.  If you tell it that a test failed when it really
belaran@999: 	succeeded, it <emphasis>might</emphasis> be able to detect the
belaran@999: 	inconsistency.  If it can identify an inconsistency in your
belaran@999: 	reports, it will tell you that a particular changeset is both
belaran@999: 	good and bad. However, it can't do this perfectly; it's about
belaran@999: 	as likely to report the wrong changeset as the source of the
belaran@999: 	bug.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Automate as much as possible</title>
belaran@999: 
belaran@999:       <para id="x_14c">When I started using the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  bisect</command> command, I tried a few times to run my
belaran@999: 	tests by hand, on the command line.  This is an approach that
belaran@999: 	I, at least, am not suited to.  After a few tries, I found
belaran@999: 	that I was making enough mistakes that I was having to restart
belaran@999: 	my searches several times before finally getting correct
belaran@999: 	results.</para>
belaran@999: 
belaran@999:       <para id="x_14d">My initial problems with driving the <command role="hg-cmd" moreinfo="none">hg bisect</command> command by hand occurred
belaran@999: 	even with simple searches on small repositories; if the
belaran@999: 	problem you're looking for is more subtle, or the number of
belaran@999: 	tests that <command role="hg-cmd" moreinfo="none">hg bisect</command> must
belaran@999: 	perform increases, the likelihood of operator error ruining
belaran@999: 	the search is much higher.  Once I started automating my
belaran@999: 	tests, I had much better results.</para>
belaran@999: 
belaran@999:       <para id="x_14e">The key to automated testing is twofold:</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_14f">always test for the same symptom, and</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_150">always feed consistent input to the <command role="hg-cmd" moreinfo="none">hg bisect</command> command.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999:       <para id="x_151">In my tutorial example above, the <command moreinfo="none">grep</command>
belaran@999: 	command tests for the symptom, and the <literal moreinfo="none">if</literal>
belaran@999: 	statement takes the result of this check and ensures that we
belaran@999: 	always feed the same input to the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  bisect</command> command.  The <literal moreinfo="none">mytest</literal>
belaran@999: 	function marries these together in a reproducible way, so that
belaran@999: 	every test is uniform and consistent.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Check your results</title>
belaran@999: 
belaran@999:       <para id="x_152">Because the output of a <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  bisect</command> search is only as good as the input you
belaran@999: 	give it, don't take the changeset it reports as the absolute
belaran@999: 	truth.  A simple way to cross-check its report is to manually
belaran@999: 	run your test at each of the following changesets:</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_153">The changeset that it reports as the first bad
belaran@999: 	    revision.  Your test should still report this as
belaran@999: 	    bad.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_154">The parent of that changeset (either parent,
belaran@999: 	    if it's a merge). Your test should report this changeset
belaran@999: 	    as good.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_155">A child of that changeset.  Your test should
belaran@999: 	    report this changeset as bad.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Beware interference between bugs</title>
belaran@999: 
belaran@999:       <para id="x_156">It's possible that your search for one bug could be
belaran@999: 	disrupted by the presence of another.  For example, let's say
belaran@999: 	your software crashes at revision 100, and worked correctly at
belaran@999: 	revision 50.  Unknown to you, someone else introduced a
belaran@999: 	different crashing bug at revision 60, and fixed it at
belaran@999: 	revision 80.  This could distort your results in one of
belaran@999: 	several ways.</para>
belaran@999: 
belaran@999:       <para id="x_157">It is possible that this other bug completely
belaran@999: 	<quote>masks</quote> yours, which is to say that it occurs
belaran@999: 	before your bug has a chance to manifest itself.  If you can't
belaran@999: 	avoid that other bug (for example, it prevents your project
belaran@999: 	from building), and so can't tell whether your bug is present
belaran@999: 	in a particular changeset, the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  bisect</command> command cannot help you directly.  Instead,
belaran@999: 	you can mark a changeset as untested by running <command role="hg-cmd" moreinfo="none">hg bisect --skip</command>.</para>
belaran@999: 
belaran@999:       <para id="x_158">A different problem could arise if your test for a bug's
belaran@999: 	presence is not specific enough.  If you check for <quote>my
belaran@999: 	  program crashes</quote>, then both your crashing bug and an
belaran@999: 	unrelated crashing bug that masks it will look like the same
belaran@999: 	thing, and mislead <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  bisect</command>.</para>
belaran@999: 
belaran@999:       <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
belaran@999: 	test a revision because your project was in a broken and hence
belaran@999: 	untestable state at that revision, perhaps because someone
belaran@999: 	checked in a change that prevented the project from
belaran@999: 	building.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>Bracket your search lazily</title>
belaran@999: 
belaran@999:       <para id="x_15a">Choosing the first <quote>good</quote> and
belaran@999: 	<quote>bad</quote> changesets that will mark the end points of
belaran@999: 	your search is often easy, but it bears a little discussion
belaran@999: 	nevertheless.  From the perspective of <command role="hg-cmd" moreinfo="none">hg bisect</command>, the <quote>newest</quote>
belaran@999: 	changeset is conventionally <quote>bad</quote>, and the older
belaran@999: 	changeset is <quote>good</quote>.</para>
belaran@999: 
belaran@999:       <para id="x_15b">If you're having trouble remembering when a suitable
belaran@999: 	<quote>good</quote> change was, so that you can tell <command role="hg-cmd" moreinfo="none">hg bisect</command>, you could do worse than
belaran@999: 	testing changesets at random.  Just remember to eliminate
belaran@999: 	contenders that can't possibly exhibit the bug (perhaps
belaran@999: 	because the feature with the bug isn't present yet) and those
belaran@999: 	where another problem masks the bug (as I discussed
belaran@999: 	above).</para>
belaran@999: 
belaran@999:       <para id="x_15c">Even if you end up <quote>early</quote> by thousands of
belaran@999: 	changesets or months of history, you will only add a handful
belaran@999: 	of tests to the total number that <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  bisect</command> must perform, thanks to its logarithmic
belaran@999: 	behavior.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: </chapter>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "chapter")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN ch10 -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <chapter id="chap:hook">
belaran@999:   <?dbhtml filename="handling-repository-events-with-hooks.html"?>
belaran@999:   <title>Handling repository events with hooks</title>
belaran@999: 
belaran@999:   <para id="x_1e6">Mercurial offers a powerful mechanism to let you perform
belaran@999:     automated actions in response to events that occur in a
belaran@999:     repository.  In some cases, you can even control Mercurial's
belaran@999:     response to those events.</para>
belaran@999: 
belaran@999:   <para id="x_1e7">The name Mercurial uses for one of these actions is a
belaran@999:     <emphasis>hook</emphasis>. Hooks are called
belaran@999:     <quote>triggers</quote> in some revision control systems, but the
belaran@999:     two names refer to the same idea.</para>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>An overview of hooks in Mercurial</title>
belaran@999: 
belaran@999:     <para id="x_1e8">Here is a brief list of the hooks that Mercurial
belaran@999:       supports. We will revisit each of these hooks in more detail
belaran@999:       later, in <xref linkend="sec:hook:ref"/>.</para>
belaran@999: 
belaran@999:     <para id="x_1f6">Each of the hooks whose description begins with the word
belaran@999:       <quote>Controlling</quote> has the ability to determine whether
belaran@999:       an activity can proceed.  If the hook succeeds, the activity may
belaran@999:       proceed; if it fails, the activity is either not permitted or
belaran@999:       undone, depending on the hook.</para>
belaran@999: 
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_1e9"><literal role="hook" moreinfo="none">changegroup</literal>: This
belaran@999: 	  is run after a group of changesets has been brought into the
belaran@999: 	  repository from elsewhere.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_1ea"><literal role="hook" moreinfo="none">commit</literal>: This is
belaran@999: 	  run after a new changeset has been created in the local
belaran@999: 	  repository.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_1eb"><literal role="hook" moreinfo="none">incoming</literal>: This is
belaran@999: 	  run once for each new changeset that is brought into the
belaran@999: 	  repository from elsewhere.  Notice the difference from
belaran@999: 	  <literal role="hook" moreinfo="none">changegroup</literal>, which is run
belaran@999: 	  once per <emphasis>group</emphasis> of changesets brought
belaran@999: 	  in.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_1ec"><literal role="hook" moreinfo="none">outgoing</literal>: This is
belaran@999: 	  run after a group of changesets has been transmitted from
belaran@999: 	  this repository.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_1ed"><literal role="hook" moreinfo="none">prechangegroup</literal>:
belaran@999: 	  This is run before starting to bring a group of changesets
belaran@999: 	  into the repository.
belaran@999: 	</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_1ee"><literal role="hook" moreinfo="none">precommit</literal>:
belaran@999: 	  Controlling. This is run before starting a commit.
belaran@999: 	</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_1ef"><literal role="hook" moreinfo="none">preoutgoing</literal>:
belaran@999: 	  Controlling. This is run before starting to transmit a group
belaran@999: 	  of changesets from this repository.
belaran@999: 	</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_1f0"><literal role="hook" moreinfo="none">pretag</literal>:
belaran@999: 	  Controlling. This is run before creating a tag.
belaran@999: 	</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_1f1"><literal role="hook" moreinfo="none">pretxnchangegroup</literal>: Controlling. This
belaran@999: 	  is run after a group of changesets has been brought into the
belaran@999: 	  local repository from another, but before the transaction
belaran@999: 	  completes that will make the changes permanent in the
belaran@999: 	  repository.
belaran@999: 	</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_1f2"><literal role="hook" moreinfo="none">pretxncommit</literal>:
belaran@999: 	  Controlling. This is run after a new changeset has been
belaran@999: 	  created in the local repository, but before the transaction
belaran@999: 	  completes that will make it permanent.
belaran@999: 	</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_1f3"><literal role="hook" moreinfo="none">preupdate</literal>:
belaran@999: 	  Controlling. This is run before starting an update or merge
belaran@999: 	  of the working directory.
belaran@999: 	</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_1f4"><literal role="hook" moreinfo="none">tag</literal>: This is run
belaran@999: 	  after a tag is created.
belaran@999: 	</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_1f5"><literal role="hook" moreinfo="none">update</literal>: This is
belaran@999: 	  run after an update or merge of the working directory has
belaran@999: 	  finished.
belaran@999: 	</para>
belaran@999:       </listitem></itemizedlist>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Hooks and security</title>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Hooks are run with your privileges</title>
belaran@999: 
belaran@999:       <para id="x_1f7">When you run a Mercurial command in a repository, and the
belaran@999: 	command causes a hook to run, that hook runs on
belaran@999: 	<emphasis>your</emphasis> system, under
belaran@999: 	<emphasis>your</emphasis> user account, with
belaran@999: 	<emphasis>your</emphasis> privilege level.  Since hooks are
belaran@999: 	arbitrary pieces of executable code, you should treat them
belaran@999: 	with an appropriate level of suspicion.  Do not install a hook
belaran@999: 	unless you are confident that you know who created it and what
belaran@999: 	it does.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_1f8">In some cases, you may be exposed to hooks that you did
belaran@999: 	not install yourself.  If you work with Mercurial on an
belaran@999: 	unfamiliar system, Mercurial will run hooks defined in that
belaran@999: 	system's global <filename role="special" moreinfo="none">~/.hgrc</filename>
belaran@999: 	file.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_1f9">If you are working with a repository owned by another
belaran@999: 	user, Mercurial can run hooks defined in that user's
belaran@999: 	repository, but it will still run them as <quote>you</quote>.
belaran@999: 	For example, if you <command role="hg-cmd" moreinfo="none">hg pull</command>
belaran@999: 	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
belaran@999: 	under your user account, even though you don't own that
belaran@999: 	repository.
belaran@999:       </para>
belaran@999: 
belaran@999:       <note>
belaran@999: 	<para id="x_1fa">  This only applies if you are pulling from a repository
belaran@999: 	  on a local or network filesystem.  If you're pulling over
belaran@999: 	  http or ssh, any <literal role="hook" moreinfo="none">outgoing</literal>
belaran@999: 	  hook will run under whatever account is executing the server
belaran@999: 	  process, on the server.
belaran@999: 	</para>
belaran@999:       </note>
belaran@999: 
belaran@999:       <para id="x_1fb">To see what hooks are defined in a repository,
belaran@999: 	use the <command role="hg-cmd" moreinfo="none">hg showconfig hooks</command>
belaran@999: 	command.  If you are working in one repository, but talking to
belaran@999: 	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
belaran@999: 	  incoming</command>), remember that it is the other
belaran@999: 	repository's hooks you should be checking, not your own.
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Hooks do not propagate</title>
belaran@999: 
belaran@999:       <para id="x_1fc">In Mercurial, hooks are not revision controlled, and do
belaran@999: 	not propagate when you clone, or pull from, a repository.  The
belaran@999: 	reason for this is simple: a hook is a completely arbitrary
belaran@999: 	piece of executable code.  It runs under your user identity,
belaran@999: 	with your privilege level, on your machine.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_1fd">It would be extremely reckless for any distributed
belaran@999: 	revision control system to implement revision-controlled
belaran@999: 	hooks, as this would offer an easily exploitable way to
belaran@999: 	subvert the accounts of users of the revision control system.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_1fe">Since Mercurial does not propagate hooks, if you are
belaran@999: 	collaborating with other people on a common project, you
belaran@999: 	should not assume that they are using the same Mercurial hooks
belaran@999: 	as you are, or that theirs are correctly configured.  You
belaran@999: 	should document the hooks you expect people to use.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_1ff">In a corporate intranet, this is somewhat easier to
belaran@999: 	control, as you can for example provide a
belaran@999: 	<quote>standard</quote> installation of Mercurial on an NFS
belaran@999: 	filesystem, and use a site-wide <filename role="special" moreinfo="none">~/.hgrc</filename> file to define hooks that all users will
belaran@999: 	see.  However, this too has its limits; see below.
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Hooks can be overridden</title>
belaran@999: 
belaran@999:       <para id="x_200">Mercurial allows you to override a hook definition by
belaran@999: 	redefining the hook.  You can disable it by setting its value
belaran@999: 	to the empty string, or change its behavior as you wish.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_201">If you deploy a system- or site-wide <filename role="special" moreinfo="none">~/.hgrc</filename> file that defines some
belaran@999: 	hooks, you should thus understand that your users can disable
belaran@999: 	or override those hooks.
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Ensuring that critical hooks are run</title>
belaran@999: 
belaran@999:       <para id="x_202">Sometimes you may want to enforce a policy that you do not
belaran@999: 	want others to be able to work around.  For example, you may
belaran@999: 	have a requirement that every changeset must pass a rigorous
belaran@999: 	set of tests.  Defining this requirement via a hook in a
belaran@999: 	site-wide <filename role="special" moreinfo="none">~/.hgrc</filename> won't
belaran@999: 	work for remote users on laptops, and of course local users
belaran@999: 	can subvert it at will by overriding the hook.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_203">Instead, you can set up your policies for use of Mercurial
belaran@999: 	so that people are expected to propagate changes through a
belaran@999: 	well-known <quote>canonical</quote> server that you have
belaran@999: 	locked down and configured appropriately.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_204">One way to do this is via a combination of social
belaran@999: 	engineering and technology.  Set up a restricted-access
belaran@999: 	account; users can push changes over the network to
belaran@999: 	repositories managed by this account, but they cannot log into
belaran@999: 	the account and run normal shell commands.  In this scenario,
belaran@999: 	a user can commit a changeset that contains any old garbage
belaran@999: 	they want.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_205">When someone pushes a changeset to the server that
belaran@999: 	everyone pulls from, the server will test the changeset before
belaran@999: 	it accepts it as permanent, and reject it if it fails to pass
belaran@999: 	the test suite.  If people only pull changes from this
belaran@999: 	filtering server, it will serve to ensure that all changes
belaran@999: 	that people pull have been automatically vetted.
belaran@999:       </para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="sec:hook:simple">
belaran@999:     <title>A short tutorial on using hooks</title>
belaran@999: 
belaran@999:     <para id="x_212">It is easy to write a Mercurial hook.  Let's start with a
belaran@999:       hook that runs when you finish a <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	commit</command>, and simply prints the hash of the changeset
belaran@999:       you just created.  The hook is called <literal role="hook" moreinfo="none">commit</literal>.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_213">All hooks follow the pattern in this example.</para>
belaran@999: 
belaran@999: <!-- BEGIN hook.simple.init -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init hook-test</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd hook-test</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo '[hooks]' &gt;&gt; .hg/hgrc</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'commit = echo committed $HG_NODE' &gt;&gt; .hg/hgrc</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/hgrc</userinput>
belaran@999: [hooks]
belaran@999: commit = echo committed $HG_NODE
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'testing commit hook'</userinput>
belaran@999: committed 13a334d1e5ca83fea465aa779110eec3c5ddd6b1
belaran@999: </screen>
belaran@999: <!-- END hook.simple.init -->
belaran@999: 
belaran@999: 
belaran@999:     <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
belaran@999:       the event to trigger on; on the right is the action to take.  As
belaran@999:       you can see, you can run an arbitrary shell command in a hook.
belaran@999:       Mercurial passes extra information to the hook using environment
belaran@999:       variables (look for <envar>HG_NODE</envar> in the example).
belaran@999:     </para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Performing multiple actions per event</title>
belaran@999: 
belaran@999:       <para id="x_215">Quite often, you will want to define more than one hook
belaran@999: 	for a particular kind of event, as shown below.</para>
belaran@999: 
belaran@999: <!-- BEGIN hook.simple.ext -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'commit.when = echo -n "date of commit: "; date' &gt;&gt; .hg/hgrc</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt;&gt; a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'i have two hooks'</userinput>
belaran@999: committed 3be6e2778fb853cbc7e5138d0b9c29386504670b
belaran@999: date of commit: Sun Aug 16 14:05:05 GMT 2009
belaran@999: </screen>
belaran@999: <!-- END hook.simple.ext -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_216">Mercurial lets you do this by adding an
belaran@999: 	<emphasis>extension</emphasis> to the end of a hook's name.
belaran@999: 	You extend a hook's name by giving the name of the hook,
belaran@999: 	followed by a full stop (the
belaran@999: 	<quote><literal moreinfo="none">.</literal></quote> character), followed by
belaran@999: 	some more text of your choosing.  For example, Mercurial will
belaran@999: 	run both <literal moreinfo="none">commit.foo</literal> and
belaran@999: 	<literal moreinfo="none">commit.bar</literal> when the
belaran@999: 	<literal moreinfo="none">commit</literal> event occurs.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_217">To give a well-defined order of execution when there are
belaran@999: 	multiple hooks defined for an event, Mercurial sorts hooks by
belaran@999: 	extension, and executes the hook commands in this sorted
belaran@999: 	order.  In the above example, it will execute
belaran@999: 	<literal moreinfo="none">commit.bar</literal> before
belaran@999: 	<literal moreinfo="none">commit.foo</literal>, and <literal moreinfo="none">commit</literal>
belaran@999: 	before both.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_218">It is a good idea to use a somewhat descriptive
belaran@999: 	extension when you define a new hook.  This will help you to
belaran@999: 	remember what the hook was for.  If the hook fails, you'll get
belaran@999: 	an error message that contains the hook name and extension, so
belaran@999: 	using a descriptive extension could give you an immediate hint
belaran@999: 	as to why the hook failed (see <xref linkend="sec:hook:perm"/> for an example).
belaran@999:       </para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2 id="sec:hook:perm">
belaran@999:       <title>Controlling whether an activity can proceed</title>
belaran@999: 
belaran@999:       <para id="x_219">In our earlier examples, we used the <literal role="hook" moreinfo="none">commit</literal> hook, which is run after a
belaran@999: 	commit has completed.  This is one of several Mercurial hooks
belaran@999: 	that run after an activity finishes.  Such hooks have no way
belaran@999: 	of influencing the activity itself.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_21a">Mercurial defines a number of events that occur before an
belaran@999: 	activity starts; or after it starts, but before it finishes.
belaran@999: 	Hooks that trigger on these events have the added ability to
belaran@999: 	choose whether the activity can continue, or will abort.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_21b">The <literal role="hook" moreinfo="none">pretxncommit</literal> hook runs
belaran@999: 	after a commit has all but completed.  In other words, the
belaran@999: 	metadata representing the changeset has been written out to
belaran@999: 	disk, but the transaction has not yet been allowed to
belaran@999: 	complete.  The <literal role="hook" moreinfo="none">pretxncommit</literal>
belaran@999: 	hook has the ability to decide whether the transaction can
belaran@999: 	complete, or must be rolled back.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_21c">If the <literal role="hook" moreinfo="none">pretxncommit</literal> hook
belaran@999: 	exits with a status code of zero, the transaction is allowed
belaran@999: 	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
belaran@999: 	non-zero status code, the transaction is rolled back; the
belaran@999: 	metadata representing the changeset is erased; and the
belaran@999: 	<literal role="hook" moreinfo="none">commit</literal> hook is not run.
belaran@999:       </para>
belaran@999: 
belaran@999: <!-- BEGIN hook.simple.pretxncommit -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat check_bug_id</userinput>
belaran@999: #!/bin/sh
belaran@999: # check that a commit comment mentions a numeric bug id
belaran@999: hg log -r $1 --template {desc} | grep -q "\&lt;bug *[0-9]"
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'pretxncommit.bug_id_required = ./check_bug_id $HG_NODE' &gt;&gt; .hg/hgrc</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt;&gt; a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'i am not mentioning a bug id'</userinput>
belaran@999: transaction abort!
belaran@999: rollback completed
belaran@999: abort: pretxncommit.bug_id_required hook exited with status 1
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'i refer you to bug 666'</userinput>
belaran@999: committed 1a52be73a1ca4fa05e269f99003ed00912e8e836
belaran@999: date of commit: Sun Aug 16 14:05:05 GMT 2009
belaran@999: </screen>
belaran@999: <!-- END hook.simple.pretxncommit -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_21d">The hook in the example above checks that a commit comment
belaran@999: 	contains a bug ID.  If it does, the commit can complete.  If
belaran@999: 	not, the commit is rolled back.
belaran@999:       </para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Writing your own hooks</title>
belaran@999: 
belaran@999:     <para id="x_21e">When you are writing a hook, you might find it useful to run
belaran@999:       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
belaran@999:       <quote>true</quote>.  When you do so, Mercurial will print a
belaran@999:       message before it calls each hook.
belaran@999:     </para>
belaran@999: 
belaran@999:     <sect2 id="sec:hook:lang">
belaran@999:       <title>Choosing how your hook should run</title>
belaran@999: 
belaran@999:       <para id="x_21f">You can write a hook either as a normal
belaran@999: 	program—typically a shell script—or as a Python
belaran@999: 	function that is executed within the Mercurial process.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_220">Writing a hook as an external program has the advantage
belaran@999: 	that it requires no knowledge of Mercurial's internals.  You
belaran@999: 	can call normal Mercurial commands to get any added
belaran@999: 	information you need.  The trade-off is that external hooks
belaran@999: 	are slower than in-process hooks.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_221">An in-process Python hook has complete access to the
belaran@999: 	Mercurial API, and does not <quote>shell out</quote> to
belaran@999: 	another process, so it is inherently faster than an external
belaran@999: 	hook.  It is also easier to obtain much of the information
belaran@999: 	that a hook requires by using the Mercurial API than by
belaran@999: 	running Mercurial commands.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_222">If you are comfortable with Python, or require high
belaran@999: 	performance, writing your hooks in Python may be a good
belaran@999: 	choice.  However, when you have a straightforward hook to
belaran@999: 	write and you don't need to care about performance (probably
belaran@999: 	the majority of hooks), a shell script is perfectly fine.
belaran@999:       </para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2 id="sec:hook:param">
belaran@999:       <title>Hook parameters</title>
belaran@999: 
belaran@999:       <para id="x_223">Mercurial calls each hook with a set of well-defined
belaran@999: 	parameters.  In Python, a parameter is passed as a keyword
belaran@999: 	argument to your hook function.  For an external program, a
belaran@999: 	parameter is passed as an environment variable.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_224">Whether your hook is written in Python or as a shell
belaran@999: 	script, the hook-specific parameter names and values will be
belaran@999: 	the same.  A boolean parameter will be represented as a
belaran@999: 	boolean value in Python, but as the number 1 (for
belaran@999: 	<quote>true</quote>) or 0 (for <quote>false</quote>) as an
belaran@999: 	environment variable for an external hook.  If a hook
belaran@999: 	parameter is named <literal moreinfo="none">foo</literal>, the keyword
belaran@999: 	argument for a Python hook will also be named
belaran@999: 	<literal moreinfo="none">foo</literal>, while the environment variable for an
belaran@999: 	external hook will be named <literal moreinfo="none">HG_FOO</literal>.
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Hook return values and activity control</title>
belaran@999: 
belaran@999:       <para id="x_225">A hook that executes successfully must exit with a status
belaran@999: 	of zero if external, or return boolean <quote>false</quote> if
belaran@999: 	in-process.  Failure is indicated with a non-zero exit status
belaran@999: 	from an external hook, or an in-process hook returning boolean
belaran@999: 	<quote>true</quote>.  If an in-process hook raises an
belaran@999: 	exception, the hook is considered to have failed.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_226">For a hook that controls whether an activity can proceed,
belaran@999: 	zero/false means <quote>allow</quote>, while
belaran@999: 	non-zero/true/exception means <quote>deny</quote>.
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Writing an external hook</title>
belaran@999: 
belaran@999:       <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
belaran@999: 	value is passed to your shell, which interprets it.  This
belaran@999: 	means that you can use normal shell constructs in the body of
belaran@999: 	the hook.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_228">An executable hook is always run with its current
belaran@999: 	directory set to a repository's root directory.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_229">Each hook parameter is passed in as an environment
belaran@999: 	variable; the name is upper-cased, and prefixed with the
belaran@999: 	string <quote><literal moreinfo="none">HG_</literal></quote>.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_22a">With the exception of hook parameters, Mercurial does not
belaran@999: 	set or modify any environment variables when running a hook.
belaran@999: 	This is useful to remember if you are writing a site-wide hook
belaran@999: 	that may be run by a number of different users with differing
belaran@999: 	environment variables set. In multi-user situations, you
belaran@999: 	should not rely on environment variables being set to the
belaran@999: 	values you have in your environment when testing the hook.
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Telling Mercurial to use an in-process hook</title>
belaran@999: 
belaran@999:       <para id="x_22b">The <filename role="special" moreinfo="none">~/.hgrc</filename> syntax
belaran@999: 	for defining an in-process hook is slightly different than for
belaran@999: 	an executable hook.  The value of the hook must start with the
belaran@999: 	text <quote><literal moreinfo="none">python:</literal></quote>, and continue
belaran@999: 	with the fully-qualified name of a callable object to use as
belaran@999: 	the hook's value.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_22c">The module in which a hook lives is automatically imported
belaran@999: 	when a hook is run.  So long as you have the module name and
belaran@999: 	<envar>PYTHONPATH</envar> right, it should <quote>just
belaran@999: 	  work</quote>.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_22d">The following <filename role="special" moreinfo="none">~/.hgrc</filename>
belaran@999: 	example snippet illustrates the syntax and meaning of the
belaran@999: 	notions we just described.
belaran@999:       </para>
belaran@999:       <programlisting format="linespecific">[hooks]
belaran@999: commit.example = python:mymodule.submodule.myhook</programlisting>
belaran@999:       <para id="x_22e">When Mercurial runs the <literal moreinfo="none">commit.example</literal>
belaran@999: 	hook, it imports <literal moreinfo="none">mymodule.submodule</literal>, looks
belaran@999: 	for the callable object named <literal moreinfo="none">myhook</literal>, and
belaran@999: 	calls it.
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Writing an in-process hook</title>
belaran@999: 
belaran@999:       <para id="x_22f">The simplest in-process hook does nothing, but illustrates
belaran@999: 	the basic shape of the hook API:
belaran@999:       </para>
belaran@999:       <programlisting format="linespecific">def myhook(ui, repo, **kwargs):
belaran@999:     pass</programlisting>
belaran@999:       <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
belaran@999: 	is a repository object; at the moment, it is always an
belaran@999: 	instance of <literal role="py-mod-mercurial.localrepo" moreinfo="none">localrepository</literal>.
belaran@999: 	Following these two arguments are other keyword arguments.
belaran@999: 	Which ones are passed in depends on the hook being called, but
belaran@999: 	a hook can ignore arguments it doesn't care about by dropping
belaran@999: 	them into a keyword argument dict, as with
belaran@999: 	<literal moreinfo="none">**kwargs</literal> above.
belaran@999:       </para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Some hook examples</title>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Writing meaningful commit messages</title>
belaran@999: 
belaran@999:       <para id="x_231">It's hard to imagine a useful commit message being very
belaran@999: 	short. The simple <literal role="hook" moreinfo="none">pretxncommit</literal>
belaran@999: 	hook of the example below will prevent you from committing a
belaran@999: 	changeset with a message that is less than ten bytes long.
belaran@999:       </para>
belaran@999: 
belaran@999: <!-- BEGIN hook.msglen.go -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/hgrc</userinput>
belaran@999: [hooks]
belaran@999: pretxncommit.msglen = test `hg tip --template {desc} | wc -c` -ge 10
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'too short'</userinput>
belaran@999: transaction abort!
belaran@999: rollback completed
belaran@999: abort: pretxncommit.msglen hook exited with status 1
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'long enough'</userinput>
belaran@999: </screen>
belaran@999: <!-- END hook.msglen.go -->
belaran@999: 
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Checking for trailing whitespace</title>
belaran@999: 
belaran@999:       <para id="x_232">An interesting use of a commit-related hook is to help you
belaran@999: 	to write cleaner code.  A simple example of <quote>cleaner
belaran@999: 	  code</quote> is the dictum that a change should not add any
belaran@999: 	new lines of text that contain <quote>trailing
belaran@999: 	  whitespace</quote>.  Trailing whitespace is a series of
belaran@999: 	space and tab characters at the end of a line of text.  In
belaran@999: 	most cases, trailing whitespace is unnecessary, invisible
belaran@999: 	noise, but it is occasionally problematic, and people often
belaran@999: 	prefer to get rid of it.
belaran@999:       </para>
belaran@999: 
belaran@999:       <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
belaran@999: 	have a trailing whitespace problem.  If you use the <literal role="hook" moreinfo="none">precommit</literal> hook, the hook will not know
belaran@999: 	which files you are committing, so it will have to check every
belaran@999: 	modified file in the repository for trailing white space.  If
belaran@999: 	you want to commit a change to just the file
belaran@999: 	<filename moreinfo="none">foo</filename>, but the file
belaran@999: 	<filename moreinfo="none">bar</filename> contains trailing whitespace, doing a
belaran@999: 	check in the <literal role="hook" moreinfo="none">precommit</literal> hook
belaran@999: 	will prevent you from committing <filename moreinfo="none">foo</filename> due
belaran@999: 	to the problem with <filename moreinfo="none">bar</filename>.  This doesn't
belaran@999: 	seem right.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_234">Should you choose the <literal role="hook" moreinfo="none">pretxncommit</literal> hook, the check won't
belaran@999: 	occur until just before the transaction for the commit
belaran@999: 	completes.  This will allow you to check for problems only the
belaran@999: 	exact files that are being committed.  However, if you entered
belaran@999: 	the commit message interactively and the hook fails, the
belaran@999: 	transaction will roll back; you'll have to re-enter the commit
belaran@999: 	message after you fix the trailing whitespace and run <command role="hg-cmd" moreinfo="none">hg commit</command> again.
belaran@999:       </para>
belaran@999: 
belaran@999:       <!-- BEGIN ch09/hook.ws.simple -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/hgrc</userinput>
belaran@999: [hooks]
belaran@999: pretxncommit.whitespace = hg export tip | (! egrep -q '^\+.*[ \t]$')
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'a ' &gt; a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'test with trailing whitespace'</userinput>
belaran@999: adding a
belaran@999: transaction abort!
belaran@999: rollback completed
belaran@999: abort: pretxncommit.whitespace hook exited with status 1
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'a' &gt; a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'drop trailing whitespace and try again'</userinput>
belaran@999: </screen>
belaran@999: <!-- END ch09/hook.ws.simple -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_235">In this example, we introduce a simple <literal role="hook" moreinfo="none">pretxncommit</literal> hook that checks for
belaran@999: 	trailing whitespace.  This hook is short, but not very
belaran@999: 	helpful.  It exits with an error status if a change adds a
belaran@999: 	line with trailing whitespace to any file, but does not print
belaran@999: 	any information that might help us to identify the offending
belaran@999: 	file or line.  It also has the nice property of not paying
belaran@999: 	attention to unmodified lines; only lines that introduce new
belaran@999: 	trailing whitespace cause problems.
belaran@999:       </para>
belaran@999: 
belaran@999:       <!-- BEGIN ch09/check_whitespace.py.lst -->
belaran@999: <programlisting format="linespecific">#!/usr/bin/env python
belaran@999: #
belaran@999: # save as .hg/check_whitespace.py and make executable
belaran@999: 
belaran@999: import re
belaran@999: 
belaran@999: def trailing_whitespace(difflines):
belaran@999:     # 
belaran@999:     linenum, header = 0, False
belaran@999: 
belaran@999:     for line in difflines:
belaran@999:         if header:
belaran@999:             # remember the name of the file that this diff affects
belaran@999:             m = re.match(r'(?:---|\+\+\+) ([^\t]+)', line)
belaran@999:             if m and m.group(1) != '/dev/null':
belaran@999:                 filename = m.group(1).split('/', 1)[-1]
belaran@999:             if line.startswith('+++ '):
belaran@999:                 header = False
belaran@999:             continue
belaran@999:         if line.startswith('diff '):
belaran@999:             header = True
belaran@999:             continue
belaran@999:         # hunk header - save the line number
belaran@999:         m = re.match(r'@@ -\d+,\d+ \+(\d+),', line)
belaran@999:         if m:
belaran@999:             linenum = int(m.group(1))
belaran@999:             continue
belaran@999:         # hunk body - check for an added line with trailing whitespace
belaran@999:         m = re.match(r'\+.*\s$', line)
belaran@999:         if m:
belaran@999:             yield filename, linenum
belaran@999:         if line and line[0] in ' +':
belaran@999:             linenum += 1
belaran@999: 
belaran@999: if __name__ == '__main__':
belaran@999:     import os, sys
belaran@999:     
belaran@999:     added = 0
belaran@999:     for filename, linenum in trailing_whitespace(os.popen('hg export tip')):
belaran@999:         print &gt;&gt; sys.stderr, ('%s, line %d: trailing whitespace added' %
belaran@999:                               (filename, linenum))
belaran@999:         added += 1
belaran@999:     if added:
belaran@999:         # save the commit message so we don't need to retype it
belaran@999:         os.system('hg tip --template "{desc}" &gt; .hg/commit.save')
belaran@999:         print &gt;&gt; sys.stderr, 'commit message saved to .hg/commit.save'
belaran@999:         sys.exit(1)</programlisting>
belaran@999: <!-- END ch09/check_whitespace.py.lst -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_236">The above version is much more complex, but also more
belaran@999: 	useful.  It parses a unified diff to see if any lines add
belaran@999: 	trailing whitespace, and prints the name of the file and the
belaran@999: 	line number of each such occurrence.  Even better, if the
belaran@999: 	change adds trailing whitespace, this hook saves the commit
belaran@999: 	comment and prints the name of the save file before exiting
belaran@999: 	and telling Mercurial to roll the transaction back, so you can
belaran@999: 	use the <option role="hg-opt-commit">-l filename</option>
belaran@999: 	option to <command role="hg-cmd" moreinfo="none">hg commit</command> to reuse
belaran@999: 	the saved commit message once you've corrected the problem.
belaran@999:       </para>
belaran@999: 
belaran@999:       <!-- BEGIN ch09/hook.ws.better -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/hgrc</userinput>
belaran@999: [hooks]
belaran@999: pretxncommit.whitespace = .hg/check_whitespace.py
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'a ' &gt;&gt; a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'add new line with trailing whitespace'</userinput>
belaran@999: a, line 2: trailing whitespace added
belaran@999: commit message saved to .hg/commit.save
belaran@999: transaction abort!
belaran@999: rollback completed
belaran@999: abort: pretxncommit.whitespace hook exited with status 1
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">sed -i 's, *$,,' a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'trimmed trailing whitespace'</userinput>
belaran@999: a, line 2: trailing whitespace added
belaran@999: commit message saved to .hg/commit.save
belaran@999: transaction abort!
belaran@999: rollback completed
belaran@999: abort: pretxncommit.whitespace hook exited with status 1
belaran@999: </screen>
belaran@999: <!-- END ch09/hook.ws.better -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_237">As a final aside, note in the example above the
belaran@999: 	use of <command moreinfo="none">sed</command>'s in-place editing feature to
belaran@999: 	get rid of trailing whitespace from a file.  This is concise
belaran@999: 	and useful enough that I will reproduce it here (using
belaran@999: 	<command moreinfo="none">perl</command> for good measure).</para>
belaran@999:       <programlisting format="linespecific">perl -pi -e 's,\s+$,,' filename</programlisting>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Bundled hooks</title>
belaran@999: 
belaran@999:     <para id="x_238">Mercurial ships with several bundled hooks.  You can find
belaran@999:       them in the <filename class="directory" moreinfo="none">hgext</filename>
belaran@999:       directory of a Mercurial source tree.  If you are using a
belaran@999:       Mercurial binary package, the hooks will be located in the
belaran@999:       <filename class="directory" moreinfo="none">hgext</filename> directory of
belaran@999:       wherever your package installer put Mercurial.
belaran@999:     </para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title><literal role="hg-ext" moreinfo="none">acl</literal>—access
belaran@999: 	control for parts of a repository</title>
belaran@999: 
belaran@999:       <para id="x_239">The <literal role="hg-ext" moreinfo="none">acl</literal> extension lets
belaran@999: 	you control which remote users are allowed to push changesets
belaran@999: 	to a networked server.  You can protect any portion of a
belaran@999: 	repository (including the entire repo), so that a specific
belaran@999: 	remote user can push changes that do not affect the protected
belaran@999: 	portion.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_23a">This extension implements access control based on the
belaran@999: 	identity of the user performing a push,
belaran@999: 	<emphasis>not</emphasis> on who committed the changesets
belaran@999: 	they're pushing.  It makes sense to use this hook only if you
belaran@999: 	have a locked-down server environment that authenticates
belaran@999: 	remote users, and you want to be sure that only specific users
belaran@999: 	are allowed to push changes to that server.
belaran@999:       </para>
belaran@999: 
belaran@999:       <sect3>
belaran@999: 	<title>Configuring the <literal role="hook" moreinfo="none">acl</literal>
belaran@999: 	  hook</title>
belaran@999: 
belaran@999: 	<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
belaran@999: 	  <literal role="hook" moreinfo="none">pretxnchangegroup</literal> hook.  This
belaran@999: 	  lets it see which files are modified by each incoming
belaran@999: 	  changeset, and roll back a group of changesets if they
belaran@999: 	  modify <quote>forbidden</quote> files.  Example:
belaran@999: 	</para>
belaran@999: 	<programlisting format="linespecific">[hooks]
belaran@999: pretxnchangegroup.acl = python:hgext.acl.hook</programlisting>
belaran@999: 
belaran@999: 	<para id="x_23c">The <literal role="hg-ext" moreinfo="none">acl</literal> extension is
belaran@999: 	  configured using three sections.
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<para id="x_23d">The <literal role="rc-acl" moreinfo="none">acl</literal> section has
belaran@999: 	  only one entry, <envar role="rc-item-acl">sources</envar>,
belaran@999: 	  which lists the sources of incoming changesets that the hook
belaran@999: 	  should pay attention to.  You don't normally need to
belaran@999: 	  configure this section.
belaran@999: 	</para>
belaran@999: 	<itemizedlist>
belaran@999: 	  <listitem><para id="x_23e"><envar role="rc-item-acl">serve</envar>:
belaran@999: 	      Control incoming changesets that are arriving from a
belaran@999: 	      remote repository over http or ssh.  This is the default
belaran@999: 	      value of <envar role="rc-item-acl">sources</envar>, and
belaran@999: 	      usually the only setting you'll need for this
belaran@999: 	      configuration item.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_23f"><envar role="rc-item-acl">pull</envar>:
belaran@999: 	      Control incoming changesets that are arriving via a pull
belaran@999: 	      from a local repository.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_240"><envar role="rc-item-acl">push</envar>:
belaran@999: 	      Control incoming changesets that are arriving via a push
belaran@999: 	      from a local repository.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_241"><envar role="rc-item-acl">bundle</envar>:
belaran@999: 	      Control incoming changesets that are arriving from
belaran@999: 	      another repository via a bundle.
belaran@999: 	    </para>
belaran@999: 	  </listitem></itemizedlist>
belaran@999: 
belaran@999: 	<para id="x_242">The <literal role="rc-acl.allow" moreinfo="none">acl.allow</literal>
belaran@999: 	  section controls the users that are allowed to add
belaran@999: 	  changesets to the repository.  If this section is not
belaran@999: 	  present, all users that are not explicitly denied are
belaran@999: 	  allowed.  If this section is present, all users that are not
belaran@999: 	  explicitly allowed are denied (so an empty section means
belaran@999: 	  that all users are denied).
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<para id="x_243">The <literal role="rc-acl.deny" moreinfo="none">acl.deny</literal>
belaran@999: 	  section determines which users are denied from adding
belaran@999: 	  changesets to the repository.  If this section is not
belaran@999: 	  present or is empty, no users are denied.
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<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
belaran@999: 	  identical.  On the left of each entry is a glob pattern that
belaran@999: 	  matches files or directories, relative to the root of the
belaran@999: 	  repository; on the right, a user name.
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<para id="x_245">In the following example, the user
belaran@999: 	  <literal moreinfo="none">docwriter</literal> can only push changes to the
belaran@999: 	  <filename class="directory" moreinfo="none">docs</filename> subtree of the
belaran@999: 	  repository, while <literal moreinfo="none">intern</literal> can push changes
belaran@999: 	  to any file or directory except <filename class="directory" moreinfo="none">source/sensitive</filename>.
belaran@999: 	</para>
belaran@999: 	<programlisting format="linespecific">[acl.allow]
belaran@999: docs/** = docwriter
belaran@999: [acl.deny]
belaran@999: source/sensitive/** = intern</programlisting>
belaran@999: 
belaran@999:       </sect3>
belaran@999:       <sect3>
belaran@999: 	<title>Testing and troubleshooting</title>
belaran@999: 
belaran@999: 	<para id="x_246">If you want to test the <literal role="hg-ext" moreinfo="none">acl</literal> hook, run it with Mercurial's
belaran@999: 	  debugging output enabled.  Since you'll probably be running
belaran@999: 	  it on a server where it's not convenient (or sometimes
belaran@999: 	  possible) to pass in the <option role="hg-opt-global">--debug</option> option, don't forget
belaran@999: 	  that you can enable debugging output in your <filename role="special" moreinfo="none">~/.hgrc</filename>:
belaran@999: 	</para>
belaran@999: 	<programlisting format="linespecific">[ui]
belaran@999: debug = true</programlisting>
belaran@999: 	<para id="x_247">With this enabled, the <literal role="hg-ext" moreinfo="none">acl</literal> hook will print enough
belaran@999: 	  information to let you figure out why it is allowing or
belaran@999: 	  forbidding pushes from specific users.
belaran@999: 	</para>
belaran@999: 
belaran@999:       </sect3>    </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title><literal role="hg-ext" moreinfo="none">bugzilla</literal>—integration with
belaran@999: 	Bugzilla</title>
belaran@999: 
belaran@999:       <para id="x_248">The <literal role="hg-ext" moreinfo="none">bugzilla</literal> extension
belaran@999: 	adds a comment to a Bugzilla bug whenever it finds a reference
belaran@999: 	to that bug ID in a commit comment.  You can install this hook
belaran@999: 	on a shared server, so that any time a remote user pushes
belaran@999: 	changes to this server, the hook gets run.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_249">It adds a comment to the bug that looks like this (you can
belaran@999: 	configure the contents of the comment—see below):
belaran@999:       </para>
belaran@999:       <programlisting format="linespecific">Changeset aad8b264143a, made by Joe User
belaran@999: 	&lt;joe.user@domain.com&gt; in the frobnitz repository, refers
belaran@999: 	to this bug. For complete details, see
belaran@999: 	http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
belaran@999: 	Changeset description: Fix bug 10483 by guarding against some
belaran@999: 	NULL pointers</programlisting>
belaran@999:       <para id="x_24a">The value of this hook is that it automates the process of
belaran@999: 	updating a bug any time a changeset refers to it.  If you
belaran@999: 	configure the hook properly, it makes it easy for people to
belaran@999: 	browse straight from a Bugzilla bug to a changeset that refers
belaran@999: 	to that bug.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_24b">You can use the code in this hook as a starting point for
belaran@999: 	some more exotic Bugzilla integration recipes.  Here are a few
belaran@999: 	possibilities:
belaran@999:       </para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_24c">Require that every changeset pushed to the
belaran@999: 	    server have a valid bug ID in its commit comment.  In this
belaran@999: 	    case, you'd want to configure the hook as a <literal role="hook" moreinfo="none">pretxncommit</literal> hook.  This would
belaran@999: 	    allow the hook to reject changes that didn't contain bug
belaran@999: 	    IDs.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_24d">Allow incoming changesets to automatically
belaran@999: 	    modify the <emphasis>state</emphasis> of a bug, as well as
belaran@999: 	    simply adding a comment.  For example, the hook could
belaran@999: 	    recognise the string <quote>fixed bug 31337</quote> as
belaran@999: 	    indicating that it should update the state of bug 31337 to
belaran@999: 	    <quote>requires testing</quote>.
belaran@999: 	  </para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <sect3 id="sec:hook:bugzilla:config">
belaran@999: 	<title>Configuring the <literal role="hook" moreinfo="none">bugzilla</literal>
belaran@999: 	  hook</title>
belaran@999: 
belaran@999: 	<para id="x_24e">You should configure this hook in your server's
belaran@999: 	  <filename role="special" moreinfo="none">~/.hgrc</filename> as an <literal role="hook" moreinfo="none">incoming</literal> hook, for example as
belaran@999: 	  follows:
belaran@999: 	</para>
belaran@999: 	<programlisting format="linespecific">[hooks]
belaran@999: incoming.bugzilla = python:hgext.bugzilla.hook</programlisting>
belaran@999: 
belaran@999: 	<para id="x_24f">Because of the specialised nature of this hook, and
belaran@999: 	  because Bugzilla was not written with this kind of
belaran@999: 	  integration in mind, configuring this hook is a somewhat
belaran@999: 	  involved process.
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<para id="x_250">Before you begin, you must install the MySQL bindings
belaran@999: 	  for Python on the host(s) where you'll be running the hook.
belaran@999: 	  If this is not available as a binary package for your
belaran@999: 	  system, you can download it from
belaran@999: 	  <citation>web:mysql-python</citation>.
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<para id="x_251">Configuration information for this hook lives in the
belaran@999: 	  <literal role="rc-bugzilla" moreinfo="none">bugzilla</literal> section of
belaran@999: 	  your <filename role="special" moreinfo="none">~/.hgrc</filename>.
belaran@999: 	</para>
belaran@999: 	<itemizedlist>
belaran@999: 	  <listitem><para id="x_252"><envar role="rc-item-bugzilla">version</envar>: The version
belaran@999: 	      of Bugzilla installed on the server.  The database
belaran@999: 	      schema that Bugzilla uses changes occasionally, so this
belaran@999: 	      hook has to know exactly which schema to use.</para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_253"><envar role="rc-item-bugzilla">host</envar>:
belaran@999: 	      The hostname of the MySQL server that stores your
belaran@999: 	      Bugzilla data.  The database must be configured to allow
belaran@999: 	      connections from whatever host you are running the
belaran@999: 	      <literal role="hook" moreinfo="none">bugzilla</literal> hook on.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_254"><envar role="rc-item-bugzilla">user</envar>:
belaran@999: 	      The username with which to connect to the MySQL server.
belaran@999: 	      The database must be configured to allow this user to
belaran@999: 	      connect from whatever host you are running the <literal role="hook" moreinfo="none">bugzilla</literal> hook on.  This user
belaran@999: 	      must be able to access and modify Bugzilla tables.  The
belaran@999: 	      default value of this item is <literal moreinfo="none">bugs</literal>,
belaran@999: 	      which is the standard name of the Bugzilla user in a
belaran@999: 	      MySQL database.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_255"><envar role="rc-item-bugzilla">password</envar>: The MySQL
belaran@999: 	      password for the user you configured above.  This is
belaran@999: 	      stored as plain text, so you should make sure that
belaran@999: 	      unauthorised users cannot read the <filename role="special" moreinfo="none">~/.hgrc</filename> file where you
belaran@999: 	      store this information.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_256"><envar role="rc-item-bugzilla">db</envar>:
belaran@999: 	      The name of the Bugzilla database on the MySQL server.
belaran@999: 	      The default value of this item is
belaran@999: 	      <literal moreinfo="none">bugs</literal>, which is the standard name of
belaran@999: 	      the MySQL database where Bugzilla stores its data.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_257"><envar role="rc-item-bugzilla">notify</envar>: If you want
belaran@999: 	      Bugzilla to send out a notification email to subscribers
belaran@999: 	      after this hook has added a comment to a bug, you will
belaran@999: 	      need this hook to run a command whenever it updates the
belaran@999: 	      database.  The command to run depends on where you have
belaran@999: 	      installed Bugzilla, but it will typically look something
belaran@999: 	      like this, if you have Bugzilla installed in <filename class="directory" moreinfo="none">/var/www/html/bugzilla</filename>:
belaran@999: 	    </para>
belaran@999: 	    <programlisting format="linespecific">cd /var/www/html/bugzilla &amp;&amp;
belaran@999: 	      ./processmail %s nobody@nowhere.com</programlisting>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_258">  The Bugzilla
belaran@999: 	      <literal moreinfo="none">processmail</literal> program expects to be
belaran@999: 	      given a bug ID (the hook replaces
belaran@999: 	      <quote><literal moreinfo="none">%s</literal></quote> with the bug ID)
belaran@999: 	      and an email address.  It also expects to be able to
belaran@999: 	      write to some files in the directory that it runs in.
belaran@999: 	      If Bugzilla and this hook are not installed on the same
belaran@999: 	      machine, you will need to find a way to run
belaran@999: 	      <literal moreinfo="none">processmail</literal> on the server where
belaran@999: 	      Bugzilla is installed.
belaran@999: 	    </para>
belaran@999: 	  </listitem></itemizedlist>
belaran@999: 
belaran@999:       </sect3>
belaran@999:       <sect3>
belaran@999: 	<title>Mapping committer names to Bugzilla user names</title>
belaran@999: 
belaran@999: 	<para id="x_259">By default, the <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook tries to use the
belaran@999: 	  email address of a changeset's committer as the Bugzilla
belaran@999: 	  user name with which to update a bug.  If this does not suit
belaran@999: 	  your needs, you can map committer email addresses to
belaran@999: 	  Bugzilla user names using a <literal role="rc-usermap" moreinfo="none">usermap</literal> section.
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<para id="x_25a">Each item in the <literal role="rc-usermap" moreinfo="none">usermap</literal> section contains an
belaran@999: 	  email address on the left, and a Bugzilla user name on the
belaran@999: 	  right.
belaran@999: 	</para>
belaran@999: 	<programlisting format="linespecific">[usermap]
belaran@999: jane.user@example.com = jane</programlisting>
belaran@999: 	<para id="x_25b">You can either keep the <literal role="rc-usermap" moreinfo="none">usermap</literal> data in a normal
belaran@999: 	  <filename role="special" moreinfo="none">~/.hgrc</filename>, or tell the
belaran@999: 	  <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook to read the
belaran@999: 	  information from an external <filename moreinfo="none">usermap</filename>
belaran@999: 	  file.  In the latter case, you can store
belaran@999: 	  <filename moreinfo="none">usermap</filename> data by itself in (for example)
belaran@999: 	  a user-modifiable repository.  This makes it possible to let
belaran@999: 	  your users maintain their own <envar role="rc-item-bugzilla">usermap</envar> entries.  The main
belaran@999: 	  <filename role="special" moreinfo="none">~/.hgrc</filename> file might look
belaran@999: 	  like this:
belaran@999: 	</para>
belaran@999: 	<programlisting format="linespecific"># regular hgrc file refers to external usermap file
belaran@999: [bugzilla]
belaran@999: usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting>
belaran@999: 	<para id="x_25c">While the <filename moreinfo="none">usermap</filename> file that it
belaran@999: 	  refers to might look like this:
belaran@999: 	</para>
belaran@999: 	<programlisting format="linespecific"># bugzilla-usermap.conf - inside a hg repository
belaran@999: [usermap] stephanie@example.com = steph</programlisting>
belaran@999: 
belaran@999:       </sect3>
belaran@999:       <sect3>
belaran@999: 	<title>Configuring the text that gets added to a bug</title>
belaran@999: 
belaran@999: 	<para id="x_25d">You can configure the text that this hook adds as a
belaran@999: 	  comment; you specify it in the form of a Mercurial template.
belaran@999: 	  Several <filename role="special" moreinfo="none">~/.hgrc</filename> entries
belaran@999: 	  (still in the <literal role="rc-bugzilla" moreinfo="none">bugzilla</literal>
belaran@999: 	  section) control this behavior.
belaran@999: 	</para>
belaran@999: 	<itemizedlist>
belaran@999: 	  <listitem><para id="x_25e"><literal moreinfo="none">strip</literal>: The number of
belaran@999: 	      leading path elements to strip from a repository's path
belaran@999: 	      name to construct a partial path for a URL. For example,
belaran@999: 	      if the repositories on your server live under <filename class="directory" moreinfo="none">/home/hg/repos</filename>, and you
belaran@999: 	      have a repository whose path is <filename class="directory" moreinfo="none">/home/hg/repos/app/tests</filename>,
belaran@999: 	      then setting <literal moreinfo="none">strip</literal> to
belaran@999: 	      <literal moreinfo="none">4</literal> will give a partial path of
belaran@999: 	      <filename class="directory" moreinfo="none">app/tests</filename>.  The
belaran@999: 	      hook will make this partial path available when
belaran@999: 	      expanding a template, as <literal moreinfo="none">webroot</literal>.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_25f"><literal moreinfo="none">template</literal>: The text of the
belaran@999: 	      template to use.  In addition to the usual
belaran@999: 	      changeset-related variables, this template can use
belaran@999: 	      <literal moreinfo="none">hgweb</literal> (the value of the
belaran@999: 	      <literal moreinfo="none">hgweb</literal> configuration item above) and
belaran@999: 	      <literal moreinfo="none">webroot</literal> (the path constructed using
belaran@999: 	      <literal moreinfo="none">strip</literal> above).
belaran@999: 	    </para>
belaran@999: 	  </listitem></itemizedlist>
belaran@999: 
belaran@999: 	<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
belaran@999: 	  available when expanding a template, as the base string to
belaran@999: 	  use when constructing a URL that will let users browse from
belaran@999: 	  a Bugzilla comment to view a changeset.  Example:
belaran@999: 	</para>
belaran@999: 	<programlisting format="linespecific">[web]
belaran@999: baseurl = http://hg.domain.com/</programlisting>
belaran@999: 
belaran@999: 	<para id="x_261">Here is an example set of <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook config information.
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<!-- BEGIN ch10/bugzilla-config.lst -->
belaran@999: <programlisting format="linespecific">[bugzilla]
belaran@999: host = bugzilla.example.com
belaran@999: password = mypassword version = 2.16
belaran@999: # server-side repos live in /home/hg/repos, so strip 4 leading
belaran@999: # separators
belaran@999: strip = 4
belaran@999: hgweb = http://hg.example.com/
belaran@999: usermap = /home/hg/repos/notify/bugzilla.conf
belaran@999: template = Changeset {node|short}, made by {author} in the {webroot}
belaran@999:   repo, refers to this bug.\n
belaran@999:   For complete details, see
belaran@999:   {hgweb}{webroot}?cmd=changeset;node={node|short}\n
belaran@999:   Changeset description:\n
belaran@999:   \t{desc|tabindent}</programlisting>
belaran@999: <!-- END ch10/bugzilla-config.lst -->
belaran@999: 
belaran@999: 
belaran@999:       </sect3>
belaran@999:       <sect3>
belaran@999: 	<title>Testing and troubleshooting</title>
belaran@999: 
belaran@999: 	<para id="x_262">The most common problems with configuring the <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook relate to running
belaran@999: 	  Bugzilla's <filename moreinfo="none">processmail</filename> script and
belaran@999: 	  mapping committer names to user names.
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<para id="x_263">Recall from <xref linkend="sec:hook:bugzilla:config"/> above that the user
belaran@999: 	  that runs the Mercurial process on the server is also the
belaran@999: 	  one that will run the <filename moreinfo="none">processmail</filename>
belaran@999: 	  script.  The <filename moreinfo="none">processmail</filename> script
belaran@999: 	  sometimes causes Bugzilla to write to files in its
belaran@999: 	  configuration directory, and Bugzilla's configuration files
belaran@999: 	  are usually owned by the user that your web server runs
belaran@999: 	  under.
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<para id="x_264">You can cause <filename moreinfo="none">processmail</filename> to be run
belaran@999: 	  with the suitable user's identity using the
belaran@999: 	  <command moreinfo="none">sudo</command> command.  Here is an example entry
belaran@999: 	  for a <filename moreinfo="none">sudoers</filename> file.
belaran@999: 	</para>
belaran@999: 	<programlisting format="linespecific">hg_user = (httpd_user)
belaran@999: NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting>
belaran@999: 	<para id="x_265">This allows the <literal moreinfo="none">hg_user</literal> user to run a
belaran@999: 	  <filename moreinfo="none">processmail-wrapper</filename> program under the
belaran@999: 	  identity of <literal moreinfo="none">httpd_user</literal>.
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<para id="x_266">This indirection through a wrapper script is necessary,
belaran@999: 	  because <filename moreinfo="none">processmail</filename> expects to be run
belaran@999: 	  with its current directory set to wherever you installed
belaran@999: 	  Bugzilla; you can't specify that kind of constraint in a
belaran@999: 	  <filename moreinfo="none">sudoers</filename> file.  The contents of the
belaran@999: 	  wrapper script are simple:
belaran@999: 	</para>
belaran@999: 	<programlisting format="linespecific">#!/bin/sh
belaran@999: cd `dirname $0` &amp;&amp; ./processmail "$1" nobody@example.com</programlisting>
belaran@999: 	<para id="x_267">It doesn't seem to matter what email address you pass to
belaran@999: 	  <filename moreinfo="none">processmail</filename>.
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<para id="x_268">If your <literal role="rc-usermap" moreinfo="none">usermap</literal> is
belaran@999: 	  not set up correctly, users will see an error message from
belaran@999: 	  the <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook when they
belaran@999: 	  push changes to the server.  The error message will look
belaran@999: 	  like this:
belaran@999: 	</para>
belaran@999: 	<programlisting format="linespecific">cannot find bugzilla user id for john.q.public@example.com</programlisting>
belaran@999: 	<para id="x_269">What this means is that the committer's address,
belaran@999: 	  <literal moreinfo="none">john.q.public@example.com</literal>, is not a valid
belaran@999: 	  Bugzilla user name, nor does it have an entry in your
belaran@999: 	  <literal role="rc-usermap" moreinfo="none">usermap</literal> that maps it to
belaran@999: 	  a valid Bugzilla user name.
belaran@999: 	</para>
belaran@999: 
belaran@999:       </sect3>    </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title><literal role="hg-ext" moreinfo="none">notify</literal>—send email
belaran@999: 	notifications</title>
belaran@999: 
belaran@999:       <para id="x_26a">Although Mercurial's built-in web server provides RSS
belaran@999: 	feeds of changes in every repository, many people prefer to
belaran@999: 	receive change notifications via email.  The <literal role="hg-ext" moreinfo="none">notify</literal> hook lets you send out
belaran@999: 	notifications to a set of email addresses whenever changesets
belaran@999: 	arrive that those subscribers are interested in.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_26b">As with the <literal role="hg-ext" moreinfo="none">bugzilla</literal>
belaran@999: 	hook, the <literal role="hg-ext" moreinfo="none">notify</literal> hook is
belaran@999: 	template-driven, so you can customise the contents of the
belaran@999: 	notification messages that it sends.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_26c">By default, the <literal role="hg-ext" moreinfo="none">notify</literal>
belaran@999: 	hook includes a diff of every changeset that it sends out; you
belaran@999: 	can limit the size of the diff, or turn this feature off
belaran@999: 	entirely.  It is useful for letting subscribers review changes
belaran@999: 	immediately, rather than clicking to follow a URL.
belaran@999:       </para>
belaran@999: 
belaran@999:       <sect3>
belaran@999: 	<title>Configuring the <literal role="hg-ext" moreinfo="none">notify</literal>
belaran@999: 	  hook</title>
belaran@999: 
belaran@999: 	<para id="x_26d">You can set up the <literal role="hg-ext" moreinfo="none">notify</literal> hook to send one email
belaran@999: 	  message per incoming changeset, or one per incoming group of
belaran@999: 	  changesets (all those that arrived in a single pull or
belaran@999: 	  push).
belaran@999: 	</para>
belaran@999: 	<programlisting format="linespecific">[hooks]
belaran@999: # send one email per group of changes
belaran@999: changegroup.notify = python:hgext.notify.hook
belaran@999: # send one email per change
belaran@999: incoming.notify = python:hgext.notify.hook</programlisting>
belaran@999: 
belaran@999: 	<para id="x_26e">Configuration information for this hook lives in the
belaran@999: 	  <literal role="rc-notify" moreinfo="none">notify</literal> section of a
belaran@999: 	  <filename role="special" moreinfo="none">~/.hgrc</filename> file.
belaran@999: 	</para>
belaran@999: 	<itemizedlist>
belaran@999: 	  <listitem><para id="x_26f"><envar role="rc-item-notify">test</envar>:
belaran@999: 	      By default, this hook does not send out email at all;
belaran@999: 	      instead, it prints the message that it
belaran@999: 	      <emphasis>would</emphasis> send.  Set this item to
belaran@999: 	      <literal moreinfo="none">false</literal> to allow email to be sent. The
belaran@999: 	      reason that sending of email is turned off by default is
belaran@999: 	      that it takes several tries to configure this extension
belaran@999: 	      exactly as you would like, and it would be bad form to
belaran@999: 	      spam subscribers with a number of <quote>broken</quote>
belaran@999: 	      notifications while you debug your configuration.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_270"><envar role="rc-item-notify">config</envar>:
belaran@999: 	      The path to a configuration file that contains
belaran@999: 	      subscription information.  This is kept separate from
belaran@999: 	      the main <filename role="special" moreinfo="none">~/.hgrc</filename> so
belaran@999: 	      that you can maintain it in a repository of its own.
belaran@999: 	      People can then clone that repository, update their
belaran@999: 	      subscriptions, and push the changes back to your server.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_271"><envar role="rc-item-notify">strip</envar>:
belaran@999: 	      The number of leading path separator characters to strip
belaran@999: 	      from a repository's path, when deciding whether a
belaran@999: 	      repository has subscribers.  For example, if the
belaran@999: 	      repositories on your server live in <filename class="directory" moreinfo="none">/home/hg/repos</filename>, and
belaran@999: 	      <literal role="hg-ext" moreinfo="none">notify</literal> is considering a
belaran@999: 	      repository named <filename class="directory" moreinfo="none">/home/hg/repos/shared/test</filename>, 
belaran@999: 	      setting <envar role="rc-item-notify">strip</envar> to
belaran@999: 	      <literal moreinfo="none">4</literal> will cause <literal role="hg-ext" moreinfo="none">notify</literal> to trim the path it
belaran@999: 	      considers down to <filename class="directory" moreinfo="none">shared/test</filename>, and it will
belaran@999: 	      match subscribers against that.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_272"><envar role="rc-item-notify">template</envar>: The template
belaran@999: 	      text to use when sending messages.  This specifies both
belaran@999: 	      the contents of the message header and its body.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_273"><envar role="rc-item-notify">maxdiff</envar>: The maximum
belaran@999: 	      number of lines of diff data to append to the end of a
belaran@999: 	      message.  If a diff is longer than this, it is
belaran@999: 	      truncated.  By default, this is set to 300.  Set this to
belaran@999: 	      <literal moreinfo="none">0</literal> to omit diffs from notification
belaran@999: 	      emails.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_274"><envar role="rc-item-notify">sources</envar>: A list of
belaran@999: 	      sources of changesets to consider.  This lets you limit
belaran@999: 	      <literal role="hg-ext" moreinfo="none">notify</literal> to only sending
belaran@999: 	      out email about changes that remote users pushed into
belaran@999: 	      this repository via a server, for example.  See 
belaran@999: 	      <xref linkend="sec:hook:sources"/> for the sources you
belaran@999: 	      can specify here.
belaran@999: 	    </para>
belaran@999: 	  </listitem></itemizedlist>
belaran@999: 
belaran@999: 	<para id="x_275">If you set the <envar role="rc-item-web">baseurl</envar>
belaran@999: 	  item in the <literal role="rc-web" moreinfo="none">web</literal> section,
belaran@999: 	  you can use it in a template; it will be available as
belaran@999: 	  <literal moreinfo="none">webroot</literal>.
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<para id="x_276">Here is an example set of <literal role="hg-ext" moreinfo="none">notify</literal> configuration information.
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<!-- BEGIN ch10/notify-config.lst -->
belaran@999: <programlisting format="linespecific">[notify]
belaran@999: # really send email
belaran@999: test = false
belaran@999: # subscriber data lives in the notify repo
belaran@999: config = /home/hg/repos/notify/notify.conf
belaran@999: # repos live in /home/hg/repos on server, so strip 4 "/" chars
belaran@999: strip = 4
belaran@999: template = X-Hg-Repo: {webroot}\n
belaran@999:   Subject: {webroot}: {desc|firstline|strip}\n
belaran@999:   From: {author}
belaran@999:   \n\n
belaran@999:   changeset {node|short} in {root}
belaran@999:   \n\ndetails:
belaran@999:   {baseurl}{webroot}?cmd=changeset;node={node|short}
belaran@999:   description: {desc|tabindent|strip}
belaran@999: 
belaran@999: [web]
belaran@999: baseurl =
belaran@999: http://hg.example.com/</programlisting>
belaran@999: <!-- END ch10/notify-config.lst -->
belaran@999: 
belaran@999: 
belaran@999: 	<para id="x_277">This will produce a message that looks like the
belaran@999: 	  following:
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<!-- BEGIN ch10/notify-config-mail.lst -->
belaran@999: <programlisting format="linespecific">X-Hg-Repo: tests/slave
belaran@999: Subject: tests/slave: Handle error case when slave has no buffers
belaran@999: Date: Wed,  2 Aug 2006 15:25:46 -0700 (PDT)
belaran@999: 
belaran@999: changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave
belaran@999: 
belaran@999: details:
belaran@999: http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5 
belaran@999: 
belaran@999: description: Handle error case when slave has no buffers
belaran@999: 
belaran@999: diffs (54 lines):
belaran@999: diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h
belaran@999: --- a/include/tests.h      Wed Aug 02 15:19:52 2006 -0700
belaran@999: +++ b/include/tests.h      Wed Aug 02 15:25:26 2006 -0700
belaran@999: @@ -212,6 +212,15 @@ static __inline__
belaran@999: void test_headers(void *h)
belaran@999: [...snip...]</programlisting>
belaran@999: <!-- END ch10/notify-config-mail.lst -->
belaran@999: 
belaran@999: 
belaran@999:       </sect3>
belaran@999:       <sect3>
belaran@999: 	<title>Testing and troubleshooting</title>
belaran@999: 
belaran@999: 	<para id="x_278">Do not forget that by default, the <literal role="hg-ext" moreinfo="none">notify</literal> extension <emphasis>will not
belaran@999: 	  send any mail</emphasis> until you explicitly configure it to do so,
belaran@999: 	  by setting <envar role="rc-item-notify">test</envar> to
belaran@999: 	  <literal moreinfo="none">false</literal>.  Until you do that, it simply
belaran@999: 	  prints the message it <emphasis>would</emphasis> send.
belaran@999: 	</para>
belaran@999: 
belaran@999:       </sect3>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1 id="sec:hook:ref">
belaran@999:     <title>Information for writers of hooks</title>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>In-process hook execution</title>
belaran@999: 
belaran@999:       <para id="x_279">An in-process hook is called with arguments of the
belaran@999: 	following form:
belaran@999:       </para>
belaran@999:       <programlisting format="linespecific">def myhook(ui, repo, **kwargs): pass</programlisting>
belaran@999:       <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
belaran@999: 	<literal moreinfo="none">repo</literal> parameter is a <literal role="py-mod-mercurial.localrepo" moreinfo="none">localrepository</literal>
belaran@999: 	object.  The names and values of the
belaran@999: 	<literal moreinfo="none">**kwargs</literal> parameters depend on the hook
belaran@999: 	being invoked, with the following common features:
belaran@999:       </para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_27b">If a parameter is named
belaran@999: 	    <literal moreinfo="none">node</literal> or <literal moreinfo="none">parentN</literal>, it
belaran@999: 	    will contain a hexadecimal changeset ID. The empty string
belaran@999: 	    is used to represent <quote>null changeset ID</quote>
belaran@999: 	    instead of a string of zeroes.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_27c">If a parameter is named
belaran@999: 	    <literal moreinfo="none">url</literal>, it will contain the URL of a
belaran@999: 	    remote repository, if that can be determined.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_27d">Boolean-valued parameters are represented as
belaran@999: 	    Python <literal moreinfo="none">bool</literal> objects.
belaran@999: 	  </para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_27e">An in-process hook is called without a change to the
belaran@999: 	process's working directory (unlike external hooks, which are
belaran@999: 	run in the root of the repository).  It must not change the
belaran@999: 	process's working directory, or it will cause any calls it
belaran@999: 	makes into the Mercurial API to fail.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_27f">If a hook returns a boolean <quote>false</quote> value, it
belaran@999: 	is considered to have succeeded.  If it returns a boolean
belaran@999: 	<quote>true</quote> value or raises an exception, it is
belaran@999: 	considered to have failed.  A useful way to think of the
belaran@999: 	calling convention is <quote>tell me if you fail</quote>.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_280">Note that changeset IDs are passed into Python hooks as
belaran@999: 	hexadecimal strings, not the binary hashes that Mercurial's
belaran@999: 	APIs normally use.  To convert a hash from hex to binary, use
belaran@999: 	the <literal moreinfo="none">bin</literal> function.
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>External hook execution</title>
belaran@999: 
belaran@999:       <para id="x_281">An external hook is passed to the shell of the user
belaran@999: 	running Mercurial. Features of that shell, such as variable
belaran@999: 	substitution and command redirection, are available.  The hook
belaran@999: 	is run in the root directory of the repository (unlike
belaran@999: 	in-process hooks, which are run in the same directory that
belaran@999: 	Mercurial was run in).
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_282">Hook parameters are passed to the hook as environment
belaran@999: 	variables.  Each environment variable's name is converted in
belaran@999: 	upper case and prefixed with the string
belaran@999: 	<quote><literal moreinfo="none">HG_</literal></quote>.  For example, if the
belaran@999: 	name of a parameter is <quote><literal moreinfo="none">node</literal></quote>,
belaran@999: 	the name of the environment variable representing that
belaran@999: 	parameter will be <quote><literal moreinfo="none">HG_NODE</literal></quote>.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_283">A boolean parameter is represented as the string
belaran@999: 	<quote><literal moreinfo="none">1</literal></quote> for <quote>true</quote>,
belaran@999: 	<quote><literal moreinfo="none">0</literal></quote> for <quote>false</quote>.
belaran@999: 	If an environment variable is named <envar>HG_NODE</envar>,
belaran@999: 	<envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it
belaran@999: 	contains a changeset ID represented as a hexadecimal string.
belaran@999: 	The empty string is used to represent <quote>null changeset
belaran@999: 	  ID</quote> instead of a string of zeroes.  If an environment
belaran@999: 	variable is named <envar>HG_URL</envar>, it will contain the
belaran@999: 	URL of a remote repository, if that can be determined.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_284">If a hook exits with a status of zero, it is considered to
belaran@999: 	have succeeded.  If it exits with a non-zero status, it is
belaran@999: 	considered to have failed.
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Finding out where changesets come from</title>
belaran@999: 
belaran@999:       <para id="x_285">A hook that involves the transfer of changesets between a
belaran@999: 	local repository and another may be able to find out
belaran@999: 	information about the <quote>far side</quote>.  Mercurial
belaran@999: 	knows <emphasis>how</emphasis> changes are being transferred,
belaran@999: 	and in many cases <emphasis>where</emphasis> they are being
belaran@999: 	transferred to or from.
belaran@999:       </para>
belaran@999: 
belaran@999:       <sect3 id="sec:hook:sources">
belaran@999: 	<title>Sources of changesets</title>
belaran@999: 
belaran@999: 	<para id="x_286">Mercurial will tell a hook what means are, or were, used
belaran@999: 	  to transfer changesets between repositories.  This is
belaran@999: 	  provided by Mercurial in a Python parameter named
belaran@999: 	  <literal moreinfo="none">source</literal>, or an environment variable named
belaran@999: 	  <envar>HG_SOURCE</envar>.
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<itemizedlist>
belaran@999: 	  <listitem><para id="x_287"><literal moreinfo="none">serve</literal>: Changesets are
belaran@999: 	      transferred to or from a remote repository over http or
belaran@999: 	      ssh.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_288"><literal moreinfo="none">pull</literal>: Changesets are
belaran@999: 	      being transferred via a pull from one repository into
belaran@999: 	      another.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_289"><literal moreinfo="none">push</literal>: Changesets are
belaran@999: 	      being transferred via a push from one repository into
belaran@999: 	      another.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_28a"><literal moreinfo="none">bundle</literal>: Changesets are
belaran@999: 	      being transferred to or from a bundle.
belaran@999: 	    </para>
belaran@999: 	  </listitem></itemizedlist>
belaran@999:       </sect3>
belaran@999: 
belaran@999:       <sect3 id="sec:hook:url">
belaran@999: 	<title>Where changes are going—remote repository
belaran@999: 	  URLs</title>
belaran@999: 
belaran@999: 	<para id="x_28b">When possible, Mercurial will tell a hook the location
belaran@999: 	  of the <quote>far side</quote> of an activity that transfers
belaran@999: 	  changeset data between repositories.  This is provided by
belaran@999: 	  Mercurial in a Python parameter named
belaran@999: 	  <literal moreinfo="none">url</literal>, or an environment variable named
belaran@999: 	  <envar>HG_URL</envar>.
belaran@999: 	</para>
belaran@999: 
belaran@999: 	<para id="x_28c">This information is not always known.  If a hook is
belaran@999: 	  invoked in a repository that is being served via http or
belaran@999: 	  ssh, Mercurial cannot tell where the remote repository is,
belaran@999: 	  but it may know where the client is connecting from.  In
belaran@999: 	  such cases, the URL will take one of the following forms:
belaran@999: 	</para>
belaran@999: 	<itemizedlist>
belaran@999: 	  <listitem><para id="x_28d"><literal moreinfo="none">remote:ssh:1.2.3.4</literal>—remote 
belaran@999: 	      ssh client, at the IP address
belaran@999: 	      <literal moreinfo="none">1.2.3.4</literal>.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_28e"><literal moreinfo="none">remote:http:1.2.3.4</literal>—remote 
belaran@999: 	      http client, at the IP address
belaran@999: 	      <literal moreinfo="none">1.2.3.4</literal>.  If the client is using SSL,
belaran@999: 	      this will be of the form
belaran@999: 	      <literal moreinfo="none">remote:https:1.2.3.4</literal>.
belaran@999: 	    </para>
belaran@999: 	  </listitem>
belaran@999: 	  <listitem><para id="x_28f">Empty—no information could be
belaran@999: 	      discovered about the remote client.
belaran@999: 	    </para>
belaran@999: 	  </listitem></itemizedlist>
belaran@999:       </sect3>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Hook reference</title>
belaran@999: 
belaran@999:     <sect2 id="sec:hook:changegroup">
belaran@999:       <title><literal role="hook" moreinfo="none">changegroup</literal>—after
belaran@999: 	remote changesets added</title>
belaran@999: 
belaran@999:       <para id="x_290">This hook is run after a group of pre-existing changesets
belaran@999: 	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
belaran@999: 	  unbundle</command>.  This hook is run once per operation
belaran@999: 	that added one or more changesets.  This is in contrast to the
belaran@999: 	<literal role="hook" moreinfo="none">incoming</literal> hook, which is run
belaran@999: 	once per changeset, regardless of whether the changesets
belaran@999: 	arrive in a group.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_291">Some possible uses for this hook include kicking off an
belaran@999: 	automated build or test of the added changesets, updating a
belaran@999: 	bug database, or notifying subscribers that a repository
belaran@999: 	contains new changes.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_292">Parameters to this hook:
belaran@999:       </para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_293"><literal moreinfo="none">node</literal>: A changeset ID.  The
belaran@999: 	    changeset ID of the first changeset in the group that was
belaran@999: 	    added.  All changesets between this and
belaran@999: 	    <literal role="tag" moreinfo="none">tip</literal>, inclusive, were added by a single
belaran@999: 	    <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>.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_294"><literal moreinfo="none">source</literal>: A
belaran@999: 	    string.  The source of these changes.  See <xref linkend="sec:hook:sources"/> for details.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_295"><literal moreinfo="none">url</literal>: A URL.  The
belaran@999: 	    location of the remote repository, if known.  See <xref linkend="sec:hook:url"/> for more information.
belaran@999: 	  </para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <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"/>)
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2 id="sec:hook:commit">
belaran@999:       <title><literal role="hook" moreinfo="none">commit</literal>—after a new
belaran@999: 	changeset is created</title>
belaran@999: 
belaran@999:       <para id="x_297">This hook is run after a new changeset has been created.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_298">Parameters to this hook:
belaran@999:       </para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_299"><literal moreinfo="none">node</literal>: A changeset ID.  The
belaran@999: 	    changeset ID of the newly committed changeset.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_29a"><literal moreinfo="none">parent1</literal>: A changeset ID.
belaran@999: 	    The changeset ID of the first parent of the newly
belaran@999: 	    committed changeset.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_29b"><literal moreinfo="none">parent2</literal>: A changeset ID.
belaran@999: 	    The changeset ID of the second parent of the newly
belaran@999: 	    committed changeset.
belaran@999: 	  </para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <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"/>)
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2 id="sec:hook:incoming">
belaran@999:       <title><literal role="hook" moreinfo="none">incoming</literal>—after one
belaran@999: 	remote changeset is added</title>
belaran@999: 
belaran@999:       <para id="x_29d">This hook is run after a pre-existing changeset has been
belaran@999: 	added to the repository, for example via a <command role="hg-cmd" moreinfo="none">hg push</command>.  If a group of changesets
belaran@999: 	was added in a single operation, this hook is called once for
belaran@999: 	each added changeset.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_29e">You can use this hook for the same purposes as
belaran@999: 	the <literal role="hook" moreinfo="none">changegroup</literal> hook (<xref linkend="sec:hook:changegroup"/>); it's simply more
belaran@999: 	convenient sometimes to run a hook once per group of
belaran@999: 	changesets, while other times it's handier once per changeset.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_29f">Parameters to this hook:
belaran@999:       </para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_2a0"><literal moreinfo="none">node</literal>: A changeset ID.  The
belaran@999: 	    ID of the newly added changeset.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2a1"><literal moreinfo="none">source</literal>: A
belaran@999: 	    string.  The source of these changes.  See <xref linkend="sec:hook:sources"/> for details.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2a2"><literal moreinfo="none">url</literal>: A URL.  The
belaran@999: 	    location of the remote repository, if known.  See <xref linkend="sec:hook:url"/> for more information.
belaran@999: 	  </para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <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"/>)
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2 id="sec:hook:outgoing">
belaran@999:       <title><literal role="hook" moreinfo="none">outgoing</literal>—after
belaran@999: 	changesets are propagated</title>
belaran@999: 
belaran@999:       <para id="x_2a4">This hook is run after a group of changesets has been
belaran@999: 	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
belaran@999: 	  bundle</command> command.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2a5">One possible use for this hook is to notify administrators
belaran@999: 	that changes have been pulled.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2a6">Parameters to this hook:
belaran@999:       </para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_2a7"><literal moreinfo="none">node</literal>: A changeset ID.  The
belaran@999: 	    changeset ID of the first changeset of the group that was
belaran@999: 	    sent.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2a8"><literal moreinfo="none">source</literal>: A string.  The
belaran@999: 	    source of the of the operation (see <xref linkend="sec:hook:sources"/>).  If a remote
belaran@999: 	    client pulled changes from this repository,
belaran@999: 	    <literal moreinfo="none">source</literal> will be
belaran@999: 	    <literal moreinfo="none">serve</literal>.  If the client that obtained
belaran@999: 	    changes from this repository was local,
belaran@999: 	    <literal moreinfo="none">source</literal> will be
belaran@999: 	    <literal moreinfo="none">bundle</literal>, <literal moreinfo="none">pull</literal>, or
belaran@999: 	    <literal moreinfo="none">push</literal>, depending on the operation the
belaran@999: 	    client performed.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2a9"><literal moreinfo="none">url</literal>: A URL.  The
belaran@999: 	    location of the remote repository, if known.  See <xref linkend="sec:hook:url"/> for more information.
belaran@999: 	  </para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_2aa">See also: <literal role="hook" moreinfo="none">preoutgoing</literal> (<xref linkend="sec:hook:preoutgoing"/>)
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2 id="sec:hook:prechangegroup">
belaran@999:       <title><literal role="hook" moreinfo="none">prechangegroup</literal>—before starting
belaran@999: 	to add remote changesets</title>
belaran@999: 
belaran@999:       <para id="x_2ab">This controlling hook is run before Mercurial begins to
belaran@999: 	add a group of changesets from another repository.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2ac">This hook does not have any information about the
belaran@999: 	changesets to be added, because it is run before transmission
belaran@999: 	of those changesets is allowed to begin.  If this hook fails,
belaran@999: 	the changesets will not be transmitted.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2ad">One use for this hook is to prevent external changes from
belaran@999: 	being added to a repository.  For example, you could use this
belaran@999: 	to <quote>freeze</quote> a server-hosted branch temporarily or
belaran@999: 	permanently so that users cannot push to it, while still
belaran@999: 	allowing a local administrator to modify the repository.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2ae">Parameters to this hook:
belaran@999:       </para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_2af"><literal moreinfo="none">source</literal>: A string.  The
belaran@999: 	    source of these changes.  See <xref linkend="sec:hook:sources"/> for details.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2b0"><literal moreinfo="none">url</literal>: A URL.  The
belaran@999: 	    location of the remote repository, if known.  See <xref linkend="sec:hook:url"/> for more information.
belaran@999: 	  </para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <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"/>)
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2 id="sec:hook:precommit">
belaran@999:       <title><literal role="hook" moreinfo="none">precommit</literal>—before
belaran@999: 	starting to commit a changeset</title>
belaran@999: 
belaran@999:       <para id="x_2b2">This hook is run before Mercurial begins to commit a new
belaran@999: 	changeset. It is run before Mercurial has any of the metadata
belaran@999: 	for the commit, such as the files to be committed, the commit
belaran@999: 	message, or the commit date.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2b3">One use for this hook is to disable the ability to commit
belaran@999: 	new changesets, while still allowing incoming changesets.
belaran@999: 	Another is to run a build or test, and only allow the commit
belaran@999: 	to begin if the build or test succeeds.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2b4">Parameters to this hook:
belaran@999:       </para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_2b5"><literal moreinfo="none">parent1</literal>: A changeset ID.
belaran@999: 	    The changeset ID of the first parent of the working
belaran@999: 	    directory.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2b6"><literal moreinfo="none">parent2</literal>: A changeset ID.
belaran@999: 	    The changeset ID of the second parent of the working
belaran@999: 	    directory.
belaran@999: 	  </para>
belaran@999: 	</listitem></itemizedlist>
belaran@999:       <para id="x_2b7">If the commit proceeds, the parents of the working
belaran@999: 	directory will become the parents of the new changeset.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2b8">See also: <literal role="hook" moreinfo="none">commit</literal>
belaran@999: 	(<xref linkend="sec:hook:commit"/>), <literal role="hook" moreinfo="none">pretxncommit</literal> (<xref linkend="sec:hook:pretxncommit"/>)
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2 id="sec:hook:preoutgoing">
belaran@999:       <title><literal role="hook" moreinfo="none">preoutgoing</literal>—before
belaran@999: 	starting to propagate changesets</title>
belaran@999: 
belaran@999:       <para id="x_2b9">This hook is invoked before Mercurial knows the identities
belaran@999: 	of the changesets to be transmitted.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2ba">One use for this hook is to prevent changes from being
belaran@999: 	transmitted to another repository.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2bb">Parameters to this hook:
belaran@999:       </para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_2bc"><literal moreinfo="none">source</literal>: A
belaran@999: 	    string.  The source of the operation that is attempting to
belaran@999: 	    obtain changes from this repository (see <xref linkend="sec:hook:sources"/>).  See the documentation
belaran@999: 	    for the <literal moreinfo="none">source</literal> parameter to the
belaran@999: 	    <literal role="hook" moreinfo="none">outgoing</literal> hook, in
belaran@999: 	    <xref linkend="sec:hook:outgoing"/>, for possible values
belaran@999: 	    of this parameter.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2bd"><literal moreinfo="none">url</literal>: A URL.  The
belaran@999: 	    location of the remote repository, if known.  See <xref linkend="sec:hook:url"/> for more information.
belaran@999: 	  </para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_2be">See also: <literal role="hook" moreinfo="none">outgoing</literal> (<xref linkend="sec:hook:outgoing"/>)
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2 id="sec:hook:pretag">
belaran@999:       <title><literal role="hook" moreinfo="none">pretag</literal>—before
belaran@999: 	tagging a changeset</title>
belaran@999: 
belaran@999:       <para id="x_2bf">This controlling hook is run before a tag is created.  If
belaran@999: 	the hook succeeds, creation of the tag proceeds.  If the hook
belaran@999: 	fails, the tag is not created.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2c0">Parameters to this hook:
belaran@999:       </para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_2c1"><literal moreinfo="none">local</literal>: A boolean.  Whether
belaran@999: 	    the tag is local to this repository instance (i.e. stored
belaran@999: 	    in <filename role="special" moreinfo="none">.hg/localtags</filename>) or
belaran@999: 	    managed by Mercurial (stored in <filename role="special" moreinfo="none">.hgtags</filename>).
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2c2"><literal moreinfo="none">node</literal>: A changeset ID.  The
belaran@999: 	    ID of the changeset to be tagged.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2c3"><literal moreinfo="none">tag</literal>: A string.  The name of
belaran@999: 	    the tag to be created.
belaran@999: 	  </para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_2c4">If the tag to be created is
belaran@999: 	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.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2c5">See also: <literal role="hook" moreinfo="none">tag</literal>
belaran@999: 	(<xref linkend="sec:hook:tag"/>)
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2 id="sec:hook:pretxnchangegroup">
belaran@999:       <title><literal role="hook" moreinfo="none">pretxnchangegroup</literal>—before
belaran@999: 	completing addition of remote changesets</title>
belaran@999: 
belaran@999:       <para id="x_2c6">This controlling hook is run before a
belaran@999: 	transaction—that manages the addition of a group of new
belaran@999: 	changesets from outside the repository—completes.  If
belaran@999: 	the hook succeeds, the transaction completes, and all of the
belaran@999: 	changesets become permanent within this repository.  If the
belaran@999: 	hook fails, the transaction is rolled back, and the data for
belaran@999: 	the changesets is erased.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2c7">This hook can access the metadata associated with the
belaran@999: 	almost-added changesets, but it should not do anything
belaran@999: 	permanent with this data. It must also not modify the working
belaran@999: 	directory.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2c8">While this hook is running, if other Mercurial processes
belaran@999: 	access this repository, they will be able to see the
belaran@999: 	almost-added changesets as if they are permanent.  This may
belaran@999: 	lead to race conditions if you do not take steps to avoid
belaran@999: 	them.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2c9">This hook can be used to automatically vet a group of
belaran@999: 	changesets.  If the hook fails, all of the changesets are
belaran@999: 	<quote>rejected</quote> when the transaction rolls back.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2ca">Parameters to this hook:
belaran@999:       </para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_2cb"><literal moreinfo="none">node</literal>: A changeset ID.  The
belaran@999: 	    changeset ID of the first changeset in the group that was
belaran@999: 	    added.  All changesets between this and
belaran@999: 	    <literal role="tag" moreinfo="none">tip</literal>,
belaran@999: 	    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>.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2cc"><literal moreinfo="none">source</literal>: A
belaran@999: 	    string.  The source of these changes.  See <xref linkend="sec:hook:sources"/> for details.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2cd"><literal moreinfo="none">url</literal>: A URL.  The
belaran@999: 	    location of the remote repository, if known.  See <xref linkend="sec:hook:url"/> for more information.
belaran@999: 	  </para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <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"/>)
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2 id="sec:hook:pretxncommit">
belaran@999:       <title><literal role="hook" moreinfo="none">pretxncommit</literal>—before
belaran@999: 	completing commit of new changeset</title>
belaran@999: 
belaran@999:       <para id="x_2cf">This controlling hook is run before a
belaran@999: 	transaction—that manages a new commit—completes.
belaran@999: 	If the hook succeeds, the transaction completes and the
belaran@999: 	changeset becomes permanent within this repository.  If the
belaran@999: 	hook fails, the transaction is rolled back, and the commit
belaran@999: 	data is erased.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2d0">This hook can access the metadata associated with the
belaran@999: 	almost-new changeset, but it should not do anything permanent
belaran@999: 	with this data.  It must also not modify the working
belaran@999: 	directory.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2d1">While this hook is running, if other Mercurial processes
belaran@999: 	access this repository, they will be able to see the
belaran@999: 	almost-new changeset as if it is permanent.  This may lead to
belaran@999: 	race conditions if you do not take steps to avoid them.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2d2">Parameters to this hook:</para>
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_2d3"><literal moreinfo="none">node</literal>: A changeset ID.  The
belaran@999: 	    changeset ID of the newly committed changeset.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2d4"><literal moreinfo="none">parent1</literal>: A changeset ID.
belaran@999: 	    The changeset ID of the first parent of the newly
belaran@999: 	    committed changeset.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2d5"><literal moreinfo="none">parent2</literal>: A changeset ID.
belaran@999: 	    The changeset ID of the second parent of the newly
belaran@999: 	    committed changeset.
belaran@999: 	  </para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_2d6">See also: <literal role="hook" moreinfo="none">precommit</literal> (<xref linkend="sec:hook:precommit"/>)
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2 id="sec:hook:preupdate">
belaran@999:       <title><literal role="hook" moreinfo="none">preupdate</literal>—before
belaran@999: 	updating or merging working directory</title>
belaran@999: 
belaran@999:       <para id="x_2d7">This controlling hook is run before an update
belaran@999: 	or merge of the working directory begins.  It is run only if
belaran@999: 	Mercurial's normal pre-update checks determine that the update
belaran@999: 	or merge can proceed.  If the hook succeeds, the update or
belaran@999: 	merge may proceed; if it fails, the update or merge does not
belaran@999: 	start.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2d8">Parameters to this hook:
belaran@999:       </para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_2d9"><literal moreinfo="none">parent1</literal>: A
belaran@999: 	    changeset ID. The ID of the parent that the working
belaran@999: 	    directory is to be updated to.  If the working directory
belaran@999: 	    is being merged, it will not change this parent.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2da"><literal moreinfo="none">parent2</literal>: A
belaran@999: 	    changeset ID. Only set if the working directory is being
belaran@999: 	    merged.  The ID of the revision that the working directory
belaran@999: 	    is being merged with.
belaran@999: 	  </para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_2db">See also: <literal role="hook" moreinfo="none">update</literal>
belaran@999: 	(<xref linkend="sec:hook:update"/>)</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2 id="sec:hook:tag">
belaran@999:       <title><literal role="hook" moreinfo="none">tag</literal>—after tagging a
belaran@999: 	changeset</title>
belaran@999: 
belaran@999:       <para id="x_2dc">This hook is run after a tag has been created.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2dd">Parameters to this hook:
belaran@999:       </para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_2de"><literal moreinfo="none">local</literal>: A boolean.  Whether
belaran@999: 	    the new tag is local to this repository instance (i.e.
belaran@999: 	    stored in <filename role="special" moreinfo="none">.hg/localtags</filename>) or managed by
belaran@999: 	    Mercurial (stored in <filename role="special" moreinfo="none">.hgtags</filename>).
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2df"><literal moreinfo="none">node</literal>: A changeset ID.  The
belaran@999: 	    ID of the changeset that was tagged.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2e0"><literal moreinfo="none">tag</literal>: A string.  The name of
belaran@999: 	    the tag that was created.
belaran@999: 	  </para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <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.
belaran@999:       </para>
belaran@999: 
belaran@999:       <para id="x_2e2">See also: <literal role="hook" moreinfo="none">pretag</literal>
belaran@999: 	(<xref linkend="sec:hook:pretag"/>)
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2 id="sec:hook:update">
belaran@999:       <title><literal role="hook" moreinfo="none">update</literal>—after
belaran@999: 	updating or merging working directory</title>
belaran@999: 
belaran@999:       <para id="x_2e3">This hook is run after an update or merge of the working
belaran@999: 	directory completes.  Since a merge can fail (if the external
belaran@999: 	<command moreinfo="none">hgmerge</command> command fails to resolve conflicts
belaran@999: 	in a file), this hook communicates whether the update or merge
belaran@999: 	completed cleanly.
belaran@999:       </para>
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_2e4"><literal moreinfo="none">error</literal>: A boolean.
belaran@999: 	    Indicates whether the update or merge completed
belaran@999: 	    successfully.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2e5"><literal moreinfo="none">parent1</literal>: A changeset ID.
belaran@999: 	    The ID of the parent that the working directory was
belaran@999: 	    updated to.  If the working directory was merged, it will
belaran@999: 	    not have changed this parent.
belaran@999: 	  </para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_2e6"><literal moreinfo="none">parent2</literal>: A changeset ID.
belaran@999: 	    Only set if the working directory was merged.  The ID of
belaran@999: 	    the revision that the working directory was merged with.
belaran@999: 	  </para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_2e7">See also: <literal role="hook" moreinfo="none">preupdate</literal>
belaran@999: 	(<xref linkend="sec:hook:preupdate"/>)
belaran@999:       </para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: </chapter>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "chapter")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN ch11 -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <chapter id="chap:template">
belaran@999:   <?dbhtml filename="customizing-the-output-of-mercurial.html"?>
belaran@999:   <title>Customizing the output of Mercurial</title>
belaran@999: 
belaran@999:   <para id="x_578">Mercurial provides a powerful mechanism to let you control how
belaran@999:     it displays information.  The mechanism is based on templates.
belaran@999:     You can use templates to generate specific output for a single
belaran@999:     command, or to customize the entire appearance of the built-in web
belaran@999:     interface.</para>
belaran@999: 
belaran@999:   <sect1 id="sec:style">
belaran@999:     <title>Using precanned output styles</title>
belaran@999: 
belaran@999:     <para id="x_579">Packaged with Mercurial are some output styles that you can
belaran@999:       use immediately.  A style is simply a precanned template that
belaran@999:       someone wrote and installed somewhere that Mercurial can
belaran@999:       find.</para>
belaran@999: 
belaran@999:     <para id="x_57a">Before we take a look at Mercurial's bundled styles, let's
belaran@999:       review its normal output.</para>
belaran@999: 
belaran@999:     <!-- BEGIN template.simple.normal -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1</userinput>
belaran@999: changeset:   1:e3d2468ca47c
belaran@999: tag:         mytag
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:17 2009 +0000
belaran@999: summary:     added line to end of &lt;&lt;hello&gt;&gt; file.
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END template.simple.normal -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_57b">This is somewhat informative, but it takes up a lot of
belaran@999:       space—five lines of output per changeset.  The
belaran@999:       <literal moreinfo="none">compact</literal> style reduces this to three lines,
belaran@999:       presented in a sparse manner.</para>
belaran@999: 
belaran@999:     <!-- BEGIN template.simple.compact -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style compact</userinput>
belaran@999: 3[tip]   d3cc7424d32c   2009-08-16 14:05 +0000   bos
belaran@999:   Added tag v0.1 for changeset a5dd5392119b
belaran@999: 
belaran@999: 2[v0.1]   a5dd5392119b   2009-08-16 14:05 +0000   bos
belaran@999:   Added tag mytag for changeset e3d2468ca47c
belaran@999: 
belaran@999: 1[mytag]   e3d2468ca47c   2009-08-16 14:05 +0000   bos
belaran@999:   added line to end of &lt;&lt;hello&gt;&gt; file.
belaran@999: 
belaran@999: 0   1cf727e9fc61   2009-08-16 14:05 +0000   bos
belaran@999:   added hello
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END template.simple.compact -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_57c">The <literal moreinfo="none">changelog</literal> style hints at the
belaran@999:       expressive power of Mercurial's templating engine.  This style
belaran@999:       attempts to follow the GNU Project's changelog
belaran@999:       guidelines<citation>web:changelog</citation>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN template.simple.changelog -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style changelog</userinput>
belaran@999: 2009-08-16  Bryan O'Sullivan  &lt;bos@serpentine.com&gt;
belaran@999: 
belaran@999: 	* .hgtags:
belaran@999: 	Added tag v0.1 for changeset a5dd5392119b
belaran@999: 	[d3cc7424d32c] [tip]
belaran@999: 
belaran@999: 	* .hgtags:
belaran@999: 	Added tag mytag for changeset e3d2468ca47c
belaran@999: 	[a5dd5392119b] [v0.1]
belaran@999: 
belaran@999: 	* goodbye, hello:
belaran@999: 	added line to end of &lt;&lt;hello&gt;&gt; file.
belaran@999: 
belaran@999: 	in addition, added a file with the helpful name (at least i hope
belaran@999: 	that some might consider it so) of goodbye.
belaran@999: 	[e3d2468ca47c] [mytag]
belaran@999: 
belaran@999: 	* hello:
belaran@999: 	added hello
belaran@999: 	[1cf727e9fc61]
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END template.simple.changelog -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_57d">You will not be shocked to learn that Mercurial's default
belaran@999:       output style is named <literal moreinfo="none">default</literal>.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Setting a default style</title>
belaran@999: 
belaran@999:       <para id="x_57e">You can modify the output style that Mercurial will use
belaran@999: 	for every command by editing your <filename role="special" moreinfo="none">~/.hgrc</filename> file, naming the style
belaran@999: 	you would prefer to use.</para>
belaran@999: 
belaran@999:       <programlisting format="linespecific">[ui]
belaran@999: style = compact</programlisting>
belaran@999: 
belaran@999:       <para id="x_57f">If you write a style of your own, you can use it by either
belaran@999: 	providing the path to your style file, or copying your style
belaran@999: 	file into a location where Mercurial can find it (typically
belaran@999: 	the <literal moreinfo="none">templates</literal> subdirectory of your
belaran@999: 	Mercurial install directory).</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Commands that support styles and templates</title>
belaran@999: 
belaran@999:     <para id="x_580">All of Mercurial's
belaran@999:       <quote><literal moreinfo="none">log</literal>-like</quote> commands let you use
belaran@999:       styles and templates: <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	incoming</command>, <command role="hg-cmd" moreinfo="none">hg log</command>,
belaran@999:       <command role="hg-cmd" moreinfo="none">hg outgoing</command>, and <command role="hg-cmd" moreinfo="none">hg tip</command>.</para>
belaran@999: 
belaran@999:     <para id="x_581">As I write this manual, these are so far the only commands
belaran@999:       that support styles and templates.  Since these are the most
belaran@999:       important commands that need customizable output, there has been
belaran@999:       little pressure from the Mercurial user community to add style
belaran@999:       and template support to other commands.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>The basics of templating</title>
belaran@999: 
belaran@999:     <para id="x_582">At its simplest, a Mercurial template is a piece of text.
belaran@999:       Some of the text never changes, while other parts are
belaran@999:       <emphasis>expanded</emphasis>, or replaced with new text, when
belaran@999:       necessary.</para>
belaran@999: 
belaran@999:     <para id="x_583">Before we continue, let's look again at a simple example of
belaran@999:       Mercurial's normal output.</para>
belaran@999: 
belaran@999:     <!-- BEGIN template.simple.normal -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1</userinput>
belaran@999: changeset:   1:e3d2468ca47c
belaran@999: tag:         mytag
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:17 2009 +0000
belaran@999: summary:     added line to end of &lt;&lt;hello&gt;&gt; file.
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END template.simple.normal -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_584">Now, let's run the same command, but using a template to
belaran@999:       change its output.</para>
belaran@999: 
belaran@999:     <!-- BEGIN template.simple.simplest -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'i saw a changeset\n'</userinput>
belaran@999: i saw a changeset
belaran@999: </screen>
belaran@999: <!-- END template.simple.simplest -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_585">The example above illustrates the simplest possible
belaran@999:       template; it's just a piece of static text, printed once for
belaran@999:       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
belaran@999:       the given text as the template when printing each
belaran@999:       changeset.</para>
belaran@999: 
belaran@999:     <para id="x_586">Notice that the template string above ends with the text
belaran@999:       <quote><literal moreinfo="none">\n</literal></quote>.  This is an
belaran@999:       <emphasis>escape sequence</emphasis>, telling Mercurial to print
belaran@999:       a newline at the end of each template item.  If you omit this
belaran@999:       newline, Mercurial will run each piece of output together.  See
belaran@999:       <xref linkend="sec:template:escape"/> for more details
belaran@999:       of escape sequences.</para>
belaran@999: 
belaran@999:     <para id="x_587">A template that prints a fixed string of text all the time
belaran@999:       isn't very useful; let's try something a bit more
belaran@999:       complex.</para>
belaran@999: 
belaran@999:     <!-- BEGIN template.simple.simplesub -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --template 'i saw a changeset: {desc}\n'</userinput>
belaran@999: i saw a changeset: Added tag v0.1 for changeset a5dd5392119b
belaran@999: i saw a changeset: Added tag mytag for changeset e3d2468ca47c
belaran@999: i saw a changeset: added line to end of &lt;&lt;hello&gt;&gt; file.
belaran@999: 
belaran@999: in addition, added a file with the helpful name (at least i hope that some might consider it so) of goodbye.
belaran@999: i saw a changeset: added hello
belaran@999: </screen>
belaran@999: <!-- END template.simple.simplesub -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_588">As you can see, the string
belaran@999:       <quote><literal moreinfo="none">{desc}</literal></quote> in the template has
belaran@999:       been replaced in the output with the description of each
belaran@999:       changeset.  Every time Mercurial finds text enclosed in curly
belaran@999:       braces (<quote><literal moreinfo="none">{</literal></quote> and
belaran@999:       <quote><literal moreinfo="none">}</literal></quote>), it will try to replace the
belaran@999:       braces and text with the expansion of whatever is inside.  To
belaran@999:       print a literal curly brace, you must escape it, as described in
belaran@999:       <xref linkend="sec:template:escape"/>.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="sec:template:keyword">
belaran@999:     <title>Common template keywords</title>
belaran@999: 
belaran@999:     <para id="x_589">You can start writing simple templates immediately using the
belaran@999:       keywords below.</para>
belaran@999: 
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_58a"><literal role="template-keyword" moreinfo="none">author</literal>: String.  The
belaran@999: 	  unmodified author of the changeset.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_58b"><literal role="template-keyword" moreinfo="none">branches</literal>: String.  The
belaran@999: 	  name of the branch on which the changeset was committed.
belaran@999: 	  Will be empty if the branch name was
belaran@999: 	  <literal moreinfo="none">default</literal>.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_58c"><literal role="template-keyword" moreinfo="none">date</literal>:
belaran@999: 	  Date information.  The date when the changeset was
belaran@999: 	  committed.  This is <emphasis>not</emphasis> human-readable;
belaran@999: 	  you must pass it through a filter that will render it
belaran@999: 	  appropriately.  See <xref linkend="sec:template:filter"/> for more information
belaran@999: 	  on filters. The date is expressed as a pair of numbers.  The
belaran@999: 	  first number is a Unix UTC timestamp (seconds since January
belaran@999: 	  1, 1970); the second is the offset of the committer's
belaran@999: 	  timezone from UTC, in seconds.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_58d"><literal role="template-keyword" moreinfo="none">desc</literal>:
belaran@999: 	  String.  The text of the changeset description.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_58e"><literal role="template-keyword" moreinfo="none">files</literal>: List of strings.
belaran@999: 	  All files modified, added, or removed by this
belaran@999: 	  changeset.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_58f"><literal role="template-keyword" moreinfo="none">file_adds</literal>: List of
belaran@999: 	  strings.  Files added by this changeset.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_590"><literal role="template-keyword" moreinfo="none">file_dels</literal>: List of
belaran@999: 	  strings.  Files removed by this changeset.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_591"><literal role="template-keyword" moreinfo="none">node</literal>:
belaran@999: 	  String.  The changeset identification hash, as a
belaran@999: 	  40-character hexadecimal string.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_592"><literal role="template-keyword" moreinfo="none">parents</literal>: List of
belaran@999: 	  strings.  The parents of the changeset.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_593"><literal role="template-keyword" moreinfo="none">rev</literal>:
belaran@999: 	  Integer.  The repository-local changeset revision
belaran@999: 	  number.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_594"><literal role="template-keyword" moreinfo="none">tags</literal>:
belaran@999: 	  List of strings.  Any tags associated with the
belaran@999: 	  changeset.</para>
belaran@999:       </listitem>
belaran@999:     </itemizedlist>
belaran@999: 
belaran@999:     <para id="x_595">A few simple experiments will show us what to expect when we
belaran@999:       use these keywords; you can see the results below.</para>
belaran@999: 
belaran@999:     <!-- BEGIN template.simple.keywords -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'author: {author}\n'</userinput>
belaran@999: author: Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'desc:\n{desc}\n'</userinput>
belaran@999: desc:
belaran@999: added line to end of &lt;&lt;hello&gt;&gt; file.
belaran@999: 
belaran@999: in addition, added a file with the helpful name (at least i hope that some might consider it so) of goodbye.
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'files: {files}\n'</userinput>
belaran@999: files: goodbye hello
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'file_adds: {file_adds}\n'</userinput>
belaran@999: file_adds: goodbye
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'file_dels: {file_dels}\n'</userinput>
belaran@999: file_dels: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'node: {node}\n'</userinput>
belaran@999: node: e3d2468ca47c10bdfbbb41b367a0c84509862197
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'parents: {parents}\n'</userinput>
belaran@999: parents: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'rev: {rev}\n'</userinput>
belaran@999: rev: 1
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'tags: {tags}\n'</userinput>
belaran@999: tags: mytag
belaran@999: </screen>
belaran@999: <!-- END template.simple.keywords -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_596">As we noted above, the date keyword does not produce
belaran@999:       human-readable output, so we must treat it specially.  This
belaran@999:       involves using a <emphasis>filter</emphasis>, about which more
belaran@999:       in <xref linkend="sec:template:filter"/>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN template.simple.datekeyword -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'date: {date}\n'</userinput>
belaran@999: date: 1250431517.00
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'date: {date|isodate}\n'</userinput>
belaran@999: date: 2009-08-16 14:05 +0000
belaran@999: </screen>
belaran@999: <!-- END template.simple.datekeyword -->
belaran@999: 
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="sec:template:escape">
belaran@999:     <title>Escape sequences</title>
belaran@999: 
belaran@999:     <para id="x_597">Mercurial's templating engine recognises the most commonly
belaran@999:       used escape sequences in strings.  When it sees a backslash
belaran@999:       (<quote><literal moreinfo="none">\</literal></quote>) character, it looks at the
belaran@999:       following character and substitutes the two characters with a
belaran@999:       single replacement, as described below.</para>
belaran@999: 
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_598"><literal moreinfo="none">\</literal>:
belaran@999: 	  Backslash, <quote><literal moreinfo="none">\</literal></quote>, ASCII
belaran@999: 	  134.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_599"><literal moreinfo="none">\n</literal>: Newline,
belaran@999: 	  ASCII 12.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_59a"><literal moreinfo="none">\r</literal>: Carriage
belaran@999: 	  return, ASCII 15.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_59b"><literal moreinfo="none">\t</literal>: Tab, ASCII
belaran@999: 	  11.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_59c"><literal moreinfo="none">\v</literal>: Vertical
belaran@999: 	  tab, ASCII 13.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_59d"><literal moreinfo="none">\{</literal>: Open curly
belaran@999: 	  brace, <quote><literal moreinfo="none">{</literal></quote>, ASCII
belaran@999: 	  173.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_59e"><literal moreinfo="none">\}</literal>: Close curly
belaran@999: 	  brace, <quote><literal moreinfo="none">}</literal></quote>, ASCII
belaran@999: 	  175.</para>
belaran@999:       </listitem></itemizedlist>
belaran@999: 
belaran@999:     <para id="x_59f">As indicated above, if you want the expansion of a template
belaran@999:       to contain a literal <quote><literal moreinfo="none">\</literal></quote>,
belaran@999:       <quote><literal moreinfo="none">{</literal></quote>, or
belaran@999:       <quote><literal moreinfo="none">{</literal></quote> character, you must escape
belaran@999:       it.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="sec:template:filter">
belaran@999:     <title>Filtering keywords to change their results</title>
belaran@999: 
belaran@999:     <para id="x_5a0">Some of the results of template expansion are not
belaran@999:       immediately easy to use.  Mercurial lets you specify an optional
belaran@999:       chain of <emphasis>filters</emphasis> to modify the result of
belaran@999:       expanding a keyword.  You have already seen a common filter,
belaran@999:       <literal role="template-kw-filt-date" moreinfo="none">isodate</literal>, in
belaran@999:       action above, to make a date readable.</para>
belaran@999: 
belaran@999:     <para id="x_5a1">Below is a list of the most commonly used filters that
belaran@999:       Mercurial supports.  While some filters can be applied to any
belaran@999:       text, others can only be used in specific circumstances.  The
belaran@999:       name of each filter is followed first by an indication of where
belaran@999:       it can be used, then a description of its effect.</para>
belaran@999: 
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_5a2"><literal role="template-filter" moreinfo="none">addbreaks</literal>: Any text. Add
belaran@999: 	  an XHTML <quote><literal moreinfo="none">&lt;br/&gt;</literal></quote> tag
belaran@999: 	  before the end of every line except the last.  For example,
belaran@999: 	  <quote><literal moreinfo="none">foo\nbar</literal></quote> becomes
belaran@999: 	  <quote><literal moreinfo="none">foo&lt;br/&gt;\nbar</literal></quote>.</para>
belaran@999:       </listitem>
belaran@999:       <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
belaran@999: 	  the age of the date, relative to the current time.  Yields a
belaran@999: 	  string like <quote><literal moreinfo="none">10
belaran@999: 	      minutes</literal></quote>.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5a4"><literal role="template-filter" moreinfo="none">basename</literal>: Any text, but
belaran@999: 	  most useful for the <literal role="template-keyword" moreinfo="none">files</literal> keyword and its
belaran@999: 	  relatives.  Treat the text as a path, and return the
belaran@999: 	  basename. For example,
belaran@999: 	  <quote><literal moreinfo="none">foo/bar/baz</literal></quote> becomes
belaran@999: 	  <quote><literal moreinfo="none">baz</literal></quote>.</para>
belaran@999:       </listitem>
belaran@999:       <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
belaran@999: 	  date in a similar format to the Unix <literal role="template-keyword" moreinfo="none">date</literal> command, but with
belaran@999: 	  timezone included.  Yields a string like <quote><literal moreinfo="none">Mon
belaran@999: 	      Sep 04 15:13:13 2006 -0700</literal></quote>.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5a6"><literal role="template-kw-filt-author" moreinfo="none">domain</literal>: Any text,
belaran@999: 	  but most useful for the <literal role="template-keyword" moreinfo="none">author</literal> keyword.  Finds
belaran@999: 	  the first string that looks like an email address, and
belaran@999: 	  extract just the domain component.  For example,
belaran@999: 	  <quote><literal moreinfo="none">Bryan O'Sullivan
belaran@999: 	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
belaran@999: 	  <quote><literal moreinfo="none">serpentine.com</literal></quote>.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5a7"><literal role="template-kw-filt-author" moreinfo="none">email</literal>: Any text,
belaran@999: 	  but most useful for the <literal role="template-keyword" moreinfo="none">author</literal> keyword.  Extract
belaran@999: 	  the first string that looks like an email address.  For
belaran@999: 	  example, <quote><literal moreinfo="none">Bryan O'Sullivan
belaran@999: 	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
belaran@999: 	  <quote><literal moreinfo="none">bos@serpentine.com</literal></quote>.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5a8"><literal role="template-filter" moreinfo="none">escape</literal>: Any text.
belaran@999: 	  Replace the special XML/XHTML characters
belaran@999: 	  <quote><literal moreinfo="none">&amp;</literal></quote>,
belaran@999: 	  <quote><literal moreinfo="none">&lt;</literal></quote> and
belaran@999: 	  <quote><literal moreinfo="none">&gt;</literal></quote> with XML
belaran@999: 	  entities.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5a9"><literal role="template-filter" moreinfo="none">fill68</literal>: Any text.  Wrap
belaran@999: 	  the text to fit in 68 columns.  This is useful before you
belaran@999: 	  pass text through the <literal role="template-filter" moreinfo="none">tabindent</literal> filter, and
belaran@999: 	  still want it to fit in an 80-column fixed-font
belaran@999: 	  window.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5aa"><literal role="template-filter" moreinfo="none">fill76</literal>: Any text.  Wrap
belaran@999: 	  the text to fit in 76 columns.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5ab"><literal role="template-filter" moreinfo="none">firstline</literal>: Any text.
belaran@999: 	  Yield the first line of text, without any trailing
belaran@999: 	  newlines.</para>
belaran@999:       </listitem>
belaran@999:       <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
belaran@999: 	  the date as a pair of readable numbers.  Yields a string
belaran@999: 	  like <quote><literal moreinfo="none">1157407993
belaran@999: 	      25200</literal></quote>.</para>
belaran@999:       </listitem>
belaran@999:       <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
belaran@999: 	  the date as a text string in ISO 8601 format.  Yields a
belaran@999: 	  string like <quote><literal moreinfo="none">2006-09-04 15:13:13
belaran@999: 	      -0700</literal></quote>.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5ae"><literal role="template-filter" moreinfo="none">obfuscate</literal>: Any text, but
belaran@999: 	  most useful for the <literal role="template-keyword" moreinfo="none">author</literal> keyword.  Yield
belaran@999: 	  the input text rendered as a sequence of XML entities.  This
belaran@999: 	  helps to defeat some particularly stupid screen-scraping
belaran@999: 	  email harvesting spambots.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5af"><literal role="template-kw-filt-author" moreinfo="none">person</literal>: Any text,
belaran@999: 	  but most useful for the <literal role="template-keyword" moreinfo="none">author</literal> keyword.  Yield
belaran@999: 	  the text before an email address. For example,
belaran@999: 	  <quote><literal moreinfo="none">Bryan O'Sullivan
belaran@999: 	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
belaran@999: 	  <quote><literal moreinfo="none">Bryan O'Sullivan</literal></quote>.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5b0"><literal role="template-kw-filt-date" moreinfo="none">rfc822date</literal>:
belaran@999: 	  <literal role="template-keyword" moreinfo="none">date</literal> keyword.
belaran@999: 	  Render a date using the same format used in email headers.
belaran@999: 	  Yields a string like <quote><literal moreinfo="none">Mon, 04 Sep 2006
belaran@999: 	      15:13:13 -0700</literal></quote>.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5b1"><literal role="template-kw-filt-node" moreinfo="none">short</literal>: Changeset
belaran@999: 	  hash.  Yield the short form of a changeset hash, i.e. a
belaran@999: 	  12-character hexadecimal string.</para>
belaran@999:       </listitem>
belaran@999:       <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
belaran@999: 	  the year, month, and day of the date.  Yields a string like
belaran@999: 	  <quote><literal moreinfo="none">2006-09-04</literal></quote>.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5b3"><literal role="template-filter" moreinfo="none">strip</literal>:
belaran@999: 	  Any text.  Strip all leading and trailing whitespace from
belaran@999: 	  the string.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5b4"><literal role="template-filter" moreinfo="none">tabindent</literal>: Any text.
belaran@999: 	  Yield the text, with every line except the first starting
belaran@999: 	  with a tab character.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5b5"><literal role="template-filter" moreinfo="none">urlescape</literal>: Any text.
belaran@999: 	  Escape all characters that are considered
belaran@999: 	  <quote>special</quote> by URL parsers.  For example,
belaran@999: 	  <literal moreinfo="none">foo bar</literal> becomes
belaran@999: 	  <literal moreinfo="none">foo%20bar</literal>.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5b6"><literal role="template-kw-filt-author" moreinfo="none">user</literal>: Any text,
belaran@999: 	  but most useful for the <literal role="template-keyword" moreinfo="none">author</literal> keyword.  Return
belaran@999: 	  the <quote>user</quote> portion of an email address.  For
belaran@999: 	  example, <quote><literal moreinfo="none">Bryan O'Sullivan
belaran@999: 	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
belaran@999: 	  <quote><literal moreinfo="none">bos</literal></quote>.</para>
belaran@999:       </listitem>
belaran@999:     </itemizedlist>
belaran@999: 
belaran@999:     <!-- BEGIN template.simple.manyfilters -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author}\n'</userinput>
belaran@999: Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author|domain}\n'</userinput>
belaran@999: serpentine.com
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author|email}\n'</userinput>
belaran@999: bos@serpentine.com
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author|obfuscate}\n' | cut -c-76</userinput>
belaran@999: &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
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author|person}\n'</userinput>
belaran@999: Bryan O'Sullivan
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author|user}\n'</userinput>
belaran@999: bos
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'looks almost right, but actually garbage: {date}\n'</userinput>
belaran@999: looks almost right, but actually garbage: 1250431517.00
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|age}\n'</userinput>
belaran@999: 3 seconds
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|date}\n'</userinput>
belaran@999: Sun Aug 16 14:05:17 2009 +0000
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|hgdate}\n'</userinput>
belaran@999: 1250431517 0
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|isodate}\n'</userinput>
belaran@999: 2009-08-16 14:05 +0000
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|rfc822date}\n'</userinput>
belaran@999: Sun, 16 Aug 2009 14:05:17 +0000
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|shortdate}\n'</userinput>
belaran@999: 2009-08-16
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc}\n' | cut -c-76</userinput>
belaran@999: added line to end of &lt;&lt;hello&gt;&gt; file.
belaran@999: 
belaran@999: in addition, added a file with the helpful name (at least i hope that some m
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|addbreaks}\n' | cut -c-76</userinput>
belaran@999: added line to end of &lt;&lt;hello&gt;&gt; file.&lt;br/&gt;
belaran@999: &lt;br/&gt;
belaran@999: in addition, added a file with the helpful name (at least i hope that some m
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|escape}\n' | cut -c-76</userinput>
belaran@999: added line to end of &amp;lt;&amp;lt;hello&amp;gt;&amp;gt; file.
belaran@999: 
belaran@999: in addition, added a file with the helpful name (at least i hope that some m
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|fill68}\n'</userinput>
belaran@999: added line to end of &lt;&lt;hello&gt;&gt; file.
belaran@999: 
belaran@999: in addition, added a file with the helpful name (at least i hope
belaran@999: that some might consider it so) of goodbye.
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|fill76}\n'</userinput>
belaran@999: added line to end of &lt;&lt;hello&gt;&gt; file.
belaran@999: 
belaran@999: in addition, added a file with the helpful name (at least i hope that some
belaran@999: might consider it so) of goodbye.
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|firstline}\n'</userinput>
belaran@999: added line to end of &lt;&lt;hello&gt;&gt; file.
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|strip}\n' | cut -c-76</userinput>
belaran@999: added line to end of &lt;&lt;hello&gt;&gt; file.
belaran@999: 
belaran@999: in addition, added a file with the helpful name (at least i hope that some m
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|tabindent}\n' | expand | cut -c-76</userinput>
belaran@999: added line to end of &lt;&lt;hello&gt;&gt; file.
belaran@999: 
belaran@999:         in addition, added a file with the helpful name (at least i hope tha
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{node}\n'</userinput>
belaran@999: e3d2468ca47c10bdfbbb41b367a0c84509862197
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{node|short}\n'</userinput>
belaran@999: e3d2468ca47c
belaran@999: </screen>
belaran@999: <!-- END template.simple.manyfilters -->
belaran@999: 
belaran@999: 
belaran@999:     <note>
belaran@999:       <para id="x_5b7">  If you try to apply a filter to a piece of data that it
belaran@999: 	cannot process, Mercurial will fail and print a Python
belaran@999: 	exception.  For example, trying to run the output of the
belaran@999: 	<literal role="template-keyword" moreinfo="none">desc</literal> keyword into
belaran@999: 	the <literal role="template-kw-filt-date" moreinfo="none">isodate</literal>
belaran@999: 	filter is not a good idea.</para>
belaran@999:     </note>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Combining filters</title>
belaran@999: 
belaran@999:       <para id="x_5b8">It is easy to combine filters to yield output in the form
belaran@999: 	you would like.  The following chain of filters tidies up a
belaran@999: 	description, then makes sure that it fits cleanly into 68
belaran@999: 	columns, then indents it by a further 8 characters (at least
belaran@999: 	on Unix-like systems, where a tab is conventionally 8
belaran@999: 	characters wide).</para>
belaran@999: 
belaran@999:       <!-- BEGIN template.simple.combine -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'description:\n\t{desc|strip|fill68|tabindent}\n'</userinput>
belaran@999: description:
belaran@999: 	added line to end of &lt;&lt;hello&gt;&gt; file.
belaran@999: 
belaran@999: 	in addition, added a file with the helpful name (at least i hope
belaran@999: 	that some might consider it so) of goodbye.
belaran@999: </screen>
belaran@999: <!-- END template.simple.combine -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_5b9">Note the use of <quote><literal moreinfo="none">\t</literal></quote> (a
belaran@999: 	tab character) in the template to force the first line to be
belaran@999: 	indented; this is necessary since <literal role="template-keyword" moreinfo="none">tabindent</literal> indents all
belaran@999: 	lines <emphasis>except</emphasis> the first.</para>
belaran@999: 
belaran@999:       <para id="x_5ba">Keep in mind that the order of filters in a chain is
belaran@999: 	significant.  The first filter is applied to the result of the
belaran@999: 	keyword; the second to the result of the first filter; and so
belaran@999: 	on.  For example, using <literal moreinfo="none">fill68|tabindent</literal>
belaran@999: 	gives very different results from
belaran@999: 	<literal moreinfo="none">tabindent|fill68</literal>.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>From templates to styles</title>
belaran@999: 
belaran@999:     <para id="x_5bb">A command line template provides a quick and simple way to
belaran@999:       format some output.  Templates can become verbose, though, and
belaran@999:       it's useful to be able to give a template a name.  A style file
belaran@999:       is a template with a name, stored in a file.</para>
belaran@999: 
belaran@999:     <para id="x_5bc">More than that, using a style file unlocks the power of
belaran@999:       Mercurial's templating engine in ways that are not possible
belaran@999:       using the command line <option role="hg-opt-log">--template</option> option.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>The simplest of style files</title>
belaran@999: 
belaran@999:       <para id="x_5bd">Our simple style file contains just one line:</para>
belaran@999: 
belaran@999:       <!-- BEGIN template.simple.rev -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'changeset = "rev: {rev}\n"' &gt; rev</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -l1 --style ./rev</userinput>
belaran@999: rev: 3
belaran@999: </screen>
belaran@999: <!-- END template.simple.rev -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_5be">This tells Mercurial, <quote>if you're printing a
belaran@999: 	  changeset, use the text on the right as the
belaran@999: 	  template</quote>.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Style file syntax</title>
belaran@999: 
belaran@999:       <para id="x_5bf">The syntax rules for a style file are simple.</para>
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_5c0">The file is processed one line at a
belaran@999: 	    time.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5c1">Leading and trailing white space are
belaran@999: 	    ignored.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5c2">Empty lines are skipped.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5c3">If a line starts with either of the characters
belaran@999: 	    <quote><literal moreinfo="none">#</literal></quote> or
belaran@999: 	    <quote><literal moreinfo="none">;</literal></quote>, the entire line is
belaran@999: 	    treated as a comment, and skipped as if empty.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5c4">A line starts with a keyword.  This must start
belaran@999: 	    with an alphabetic character or underscore, and can
belaran@999: 	    subsequently contain any alphanumeric character or
belaran@999: 	    underscore.  (In regexp notation, a keyword must match
belaran@999: 	    <literal moreinfo="none">[A-Za-z_][A-Za-z0-9_]*</literal>.)</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5c5">The next element must be an
belaran@999: 	    <quote><literal moreinfo="none">=</literal></quote> character, which can
belaran@999: 	    be preceded or followed by an arbitrary amount of white
belaran@999: 	    space.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5c6">If the rest of the line starts and ends with
belaran@999: 	    matching quote characters (either single or double quote),
belaran@999: 	    it is treated as a template body.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5c7">If the rest of the line <emphasis>does
belaran@999: 	      not</emphasis> start with a quote character, it is
belaran@999: 	    treated as the name of a file; the contents of this file
belaran@999: 	    will be read and used as a template body.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Style files by example</title>
belaran@999: 
belaran@999:     <para id="x_5c8">To illustrate how to write a style file, we will construct a
belaran@999:       few by example.  Rather than provide a complete style file and
belaran@999:       walk through it, we'll mirror the usual process of developing a
belaran@999:       style file by starting with something very simple, and walking
belaran@999:       through a series of successively more complete examples.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Identifying mistakes in style files</title>
belaran@999: 
belaran@999:       <para id="x_5c9">If Mercurial encounters a problem in a style file you are
belaran@999: 	working on, it prints a terse error message that, once you
belaran@999: 	figure out what it means, is actually quite useful.</para>
belaran@999: 
belaran@999: <!-- BEGIN template.svnstyle.syntax.input -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat broken.style</userinput>
belaran@999: changeset =
belaran@999: </screen>
belaran@999: <!-- END template.svnstyle.syntax.input -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_5ca">Notice that <filename moreinfo="none">broken.style</filename> attempts to
belaran@999: 	define a <literal moreinfo="none">changeset</literal> keyword, but forgets to
belaran@999: 	give any content for it. When instructed to use this style
belaran@999: 	file, Mercurial promptly complains.</para>
belaran@999: 
belaran@999:       <!-- BEGIN template.svnstyle.syntax.error -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --style broken.style</userinput>
belaran@999: abort: broken.style:1: parse error
belaran@999: </screen>
belaran@999: <!-- END template.svnstyle.syntax.error -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_5cb">This error message looks intimidating, but it is not too
belaran@999: 	hard to follow.</para>
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_5cc">The first component is simply Mercurial's way
belaran@999: 	    of saying <quote>I am giving up</quote>.</para>
belaran@999: 	  <programlisting format="linespecific">___abort___: broken.style:1: parse error</programlisting>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5cd">Next comes the name of the style file that
belaran@999: 	    contains the error.</para>
belaran@999: 	  <programlisting format="linespecific">abort: ___broken.style___:1: parse error</programlisting>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5ce">Following the file name is the line number
belaran@999: 	    where the error was encountered.</para>
belaran@999: 	  <programlisting format="linespecific">abort: broken.style:___1___: parse error</programlisting>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5cf">Finally, a description of what went
belaran@999: 	    wrong.</para>
belaran@999: 	  <programlisting format="linespecific">abort: broken.style:1: ___parse error___</programlisting>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5d0">The description of the problem is not always
belaran@999: 	    clear (as in this case), but even when it is cryptic, it
belaran@999: 	    is almost always trivial to visually inspect the offending
belaran@999: 	    line in the style file and see what is wrong.</para>
belaran@999: 	</listitem>
belaran@999:       </itemizedlist>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Uniquely identifying a repository</title>
belaran@999: 
belaran@999:       <para id="x_5d1">If you would like to be able to identify a Mercurial
belaran@999: 	repository <quote>fairly uniquely</quote> using a short string
belaran@999: 	as an identifier, you can use the first revision in the
belaran@999: 	repository.</para>
belaran@999: 
belaran@999:       <!-- BEGIN template.svnstyle.id -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r0 --template '{node}'</userinput>
belaran@999: 02b4f9d8a52a6da645e20fa7df0accc8aa33b650</screen>
belaran@999: <!-- END template.svnstyle.id -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_5d2">This is likely to be unique, and so it is
belaran@999: 	useful in many cases.  There are a few caveats.</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_5d3">It will not work in a completely empty
belaran@999: 	    repository, because such a repository does not have a
belaran@999: 	    revision zero.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5d4">Neither will it work in the (extremely rare)
belaran@999: 	    case where a repository is a merge of two or more formerly
belaran@999: 	    independent repositories, and you still have those
belaran@999: 	    repositories around.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999:       <para id="x_5d5">Here are some uses to which you could put this
belaran@999: 	identifier:</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_5d6">As a key into a table for a database that
belaran@999: 	    manages repositories on a server.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5d7">As half of a {<emphasis>repository
belaran@999: 	      ID</emphasis>, <emphasis>revision ID</emphasis>} tuple.
belaran@999: 	    Save this information away when you run an automated build
belaran@999: 	    or other activity, so that you can <quote>replay</quote>
belaran@999: 	    the build later if necessary.</para>
belaran@999: 	</listitem>
belaran@999:       </itemizedlist>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Listing files on multiple lines</title>
belaran@999: 
belaran@999:       <para id="x_714">Suppose we want to list the files changed by a changeset,
belaran@999: 	one per line, with a little indentation before each file
belaran@999: 	name.</para>
belaran@999: 
belaran@999:       <!-- BEGIN ch10/multiline.go -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat &gt; multiline &lt;&lt; EOF</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">changeset = "Changed in {node|short}:\n{files}"</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">file = "  {file}\n"</userinput>
belaran@999: <prompt moreinfo="none">&gt;</prompt> <userinput moreinfo="none">EOF</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style multiline</userinput>
belaran@999: Changed in badb58085712:
belaran@999:   .bashrc
belaran@999:   .hgrc
belaran@999:   test.c
belaran@999: </screen>
belaran@999: <!-- END ch10/multiline.go -->
belaran@999: 
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Mimicking Subversion's output</title>
belaran@999: 
belaran@999:       <para id="x_5d8">Let's try to emulate the default output format used by
belaran@999: 	another revision control tool, Subversion.</para>
belaran@999: 
belaran@999:       <!-- BEGIN template.svnstyle.short -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">svn log -r9653</userinput>
belaran@999: ------------------------------------------------------------------------
belaran@999: r9653 | sean.hefty | 2006-09-27 14:39:55 -0700 (Wed, 27 Sep 2006) | 5 lines
belaran@999: 
belaran@999: On reporting a route error, also include the status for the error,
belaran@999: rather than indicating a status of 0 when an error has occurred.
belaran@999: 
belaran@999: Signed-off-by: Sean Hefty &lt;sean.hefty@intel.com&gt;
belaran@999: 
belaran@999: ------------------------------------------------------------------------
belaran@999: </screen>
belaran@999: <!-- END template.svnstyle.short -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_5d9">Since Subversion's output style is fairly simple, it is
belaran@999: 	easy to copy-and-paste a hunk of its output into a file, and
belaran@999: 	replace the text produced above by Subversion with the
belaran@999: 	template values we'd like to see expanded.</para>
belaran@999: 
belaran@999:       <!-- BEGIN template.svnstyle.template -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat svn.template</userinput>
belaran@999: r{rev} | {author|user} | {date|isodate} ({date|rfc822date})
belaran@999: 
belaran@999: {desc|strip|fill76}
belaran@999: 
belaran@999: ------------------------------------------------------------------------
belaran@999: </screen>
belaran@999: <!-- END template.svnstyle.template -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_5da">There are a few small ways in which this template deviates
belaran@999: 	from the output produced by Subversion.</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_5db">Subversion prints a <quote>readable</quote>
belaran@999: 	    date (the <quote><literal moreinfo="none">Wed, 27 Sep 2006</literal></quote> in the
belaran@999: 	    example output above) in parentheses.  Mercurial's
belaran@999: 	    templating engine does not provide a way to display a date
belaran@999: 	    in this format without also printing the time and time
belaran@999: 	    zone.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5dc">We emulate Subversion's printing of
belaran@999: 	    <quote>separator</quote> lines full of
belaran@999: 	    <quote><literal moreinfo="none">-</literal></quote> characters by ending
belaran@999: 	    the template with such a line. We use the templating
belaran@999: 	    engine's <literal role="template-keyword" moreinfo="none">header</literal>
belaran@999: 	    keyword to print a separator line as the first line of
belaran@999: 	    output (see below), thus achieving similar output to
belaran@999: 	    Subversion.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5dd">Subversion's output includes a count in the
belaran@999: 	    header of the number of lines in the commit message.  We
belaran@999: 	    cannot replicate this in Mercurial; the templating engine
belaran@999: 	    does not currently provide a filter that counts the number
belaran@999: 	    of lines the template generates.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999:       <para id="x_5de">It took me no more than a minute or two of work to replace
belaran@999: 	literal text from an example of Subversion's output with some
belaran@999: 	keywords and filters to give the template above.  The style
belaran@999: 	file simply refers to the template.</para>
belaran@999: 
belaran@999:       <!-- BEGIN template.svnstyle.style -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat svn.style</userinput>
belaran@999: header = '------------------------------------------------------------------------\n\n'
belaran@999: changeset = svn.template
belaran@999: </screen>
belaran@999: <!-- END template.svnstyle.style -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_5df">We could have included the text of the template file
belaran@999: 	directly in the style file by enclosing it in quotes and
belaran@999: 	replacing the newlines with
belaran@999: 	<quote><literal moreinfo="none">\n</literal></quote> sequences, but it would
belaran@999: 	have made the style file too difficult to read.  Readability
belaran@999: 	is a good guide when you're trying to decide whether some text
belaran@999: 	belongs in a style file, or in a template file that the style
belaran@999: 	file points to.  If the style file will look too big or
belaran@999: 	cluttered if you insert a literal piece of text, drop it into
belaran@999: 	a template instead.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: </chapter>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "chapter")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN ch12 -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <chapter id="chap:mq">
belaran@999:   <?dbhtml filename="managing-change-with-mercurial-queues.html"?>
belaran@999:   <title>Managing change with Mercurial Queues</title>
belaran@999: 
belaran@999:   <sect1 id="sec:mq:patch-mgmt">
belaran@999:     <title>The patch management problem</title>
belaran@999: 
belaran@999:     <para id="x_3ac">Here is a common scenario: you need to install a software
belaran@999:       package from source, but you find a bug that you must fix in the
belaran@999:       source before you can start using the package.  You make your
belaran@999:       changes, forget about the package for a while, and a few months
belaran@999:       later you need to upgrade to a newer version of the package.  If
belaran@999:       the newer version of the package still has the bug, you must
belaran@999:       extract your fix from the older source tree and apply it against
belaran@999:       the newer version.  This is a tedious task, and it's easy to
belaran@999:       make mistakes.</para>
belaran@999: 
belaran@999:     <para id="x_3ad">This is a simple case of the <quote>patch management</quote>
belaran@999:       problem.  You have an <quote>upstream</quote> source tree that
belaran@999:       you can't change; you need to make some local changes on top of
belaran@999:       the upstream tree; and you'd like to be able to keep those
belaran@999:       changes separate, so that you can apply them to newer versions
belaran@999:       of the upstream source.</para>
belaran@999: 
belaran@999:     <para id="x_3ae">The patch management problem arises in many situations.
belaran@999:       Probably the most visible is that a user of an open source
belaran@999:       software project will contribute a bug fix or new feature to the
belaran@999:       project's maintainers in the form of a patch.</para>
belaran@999: 
belaran@999:     <para id="x_3af">Distributors of operating systems that include open source
belaran@999:       software often need to make changes to the packages they
belaran@999:       distribute so that they will build properly in their
belaran@999:       environments.</para>
belaran@999: 
belaran@999:     <para id="x_3b0">When you have few changes to maintain, it is easy to manage
belaran@999:       a single patch using the standard <command moreinfo="none">diff</command> and
belaran@999:       <command moreinfo="none">patch</command> programs (see <xref linkend="sec:mq:patch"/> for a discussion of these
belaran@999:       tools). Once the number of changes grows, it starts to make
belaran@999:       sense to maintain patches as discrete <quote>chunks of
belaran@999: 	work,</quote> so that for example a single patch will contain
belaran@999:       only one bug fix (the patch might modify several files, but it's
belaran@999:       doing <quote>only one thing</quote>), and you may have a number
belaran@999:       of such patches for different bugs you need fixed and local
belaran@999:       changes you require.  In this situation, if you submit a bug fix
belaran@999:       patch to the upstream maintainers of a package and they include
belaran@999:       your fix in a subsequent release, you can simply drop that
belaran@999:       single patch when you're updating to the newer release.</para>
belaran@999: 
belaran@999:     <para id="x_3b1">Maintaining a single patch against an upstream tree is a
belaran@999:       little tedious and error-prone, but not difficult.  However, the
belaran@999:       complexity of the problem grows rapidly as the number of patches
belaran@999:       you have to maintain increases.  With more than a tiny number of
belaran@999:       patches in hand, understanding which ones you have applied and
belaran@999:       maintaining them moves from messy to overwhelming.</para>
belaran@999: 
belaran@999:     <para id="x_3b2">Fortunately, Mercurial includes a powerful extension,
belaran@999:       Mercurial Queues (or simply <quote>MQ</quote>), that massively
belaran@999:       simplifies the patch management problem.</para>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1 id="sec:mq:history">
belaran@999:     <title>The prehistory of Mercurial Queues</title>
belaran@999: 
belaran@999:     <para id="x_3b3">During the late 1990s, several Linux kernel developers
belaran@999:       started to maintain <quote>patch series</quote> that modified
belaran@999:       the behavior of the Linux kernel.  Some of these series were
belaran@999:       focused on stability, some on feature coverage, and others were
belaran@999:       more speculative.</para>
belaran@999: 
belaran@999:     <para id="x_3b4">The sizes of these patch series grew rapidly.  In 2002,
belaran@999:       Andrew Morton published some shell scripts he had been using to
belaran@999:       automate the task of managing his patch queues.  Andrew was
belaran@999:       successfully using these scripts to manage hundreds (sometimes
belaran@999:       thousands) of patches on top of the Linux kernel.</para>
belaran@999: 
belaran@999:     <sect2 id="sec:mq:quilt">
belaran@999:       <title>A patchwork quilt</title>
belaran@999: 
belaran@999:       <para id="x_3b5">In early 2003, Andreas Gruenbacher and Martin Quinson
belaran@999: 	borrowed the approach of Andrew's scripts and published a tool
belaran@999: 	called <quote>patchwork quilt</quote>
belaran@999: 	<citation>web:quilt</citation>, or simply <quote>quilt</quote>
belaran@999: 	(see <citation>gruenbacher:2005</citation> for a paper
belaran@999: 	describing it).  Because quilt substantially automated patch
belaran@999: 	management, it rapidly gained a large following among open
belaran@999: 	source software developers.</para>
belaran@999: 
belaran@999:       <para id="x_3b6">Quilt manages a <emphasis>stack of patches</emphasis> on
belaran@999: 	top of a directory tree. To begin, you tell quilt to manage a
belaran@999: 	directory tree, and tell it which files you want to manage; it
belaran@999: 	stores away the names and contents of those files.  To fix a
belaran@999: 	bug, you create a new patch (using a single command), edit the
belaran@999: 	files you need to fix, then <quote>refresh</quote> the
belaran@999: 	patch.</para>
belaran@999: 
belaran@999:       <para id="x_3b7">The refresh step causes quilt to scan the directory tree;
belaran@999: 	it updates the patch with all of the changes you have made.
belaran@999: 	You can create another patch on top of the first, which will
belaran@999: 	track the changes required to modify the tree from <quote>tree
belaran@999: 	  with one patch applied</quote> to <quote>tree with two
belaran@999: 	  patches applied</quote>.</para>
belaran@999: 
belaran@999:       <para id="x_3b8">You can <emphasis>change</emphasis> which patches are
belaran@999: 	applied to the tree.  If you <quote>pop</quote> a patch, the
belaran@999: 	changes made by that patch will vanish from the directory
belaran@999: 	tree.  Quilt remembers which patches you have popped, though,
belaran@999: 	so you can <quote>push</quote> a popped patch again, and the
belaran@999: 	directory tree will be restored to contain the modifications
belaran@999: 	in the patch.  Most importantly, you can run the
belaran@999: 	<quote>refresh</quote> command at any time, and the topmost
belaran@999: 	applied patch will be updated.  This means that you can, at
belaran@999: 	any time, change both which patches are applied and what
belaran@999: 	modifications those patches make.</para>
belaran@999: 
belaran@999:       <para id="x_3b9">Quilt knows nothing about revision control tools, so it
belaran@999: 	works equally well on top of an unpacked tarball or a
belaran@999: 	Subversion working copy.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2 id="sec:mq:quilt-mq">
belaran@999:       <title>From patchwork quilt to Mercurial Queues</title>
belaran@999: 
belaran@999:       <para id="x_3ba">In mid-2005, Chris Mason took the features of quilt and
belaran@999: 	wrote an extension that he called Mercurial Queues, which
belaran@999: 	added quilt-like behavior to Mercurial.</para>
belaran@999: 
belaran@999:       <para id="x_3bb">The key difference between quilt and MQ is that quilt
belaran@999: 	knows nothing about revision control systems, while MQ is
belaran@999: 	<emphasis>integrated</emphasis> into Mercurial.  Each patch
belaran@999: 	that you push is represented as a Mercurial changeset.  Pop a
belaran@999: 	patch, and the changeset goes away.</para>
belaran@999: 
belaran@999:       <para id="x_3bc">Because quilt does not care about revision control tools,
belaran@999: 	it is still a tremendously useful piece of software to know
belaran@999: 	about for situations where you cannot use Mercurial and
belaran@999: 	MQ.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>The huge advantage of MQ</title>
belaran@999: 
belaran@999:     <para id="x_3bd">I cannot overstate the value that MQ offers through the
belaran@999:       unification of patches and revision control.</para>
belaran@999: 
belaran@999:     <para id="x_3be">A major reason that patches have persisted in the free
belaran@999:       software and open source world—in spite of the
belaran@999:       availability of increasingly capable revision control tools over
belaran@999:       the years—is the <emphasis>agility</emphasis> they
belaran@999:       offer.</para>
belaran@999: 
belaran@999:     <para id="x_3bf">Traditional revision control tools make a permanent,
belaran@999:       irreversible record of everything that you do.  While this has
belaran@999:       great value, it's also somewhat stifling.  If you want to
belaran@999:       perform a wild-eyed experiment, you have to be careful in how
belaran@999:       you go about it, or you risk leaving unneeded—or worse,
belaran@999:       misleading or destabilising—traces of your missteps and
belaran@999:       errors in the permanent revision record.</para>
belaran@999: 
belaran@999:     <para id="x_3c0">By contrast, MQ's marriage of distributed revision control
belaran@999:       with patches makes it much easier to isolate your work.  Your
belaran@999:       patches live on top of normal revision history, and you can make
belaran@999:       them disappear or reappear at will.  If you don't like a patch,
belaran@999:       you can drop it.  If a patch isn't quite as you want it to be,
belaran@999:       simply fix it—as many times as you need to, until you
belaran@999:       have refined it into the form you desire.</para>
belaran@999: 
belaran@999:     <para id="x_3c1">As an example, the integration of patches with revision
belaran@999:       control makes understanding patches and debugging their
belaran@999:       effects—and their interplay with the code they're based
belaran@999:       on—<emphasis>enormously</emphasis> easier. Since every
belaran@999:       applied patch has an associated changeset, you can give <command role="hg-cmd" moreinfo="none">hg log</command> a file name to see which
belaran@999:       changesets and patches affected the file.  You can use the
belaran@999:       <command role="hg-cmd" moreinfo="none">hg bisect</command> command to
belaran@999:       binary-search through all changesets and applied patches to see
belaran@999:       where a bug got introduced or fixed.  You can use the <command role="hg-cmd" moreinfo="none">hg annotate</command> command to see which
belaran@999:       changeset or patch modified a particular line of a source file.
belaran@999:       And so on.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="sec:mq:patch">
belaran@999:     <title>Understanding patches</title>
belaran@999: 
belaran@999:     <para id="x_3c2">Because MQ doesn't hide its patch-oriented nature, it is
belaran@999:       helpful to understand what patches are, and a little about the
belaran@999:       tools that work with them.</para>
belaran@999: 
belaran@999:     <para id="x_3c3">The traditional Unix <command moreinfo="none">diff</command> command
belaran@999:       compares two files, and prints a list of differences between
belaran@999:       them. The <command moreinfo="none">patch</command> command understands these
belaran@999:       differences as <emphasis>modifications</emphasis> to make to a
belaran@999:       file.  Take a look below for a simple example of these commands
belaran@999:       in action.</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.dodiff.diff -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'this is my original thought' &gt; oldfile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'i have changed my mind' &gt; newfile</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">diff -u oldfile newfile &gt; tiny.patch</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat tiny.patch</userinput>
belaran@999: --- oldfile	2009-08-16 14:05:06.000000000 +0000
belaran@999: +++ newfile	2009-08-16 14:05:06.000000000 +0000
belaran@999: @@ -1 +1 @@
belaran@999: -this is my original thought
belaran@999: +i have changed my mind
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">patch &lt; tiny.patch</userinput>
belaran@999: patching file oldfile
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat oldfile</userinput>
belaran@999: i have changed my mind
belaran@999: </screen>
belaran@999: <!-- END mq.dodiff.diff -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_3c4">The type of file that <command moreinfo="none">diff</command> generates (and
belaran@999:       <command moreinfo="none">patch</command> takes as input) is called a
belaran@999:       <quote>patch</quote> or a <quote>diff</quote>; there is no
belaran@999:       difference between a patch and a diff.  (We'll use the term
belaran@999:       <quote>patch</quote>, since it's more commonly used.)</para>
belaran@999: 
belaran@999:     <para id="x_3c5">A patch file can start with arbitrary text; the
belaran@999:       <command moreinfo="none">patch</command> command ignores this text, but MQ uses
belaran@999:       it as the commit message when creating changesets.  To find the
belaran@999:       beginning of the patch content, <command moreinfo="none">patch</command>
belaran@999:       searches for the first line that starts with the string
belaran@999:       <quote><literal moreinfo="none">diff -</literal></quote>.</para>
belaran@999: 
belaran@999:     <para id="x_3c6">MQ works with <emphasis>unified</emphasis> diffs
belaran@999:       (<command moreinfo="none">patch</command> can accept several other diff formats,
belaran@999:       but MQ doesn't).  A unified diff contains two kinds of header.
belaran@999:       The <emphasis>file header</emphasis> describes the file being
belaran@999:       modified; it contains the name of the file to modify.  When
belaran@999:       <command moreinfo="none">patch</command> sees a new file header, it looks for a
belaran@999:       file with that name to start modifying.</para>
belaran@999: 
belaran@999:     <para id="x_3c7">After the file header comes a series of
belaran@999:       <emphasis>hunks</emphasis>.  Each hunk starts with a header;
belaran@999:       this identifies the range of line numbers within the file that
belaran@999:       the hunk should modify.  Following the header, a hunk starts and
belaran@999:       ends with a few (usually three) lines of text from the
belaran@999:       unmodified file; these are called the
belaran@999:       <emphasis>context</emphasis> for the hunk.  If there's only a
belaran@999:       small amount of context between successive hunks,
belaran@999:       <command moreinfo="none">diff</command> doesn't print a new hunk header; it just
belaran@999:       runs the hunks together, with a few lines of context between
belaran@999:       modifications.</para>
belaran@999: 
belaran@999:     <para id="x_3c8">Each line of context begins with a space character.  Within
belaran@999:       the hunk, a line that begins with
belaran@999:       <quote><literal moreinfo="none">-</literal></quote> means <quote>remove this
belaran@999: 	line,</quote> while a line that begins with
belaran@999:       <quote><literal moreinfo="none">+</literal></quote> means <quote>insert this
belaran@999: 	line.</quote>  For example, a line that is modified is
belaran@999:       represented by one deletion and one insertion.</para>
belaran@999: 
belaran@999:     <para id="x_3c9">We will return to some of the more subtle aspects of patches
belaran@999:       later (in <xref linkend="sec:mq:adv-patch"/>), but you
belaran@999:       should have
belaran@999:       enough information now to use MQ.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="sec:mq:start">
belaran@999:     <title>Getting started with Mercurial Queues</title>
belaran@999: 
belaran@999:     <para id="x_3ca">Because MQ is implemented as an extension, you must
belaran@999:       explicitly enable before you can use it.  (You don't need to
belaran@999:       download anything; MQ ships with the standard Mercurial
belaran@999:       distribution.)  To enable MQ, edit your <filename role="home" moreinfo="none">~/.hgrc</filename> file, and add the lines
belaran@999:       below.</para>
belaran@999: 
belaran@999:     <programlisting format="linespecific">[extensions]
belaran@999: hgext.mq =</programlisting>
belaran@999: 
belaran@999:     <para id="x_3cb">Once the extension is enabled, it will make a number of new
belaran@999:       commands available.  To verify that the extension is working,
belaran@999:       you can use <command role="hg-cmd" moreinfo="none">hg help</command> to see if
belaran@999:       the <command role="hg-ext-mq" moreinfo="none">qinit</command> command is now
belaran@999:       available.</para>
belaran@999: 
belaran@999:     <!-- BEGIN mq.qinit-help.help -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg help qinit</userinput>
belaran@999: hg qinit [-c]
belaran@999: 
belaran@999: init a new queue repository
belaran@999: 
belaran@999:     The queue repository is unversioned by default. If -c is
belaran@999:     specified, qinit will create a separate nested repository
belaran@999:     for patches (qinit -c may also be run later to convert
belaran@999:     an unversioned patch repository into a versioned one).
belaran@999:     You can use qcommit to commit changes to this queue repository.
belaran@999: 
belaran@999: options:
belaran@999: 
belaran@999:  -c --create-repo  create queue repository
belaran@999: 
belaran@999: use "hg -v help qinit" to show global options
belaran@999: </screen>
belaran@999: <!-- END mq.qinit-help.help -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_3cc">You can use MQ with <emphasis>any</emphasis> Mercurial
belaran@999:       repository, and its commands only operate within that
belaran@999:       repository.  To get started, simply prepare the repository using
belaran@999:       the <command role="hg-ext-mq" moreinfo="none">qinit</command> command.</para>
belaran@999: 
belaran@999:     <!-- BEGIN mq.tutorial.qinit -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init mq-sandbox</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd mq-sandbox</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'line 1' &gt; file1</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'another line 1' &gt; file2</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add file1 file2</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m'first change'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qinit</userinput>
belaran@999: </screen>
belaran@999: <!-- END mq.tutorial.qinit -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_3cd">This command creates an empty directory called <filename role="special" class="directory" moreinfo="none">.hg/patches</filename>, where
belaran@999:       MQ will keep its metadata.  As with many Mercurial commands, the
belaran@999:       <command role="hg-ext-mq" moreinfo="none">qinit</command> command prints nothing
belaran@999:       if it succeeds.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Creating a new patch</title>
belaran@999: 
belaran@999:       <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
belaran@999: 	one argument, the name of the patch to create.</para>
belaran@999: 
belaran@999:       <para id="x_3cf">MQ will use this as the name of an actual file in the
belaran@999: 	<filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory, as you
belaran@999: 	can see below.</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.tutorial.qnew -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
belaran@999: changeset:   0:5d84c303994b
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:11 2009 +0000
belaran@999: summary:     first change
belaran@999: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew first.patch</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
belaran@999: changeset:   1:ba4d7a3f2149
belaran@999: tag:         qtip
belaran@999: tag:         first.patch
belaran@999: tag:         tip
belaran@999: tag:         qbase
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:11 2009 +0000
belaran@999: summary:     [mq]: first.patch
belaran@999: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls .hg/patches</userinput>
belaran@999: first.patch  series  status
belaran@999: </screen>
belaran@999: <!-- END mq.tutorial.qnew -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_3d0">Also newly present in the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory are two
belaran@999: 	other files, <filename role="special" moreinfo="none">series</filename> and
belaran@999: 	<filename role="special" moreinfo="none">status</filename>.  The <filename role="special" moreinfo="none">series</filename> file lists all of the
belaran@999: 	patches that MQ knows about for this repository, with one
belaran@999: 	patch per line.  Mercurial uses the <filename role="special" moreinfo="none">status</filename> file for internal
belaran@999: 	book-keeping; it tracks all of the patches that MQ has
belaran@999: 	<emphasis>applied</emphasis> in this repository.</para>
belaran@999: 
belaran@999:       <note>
belaran@999: 	<para id="x_3d1">  You may sometimes want to edit the <filename role="special" moreinfo="none">series</filename> file by hand; for
belaran@999: 	  example, to change the sequence in which some patches are
belaran@999: 	  applied.  However, manually editing the <filename role="special" moreinfo="none">status</filename> file is almost always a
belaran@999: 	  bad idea, as it's easy to corrupt MQ's idea of what is
belaran@999: 	  happening.</para>
belaran@999:       </note>
belaran@999: 
belaran@999:       <para id="x_3d2">Once you have created your new patch, you can edit files
belaran@999: 	in the working directory as you usually would.  All of the
belaran@999: 	normal Mercurial commands, such as <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  diff</command> and <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  annotate</command>, work exactly as they did before.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Refreshing a patch</title>
belaran@999: 
belaran@999:       <para id="x_3d3">When you reach a point where you want to save your work,
belaran@999: 	use the <command role="hg-ext-mq" moreinfo="none">qrefresh</command> command
belaran@999: 	to update the patch you are working on.</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.tutorial.qrefresh -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'line 2' &gt;&gt; file1</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
belaran@999: diff -r ba4d7a3f2149 file1
belaran@999: --- a/file1	Sun Aug 16 14:05:11 2009 +0000
belaran@999: +++ b/file1	Sun Aug 16 14:05:11 2009 +0000
belaran@999: @@ -1,1 +1,2 @@
belaran@999:  line 1
belaran@999: +line 2
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip --style=compact --patch</userinput>
belaran@999: 1[qtip,first.patch,tip,qbase]   1aa236e17e55   2009-08-16 14:05 +0000   bos
belaran@999:   [mq]: first.patch
belaran@999: 
belaran@999: diff -r 5d84c303994b -r 1aa236e17e55 file1
belaran@999: --- a/file1	Sun Aug 16 14:05:11 2009 +0000
belaran@999: +++ b/file1	Sun Aug 16 14:05:11 2009 +0000
belaran@999: @@ -1,1 +1,2 @@
belaran@999:  line 1
belaran@999: +line 2
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END mq.tutorial.qrefresh -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_3d4">This command folds the changes you have made in the
belaran@999: 	working directory into your patch, and updates its
belaran@999: 	corresponding changeset to contain those changes.</para>
belaran@999: 
belaran@999:       <para id="x_3d5">You can run <command role="hg-ext-mq" moreinfo="none">qrefresh</command>
belaran@999: 	as often as you like, so it's a good way to
belaran@999: 	<quote>checkpoint</quote> your work.  Refresh your patch at an
belaran@999: 	opportune time; try an experiment; and if the experiment
belaran@999: 	doesn't work out, <command role="hg-cmd" moreinfo="none">hg revert</command>
belaran@999: 	your modifications back to the last time you refreshed.</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.tutorial.qrefresh2 -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'line 3' &gt;&gt; file1</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
belaran@999: M file1
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip --style=compact --patch</userinput>
belaran@999: 1[qtip,first.patch,tip,qbase]   ebec7ce95e11   2009-08-16 14:05 +0000   bos
belaran@999:   [mq]: first.patch
belaran@999: 
belaran@999: diff -r 5d84c303994b -r ebec7ce95e11 file1
belaran@999: --- a/file1	Sun Aug 16 14:05:11 2009 +0000
belaran@999: +++ b/file1	Sun Aug 16 14:05:12 2009 +0000
belaran@999: @@ -1,1 +1,3 @@
belaran@999:  line 1
belaran@999: +line 2
belaran@999: +line 3
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END mq.tutorial.qrefresh2 -->
belaran@999: 
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Stacking and tracking patches</title>
belaran@999: 
belaran@999:       <para id="x_3d6">Once you have finished working on a patch, or need to work
belaran@999: 	on another, you can use the <command role="hg-ext-mq" moreinfo="none">qnew</command> command again to create a
belaran@999: 	new patch. Mercurial will apply this patch on top of your
belaran@999: 	existing patch.</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.tutorial.qnew2 -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew second.patch</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style=compact --limit=2</userinput>
belaran@999: 2[qtip,second.patch,tip]   dffbc4265523   2009-08-16 14:05 +0000   bos
belaran@999:   [mq]: second.patch
belaran@999: 
belaran@999: 1[first.patch,qbase]   ebec7ce95e11   2009-08-16 14:05 +0000   bos
belaran@999:   [mq]: first.patch
belaran@999: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'line 4' &gt;&gt; file1</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip --style=compact --patch</userinput>
belaran@999: 2[qtip,second.patch,tip]   fdacb9b232ac   2009-08-16 14:05 +0000   bos
belaran@999:   [mq]: second.patch
belaran@999: 
belaran@999: diff -r ebec7ce95e11 -r fdacb9b232ac file1
belaran@999: --- a/file1	Sun Aug 16 14:05:12 2009 +0000
belaran@999: +++ b/file1	Sun Aug 16 14:05:12 2009 +0000
belaran@999: @@ -1,3 +1,4 @@
belaran@999:  line 1
belaran@999:  line 2
belaran@999:  line 3
belaran@999: +line 4
belaran@999: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg annotate file1</userinput>
belaran@999: 0: line 1
belaran@999: 1: line 2
belaran@999: 1: line 3
belaran@999: 2: line 4
belaran@999: </screen>
belaran@999: <!-- END mq.tutorial.qnew2 -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_3d7">Notice that the patch contains the changes in our prior
belaran@999: 	patch as part of its context (you can see this more clearly in
belaran@999: 	the output of <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  annotate</command>).</para>
belaran@999: 
belaran@999:       <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
belaran@999: 	only use regular Mercurial commands.  However, MQ provides
belaran@999: 	many commands that are easier to use when you are thinking
belaran@999: 	about patches, as illustrated below.</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.tutorial.qseries -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qseries</userinput>
belaran@999: first.patch
belaran@999: second.patch
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
belaran@999: first.patch
belaran@999: second.patch
belaran@999: </screen>
belaran@999: <!-- END mq.tutorial.qseries -->
belaran@999: 
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_3d9">The <command role="hg-ext-mq" moreinfo="none">qseries</command> command lists every
belaran@999: 	    patch that MQ knows about in this repository, from oldest
belaran@999: 	    to newest (most recently
belaran@999: 	    <emphasis>created</emphasis>).</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_3da">The <command role="hg-ext-mq" moreinfo="none">qapplied</command> command lists every
belaran@999: 	    patch that MQ has <emphasis>applied</emphasis> in this
belaran@999: 	    repository, again from oldest to newest (most recently
belaran@999: 	    applied).</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Manipulating the patch stack</title>
belaran@999: 
belaran@999:       <para id="x_3db">The previous discussion implied that there must be a
belaran@999: 	difference between <quote>known</quote> and
belaran@999: 	<quote>applied</quote> patches, and there is.  MQ can manage a
belaran@999: 	patch without it being applied in the repository.</para>
belaran@999: 
belaran@999:       <para id="x_3dc">An <emphasis>applied</emphasis> patch has a corresponding
belaran@999: 	changeset in the repository, and the effects of the patch and
belaran@999: 	changeset are visible in the working directory.  You can undo
belaran@999: 	the application of a patch using the <command role="hg-ext-mq" moreinfo="none">qpop</command> command.  MQ still
belaran@999: 	<emphasis>knows about</emphasis>, or manages, a popped patch,
belaran@999: 	but the patch no longer has a corresponding changeset in the
belaran@999: 	repository, and the working directory does not contain the
belaran@999: 	changes made by the patch.  <xref linkend="fig:mq:stack"/> illustrates
belaran@999: 	the difference between applied and tracked patches.</para>
belaran@999: 
belaran@999:       <figure id="fig:mq:stack" float="0">
belaran@999: 	<title>Applied and unapplied patches in the MQ patch
belaran@999: 	  stack</title>
belaran@999: 	<mediaobject>
belaran@999: 	  <imageobject><imagedata fileref="figs/mq-stack.png"/></imageobject>
belaran@999: 	  <textobject><phrase>XXX add text</phrase></textobject>
belaran@999: 	</mediaobject>
belaran@999:       </figure>
belaran@999: 
belaran@999:       <para id="x_3de">You can reapply an unapplied, or popped, patch using the
belaran@999: 	<command role="hg-ext-mq" moreinfo="none">qpush</command> command.  This
belaran@999: 	creates a new changeset to correspond to the patch, and the
belaran@999: 	patch's changes once again become present in the working
belaran@999: 	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>
belaran@999: 
belaran@999:       <!-- BEGIN mq.tutorial.qpop -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
belaran@999: first.patch
belaran@999: second.patch
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop</userinput>
belaran@999: now at: first.patch
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qseries</userinput>
belaran@999: first.patch
belaran@999: second.patch
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
belaran@999: first.patch
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat file1</userinput>
belaran@999: line 1
belaran@999: line 2
belaran@999: line 3
belaran@999: </screen>
belaran@999: <!-- END mq.tutorial.qpop -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_3df">Notice that once we have popped a patch or two patches,
belaran@999: 	the output of <command role="hg-ext-mq" moreinfo="none">qseries</command>
belaran@999: 	remains the same, while that of <command role="hg-ext-mq" moreinfo="none">qapplied</command> has changed.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Pushing and popping many patches</title>
belaran@999: 
belaran@999:       <para id="x_3e0">While <command role="hg-ext-mq" moreinfo="none">qpush</command> and
belaran@999: 	<command role="hg-ext-mq" moreinfo="none">qpop</command> each operate on a
belaran@999: 	single patch at a time by default, you can push and pop many
belaran@999: 	patches in one go.  The <option role="hg-ext-mq-cmd-qpush-opt">hg -a</option> option to
belaran@999: 	<command role="hg-ext-mq" moreinfo="none">qpush</command> causes it to push
belaran@999: 	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
belaran@999: 	patches.  (For some more ways to push and pop many patches,
belaran@999: 	see <xref linkend="sec:mq:perf"/> below.)</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.tutorial.qpush-a -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpush -a</userinput>
belaran@999: applying second.patch
belaran@999: now at: second.patch
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat file1</userinput>
belaran@999: line 1
belaran@999: line 2
belaran@999: line 3
belaran@999: line 4
belaran@999: </screen>
belaran@999: <!-- END mq.tutorial.qpush-a -->
belaran@999: 
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Safety checks, and overriding them</title>
belaran@999: 
belaran@999:       <para id="x_3e1">Several MQ commands check the working directory before
belaran@999: 	they do anything, and fail if they find any modifications.
belaran@999: 	They do this to ensure that you won't lose any changes that
belaran@999: 	you have made, but not yet incorporated into a patch.  The
belaran@999: 	example below illustrates this; the <command role="hg-ext-mq" moreinfo="none">qnew</command> command will not create a
belaran@999: 	new patch if there are outstanding changes, caused in this
belaran@999: 	case by the <command role="hg-cmd" moreinfo="none">hg add</command> of
belaran@999: 	<filename moreinfo="none">file3</filename>.</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.tutorial.add -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'file 3, line 1' &gt;&gt; file3</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew add-file3.patch</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew -f add-file3.patch</userinput>
belaran@999: abort: patch "add-file3.patch" already exists
belaran@999: </screen>
belaran@999: <!-- END mq.tutorial.add -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_3e2">Commands that check the working directory all take an
belaran@999: 	<quote>I know what I'm doing</quote> option, which is always
belaran@999: 	named <option>-f</option>.  The exact meaning of
belaran@999: 	<option>-f</option> depends on the command.  For example,
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg qnew <option role="hg-ext-mq-cmd-qnew-opt">hg -f</option></command>
belaran@999: 	will incorporate any outstanding changes into the new patch it
belaran@999: 	creates, but <command role="hg-cmd" moreinfo="none">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">hg -f</option></command>
belaran@999: 	will revert modifications to any files affected by the patch
belaran@999: 	that it is popping.  Be sure to read the documentation for a
belaran@999: 	command's <option>-f</option> option before you use it!</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Working on several patches at once</title>
belaran@999: 
belaran@999:       <para id="x_3e3">The <command role="hg-ext-mq" moreinfo="none">qrefresh</command> command
belaran@999: 	always refreshes the <emphasis>topmost</emphasis> applied
belaran@999: 	patch.  This means that you can suspend work on one patch (by
belaran@999: 	refreshing it), pop or push to make a different patch the top,
belaran@999: 	and work on <emphasis>that</emphasis> patch for a
belaran@999: 	while.</para>
belaran@999: 
belaran@999:       <para id="x_3e4">Here's an example that illustrates how you can use this
belaran@999: 	ability. Let's say you're developing a new feature as two
belaran@999: 	patches.  The first is a change to the core of your software,
belaran@999: 	and the second—layered on top of the
belaran@999: 	first—changes the user interface to use the code you
belaran@999: 	just added to the core.  If you notice a bug in the core while
belaran@999: 	you're working on the UI patch, it's easy to fix the core.
belaran@999: 	Simply <command role="hg-ext-mq" moreinfo="none">qrefresh</command> the UI
belaran@999: 	patch to save your in-progress changes, and <command role="hg-ext-mq" moreinfo="none">qpop</command> down to the core patch.  Fix
belaran@999: 	the core bug, <command role="hg-ext-mq" moreinfo="none">qrefresh</command> the
belaran@999: 	core patch, and <command role="hg-ext-mq" moreinfo="none">qpush</command> back
belaran@999: 	to the UI patch to continue where you left off.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="sec:mq:adv-patch">
belaran@999:     <title>More about patches</title>
belaran@999: 
belaran@999:     <para id="x_3e5">MQ uses the GNU <command moreinfo="none">patch</command> command to apply
belaran@999:       patches, so it's helpful to know a few more detailed aspects of
belaran@999:       how <command moreinfo="none">patch</command> works, and about patches
belaran@999:       themselves.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>The strip count</title>
belaran@999: 
belaran@999:       <para id="x_3e6">If you look at the file headers in a patch, you will
belaran@999: 	notice that the pathnames usually have an extra component on
belaran@999: 	the front that isn't present in the actual path name.  This is
belaran@999: 	a holdover from the way that people used to generate patches
belaran@999: 	(people still do this, but it's somewhat rare with modern
belaran@999: 	revision control tools).</para>
belaran@999: 
belaran@999:       <para id="x_3e7">Alice would unpack a tarball, edit her files, then decide
belaran@999: 	that she wanted to create a patch.  So she'd rename her
belaran@999: 	working directory, unpack the tarball again (hence the need
belaran@999: 	for the rename), and use the <option role="cmd-opt-diff">-r</option> and <option role="cmd-opt-diff">-N</option> options to
belaran@999: 	<command moreinfo="none">diff</command> to recursively generate a patch
belaran@999: 	between the unmodified directory and the modified one.  The
belaran@999: 	result would be that the name of the unmodified directory
belaran@999: 	would be at the front of the left-hand path in every file
belaran@999: 	header, and the name of the modified directory would be at the
belaran@999: 	front of the right-hand path.</para>
belaran@999: 
belaran@999:       <para id="x_3e8">Since someone receiving a patch from the Alices of the net
belaran@999: 	would be unlikely to have unmodified and modified directories
belaran@999: 	with exactly the same names, the <command moreinfo="none">patch</command>
belaran@999: 	command has a <option role="cmd-opt-patch">-p</option> option
belaran@999: 	that indicates the number of leading path name components to
belaran@999: 	strip when trying to apply a patch.  This number is called the
belaran@999: 	<emphasis>strip count</emphasis>.</para>
belaran@999: 
belaran@999:       <para id="x_3e9">An option of <quote><literal moreinfo="none">-p1</literal></quote> means
belaran@999: 	<quote>use a strip count of one</quote>.  If
belaran@999: 	<command moreinfo="none">patch</command> sees a file name
belaran@999: 	<filename moreinfo="none">foo/bar/baz</filename> in a file header, it will
belaran@999: 	strip <filename moreinfo="none">foo</filename> and try to patch a file named
belaran@999: 	<filename moreinfo="none">bar/baz</filename>.  (Strictly speaking, the strip
belaran@999: 	count refers to the number of <emphasis>path
belaran@999: 	  separators</emphasis> (and the components that go with them
belaran@999: 	) to strip.  A strip count of one will turn
belaran@999: 	<filename moreinfo="none">foo/bar</filename> into <filename moreinfo="none">bar</filename>,
belaran@999: 	but <filename moreinfo="none">/foo/bar</filename> (notice the extra leading
belaran@999: 	slash) into <filename moreinfo="none">foo/bar</filename>.)</para>
belaran@999: 
belaran@999:       <para id="x_3ea">The <quote>standard</quote> strip count for patches is
belaran@999: 	one; almost all patches contain one leading path name
belaran@999: 	component that needs to be stripped. Mercurial's <command role="hg-cmd" moreinfo="none">hg diff</command> command generates path names
belaran@999: 	in this form, and the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  import</command> command and MQ expect patches to have a
belaran@999: 	strip count of one.</para>
belaran@999: 
belaran@999:       <para id="x_3eb">If you receive a patch from someone that you want to add
belaran@999: 	to your patch queue, and the patch needs a strip count other
belaran@999: 	than one, you cannot just <command role="hg-ext-mq" moreinfo="none">qimport</command> the patch, because
belaran@999: 	<command role="hg-ext-mq" moreinfo="none">qimport</command> does not yet have
belaran@999: 	a <literal moreinfo="none">-p</literal> option (see <ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue311">issue
belaran@999: 	  311</ulink>).  Your best bet is to <command role="hg-ext-mq" moreinfo="none">qnew</command> a patch of your own, then
belaran@999: 	use <command moreinfo="none">patch -pN</command> to apply their patch,
belaran@999: 	followed by <command role="hg-cmd" moreinfo="none">hg addremove</command> to
belaran@999: 	pick up any files added or removed by the patch, followed by
belaran@999: 	<command role="hg-ext-mq" moreinfo="none">hg qrefresh</command>. This
belaran@999: 	complexity may become unnecessary; see <ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue311">issue
belaran@999: 	  311</ulink> for details.
belaran@999:       </para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Strategies for applying a patch</title>
belaran@999: 
belaran@999:       <para id="x_3ec">When <command moreinfo="none">patch</command> applies a hunk, it tries a
belaran@999: 	handful of successively less accurate strategies to try to
belaran@999: 	make the hunk apply. This falling-back technique often makes
belaran@999: 	it possible to take a patch that was generated against an old
belaran@999: 	version of a file, and apply it against a newer version of
belaran@999: 	that file.</para>
belaran@999: 
belaran@999:       <para id="x_3ed">First, <command moreinfo="none">patch</command> tries an exact match,
belaran@999: 	where the line numbers, the context, and the text to be
belaran@999: 	modified must apply exactly.  If it cannot make an exact
belaran@999: 	match, it tries to find an exact match for the context,
belaran@999: 	without honouring the line numbering information.  If this
belaran@999: 	succeeds, it prints a line of output saying that the hunk was
belaran@999: 	applied, but at some <emphasis>offset</emphasis> from the
belaran@999: 	original line number.</para>
belaran@999: 
belaran@999:       <para id="x_3ee">If a context-only match fails, <command moreinfo="none">patch</command>
belaran@999: 	removes the first and last lines of the context, and tries a
belaran@999: 	<emphasis>reduced</emphasis> context-only match.  If the hunk
belaran@999: 	with reduced context succeeds, it prints a message saying that
belaran@999: 	it applied the hunk with a <emphasis>fuzz factor</emphasis>
belaran@999: 	(the number after the fuzz factor indicates how many lines of
belaran@999: 	context <command moreinfo="none">patch</command> had to trim before the patch
belaran@999: 	applied).</para>
belaran@999: 
belaran@999:       <para id="x_3ef">When neither of these techniques works,
belaran@999: 	<command moreinfo="none">patch</command> prints a message saying that the hunk
belaran@999: 	in question was rejected.  It saves rejected hunks (also
belaran@999: 	simply called <quote>rejects</quote>) to a file with the same
belaran@999: 	name, and an added <filename role="special" moreinfo="none">.rej</filename>
belaran@999: 	extension.  It also saves an unmodified copy of the file with
belaran@999: 	a <filename role="special" moreinfo="none">.orig</filename> extension; the
belaran@999: 	copy of the file without any extensions will contain any
belaran@999: 	changes made by hunks that <emphasis>did</emphasis> apply
belaran@999: 	cleanly.  If you have a patch that modifies
belaran@999: 	<filename moreinfo="none">foo</filename> with six hunks, and one of them fails
belaran@999: 	to apply, you will have: an unmodified
belaran@999: 	<filename moreinfo="none">foo.orig</filename>, a <filename moreinfo="none">foo.rej</filename>
belaran@999: 	containing one hunk, and <filename moreinfo="none">foo</filename>, containing
belaran@999: 	the changes made by the five successful hunks.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Some quirks of patch representation</title>
belaran@999: 
belaran@999:       <para id="x_3f0">There are a few useful things to know about how
belaran@999: 	<command moreinfo="none">patch</command> works with files.</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_3f1">This should already be obvious, but
belaran@999: 	    <command moreinfo="none">patch</command> cannot handle binary
belaran@999: 	    files.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_3f2">Neither does it care about the executable bit;
belaran@999: 	    it creates new files as readable, but not
belaran@999: 	    executable.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_3f3"><command moreinfo="none">patch</command> treats the removal of
belaran@999: 	    a file as a diff between the file to be removed and the
belaran@999: 	    empty file.  So your idea of <quote>I deleted this
belaran@999: 	      file</quote> looks like <quote>every line of this file
belaran@999: 	      was deleted</quote> in a patch.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_3f4">It treats the addition of a file as a diff
belaran@999: 	    between the empty file and the file to be added.  So in a
belaran@999: 	    patch, your idea of <quote>I added this file</quote> looks
belaran@999: 	    like <quote>every line of this file was
belaran@999: 	      added</quote>.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_3f5">It treats a renamed file as the removal of the
belaran@999: 	    old name, and the addition of the new name.  This means
belaran@999: 	    that renamed files have a big footprint in patches.  (Note
belaran@999: 	    also that Mercurial does not currently try to infer when
belaran@999: 	    files have been renamed or copied in a patch.)</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_3f6"><command moreinfo="none">patch</command> cannot represent
belaran@999: 	    empty files, so you cannot use a patch to represent the
belaran@999: 	    notion <quote>I added this empty file to the
belaran@999: 	      tree</quote>.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Beware the fuzz</title>
belaran@999: 
belaran@999:       <para id="x_3f7">While applying a hunk at an offset, or with a fuzz factor,
belaran@999: 	will often be completely successful, these inexact techniques
belaran@999: 	naturally leave open the possibility of corrupting the patched
belaran@999: 	file.  The most common cases typically involve applying a
belaran@999: 	patch twice, or at an incorrect location in the file.  If
belaran@999: 	<command moreinfo="none">patch</command> or <command role="hg-ext-mq" moreinfo="none">qpush</command> ever mentions an offset or
belaran@999: 	fuzz factor, you should make sure that the modified files are
belaran@999: 	correct afterwards.</para>
belaran@999: 
belaran@999:       <para id="x_3f8">It's often a good idea to refresh a patch that has applied
belaran@999: 	with an offset or fuzz factor; refreshing the patch generates
belaran@999: 	new context information that will make it apply cleanly.  I
belaran@999: 	say <quote>often,</quote> not <quote>always,</quote> because
belaran@999: 	sometimes refreshing a patch will make it fail to apply
belaran@999: 	against a different revision of the underlying files.  In some
belaran@999: 	cases, such as when you're maintaining a patch that must sit
belaran@999: 	on top of multiple versions of a source tree, it's acceptable
belaran@999: 	to have a patch apply with some fuzz, provided you've verified
belaran@999: 	the results of the patching process in such cases.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Handling rejection</title>
belaran@999: 
belaran@999:       <para id="x_3f9">If <command role="hg-ext-mq" moreinfo="none">qpush</command> fails to
belaran@999: 	apply a patch, it will print an error message and exit.  If it
belaran@999: 	has left <filename role="special" moreinfo="none">.rej</filename> files
belaran@999: 	behind, it is usually best to fix up the rejected hunks before
belaran@999: 	you push more patches or do any further work.</para>
belaran@999: 
belaran@999:       <para id="x_3fa">If your patch <emphasis>used to</emphasis> apply cleanly,
belaran@999: 	and no longer does because you've changed the underlying code
belaran@999: 	that your patches are based on, Mercurial Queues can help; see
belaran@999: 	<xref linkend="sec:mq:merge"/> for details.</para>
belaran@999: 
belaran@999:       <para id="x_3fb">Unfortunately, there aren't any great techniques for
belaran@999: 	dealing with rejected hunks.  Most often, you'll need to view
belaran@999: 	the <filename role="special" moreinfo="none">.rej</filename> file and edit the
belaran@999: 	target file, applying the rejected hunks by hand.</para>
belaran@999: 
belaran@999:       <para id="x_3fd">A Linux kernel hacker, Chris Mason (the author
belaran@999: 	of Mercurial Queues), wrote a tool called
belaran@999: 	<command moreinfo="none">mpatch</command> (<ulink url="http://oss.oracle.com/~mason/mpatch/">http://oss.oracle.com/~mason/mpatch/</ulink>), 
belaran@999: 	which takes a simple approach to automating the application of
belaran@999: 	hunks rejected by <command moreinfo="none">patch</command>.  The
belaran@999: 	<command moreinfo="none">mpatch</command> command can help with four common
belaran@999: 	reasons that a hunk may be rejected:</para>
belaran@999: 
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_3fe">The context in the middle of a hunk has
belaran@999: 	    changed.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_3ff">A hunk is missing some context at the
belaran@999: 	    beginning or end.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_400">A large hunk might apply better—either
belaran@999: 	    entirely or in part—if it was broken up into
belaran@999: 	    smaller hunks.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_401">A hunk removes lines with slightly different
belaran@999: 	    content than those currently present in the file.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_402">If you use <command moreinfo="none">mpatch</command>, you
belaran@999: 	should be doubly careful to check your results when you're
belaran@999: 	done.  In fact, <command moreinfo="none">mpatch</command> enforces this method
belaran@999: 	of double-checking the tool's output, by automatically
belaran@999: 	dropping you into a merge program when it has done its job, so
belaran@999: 	that you can verify its work and finish off any remaining
belaran@999: 	merges.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>More on patch management</title>
belaran@999: 
belaran@999:     <para id="x_6db">As you grow familiar with MQ, you will find yourself wanting
belaran@999:       to perform other kinds of patch management operations.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Deleting unwanted patches</title>
belaran@999: 
belaran@999:       <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
belaran@999: 	patch file and remove its entry from the patch series.  If you
belaran@999: 	try to delete a patch that is still applied, <command role="hg-ext-mq" moreinfo="none">hg qdelete</command> will refuse.</para>
belaran@999: 
belaran@999:       <!-- BEGIN ch11/qdelete.go -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init myrepo</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd myrepo</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qinit</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew bad.patch</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qdelete bad.patch</userinput>
belaran@999: abort: cannot delete applied patch bad.patch
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop</userinput>
belaran@999: patch queue now empty
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qdelete bad.patch</userinput>
belaran@999: </screen>
belaran@999: <!-- END ch11/qdelete.go -->
belaran@999: 
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Converting to and from permanent revisions</title>
belaran@999: 
belaran@999:       <para id="x_6dd">Once you're done working on a patch and want to
belaran@999:       turn it into a permanent changeset, use the <command role="hg-ext-mq" moreinfo="none">hg qfinish</command> command. Pass a revision
belaran@999:       to the command to identify the patch that you want to turn into
belaran@999:       a regular changeset; this patch must already be applied.</para>
belaran@999: 
belaran@999:       <!-- BEGIN ch11/qdelete.convert -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew good.patch</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a &gt; a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh -m 'Good change'</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qfinish tip</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip --style=compact</userinput>
belaran@999: 0[tip]   32fc5ce6b092   2009-08-16 14:04 +0000   bos
belaran@999:   Good change
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END ch11/qdelete.convert -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_6e0">The <command role="hg-ext-mq" moreinfo="none">hg qfinish</command> command
belaran@999:         accepts an <option>--all</option> or <option>-a</option>
belaran@999:         option, which turns all applied patches into regular
belaran@999:         changesets.</para>
belaran@999: 
belaran@999:       <para id="x_6de">It is also possible to turn an existing changeset into a
belaran@999: 	patch, by passing the <option>-r</option> option to <command role="hg-ext-mq" moreinfo="none">hg qimport</command>.</para>
belaran@999: 
belaran@999:       <!-- BEGIN ch11/qdelete.import -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qimport -r tip</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
belaran@999: 0.diff
belaran@999: </screen>
belaran@999: <!-- END ch11/qdelete.import -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_6df">Note that it only makes sense to convert a changeset into
belaran@999: 	a patch if you have not propagated that changeset into any
belaran@999: 	other repositories.  The imported changeset's ID will change
belaran@999: 	every time you refresh the patch, which will make Mercurial
belaran@999: 	treat it as unrelated to the original changeset if you have
belaran@999: 	pushed it somewhere else.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="sec:mq:perf">
belaran@999:     <title>Getting the best performance out of MQ</title>
belaran@999: 
belaran@999:     <para id="x_403">MQ is very efficient at handling a large number
belaran@999:       of patches. I ran some performance experiments in mid-2006 for a
belaran@999:       talk that I gave at the 2006 EuroPython conference (on modern
belaran@999:       hardware, you should expect better performance than you'll see
belaran@999:       below).  I used as my data set the Linux 2.6.17-mm1 patch
belaran@999:       series, which consists of 1,738 patches. I applied these on top
belaran@999:       of a Linux kernel repository containing all 27,472 revisions
belaran@999:       between Linux 2.6.12-rc2 and Linux 2.6.17.</para>
belaran@999: 
belaran@999:     <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
belaran@999:       1,738 patches in 3.5 minutes, and <command role="hg-cmd" moreinfo="none">hg qpop
belaran@999: 	<option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command>
belaran@999:       them all in 30 seconds.  (On a newer laptop, the time to push
belaran@999:       all patches dropped to two minutes.)  I could <command role="hg-ext-mq" moreinfo="none">qrefresh</command> one of the biggest patches
belaran@999:       (which made 22,779 lines of changes to 287 files) in 6.6
belaran@999:       seconds.</para>
belaran@999: 
belaran@999:     <para id="x_405">Clearly, MQ is well suited to working in large trees, but
belaran@999:       there are a few tricks you can use to get the best performance
belaran@999:       of it.</para>
belaran@999: 
belaran@999:     <para id="x_406">First of all, try to <quote>batch</quote> operations
belaran@999:       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
belaran@999:       working directory once to make sure you haven't made some
belaran@999:       changes and then forgotten to run <command role="hg-ext-mq" moreinfo="none">qrefresh</command>.  On a small tree, the
belaran@999:       time that this scan takes is unnoticeable.  However, on a
belaran@999:       medium-sized tree (containing tens of thousands of files), it
belaran@999:       can take a second or more.</para>
belaran@999: 
belaran@999:     <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
belaran@999:       pop multiple patches at a time.  You can identify the
belaran@999:       <quote>destination patch</quote> that you want to end up at.
belaran@999:       When you <command role="hg-ext-mq" moreinfo="none">qpush</command> with a
belaran@999:       destination specified, it will push patches until that patch is
belaran@999:       at the top of the applied stack.  When you <command role="hg-ext-mq" moreinfo="none">qpop</command> to a destination, MQ will pop
belaran@999:       patches until the destination patch is at the top.</para>
belaran@999: 
belaran@999:     <para id="x_408">You can identify a destination patch using either the name
belaran@999:       of the patch, or by number.  If you use numeric addressing,
belaran@999:       patches are counted from zero; this means that the first patch
belaran@999:       is zero, the second is one, and so on.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="sec:mq:merge">
belaran@999:     <title>Updating your patches when the underlying code
belaran@999:       changes</title>
belaran@999: 
belaran@999:     <para id="x_409">It's common to have a stack of patches on top of an
belaran@999:       underlying repository that you don't modify directly.  If you're
belaran@999:       working on changes to third-party code, or on a feature that is
belaran@999:       taking longer to develop than the rate of change of the code
belaran@999:       beneath, you will often need to sync up with the underlying
belaran@999:       code, and fix up any hunks in your patches that no longer apply.
belaran@999:       This is called <emphasis>rebasing</emphasis> your patch
belaran@999:       series.</para>
belaran@999: 
belaran@999:     <para id="x_40a">The simplest way to do this is to <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	qpop <option role="hg-ext-mq-cmd-qpop-opt">hg
belaran@999: 	  -a</option></command> your patches, then <command role="hg-cmd" moreinfo="none">hg pull</command> changes into the underlying
belaran@999:       repository, and finally <command role="hg-cmd" moreinfo="none">hg qpush <option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> your
belaran@999:       patches again.  MQ will stop pushing any time it runs across a
belaran@999:       patch that fails to apply during conflicts, allowing you to fix
belaran@999:       your conflicts, <command role="hg-ext-mq" moreinfo="none">qrefresh</command> the
belaran@999:       affected patch, and continue pushing until you have fixed your
belaran@999:       entire stack.</para>
belaran@999: 
belaran@999:     <para id="x_40b">This approach is easy to use and works well if you don't
belaran@999:       expect changes to the underlying code to affect how well your
belaran@999:       patches apply. If your patch stack touches code that is modified
belaran@999:       frequently or invasively in the underlying repository, however,
belaran@999:       fixing up rejected hunks by hand quickly becomes
belaran@999:       tiresome.</para>
belaran@999: 
belaran@999:     <para id="x_40c">It's possible to partially automate the rebasing process.
belaran@999:       If your patches apply cleanly against some revision of the
belaran@999:       underlying repo, MQ can use this information to help you to
belaran@999:       resolve conflicts between your patches and a different
belaran@999:       revision.</para>
belaran@999: 
belaran@999:     <para id="x_40d">The process is a little involved.</para>
belaran@999:     <orderedlist inheritnum="ignore" continuation="restarts">
belaran@999:       <listitem><para id="x_40e">To begin, <command role="hg-cmd" moreinfo="none">hg qpush
belaran@999: 	    -a</command> all of your patches on top of the revision
belaran@999: 	  where you know that they apply cleanly.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_40f">Save a backup copy of your patch directory using
belaran@999: 	  <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>.
belaran@999: 	  This prints the name of the directory that it has saved the
belaran@999: 	  patches in.  It will save the patches to a directory called
belaran@999: 	  <filename role="special" class="directory" moreinfo="none">.hg/patches.N</filename>, where
belaran@999: 	  <literal moreinfo="none">N</literal> is a small integer.  It also commits a
belaran@999: 	  <quote>save changeset</quote> on top of your applied
belaran@999: 	  patches; this is for internal book-keeping, and records the
belaran@999: 	  states of the <filename role="special" moreinfo="none">series</filename> and
belaran@999: 	  <filename role="special" moreinfo="none">status</filename> files.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_410">Use <command role="hg-cmd" moreinfo="none">hg pull</command> to
belaran@999: 	  bring new changes into the underlying repository.  (Don't
belaran@999: 	  run <command role="hg-cmd" moreinfo="none">hg pull -u</command>; see below
belaran@999: 	  for why.)</para>
belaran@999:       </listitem>
belaran@999:       <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
belaran@999: 	  the patches you have pushed.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_412">Merge all patches using <command moreinfo="none">hg qpush -m
belaran@999: 	    -a</command>.  The <option role="hg-ext-mq-cmd-qpush-opt">-m</option> option to
belaran@999: 	  <command role="hg-ext-mq" moreinfo="none">qpush</command> tells MQ to
belaran@999: 	  perform a three-way merge if the patch fails to
belaran@999: 	  apply.</para>
belaran@999:       </listitem></orderedlist>
belaran@999: 
belaran@999:     <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>,
belaran@999:       each patch in the <filename role="special" moreinfo="none">series</filename>
belaran@999:       file is applied normally.  If a patch applies with fuzz or
belaran@999:       rejects, MQ looks at the queue you <command role="hg-ext-mq" moreinfo="none">qsave</command>d, and performs a three-way
belaran@999:       merge with the corresponding changeset.  This merge uses
belaran@999:       Mercurial's normal merge machinery, so it may pop up a GUI merge
belaran@999:       tool to help you to resolve problems.</para>
belaran@999: 
belaran@999:     <para id="x_414">When you finish resolving the effects of a patch, MQ
belaran@999:       refreshes your patch based on the result of the merge.</para>
belaran@999: 
belaran@999:     <para id="x_415">At the end of this process, your repository will have one
belaran@999:       extra head from the old patch queue, and a copy of the old patch
belaran@999:       queue will be in <filename role="special" class="directory" moreinfo="none">.hg/patches.N</filename>. You can remove the
belaran@999:       extra head using <command role="hg-cmd" moreinfo="none">hg qpop -a -n
belaran@999: 	patches.N</command> or <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	strip</command>.  You can delete <filename role="special" class="directory" moreinfo="none">.hg/patches.N</filename> once you are sure
belaran@999:       that you no longer need it as a backup.</para>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Identifying patches</title>
belaran@999: 
belaran@999:     <para id="x_416">MQ commands that work with patches let you refer to a patch
belaran@999:       either by using its name or by a number.  By name is obvious
belaran@999:       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
belaran@999:       push patches until <filename moreinfo="none">foo.patch</filename> is
belaran@999:       applied.</para>
belaran@999: 
belaran@999:     <para id="x_417">As a shortcut, you can refer to a patch using both a name
belaran@999:       and a numeric offset; <literal moreinfo="none">foo.patch-2</literal> means
belaran@999:       <quote>two patches before <literal moreinfo="none">foo.patch</literal></quote>,
belaran@999:       while <literal moreinfo="none">bar.patch+4</literal> means <quote>four patches
belaran@999: 	after <literal moreinfo="none">bar.patch</literal></quote>.</para>
belaran@999: 
belaran@999:     <para id="x_418">Referring to a patch by index isn't much different.  The
belaran@999:       first patch printed in the output of <command role="hg-ext-mq" moreinfo="none">qseries</command> is patch zero (yes, it's
belaran@999:       one of those start-at-zero counting systems); the second is
belaran@999:       patch one; and so on.</para>
belaran@999: 
belaran@999:     <para id="x_419">MQ also makes it easy to work with patches when you are
belaran@999:       using normal Mercurial commands.  Every command that accepts a
belaran@999:       changeset ID will also accept the name of an applied patch.  MQ
belaran@999:       augments the tags normally in the repository with an eponymous
belaran@999:       one for each applied patch.  In addition, the special tags
belaran@999:       <literal role="tag" moreinfo="none">qbase</literal> and
belaran@999:       <literal role="tag" moreinfo="none">qtip</literal> identify
belaran@999:       the <quote>bottom-most</quote> and topmost applied patches,
belaran@999:       respectively.</para>
belaran@999: 
belaran@999:     <para id="x_41a">These additions to Mercurial's normal tagging capabilities
belaran@999:       make dealing with patches even more of a breeze.</para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_41b">Want to patchbomb a mailing list with your
belaran@999: 	  latest series of changes?</para>
belaran@999: 	<programlisting format="linespecific">hg email qbase:qtip</programlisting>
belaran@999: 	<para id="x_41c">  (Don't know what <quote>patchbombing</quote> is?  See
belaran@999: 	  <xref linkend="sec:hgext:patchbomb"/>.)</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_41d">Need to see all of the patches since
belaran@999: 	  <literal moreinfo="none">foo.patch</literal> that have touched files in a
belaran@999: 	  subdirectory of your tree?</para>
belaran@999: 	<programlisting format="linespecific">hg log -r foo.patch:qtip subdir</programlisting>
belaran@999:       </listitem>
belaran@999:     </itemizedlist>
belaran@999: 
belaran@999:     <para id="x_41e">Because MQ makes the names of patches available to the rest
belaran@999:       of Mercurial through its normal internal tag machinery, you
belaran@999:       don't need to type in the entire name of a patch when you want
belaran@999:       to identify it by name.</para>
belaran@999: 
belaran@999:     <para id="x_41f">Another nice consequence of representing patch names as tags
belaran@999:       is that when you run the <command role="hg-cmd" moreinfo="none">hg log</command>
belaran@999:       command, it will display a patch's name as a tag, simply as part
belaran@999:       of its normal output.  This makes it easy to visually
belaran@999:       distinguish applied patches from underlying
belaran@999:       <quote>normal</quote> revisions.  The following example shows a
belaran@999:       few normal Mercurial commands in use with applied
belaran@999:       patches.</para>
belaran@999: 
belaran@999:     <!-- BEGIN mq.id.output -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
belaran@999: first.patch
belaran@999: second.patch
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r qbase:qtip</userinput>
belaran@999: changeset:   1:c3bcf3b7335a
belaran@999: tag:         first.patch
belaran@999: tag:         qbase
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:08 2009 +0000
belaran@999: summary:     [mq]: first.patch
belaran@999: 
belaran@999: changeset:   2:d189ba63b5f7
belaran@999: tag:         qtip
belaran@999: tag:         second.patch
belaran@999: tag:         tip
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:09 2009 +0000
belaran@999: summary:     [mq]: second.patch
belaran@999: 
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg export second.patch</userinput>
belaran@999: # HG changeset patch
belaran@999: # User Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: # Date 1250431509 0
belaran@999: # Node ID d189ba63b5f7427f9644663c01fc16fe80399c65
belaran@999: # Parent  c3bcf3b7335afc0a250e85c51a1266d35d43a545
belaran@999: [mq]: second.patch
belaran@999: 
belaran@999: diff -r c3bcf3b7335a -r d189ba63b5f7 other.c
belaran@999: --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
belaran@999: +++ b/other.c	Sun Aug 16 14:05:09 2009 +0000
belaran@999: @@ -0,0 +1,1 @@
belaran@999: +double u;
belaran@999: </screen>
belaran@999: <!-- END mq.id.output -->
belaran@999: 
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Useful things to know about</title>
belaran@999: 
belaran@999:     <para id="x_420">There are a number of aspects of MQ usage that don't fit
belaran@999:       tidily into sections of their own, but that are good to know.
belaran@999:       Here they are, in one place.</para>
belaran@999: 
belaran@999:     <itemizedlist>
belaran@999:       <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
belaran@999: 	  that represents the patch after the pop/push will have a
belaran@999: 	  <emphasis>different identity</emphasis> than the changeset
belaran@999: 	  that represented the hash beforehand.  See <xref linkend="sec:mqref:cmd:qpush"/> for
belaran@999: 	  information as to why this is.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_422">It's not a good idea to <command role="hg-cmd" moreinfo="none">hg merge</command> changes from another
belaran@999: 	  branch with a patch changeset, at least if you want to
belaran@999: 	  maintain the <quote>patchiness</quote> of that changeset and
belaran@999: 	  changesets below it on the patch stack.  If you try to do
belaran@999: 	  this, it will appear to succeed, but MQ will become
belaran@999: 	  confused.</para>
belaran@999:       </listitem></itemizedlist>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1 id="sec:mq:repo">
belaran@999:     <title>Managing patches in a repository</title>
belaran@999: 
belaran@999:     <para id="x_423">Because MQ's <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory resides
belaran@999:       outside a Mercurial repository's working directory, the
belaran@999:       <quote>underlying</quote> Mercurial repository knows nothing
belaran@999:       about the management or presence of patches.</para>
belaran@999: 
belaran@999:     <para id="x_424">This presents the interesting possibility of managing the
belaran@999:       contents of the patch directory as a Mercurial repository in its
belaran@999:       own right.  This can be a useful way to work.  For example, you
belaran@999:       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
belaran@999:       patch.  This lets you <quote>roll back</quote> to that version
belaran@999:       of the patch later on.</para>
belaran@999: 
belaran@999:     <para id="x_425">You can then share different versions of the same patch
belaran@999:       stack among multiple underlying repositories.  I use this when I
belaran@999:       am developing a Linux kernel feature.  I have a pristine copy of
belaran@999:       my kernel sources for each of several CPU architectures, and a
belaran@999:       cloned repository under each that contains the patches I am
belaran@999:       working on.  When I want to test a change on a different
belaran@999:       architecture, I push my current patches to the patch repository
belaran@999:       associated with that kernel tree, pop and push all of my
belaran@999:       patches, and build and test that kernel.</para>
belaran@999: 
belaran@999:     <para id="x_426">Managing patches in a repository makes it possible for
belaran@999:       multiple developers to work on the same patch series without
belaran@999:       colliding with each other, all on top of an underlying source
belaran@999:       base that they may or may not control.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>MQ support for patch repositories</title>
belaran@999: 
belaran@999:       <para id="x_427">MQ helps you to work with the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory as a
belaran@999: 	repository; when you prepare a repository for working with
belaran@999: 	patches using <command role="hg-ext-mq" moreinfo="none">qinit</command>, you
belaran@999: 	can pass the <option role="hg-ext-mq-cmd-qinit-opt">hg
belaran@999: 	  -c</option> option to create the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory as a
belaran@999: 	Mercurial repository.</para>
belaran@999: 
belaran@999:       <note>
belaran@999: 	<para id="x_428">  If you forget to use the <option role="hg-ext-mq-cmd-qinit-opt">hg -c</option> option, you
belaran@999: 	  can simply go into the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory at any
belaran@999: 	  time and run <command role="hg-cmd" moreinfo="none">hg init</command>.
belaran@999: 	  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>
belaran@999: 
belaran@999: 	<para id="x_429">  (<command role="hg-cmd" moreinfo="none">hg qinit <option role="hg-ext-mq-cmd-qinit-opt">hg -c</option></command>
belaran@999: 	  does this for you automatically); you
belaran@999: 	  <emphasis>really</emphasis> don't want to manage the
belaran@999: 	  <filename role="special" moreinfo="none">status</filename> file.</para>
belaran@999:       </note>
belaran@999: 
belaran@999:       <para id="x_42a">As a convenience, if MQ notices that the <filename class="directory" moreinfo="none">.hg/patches</filename> directory is a
belaran@999: 	repository, it will automatically <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  add</command> every patch that you create and import.</para>
belaran@999: 
belaran@999:       <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>
belaran@999: 	directory.  This saves some bothersome typing.</para>
belaran@999: 
belaran@999:       <para id="x_42c">Finally, as a convenience to manage the patch directory,
belaran@999: 	you can define the alias <command moreinfo="none">mq</command> on Unix
belaran@999: 	systems. For example, on Linux systems using the
belaran@999: 	<command moreinfo="none">bash</command> shell, you can include the following
belaran@999: 	snippet in your <filename role="home" moreinfo="none">~/.bashrc</filename>.</para>
belaran@999: 
belaran@999:       <programlisting format="linespecific">alias mq=`hg -R $(hg root)/.hg/patches'</programlisting>
belaran@999: 
belaran@999:       <para id="x_42d">You can then issue commands of the form <command moreinfo="none">mq
belaran@999: 	  pull</command> from the main repository.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>A few things to watch out for</title>
belaran@999: 
belaran@999:       <para id="x_42e">MQ's support for working with a repository full of patches
belaran@999: 	is limited in a few small respects.</para>
belaran@999: 
belaran@999:       <para id="x_42f">MQ cannot automatically detect changes that you make to
belaran@999: 	the patch directory.  If you <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  pull</command>, manually edit, or <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  update</command> changes to patches or the <filename role="special" moreinfo="none">series</filename> file, you will have to
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> and
belaran@999: 	then <command role="hg-cmd" moreinfo="none">hg qpush <option role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> in
belaran@999: 	the underlying repository to see those changes show up there.
belaran@999: 	If you forget to do this, you can confuse MQ's idea of which
belaran@999: 	patches are applied.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1 id="sec:mq:tools">
belaran@999:     <title>Third party tools for working with patches</title>
belaran@999: 
belaran@999:     <para id="x_430">Once you've been working with patches for a while, you'll
belaran@999:       find yourself hungry for tools that will help you to understand
belaran@999:       and manipulate the patches you're dealing with.</para>
belaran@999: 
belaran@999:     <para id="x_431">The <command moreinfo="none">diffstat</command> command
belaran@999:       <citation>web:diffstat</citation> generates a histogram of the
belaran@999:       modifications made to each file in a patch.  It provides a good
belaran@999:       way to <quote>get a sense of</quote> a patch—which files
belaran@999:       it affects, and how much change it introduces to each file and
belaran@999:       as a whole.  (I find that it's a good idea to use
belaran@999:       <command moreinfo="none">diffstat</command>'s <option role="cmd-opt-diffstat">-p</option> option as a matter of
belaran@999:       course, as otherwise it will try to do clever things with
belaran@999:       prefixes of file names that inevitably confuse at least
belaran@999:       me.)</para>
belaran@999: 
belaran@999: <!-- BEGIN mq.tools.tools -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">diffstat -p1 remove-redundant-null-checks.patch</userinput>
belaran@999:  drivers/char/agp/sgi-agp.c        |    5 ++---
belaran@999:  drivers/char/hvcs.c               |   11 +++++------
belaran@999:  drivers/message/fusion/mptfc.c    |    6 ++----
belaran@999:  drivers/message/fusion/mptsas.c   |    3 +--
belaran@999:  drivers/net/fs_enet/fs_enet-mii.c |    3 +--
belaran@999:  drivers/net/wireless/ipw2200.c    |   22 ++++++----------------
belaran@999:  drivers/scsi/libata-scsi.c        |    4 +---
belaran@999:  drivers/video/au1100fb.c          |    3 +--
belaran@999:  8 files changed, 19 insertions(+), 38 deletions(-)
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">filterdiff -i '*/video/*' remove-redundant-null-checks.patch</userinput>
belaran@999: --- a/drivers/video/au1100fb.c~remove-redundant-null-checks-before-free-in-drivers
belaran@999: +++ a/drivers/video/au1100fb.c
belaran@999: @@ -743,8 +743,7 @@ void __exit au1100fb_cleanup(void)
belaran@999:  {
belaran@999:  	driver_unregister(&amp;au1100fb_driver);
belaran@999:  
belaran@999: -	if (drv_info.opt_mode)
belaran@999: -		kfree(drv_info.opt_mode);
belaran@999: +	kfree(drv_info.opt_mode);
belaran@999:  }
belaran@999:  
belaran@999:  module_init(au1100fb_init);
belaran@999: </screen>
belaran@999: <!-- END mq.tools.tools -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_432">The <literal role="package" moreinfo="none">patchutils</literal> package
belaran@999:       <citation>web:patchutils</citation> is invaluable. It provides a
belaran@999:       set of small utilities that follow the <quote>Unix
belaran@999: 	philosophy;</quote> each does one useful thing with a patch.
belaran@999:       The <literal role="package" moreinfo="none">patchutils</literal> command I use
belaran@999:       most is <command moreinfo="none">filterdiff</command>, which extracts subsets
belaran@999:       from a patch file.  For example, given a patch that modifies
belaran@999:       hundreds of files across dozens of directories, a single
belaran@999:       invocation of <command moreinfo="none">filterdiff</command> can generate a
belaran@999:       smaller patch that only touches files whose names match a
belaran@999:       particular glob pattern.  See <xref linkend="mq-collab:tips:interdiff"/> for another
belaran@999:       example.</para>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Good ways to work with patches</title>
belaran@999: 
belaran@999:     <para id="x_433">Whether you are working on a patch series to submit to a
belaran@999:       free software or open source project, or a series that you
belaran@999:       intend to treat as a sequence of regular changesets when you're
belaran@999:       done, you can use some simple techniques to keep your work well
belaran@999:       organized.</para>
belaran@999: 
belaran@999:     <para id="x_434">Give your patches descriptive names.  A good name for a
belaran@999:       patch might be <filename moreinfo="none">rework-device-alloc.patch</filename>,
belaran@999:       because it will immediately give you a hint what the purpose of
belaran@999:       the patch is.  Long names shouldn't be a problem; you won't be
belaran@999:       typing the names often, but you <emphasis>will</emphasis> be
belaran@999:       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
belaran@999:       becomes especially important when you have a number of patches
belaran@999:       to work with, or if you are juggling a number of different tasks
belaran@999:       and your patches only get a fraction of your attention.</para>
belaran@999: 
belaran@999:     <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
belaran@999:       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
belaran@999:       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
belaran@999:       one I intended, and it's often tricky to migrate changes into
belaran@999:       the right patch after making them in the wrong one.</para>
belaran@999: 
belaran@999:     <para id="x_436">For this reason, it is very much worth investing a little
belaran@999:       time to learn how to use some of the third-party tools I
belaran@999:       described in <xref linkend="sec:mq:tools"/>,
belaran@999:       particularly
belaran@999:       <command moreinfo="none">diffstat</command> and <command moreinfo="none">filterdiff</command>.
belaran@999:       The former will give you a quick idea of what changes your patch
belaran@999:       is making, while the latter makes it easy to splice hunks
belaran@999:       selectively out of one patch and into another.</para>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>MQ cookbook</title>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Manage <quote>trivial</quote> patches</title>
belaran@999: 
belaran@999:       <para id="x_437">Because the overhead of dropping files into a new
belaran@999: 	Mercurial repository is so low, it makes a lot of sense to
belaran@999: 	manage patches this way even if you simply want to make a few
belaran@999: 	changes to a source tarball that you downloaded.</para>
belaran@999: 
belaran@999:       <para id="x_438">Begin by downloading and unpacking the source tarball, and
belaran@999: 	turning it into a Mercurial repository.</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.tarball.download -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">download netplug-1.2.5.tar.bz2</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">tar jxf netplug-1.2.5.tar.bz2</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd netplug-1.2.5</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -q --addremove --message netplug-1.2.5</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone netplug-1.2.5 netplug</userinput>
belaran@999: updating working directory
belaran@999: 18 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: </screen>
belaran@999: <!-- END mq.tarball.download -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_439">Continue by creating a patch stack and making your
belaran@999: 	changes.</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.tarball.qinit -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd netplug</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qinit</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew -m 'fix build problem with gcc 4' build-fix.patch</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">perl -pi -e 's/int addr_len/socklen_t addr_len/' netlink.c</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip -p</userinput>
belaran@999: changeset:   1:eeab56666c54
belaran@999: tag:         qtip
belaran@999: tag:         build-fix.patch
belaran@999: tag:         tip
belaran@999: tag:         qbase
belaran@999: user:        Bryan O'Sullivan &lt;bos@serpentine.com&gt;
belaran@999: date:        Sun Aug 16 14:05:10 2009 +0000
belaran@999: summary:     fix build problem with gcc 4
belaran@999: 
belaran@999: diff -r 1f6afe9a2d68 -r eeab56666c54 netlink.c
belaran@999: --- a/netlink.c	Sun Aug 16 14:05:09 2009 +0000
belaran@999: +++ b/netlink.c	Sun Aug 16 14:05:10 2009 +0000
belaran@999: @@ -275,7 +275,7 @@
belaran@999:          exit(1);
belaran@999:      }
belaran@999:  
belaran@999: -    int addr_len = sizeof(addr);
belaran@999: +    socklen_t addr_len = sizeof(addr);
belaran@999:  
belaran@999:      if (getsockname(fd, (struct sockaddr *) &amp;addr, &amp;addr_len) == -1) {
belaran@999:          do_log(LOG_ERR, "Could not get socket details: %m");
belaran@999: 
belaran@999: </screen>
belaran@999: <!-- END mq.tarball.qinit -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_43a">Let's say a few weeks or months pass, and your package
belaran@999: 	author releases a new version.  First, bring their changes
belaran@999: 	into the repository.</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.tarball.newsource -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop -a</userinput>
belaran@999: patch queue now empty
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">download netplug-1.2.8.tar.bz2</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone netplug-1.2.5 netplug-1.2.8</userinput>
belaran@999: updating working directory
belaran@999: 18 files updated, 0 files merged, 0 files removed, 0 files unresolved
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd netplug-1.2.8</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg locate -0 | xargs -0 rm</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">tar jxf netplug-1.2.8.tar.bz2</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd netplug-1.2.8</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit --addremove --message netplug-1.2.8</userinput>
belaran@999: </screen>
belaran@999: <!-- END mq.tarball.newsource -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_43b">The pipeline starting with <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  locate</command> above deletes all files in the working
belaran@999: 	directory, so that <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  commit</command>'s <option role="hg-opt-commit">--addremove</option> option can
belaran@999: 	actually tell which files have really been removed in the
belaran@999: 	newer version of the source.</para>
belaran@999: 
belaran@999:       <para id="x_43c">Finally, you can apply your patches on top of the new
belaran@999: 	tree.</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.tarball.repush -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../netplug</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../netplug-1.2.8</userinput>
belaran@999: pulling from ../netplug-1.2.8
belaran@999: searching for changes
belaran@999: adding changesets
belaran@999: adding manifests
belaran@999: adding file changes
belaran@999: added 1 changesets with 12 changes to 12 files
belaran@999: (run 'hg update' to get a working copy)
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpush -a</userinput>
belaran@999: (working directory not at tip)
belaran@999: applying build-fix.patch
belaran@999: now at: build-fix.patch
belaran@999: </screen>
belaran@999: <!-- END mq.tarball.repush -->
belaran@999: 
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2 id="sec:mq:combine">
belaran@999:       <title>Combining entire patches</title>
belaran@999: 
belaran@999:       <para id="x_43d">MQ provides a command, <command role="hg-ext-mq" moreinfo="none">qfold</command> that lets you combine
belaran@999: 	entire patches.  This <quote>folds</quote> the patches you
belaran@999: 	name, in the order you name them, into the topmost applied
belaran@999: 	patch, and concatenates their descriptions onto the end of its
belaran@999: 	description.  The patches that you fold must be unapplied
belaran@999: 	before you fold them.</para>
belaran@999: 
belaran@999:       <para id="x_43e">The order in which you fold patches matters.  If your
belaran@999: 	topmost applied patch is <literal moreinfo="none">foo</literal>, and you
belaran@999: 	<command role="hg-ext-mq" moreinfo="none">qfold</command>
belaran@999: 	<literal moreinfo="none">bar</literal> and <literal moreinfo="none">quux</literal> into it,
belaran@999: 	you will end up with a patch that has the same effect as if
belaran@999: 	you applied first <literal moreinfo="none">foo</literal>, then
belaran@999: 	<literal moreinfo="none">bar</literal>, followed by
belaran@999: 	<literal moreinfo="none">quux</literal>.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Merging part of one patch into another</title>
belaran@999: 
belaran@999:       <para id="x_43f">Merging <emphasis>part</emphasis> of one patch into
belaran@999: 	another is more difficult than combining entire
belaran@999: 	patches.</para>
belaran@999: 
belaran@999:       <para id="x_440">If you want to move changes to entire files, you can use
belaran@999: 	<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
belaran@999: 	modifications to snip out of one patch, concatenating its
belaran@999: 	output onto the end of the patch you want to merge into.  You
belaran@999: 	usually won't need to modify the patch you've merged the
belaran@999: 	changes from.  Instead, MQ will report some rejected hunks
belaran@999: 	when you <command role="hg-ext-mq" moreinfo="none">qpush</command> it (from
belaran@999: 	the hunks you moved into the other patch), and you can simply
belaran@999: 	<command role="hg-ext-mq" moreinfo="none">qrefresh</command> the patch to drop
belaran@999: 	the duplicate hunks.</para>
belaran@999: 
belaran@999:       <para id="x_441">If you have a patch that has multiple hunks modifying a
belaran@999: 	file, and you only want to move a few of those hunks, the job
belaran@999: 	becomes more messy, but you can still partly automate it.  Use
belaran@999: 	<command moreinfo="none">lsdiff -nvv</command> to print some metadata about
belaran@999: 	the patch.</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.tools.lsdiff -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">lsdiff -nvv remove-redundant-null-checks.patch</userinput>
belaran@999: 22	File #1  	a/drivers/char/agp/sgi-agp.c
belaran@999: 	24	Hunk #1	static int __devinit agp_sgi_init(void)
belaran@999: 37	File #2  	a/drivers/char/hvcs.c
belaran@999: 	39	Hunk #1	static struct tty_operations hvcs_ops = 
belaran@999: 	53	Hunk #2	static int hvcs_alloc_index_list(int n)
belaran@999: 69	File #3  	a/drivers/message/fusion/mptfc.c
belaran@999: 	71	Hunk #1	mptfc_GetFcDevPage0(MPT_ADAPTER *ioc, in
belaran@999: 85	File #4  	a/drivers/message/fusion/mptsas.c
belaran@999: 	87	Hunk #1	mptsas_probe_hba_phys(MPT_ADAPTER *ioc)
belaran@999: 98	File #5  	a/drivers/net/fs_enet/fs_enet-mii.c
belaran@999: 	100	Hunk #1	static struct fs_enet_mii_bus *create_bu
belaran@999: 111	File #6  	a/drivers/net/wireless/ipw2200.c
belaran@999: 	113	Hunk #1	static struct ipw_fw_error *ipw_alloc_er
belaran@999: 	126	Hunk #2	static ssize_t clear_error(struct device
belaran@999: 	140	Hunk #3	static void ipw_irq_tasklet(struct ipw_p
belaran@999: 	150	Hunk #4	static void ipw_pci_remove(struct pci_de
belaran@999: 164	File #7  	a/drivers/scsi/libata-scsi.c
belaran@999: 	166	Hunk #1	int ata_cmd_ioctl(struct scsi_device *sc
belaran@999: 178	File #8  	a/drivers/video/au1100fb.c
belaran@999: 	180	Hunk #1	void __exit au1100fb_cleanup(void)
belaran@999: </screen>
belaran@999: <!-- END mq.tools.lsdiff -->
belaran@999: 
belaran@999: 
belaran@999:       <para id="x_442">This command prints three different kinds of
belaran@999: 	number:</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_443">(in the first column) a <emphasis>file
belaran@999: 	      number</emphasis> to identify each file modified in the
belaran@999: 	    patch;</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_444">(on the next line, indented) the line number
belaran@999: 	    within a modified file where a hunk starts; and</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_445">(on the same line) a <emphasis>hunk
belaran@999: 	      number</emphasis> to identify that hunk.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_446">You'll have to use some visual inspection, and reading of
belaran@999: 	the patch, to identify the file and hunk numbers you'll want,
belaran@999: 	but you can then pass them to to
belaran@999: 	<command moreinfo="none">filterdiff</command>'s <option role="cmd-opt-filterdiff">--files</option> and <option role="cmd-opt-filterdiff">--hunks</option> options, to
belaran@999: 	select exactly the file and hunk you want to extract.</para>
belaran@999: 
belaran@999:       <para id="x_447">Once you have this hunk, you can concatenate it onto the
belaran@999: 	end of your destination patch and continue with the remainder
belaran@999: 	of <xref linkend="sec:mq:combine"/>.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Differences between quilt and MQ</title>
belaran@999: 
belaran@999:     <para id="x_448">If you are already familiar with quilt, MQ provides a
belaran@999:       similar command set.  There are a few differences in the way
belaran@999:       that it works.</para>
belaran@999: 
belaran@999:     <para id="x_449">You will already have noticed that most quilt commands have
belaran@999:       MQ counterparts that simply begin with a
belaran@999:       <quote><literal moreinfo="none">q</literal></quote>.  The exceptions are quilt's
belaran@999:       <literal moreinfo="none">add</literal> and <literal moreinfo="none">remove</literal> commands,
belaran@999:       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
belaran@999: 	remove</command> commands.  There is no MQ equivalent of the
belaran@999:       quilt <literal moreinfo="none">edit</literal> command.</para>
belaran@999: 
belaran@999:   </sect1>
belaran@999: </chapter>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "chapter")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN ch13 -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <chapter id="chap:mq-collab">
belaran@999:   <?dbhtml filename="advanced-uses-of-mercurial-queues.html"?>
belaran@999:   <title>Advanced uses of Mercurial Queues</title>
belaran@999: 
belaran@999:   <para id="x_15d">While it's easy to pick up straightforward uses of Mercurial
belaran@999:     Queues, use of a little discipline and some of MQ's less
belaran@999:     frequently used capabilities makes it possible to work in
belaran@999:     complicated development environments.</para>
belaran@999: 
belaran@999:   <para id="x_15e">In this chapter, I will use as an example a technique I have
belaran@999:     used to manage the development of an Infiniband device driver for
belaran@999:     the Linux kernel.  The driver in question is large (at least as
belaran@999:     drivers go), with 25,000 lines of code spread across 35 source
belaran@999:     files.  It is maintained by a small team of developers.</para>
belaran@999: 
belaran@999:   <para id="x_15f">While much of the material in this chapter is specific to
belaran@999:     Linux, the same principles apply to any code base for which you're
belaran@999:     not the primary owner, and upon which you need to do a lot of
belaran@999:     development.</para>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>The problem of many targets</title>
belaran@999: 
belaran@999:     <para id="x_160">The Linux kernel changes rapidly, and has never been
belaran@999:       internally stable; developers frequently make drastic changes
belaran@999:       between releases. This means that a version of the driver that
belaran@999:       works well with a particular released version of the kernel will
belaran@999:       not even <emphasis>compile</emphasis> correctly against,
belaran@999:       typically, any other version.</para>
belaran@999: 
belaran@999:     <para id="x_161">To maintain a driver, we have to keep a number of distinct
belaran@999:       versions of Linux in mind.</para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_162">One target is the main Linux kernel development
belaran@999: 	  tree. Maintenance of the code is in this case partly shared
belaran@999: 	  by other developers in the kernel community, who make
belaran@999: 	  <quote>drive-by</quote> modifications to the driver as they
belaran@999: 	  develop and refine kernel subsystems.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_163">We also maintain a number of
belaran@999: 	  <quote>backports</quote> to older versions of the Linux
belaran@999: 	  kernel, to support the needs of customers who are running
belaran@999: 	  older Linux distributions that do not incorporate our
belaran@999: 	  drivers.  (To <emphasis>backport</emphasis> a piece of code
belaran@999: 	  is to modify it to work in an older version of its target
belaran@999: 	  environment than the version it was developed for.)</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_164">Finally, we make software releases on a schedule
belaran@999: 	  that is necessarily not aligned with those used by Linux
belaran@999: 	  distributors and kernel developers, so that we can deliver
belaran@999: 	  new features to customers without forcing them to upgrade
belaran@999: 	  their entire kernels or distributions.</para>
belaran@999:       </listitem></itemizedlist>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Tempting approaches that don't work well</title>
belaran@999: 
belaran@999:       <para id="x_165">There are two <quote>standard</quote> ways to maintain a
belaran@999: 	piece of software that has to target many different
belaran@999: 	environments.</para>
belaran@999: 
belaran@999:       <para id="x_166">The first is to maintain a number of branches, each
belaran@999: 	intended for a single target.  The trouble with this approach
belaran@999: 	is that you must maintain iron discipline in the flow of
belaran@999: 	changes between repositories. A new feature or bug fix must
belaran@999: 	start life in a <quote>pristine</quote> repository, then
belaran@999: 	percolate out to every backport repository.  Backport changes
belaran@999: 	are more limited in the branches they should propagate to; a
belaran@999: 	backport change that is applied to a branch where it doesn't
belaran@999: 	belong will probably stop the driver from compiling.</para>
belaran@999: 
belaran@999:       <para id="x_167">The second is to maintain a single source tree filled with
belaran@999: 	conditional statements that turn chunks of code on or off
belaran@999: 	depending on the intended target.  Because these
belaran@999: 	<quote>ifdefs</quote> are not allowed in the Linux kernel
belaran@999: 	tree, a manual or automatic process must be followed to strip
belaran@999: 	them out and yield a clean tree.  A code base maintained in
belaran@999: 	this fashion rapidly becomes a rat's nest of conditional
belaran@999: 	blocks that are difficult to understand and maintain.</para>
belaran@999: 
belaran@999:       <para id="x_168">Neither of these approaches is well suited to a situation
belaran@999: 	where you don't <quote>own</quote> the canonical copy of a
belaran@999: 	source tree.  In the case of a Linux driver that is
belaran@999: 	distributed with the standard kernel, Linus's tree contains
belaran@999: 	the copy of the code that will be treated by the world as
belaran@999: 	canonical.  The upstream version of <quote>my</quote> driver
belaran@999: 	can be modified by people I don't know, without me even
belaran@999: 	finding out about it until after the changes show up in
belaran@999: 	Linus's tree.</para>
belaran@999: 
belaran@999:       <para id="x_169">These approaches have the added weakness of making it
belaran@999: 	difficult to generate well-formed patches to submit
belaran@999: 	upstream.</para>
belaran@999: 
belaran@999:       <para id="x_16a">In principle, Mercurial Queues seems like a good candidate
belaran@999: 	to manage a development scenario such as the above.  While
belaran@999: 	this is indeed the case, MQ contains a few added features that
belaran@999: 	make the job more pleasant.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Conditionally applying patches with guards</title>
belaran@999: 
belaran@999:     <para id="x_16b">Perhaps the best way to maintain sanity with so many targets
belaran@999:       is to be able to choose specific patches to apply for a given
belaran@999:       situation.  MQ provides a feature called <quote>guards</quote>
belaran@999:       (which originates with quilt's <literal moreinfo="none">guards</literal>
belaran@999:       command) that does just this.  To start off, let's create a
belaran@999:       simple repository for experimenting in.</para>
belaran@999: 
belaran@999:     <!-- BEGIN mq.guards.init -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qinit</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew hello.patch</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo hello &gt; hello</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add hello</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew goodbye.patch</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo goodbye &gt; goodbye</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add goodbye</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
belaran@999: </screen>
belaran@999: <!-- END mq.guards.init -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_16c">This gives us a tiny repository that contains two patches
belaran@999:       that don't have any dependencies on each other, because they
belaran@999:       touch different files.</para>
belaran@999: 
belaran@999:     <para id="x_16d">The idea behind conditional application is that you can
belaran@999:       <quote>tag</quote> a patch with a <emphasis>guard</emphasis>,
belaran@999:       which is simply a text string of your choosing, then tell MQ to
belaran@999:       select specific guards to use when applying patches.  MQ will
belaran@999:       then either apply, or skip over, a guarded patch, depending on
belaran@999:       the guards that you have selected.</para>
belaran@999: 
belaran@999:     <para id="x_16e">A patch can have an arbitrary number of guards; each one is
belaran@999:       <emphasis>positive</emphasis> (<quote>apply this patch if this
belaran@999: 	guard is selected</quote>) or <emphasis>negative</emphasis>
belaran@999:       (<quote>skip this patch if this guard is selected</quote>).  A
belaran@999:       patch with no guards is always applied.</para>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Controlling the guards on a patch</title>
belaran@999: 
belaran@999:     <para id="x_16f">The <command role="hg-ext-mq" moreinfo="none">qguard</command> command lets
belaran@999:       you determine which guards should apply to a patch, or display
belaran@999:       the guards that are already in effect. Without any arguments, it
belaran@999:       displays the guards on the current topmost patch.</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.guards.qguard -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qguard</userinput>
belaran@999: goodbye.patch: unguarded
belaran@999: </screen>
belaran@999: <!-- END mq.guards.qguard -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_170">To set a positive guard on a patch, prefix the name of the
belaran@999:       guard with a <quote><literal moreinfo="none">+</literal></quote>.</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.guards.qguard.pos -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qguard +foo</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qguard</userinput>
belaran@999: goodbye.patch: +foo
belaran@999: </screen>
belaran@999: <!-- END mq.guards.qguard.pos -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_171">To set a negative guard
belaran@999:       on a patch, prefix the name of the guard with a
belaran@999:       <quote><literal moreinfo="none">-</literal></quote>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN mq.guards.qguard.neg -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qguard -- hello.patch -quux</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qguard hello.patch</userinput>
belaran@999: hello.patch: -quux
belaran@999: </screen>
belaran@999: <!-- END mq.guards.qguard.neg -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_74a">Notice that we prefixed the arguments to the <command moreinfo="none">hg
belaran@999: 	qguard</command> command with a <literal moreinfo="none">--</literal> here, so
belaran@999:       that Mercurial would not interpret the text
belaran@999:       <literal moreinfo="none">-quux</literal> as an option.</para>
belaran@999: 
belaran@999:     <note>
belaran@999:       <title>Setting vs. modifying</title>
belaran@999: 
belaran@999:       <para id="x_172">  The <command role="hg-ext-mq" moreinfo="none">qguard</command> command
belaran@999: 	<emphasis>sets</emphasis> the guards on a patch; it doesn't
belaran@999: 	<emphasis>modify</emphasis> them.  What this means is that if
belaran@999: 	you run <command role="hg-cmd" moreinfo="none">hg qguard +a +b</command> on a
belaran@999: 	patch, then <command role="hg-cmd" moreinfo="none">hg qguard +c</command> on
belaran@999: 	the same patch, the <emphasis>only</emphasis> guard that will
belaran@999: 	be set on it afterwards is <literal moreinfo="none">+c</literal>.</para>
belaran@999:     </note>
belaran@999: 
belaran@999:     <para id="x_173">Mercurial stores guards in the <filename role="special" moreinfo="none">series</filename> file; the form in which they
belaran@999:       are stored is easy both to understand and to edit by hand. (In
belaran@999:       other words, you don't have to use the <command role="hg-ext-mq" moreinfo="none">qguard</command> command if you don't want
belaran@999:       to; it's okay to simply edit the <filename role="special" moreinfo="none">series</filename> file.)</para>
belaran@999: 
belaran@999:     <!-- BEGIN mq.guards.series -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/patches/series</userinput>
belaran@999: hello.patch #-quux
belaran@999: goodbye.patch #+foo
belaran@999: </screen>
belaran@999: <!-- END mq.guards.series -->
belaran@999: 
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Selecting the guards to use</title>
belaran@999: 
belaran@999:     <para id="x_174">The <command role="hg-ext-mq" moreinfo="none">qselect</command> command
belaran@999:       determines which guards are active at a given time.  The effect
belaran@999:       of this is to determine which patches MQ will apply the next
belaran@999:       time you run <command role="hg-ext-mq" moreinfo="none">qpush</command>.  It has
belaran@999:       no other effect; in particular, it doesn't do anything to
belaran@999:       patches that are already applied.</para>
belaran@999: 
belaran@999:     <para id="x_175">With no arguments, the <command role="hg-ext-mq" moreinfo="none">qselect</command> command lists the guards
belaran@999:       currently in effect, one per line of output.  Each argument is
belaran@999:       treated as the name of a guard to apply.</para>
belaran@999: 
belaran@999:       <!-- BEGIN mq.guards.qselect.foo -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop -a</userinput>
belaran@999: patch queue now empty
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect</userinput>
belaran@999: no active guards
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect foo</userinput>
belaran@999: number of unguarded, unapplied patches has changed from 1 to 2
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect</userinput>
belaran@999: foo
belaran@999: </screen>
belaran@999: <!-- END mq.guards.qselect.foo -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_176">In case you're interested, the currently selected guards are
belaran@999:       stored in the <filename role="special" moreinfo="none">guards</filename> file.</para>
belaran@999: 
belaran@999:     <!-- BEGIN mq.guards.qselect.cat -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/patches/guards</userinput>
belaran@999: foo
belaran@999: </screen>
belaran@999: <!-- END mq.guards.qselect.cat -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_177">We can see the effect the selected guards have when we run
belaran@999:       <command role="hg-ext-mq" moreinfo="none">qpush</command>.</para>
belaran@999: 
belaran@999:     <!-- BEGIN mq.guards.qselect.qpush -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpush -a</userinput>
belaran@999: applying hello.patch
belaran@999: applying goodbye.patch
belaran@999: now at: goodbye.patch
belaran@999: </screen>
belaran@999: <!-- END mq.guards.qselect.qpush -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_178">A guard cannot start with a
belaran@999:       <quote><literal moreinfo="none">+</literal></quote> or
belaran@999:       <quote><literal moreinfo="none">-</literal></quote> character.  The name of a
belaran@999:       guard must not contain white space, but most other characters
belaran@999:       are acceptable.  If you try to use a guard with an invalid name,
belaran@999:       MQ will complain:</para>
belaran@999: 
belaran@999:     <!-- BEGIN mq.guards.qselect.error -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect +foo</userinput>
belaran@999: abort: guard '+foo' starts with invalid character: '+'
belaran@999: </screen>
belaran@999: <!-- END mq.guards.qselect.error -->
belaran@999: 
belaran@999:       
belaran@999:     <para id="x_179">Changing the selected guards changes the patches that are
belaran@999:       applied.</para>
belaran@999: 
belaran@999:     <!-- BEGIN mq.guards.qselect.quux -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect quux</userinput>
belaran@999: number of guarded, applied patches has changed from 0 to 2
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop -a</userinput>
belaran@999: patch queue now empty
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpush -a</userinput>
belaran@999: patch series already fully applied
belaran@999: </screen>
belaran@999: <!-- END mq.guards.qselect.quux -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_17a">You can see in the example below that negative guards take
belaran@999:       precedence over positive guards.</para>
belaran@999: 
belaran@999:     <!-- BEGIN mq.guards.qselect.foobar -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect foo bar</userinput>
belaran@999: number of unguarded, unapplied patches has changed from 0 to 2
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop -a</userinput>
belaran@999: no patches applied
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpush -a</userinput>
belaran@999: applying hello.patch
belaran@999: applying goodbye.patch
belaran@999: now at: goodbye.patch
belaran@999: </screen>
belaran@999: <!-- END mq.guards.qselect.foobar -->
belaran@999: 
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>MQ's rules for applying patches</title>
belaran@999: 
belaran@999:     <para id="x_17b">The rules that MQ uses when deciding whether to apply a
belaran@999:       patch are as follows.</para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_17c">A patch that has no guards is always
belaran@999: 	  applied.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_17d">If the patch has any negative guard that matches
belaran@999: 	  any currently selected guard, the patch is skipped.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_17e">If the patch has any positive guard that matches
belaran@999: 	  any currently selected guard, the patch is applied.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_17f">If the patch has positive or negative guards,
belaran@999: 	  but none matches any currently selected guard, the patch is
belaran@999: 	  skipped.</para>
belaran@999:       </listitem></itemizedlist>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Trimming the work environment</title>
belaran@999: 
belaran@999:     <para id="x_180">In working on the device driver I mentioned earlier, I don't
belaran@999:       apply the patches to a normal Linux kernel tree.  Instead, I use
belaran@999:       a repository that contains only a snapshot of the source files
belaran@999:       and headers that are relevant to Infiniband development.  This
belaran@999:       repository is 1% the size of a kernel repository, so it's easier
belaran@999:       to work with.</para>
belaran@999: 
belaran@999:     <para id="x_181">I then choose a <quote>base</quote> version on top of which
belaran@999:       the patches are applied.  This is a snapshot of the Linux kernel
belaran@999:       tree as of a revision of my choosing.  When I take the snapshot,
belaran@999:       I record the changeset ID from the kernel repository in the
belaran@999:       commit message.  Since the snapshot preserves the
belaran@999:       <quote>shape</quote> and content of the relevant parts of the
belaran@999:       kernel tree, I can apply my patches on top of either my tiny
belaran@999:       repository or a normal kernel tree.</para>
belaran@999: 
belaran@999:     <para id="x_182">Normally, the base tree atop which the patches apply should
belaran@999:       be a snapshot of a very recent upstream tree.  This best
belaran@999:       facilitates the development of patches that can easily be
belaran@999:       submitted upstream with few or no modifications.</para>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Dividing up the <filename role="special" moreinfo="none">series</filename>
belaran@999:       file</title>
belaran@999: 
belaran@999:     <para id="x_183">I categorise the patches in the <filename role="special" moreinfo="none">series</filename> file into a number of logical
belaran@999:       groups.  Each section of like patches begins with a block of
belaran@999:       comments that describes the purpose of the patches that
belaran@999:       follow.</para>
belaran@999: 
belaran@999:     <para id="x_184">The sequence of patch groups that I maintain follows.  The
belaran@999:       ordering of these groups is important; I'll describe why after I
belaran@999:       introduce the groups.</para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_185">The <quote>accepted</quote> group.  Patches that
belaran@999: 	  the development team has submitted to the maintainer of the
belaran@999: 	  Infiniband subsystem, and which he has accepted, but which
belaran@999: 	  are not present in the snapshot that the tiny repository is
belaran@999: 	  based on.  These are <quote>read only</quote> patches,
belaran@999: 	  present only to transform the tree into a similar state as
belaran@999: 	  it is in the upstream maintainer's repository.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_186">The <quote>rework</quote> group.  Patches that I
belaran@999: 	  have submitted, but that the upstream maintainer has
belaran@999: 	  requested modifications to before he will accept
belaran@999: 	  them.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_187">The <quote>pending</quote> group.  Patches that
belaran@999: 	  I have not yet submitted to the upstream maintainer, but
belaran@999: 	  which we have finished working on. These will be <quote>read
belaran@999: 	    only</quote> for a while.  If the upstream maintainer
belaran@999: 	  accepts them upon submission, I'll move them to the end of
belaran@999: 	  the <quote>accepted</quote> group.  If he requests that I
belaran@999: 	  modify any, I'll move them to the beginning of the
belaran@999: 	  <quote>rework</quote> group.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_188">The <quote>in progress</quote> group.  Patches
belaran@999: 	  that are actively being developed, and should not be
belaran@999: 	  submitted anywhere yet.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_189">The <quote>backport</quote> group.  Patches that
belaran@999: 	  adapt the source tree to older versions of the kernel
belaran@999: 	  tree.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_18a">The <quote>do not ship</quote> group.  Patches
belaran@999: 	  that for some reason should never be submitted upstream.
belaran@999: 	  For example, one such patch might change embedded driver
belaran@999: 	  identification strings to make it easier to distinguish, in
belaran@999: 	  the field, between an out-of-tree version of the driver and
belaran@999: 	  a version shipped by a distribution vendor.</para>
belaran@999:       </listitem></itemizedlist>
belaran@999: 
belaran@999:     <para id="x_18b">Now to return to the reasons for ordering groups of patches
belaran@999:       in this way.  We would like the lowest patches in the stack to
belaran@999:       be as stable as possible, so that we will not need to rework
belaran@999:       higher patches due to changes in context.  Putting patches that
belaran@999:       will never be changed first in the <filename role="special" moreinfo="none">series</filename> file serves this
belaran@999:       purpose.</para>
belaran@999: 
belaran@999:     <para id="x_18c">We would also like the patches that we know we'll need to
belaran@999:       modify to be applied on top of a source tree that resembles the
belaran@999:       upstream tree as closely as possible.  This is why we keep
belaran@999:       accepted patches around for a while.</para>
belaran@999: 
belaran@999:     <para id="x_18d">The <quote>backport</quote> and <quote>do not ship</quote>
belaran@999:       patches float at the end of the <filename role="special" moreinfo="none">series</filename> file.  The backport patches
belaran@999:       must be applied on top of all other patches, and the <quote>do
belaran@999: 	not ship</quote> patches might as well stay out of harm's
belaran@999:       way.</para>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Maintaining the patch series</title>
belaran@999: 
belaran@999:     <para id="x_18e">In my work, I use a number of guards to control which
belaran@999:       patches are to be applied.</para>
belaran@999: 
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_18f"><quote>Accepted</quote> patches are guarded with
belaran@999: 	  <literal moreinfo="none">accepted</literal>.  I enable this guard most of
belaran@999: 	  the time.  When I'm applying the patches on top of a tree
belaran@999: 	  where the patches are already present, I can turn this patch
belaran@999: 	  off, and the patches that follow it will apply
belaran@999: 	  cleanly.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_190">Patches that are <quote>finished</quote>, but
belaran@999: 	  not yet submitted, have no guards.  If I'm applying the
belaran@999: 	  patch stack to a copy of the upstream tree, I don't need to
belaran@999: 	  enable any guards in order to get a reasonably safe source
belaran@999: 	  tree.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_191">Those patches that need reworking before being
belaran@999: 	  resubmitted are guarded with
belaran@999: 	  <literal moreinfo="none">rework</literal>.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_192">For those patches that are still under
belaran@999: 	  development, I use <literal moreinfo="none">devel</literal>.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_193">A backport patch may have several guards, one
belaran@999: 	  for each version of the kernel to which it applies.  For
belaran@999: 	  example, a patch that backports a piece of code to 2.6.9
belaran@999: 	  will have a <literal moreinfo="none">2.6.9</literal> guard.</para>
belaran@999:       </listitem></itemizedlist>
belaran@999:     <para id="x_194">This variety of guards gives me considerable flexibility in
belaran@999:       determining what kind of source tree I want to end up with.  For
belaran@999:       most situations, the selection of appropriate guards is
belaran@999:       automated during the build process, but I can manually tune the
belaran@999:       guards to use for less common circumstances.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>The art of writing backport patches</title>
belaran@999: 
belaran@999:       <para id="x_195">Using MQ, writing a backport patch is a simple process.
belaran@999: 	All such a patch has to do is modify a piece of code that uses
belaran@999: 	a kernel feature not present in the older version of the
belaran@999: 	kernel, so that the driver continues to work correctly under
belaran@999: 	that older version.</para>
belaran@999: 
belaran@999:       <para id="x_196">A useful goal when writing a good backport patch is to
belaran@999: 	make your code look as if it was written for the older version
belaran@999: 	of the kernel you're targeting.  The less obtrusive the patch,
belaran@999: 	the easier it will be to understand and maintain.  If you're
belaran@999: 	writing a collection of backport patches to avoid the
belaran@999: 	<quote>rat's nest</quote> effect of lots of
belaran@999: 	<literal moreinfo="none">#ifdef</literal>s (hunks of source code that are only
belaran@999: 	used conditionally) in your code, don't introduce
belaran@999: 	version-dependent <literal moreinfo="none">#ifdef</literal>s into the patches.
belaran@999: 	Instead, write several patches, each of which makes
belaran@999: 	unconditional changes, and control their application using
belaran@999: 	guards.</para>
belaran@999: 
belaran@999:       <para id="x_197">There are two reasons to divide backport patches into a
belaran@999: 	distinct group, away from the <quote>regular</quote> patches
belaran@999: 	whose effects they modify. The first is that intermingling the
belaran@999: 	two makes it more difficult to use a tool like the <literal role="hg-ext" moreinfo="none">patchbomb</literal> extension to automate the
belaran@999: 	process of submitting the patches to an upstream maintainer.
belaran@999: 	The second is that a backport patch could perturb the context
belaran@999: 	in which a subsequent regular patch is applied, making it
belaran@999: 	impossible to apply the regular patch cleanly
belaran@999: 	<emphasis>without</emphasis> the earlier backport patch
belaran@999: 	already being applied.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Useful tips for developing with MQ</title>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Organising patches in directories</title>
belaran@999: 
belaran@999:       <para id="x_198">If you're working on a substantial project with MQ, it's
belaran@999: 	not difficult to accumulate a large number of patches.  For
belaran@999: 	example, I have one patch repository that contains over 250
belaran@999: 	patches.</para>
belaran@999: 
belaran@999:       <para id="x_199">If you can group these patches into separate logical
belaran@999: 	categories, you can if you like store them in different
belaran@999: 	directories; MQ has no problems with patch names that contain
belaran@999: 	path separators.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2 id="mq-collab:tips:interdiff">
belaran@999:       <title>Viewing the history of a patch</title>
belaran@999: 
belaran@999:       <para id="x_19a">If you're developing a set of patches over a long time,
belaran@999: 	it's a good idea to maintain them in a repository, as
belaran@999: 	discussed in <xref linkend="sec:mq:repo"/>.  If you do
belaran@999: 	so, you'll quickly
belaran@999: 	discover that using the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  diff</command> command to look at the history of changes to
belaran@999: 	a patch is unworkable.  This is in part because you're looking
belaran@999: 	at the second derivative of the real code (a diff of a diff),
belaran@999: 	but also because MQ adds noise to the process by modifying
belaran@999: 	time stamps and directory names when it updates a
belaran@999: 	patch.</para>
belaran@999: 
belaran@999:       <para id="x_19b">However, you can use the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension, which is bundled
belaran@999: 	with Mercurial, to turn a diff of two versions of a patch into
belaran@999: 	something readable.  To do this, you will need a third-party
belaran@999: 	package called <literal role="package" moreinfo="none">patchutils</literal>
belaran@999: 	<citation>web:patchutils</citation>.  This provides a command
belaran@999: 	named <command moreinfo="none">interdiff</command>, which shows the
belaran@999: 	differences between two diffs as a diff.  Used on two versions
belaran@999: 	of the same diff, it generates a diff that represents the diff
belaran@999: 	from the first to the second version.</para>
belaran@999: 
belaran@999:       <para id="x_19c">You can enable the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension in the usual way,
belaran@999: 	by adding a line to the <literal role="rc-extensions" moreinfo="none">extensions</literal> section of your
belaran@999: 	<filename role="special" moreinfo="none">~/.hgrc</filename>.</para>
belaran@999:       <programlisting format="linespecific">[extensions]
belaran@999: extdiff =</programlisting>
belaran@999:       <para id="x_19d">The <command moreinfo="none">interdiff</command> command expects to be
belaran@999: 	passed the names of two files, but the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension passes the program
belaran@999: 	it runs a pair of directories, each of which can contain an
belaran@999: 	arbitrary number of files.  We thus need a small program that
belaran@999: 	will run <command moreinfo="none">interdiff</command> on each pair of files in
belaran@999: 	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
belaran@999: 	source code repository that accompanies this book. <!--
belaran@999: 	&example.hg-interdiff; --></para>
belaran@999: 
belaran@999:       <para id="x_19e">With the <filename role="special" moreinfo="none">hg-interdiff</filename>
belaran@999: 	program in your shell's search path, you can run it as
belaran@999: 	follows, from inside an MQ patch directory:</para>
belaran@999:       <programlisting format="linespecific">hg extdiff -p hg-interdiff -r A:B my-change.patch</programlisting>
belaran@999:       <para id="x_19f">Since you'll probably want to use this long-winded command
belaran@999: 	a lot, you can get <literal role="hg-ext" moreinfo="none">hgext</literal> to
belaran@999: 	make it available as a normal Mercurial command, again by
belaran@999: 	editing your <filename role="special" moreinfo="none">~/.hgrc</filename>.</para>
belaran@999:       <programlisting format="linespecific">[extdiff]
belaran@999: cmd.interdiff = hg-interdiff</programlisting>
belaran@999:       <para id="x_1a0">This directs <literal role="hg-ext" moreinfo="none">hgext</literal> to
belaran@999: 	make an <literal moreinfo="none">interdiff</literal> command available, so you
belaran@999: 	can now shorten the previous invocation of <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> to something a
belaran@999: 	little more wieldy.</para>
belaran@999:       <programlisting format="linespecific">hg interdiff -r A:B my-change.patch</programlisting>
belaran@999: 
belaran@999:       <note>
belaran@999: 	<para id="x_1a1">  The <command moreinfo="none">interdiff</command> command works well
belaran@999: 	  only if the underlying files against which versions of a
belaran@999: 	  patch are generated remain the same.  If you create a patch,
belaran@999: 	  modify the underlying files, and then regenerate the patch,
belaran@999: 	  <command moreinfo="none">interdiff</command> may not produce useful
belaran@999: 	  output.</para>
belaran@999:       </note>
belaran@999: 
belaran@999:       <para id="x_1a2">The <literal role="hg-ext" moreinfo="none">extdiff</literal> extension is
belaran@999: 	useful for more than merely improving the presentation of MQ
belaran@999: 	patches.  To read more about it, go to <xref linkend="sec:hgext:extdiff"/>.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: </chapter>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "chapter")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN ch14 -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <chapter id="chap:hgext">
belaran@999:   <?dbhtml filename="adding-functionality-with-extensions.html"?>
belaran@999:   <title>Adding functionality with extensions</title>
belaran@999: 
belaran@999:   <para id="x_4fe">While the core of Mercurial is quite complete from a
belaran@999:     functionality standpoint, it's deliberately shorn of fancy
belaran@999:     features.  This approach of preserving simplicity keeps the
belaran@999:     software easy to deal with for both maintainers and users.</para>
belaran@999: 
belaran@999:   <para id="x_4ff">However, Mercurial doesn't box you in with an inflexible
belaran@999:     command set: you can add features to it as
belaran@999:     <emphasis>extensions</emphasis> (sometimes known as
belaran@999:     <emphasis>plugins</emphasis>).  We've already discussed a few of
belaran@999:     these extensions in earlier chapters.</para>
belaran@999:   <itemizedlist>
belaran@999:     <listitem><para id="x_500"><xref linkend="sec:tour-merge:fetch"/>
belaran@999: 	covers the <literal role="hg-ext" moreinfo="none">fetch</literal> extension;
belaran@999: 	this combines pulling new changes and merging them with local
belaran@999: 	changes into a single command, <command role="hg-ext-fetch" moreinfo="none">fetch</command>.</para>
belaran@999:     </listitem>
belaran@999:     <listitem><para id="x_501">In <xref linkend="chap:hook"/>, we covered
belaran@999: 	several extensions that are useful for hook-related
belaran@999: 	functionality: <literal role="hg-ext" moreinfo="none">acl</literal> adds
belaran@999: 	access control lists; <literal role="hg-ext" moreinfo="none">bugzilla</literal> adds integration with the
belaran@999: 	Bugzilla bug tracking system; and <literal role="hg-ext" moreinfo="none">notify</literal> sends notification emails on
belaran@999: 	new changes.</para>
belaran@999:     </listitem>
belaran@999:     <listitem><para id="x_502">The Mercurial Queues patch management extension is
belaran@999: 	so invaluable that it merits two chapters and an appendix all
belaran@999: 	to itself. <xref linkend="chap:mq"/> covers the
belaran@999: 	basics; <xref linkend="chap:mq-collab"/> discusses advanced topics;
belaran@999: 	and <xref linkend="chap:mqref"/> goes into detail on
belaran@999: 	each
belaran@999: 	command.</para>
belaran@999:     </listitem></itemizedlist>
belaran@999: 
belaran@999:   <para id="x_503">In this chapter, we'll cover some of the other extensions that
belaran@999:     are available for Mercurial, and briefly touch on some of the
belaran@999:     machinery you'll need to know about if you want to write an
belaran@999:     extension of your own.</para>
belaran@999:   <itemizedlist>
belaran@999:     <listitem><para id="x_504">In <xref linkend="sec:hgext:inotify"/>,
belaran@999: 	we'll discuss the possibility of <emphasis>huge</emphasis>
belaran@999: 	performance improvements using the <literal role="hg-ext" moreinfo="none">inotify</literal> extension.</para>
belaran@999:     </listitem></itemizedlist>
belaran@999: 
belaran@999:   <sect1 id="sec:hgext:inotify">
belaran@999:     <title>Improve performance with the <literal role="hg-ext" moreinfo="none">inotify</literal> extension</title>
belaran@999: 
belaran@999:     <para id="x_505">Are you interested in having some of the most common
belaran@999:       Mercurial operations run as much as a hundred times faster?
belaran@999:       Read on!</para>
belaran@999: 
belaran@999:     <para id="x_506">Mercurial has great performance under normal circumstances.
belaran@999:       For example, when you run the <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	status</command> command, Mercurial has to scan almost every
belaran@999:       directory and file in your repository so that it can display
belaran@999:       file status.  Many other Mercurial commands need to do the same
belaran@999:       work behind the scenes; for example, the <command role="hg-cmd" moreinfo="none">hg diff</command> command uses the status
belaran@999:       machinery to avoid doing an expensive comparison operation on
belaran@999:       files that obviously haven't changed.</para>
belaran@999: 
belaran@999:     <para id="x_507">Because obtaining file status is crucial to good
belaran@999:       performance, the authors of Mercurial have optimised this code
belaran@999:       to within an inch of its life.  However, there's no avoiding the
belaran@999:       fact that when you run <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	status</command>, Mercurial is going to have to perform at
belaran@999:       least one expensive system call for each managed file to
belaran@999:       determine whether it's changed since the last time Mercurial
belaran@999:       checked.  For a sufficiently large repository, this can take a
belaran@999:       long time.</para>
belaran@999: 
belaran@999:     <para id="x_508">To put a number on the magnitude of this effect, I created a
belaran@999:       repository containing 150,000 managed files.  I timed <command role="hg-cmd" moreinfo="none">hg status</command> as taking ten seconds to
belaran@999:       run, even when <emphasis>none</emphasis> of those files had been
belaran@999:       modified.</para>
belaran@999: 
belaran@999:     <para id="x_509">Many modern operating systems contain a file notification
belaran@999:       facility. If a program signs up to an appropriate service, the
belaran@999:       operating system will notify it every time a file of interest is
belaran@999:       created, modified, or deleted.  On Linux systems, the kernel
belaran@999:       component that does this is called
belaran@999:       <literal moreinfo="none">inotify</literal>.</para>
belaran@999: 
belaran@999:     <para id="x_50a">Mercurial's <literal role="hg-ext" moreinfo="none">inotify</literal>
belaran@999:       extension talks to the kernel's <literal moreinfo="none">inotify</literal>
belaran@999:       component to optimise <command role="hg-cmd" moreinfo="none">hg status</command>
belaran@999:       commands.  The extension has two components.  A daemon sits in
belaran@999:       the background and receives notifications from the
belaran@999:       <literal moreinfo="none">inotify</literal> subsystem.  It also listens for
belaran@999:       connections from a regular Mercurial command.  The extension
belaran@999:       modifies Mercurial's behavior so that instead of scanning the
belaran@999:       filesystem, it queries the daemon.  Since the daemon has perfect
belaran@999:       information about the state of the repository, it can respond
belaran@999:       with a result instantaneously, avoiding the need to scan every
belaran@999:       directory and file in the repository.</para>
belaran@999: 
belaran@999:     <para id="x_50b">Recall the ten seconds that I measured plain Mercurial as
belaran@999:       taking to run <command role="hg-cmd" moreinfo="none">hg status</command> on a
belaran@999:       150,000 file repository.  With the <literal role="hg-ext" moreinfo="none">inotify</literal> extension enabled, the time
belaran@999:       dropped to 0.1 seconds, a factor of <emphasis>one
belaran@999: 	hundred</emphasis> faster.</para>
belaran@999: 
belaran@999:     <para id="x_50c">Before we continue, please pay attention to some
belaran@999:       caveats.</para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem><para id="x_50d">The <literal role="hg-ext" moreinfo="none">inotify</literal>
belaran@999: 	  extension is Linux-specific.  Because it interfaces directly
belaran@999: 	  to the Linux kernel's <literal moreinfo="none">inotify</literal> subsystem,
belaran@999: 	  it does not work on other operating systems.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_50e">It should work on any Linux distribution that
belaran@999: 	  was released after early 2005.  Older distributions are
belaran@999: 	  likely to have a kernel that lacks
belaran@999: 	  <literal moreinfo="none">inotify</literal>, or a version of
belaran@999: 	  <literal moreinfo="none">glibc</literal> that does not have the necessary
belaran@999: 	  interfacing support.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_50f">Not all filesystems are suitable for use with
belaran@999: 	  the <literal role="hg-ext" moreinfo="none">inotify</literal> extension.
belaran@999: 	  Network filesystems such as NFS are a non-starter, for
belaran@999: 	  example, particularly if you're running Mercurial on several
belaran@999: 	  systems, all mounting the same network filesystem.  The
belaran@999: 	  kernel's <literal moreinfo="none">inotify</literal> system has no way of
belaran@999: 	  knowing about changes made on another system.  Most local
belaran@999: 	  filesystems (e.g. ext3, XFS, ReiserFS) should work
belaran@999: 	  fine.</para>
belaran@999:       </listitem></itemizedlist>
belaran@999: 
belaran@999:     <para id="x_510">The <literal role="hg-ext" moreinfo="none">inotify</literal> extension is
belaran@999:       not yet shipped with Mercurial as of May 2007, so it's a little
belaran@999:       more involved to set up than other extensions.  But the
belaran@999:       performance improvement is worth it!</para>
belaran@999: 
belaran@999:     <para id="x_511">The extension currently comes in two parts: a set of patches
belaran@999:       to the Mercurial source code, and a library of Python bindings
belaran@999:       to the <literal moreinfo="none">inotify</literal> subsystem.</para>
belaran@999:     <note>
belaran@999:       <para id="x_512">  There are <emphasis>two</emphasis> Python
belaran@999: 	<literal moreinfo="none">inotify</literal> binding libraries.  One of them is
belaran@999: 	called <literal moreinfo="none">pyinotify</literal>, and is packaged by some
belaran@999: 	Linux distributions as <literal moreinfo="none">python-inotify</literal>.
belaran@999: 	This is <emphasis>not</emphasis> the one you'll need, as it is
belaran@999: 	too buggy and inefficient to be practical.</para>
belaran@999:     </note>
belaran@999:     <para id="x_513">To get going, it's best to already have a functioning copy
belaran@999:       of Mercurial installed.</para>
belaran@999:     <note>
belaran@999:       <para id="x_514">  If you follow the instructions below, you'll be
belaran@999: 	<emphasis>replacing</emphasis> and overwriting any existing
belaran@999: 	installation of Mercurial that you might already have, using
belaran@999: 	the latest <quote>bleeding edge</quote> Mercurial code. Don't
belaran@999: 	say you weren't warned!</para>
belaran@999:     </note>
belaran@999:     <orderedlist inheritnum="ignore" continuation="restarts">
belaran@999:       <listitem><para id="x_515">Clone the Python <literal moreinfo="none">inotify</literal>
belaran@999: 	  binding repository.  Build and install it.</para>
belaran@999: 	<programlisting format="linespecific">hg clone http://hg.kublai.com/python/inotify
belaran@999: cd inotify
belaran@999: python setup.py build --force
belaran@999: sudo python setup.py install --skip-build</programlisting>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_516">Clone the <filename class="directory" moreinfo="none">crew</filename> Mercurial repository.
belaran@999: 	  Clone the <literal role="hg-ext" moreinfo="none">inotify</literal> patch
belaran@999: 	  repository so that Mercurial Queues will be able to apply
belaran@999: 	  patches to your cope of the <filename class="directory" moreinfo="none">crew</filename> repository.</para>
belaran@999: 	<programlisting format="linespecific">hg clone http://hg.intevation.org/mercurial/crew
belaran@999: hg clone crew inotify
belaran@999: hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches</programlisting>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_517">Make sure that you have the Mercurial Queues
belaran@999: 	  extension, <literal role="hg-ext" moreinfo="none">mq</literal>, enabled.  If
belaran@999: 	  you've never used MQ, read <xref linkend="sec:mq:start"/> to get started
belaran@999: 	  quickly.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_518">Go into the <filename class="directory" moreinfo="none">inotify</filename> repo, and apply all
belaran@999: 	  of the <literal role="hg-ext" moreinfo="none">inotify</literal> patches
belaran@999: 	  using the <option role="hg-ext-mq-cmd-qpush-opt">hg
belaran@999: 	    -a</option> option to the <command role="hg-ext-mq" moreinfo="none">qpush</command> command.</para>
belaran@999: 	<programlisting format="linespecific">cd inotify
belaran@999: hg qpush -a</programlisting>
belaran@999:       </listitem>
belaran@999:       <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.
belaran@999: 	  Instead, ask for help.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_51a">Build and install the patched version of
belaran@999: 	  Mercurial.</para>
belaran@999: 	<programlisting format="linespecific">python setup.py build --force
belaran@999: sudo python setup.py install --skip-build</programlisting>
belaran@999:       </listitem>
belaran@999:     </orderedlist>
belaran@999:     <para id="x_51b">Once you've build a suitably patched version of Mercurial,
belaran@999:       all you need to do to enable the <literal role="hg-ext" moreinfo="none">inotify</literal> extension is add an entry to
belaran@999:       your <filename role="special" moreinfo="none">~/.hgrc</filename>.</para>
belaran@999:     <programlisting format="linespecific">[extensions] inotify =</programlisting>
belaran@999:     <para id="x_51c">When the <literal role="hg-ext" moreinfo="none">inotify</literal> extension
belaran@999:       is enabled, Mercurial will automatically and transparently start
belaran@999:       the status daemon the first time you run a command that needs
belaran@999:       status in a repository.  It runs one status daemon per
belaran@999:       repository.</para>
belaran@999: 
belaran@999:     <para id="x_51d">The status daemon is started silently, and runs in the
belaran@999:       background.  If you look at a list of running processes after
belaran@999:       you've enabled the <literal role="hg-ext" moreinfo="none">inotify</literal>
belaran@999:       extension and run a few commands in different repositories,
belaran@999:       you'll thus see a few <literal moreinfo="none">hg</literal> processes sitting
belaran@999:       around, waiting for updates from the kernel and queries from
belaran@999:       Mercurial.</para>
belaran@999: 
belaran@999:     <para id="x_51e">The first time you run a Mercurial command in a repository
belaran@999:       when you have the <literal role="hg-ext" moreinfo="none">inotify</literal>
belaran@999:       extension enabled, it will run with about the same performance
belaran@999:       as a normal Mercurial command.  This is because the status
belaran@999:       daemon needs to perform a normal status scan so that it has a
belaran@999:       baseline against which to apply later updates from the kernel.
belaran@999:       However, <emphasis>every</emphasis> subsequent command that does
belaran@999:       any kind of status check should be noticeably faster on
belaran@999:       repositories of even fairly modest size.  Better yet, the bigger
belaran@999:       your repository is, the greater a performance advantage you'll
belaran@999:       see.  The <literal role="hg-ext" moreinfo="none">inotify</literal> daemon makes
belaran@999:       status operations almost instantaneous on repositories of all
belaran@999:       sizes!</para>
belaran@999: 
belaran@999:     <para id="x_51f">If you like, you can manually start a status daemon using
belaran@999:       the <command role="hg-ext-inotify" moreinfo="none">inserve</command> command.
belaran@999:       This gives you slightly finer control over how the daemon ought
belaran@999:       to run.  This command will of course only be available when the
belaran@999:       <literal role="hg-ext" moreinfo="none">inotify</literal> extension is
belaran@999:       enabled.</para>
belaran@999: 
belaran@999:     <para id="x_520">When you're using the <literal role="hg-ext" moreinfo="none">inotify</literal> extension, you should notice
belaran@999:       <emphasis>no difference at all</emphasis> in Mercurial's
belaran@999:       behavior, with the sole exception of status-related commands
belaran@999:       running a whole lot faster than they used to.  You should
belaran@999:       specifically expect that commands will not print different
belaran@999:       output; neither should they give different results. If either of
belaran@999:       these situations occurs, please report a bug.</para>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1 id="sec:hgext:extdiff">
belaran@999:     <title>Flexible diff support with the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension</title>
belaran@999: 
belaran@999:     <para id="x_521">Mercurial's built-in <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	diff</command> command outputs plaintext unified diffs.</para>
belaran@999: 
belaran@999:     <!-- BEGIN extdiff.diff -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
belaran@999: diff -r 801b35c37d8b myfile
belaran@999: --- a/myfile	Sun Aug 16 14:05:02 2009 +0000
belaran@999: +++ b/myfile	Sun Aug 16 14:05:02 2009 +0000
belaran@999: @@ -1,1 +1,2 @@
belaran@999:  The first line.
belaran@999: +The second line.
belaran@999: </screen>
belaran@999: <!-- END extdiff.diff -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_522">If you would like to use an external tool to display
belaran@999:       modifications, you'll want to use the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension.  This will let you
belaran@999:       use, for example, a graphical diff tool.</para>
belaran@999: 
belaran@999:     <para id="x_523">The <literal role="hg-ext" moreinfo="none">extdiff</literal> extension is
belaran@999:       bundled with Mercurial, so it's easy to set up.  In the <literal role="rc-extensions" moreinfo="none">extensions</literal> section of your
belaran@999:       <filename role="special" moreinfo="none">~/.hgrc</filename>, simply add a
belaran@999:       one-line entry to enable the extension.</para>
belaran@999:     <programlisting format="linespecific">[extensions]
belaran@999: extdiff =</programlisting>
belaran@999:     <para id="x_524">This introduces a command named <command role="hg-ext-extdiff" moreinfo="none">extdiff</command>, which by default uses
belaran@999:       your system's <command moreinfo="none">diff</command> command to generate a
belaran@999:       unified diff in the same form as the built-in <command role="hg-cmd" moreinfo="none">hg diff</command> command.</para>
belaran@999:     
belaran@999:     <!-- BEGIN extdiff.extdiff -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg extdiff</userinput>
belaran@999: --- a.801b35c37d8b/myfile	2009-08-16 14:05:02.000000000 +0000
belaran@999: +++ /tmp/extdiffl1y_s9/a/myfile	2009-08-16 14:05:02.000000000 +0000
belaran@999: @@ -1 +1,2 @@
belaran@999:  The first line.
belaran@999: +The second line.
belaran@999: </screen>
belaran@999: <!-- END extdiff.extdiff -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_525">The result won't be exactly the same as with the built-in
belaran@999:       <command role="hg-cmd" moreinfo="none">hg diff</command> variations, because the
belaran@999:       output of <command moreinfo="none">diff</command> varies from one system to
belaran@999:       another, even when passed the same options.</para>
belaran@999: 
belaran@999:     <para id="x_526">As the <quote><literal moreinfo="none">making snapshot</literal></quote>
belaran@999:       lines of output above imply, the <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> command works by
belaran@999:       creating two snapshots of your source tree.  The first snapshot
belaran@999:       is of the source revision; the second, of the target revision or
belaran@999:       working directory.  The <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> command generates
belaran@999:       these snapshots in a temporary directory, passes the name of
belaran@999:       each directory to an external diff viewer, then deletes the
belaran@999:       temporary directory.  For efficiency, it only snapshots the
belaran@999:       directories and files that have changed between the two
belaran@999:       revisions.</para>
belaran@999: 
belaran@999:     <para id="x_527">Snapshot directory names have the same base name as your
belaran@999:       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
belaran@999:       snapshot directory.  Each snapshot directory name has its
belaran@999:       changeset ID appended, if appropriate.  If a snapshot is of
belaran@999:       revision <literal moreinfo="none">a631aca1083f</literal>, the directory will be
belaran@999:       named <filename class="directory" moreinfo="none">foo.a631aca1083f</filename>.
belaran@999:       A snapshot of the working directory won't have a changeset ID
belaran@999:       appended, so it would just be <filename class="directory" moreinfo="none">foo</filename> in this example.  To see what
belaran@999:       this looks like in practice, look again at the <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> example above.  Notice
belaran@999:       that the diff has the snapshot directory names embedded in its
belaran@999:       header.</para>
belaran@999: 
belaran@999:     <para id="x_528">The <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> command
belaran@999:       accepts two important options. The <option role="hg-ext-extdiff-cmd-extdiff-opt">hg -p</option> option
belaran@999:       lets you choose a program to view differences with, instead of
belaran@999:       <command moreinfo="none">diff</command>.  With the <option role="hg-ext-extdiff-cmd-extdiff-opt">hg -o</option> option,
belaran@999:       you can change the options that <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> passes to the program
belaran@999:       (by default, these options are
belaran@999:       <quote><literal moreinfo="none">-Npru</literal></quote>, which only make sense
belaran@999:       if you're running <command moreinfo="none">diff</command>).  In other respects,
belaran@999:       the <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> command
belaran@999:       acts similarly to the built-in <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	diff</command> command: you use the same option names, syntax,
belaran@999:       and arguments to specify the revisions you want, the files you
belaran@999:       want, and so on.</para>
belaran@999: 
belaran@999:     <para id="x_529">As an example, here's how to run the normal system
belaran@999:       <command moreinfo="none">diff</command> command, getting it to generate context
belaran@999:       diffs (using the <option role="cmd-opt-diff">-c</option> option)
belaran@999:       instead of unified diffs, and five lines of context instead of
belaran@999:       the default three (passing <literal moreinfo="none">5</literal> as the argument
belaran@999:       to the <option role="cmd-opt-diff">-C</option> option).</para>
belaran@999: 
belaran@999:       <!-- BEGIN extdiff.extdiff-ctx -->
belaran@999: <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg extdiff -o -NprcC5</userinput>
belaran@999: *** a.801b35c37d8b/myfile	Sun Aug 16 14:05:02 2009
belaran@999: --- /tmp/extdiffl1y_s9/a/myfile	Sun Aug 16 14:05:02 2009
belaran@999: ***************
belaran@999: *** 1 ****
belaran@999: --- 1,2 ----
belaran@999:   The first line.
belaran@999: + The second line.
belaran@999: </screen>
belaran@999: <!-- END extdiff.extdiff-ctx -->
belaran@999: 
belaran@999: 
belaran@999:     <para id="x_52a">Launching a visual diff tool is just as easy.  Here's how to
belaran@999:       launch the <command moreinfo="none">kdiff3</command> viewer.</para>
belaran@999:     <programlisting format="linespecific">hg extdiff -p kdiff3 -o</programlisting>
belaran@999: 
belaran@999:     <para id="x_52b">If your diff viewing command can't deal with directories,
belaran@999:       you can easily work around this with a little scripting.  For an
belaran@999:       example of such scripting in action with the <literal role="hg-ext" moreinfo="none">mq</literal> extension and the
belaran@999:       <command moreinfo="none">interdiff</command> command, see <xref linkend="mq-collab:tips:interdiff"/>.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Defining command aliases</title>
belaran@999: 
belaran@999:       <para id="x_52c">It can be cumbersome to remember the options to both the
belaran@999: 	<command role="hg-ext-extdiff" moreinfo="none">extdiff</command> command and
belaran@999: 	the diff viewer you want to use, so the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension lets you define
belaran@999: 	<emphasis>new</emphasis> commands that will invoke your diff
belaran@999: 	viewer with exactly the right options.</para>
belaran@999: 
belaran@999:       <para id="x_52d">All you need to do is edit your <filename role="special" moreinfo="none">~/.hgrc</filename>, and add a section named
belaran@999: 	<literal role="rc-extdiff" moreinfo="none">extdiff</literal>.  Inside this
belaran@999: 	section, you can define multiple commands.  Here's how to add
belaran@999: 	a <literal moreinfo="none">kdiff3</literal> command.  Once you've defined
belaran@999: 	this, you can type <quote><literal moreinfo="none">hg kdiff3</literal></quote>
belaran@999: 	and the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension
belaran@999: 	will run <command moreinfo="none">kdiff3</command> for you.</para>
belaran@999:       <programlisting format="linespecific">[extdiff]
belaran@999: cmd.kdiff3 =</programlisting>
belaran@999:       <para id="x_52e">If you leave the right hand side of the definition empty,
belaran@999: 	as above, the <literal role="hg-ext" moreinfo="none">extdiff</literal>
belaran@999: 	extension uses the name of the command you defined as the name
belaran@999: 	of the external program to run.  But these names don't have to
belaran@999: 	be the same.  Here, we define a command named
belaran@999: 	<quote><literal moreinfo="none">hg wibble</literal></quote>, which runs
belaran@999: 	<command moreinfo="none">kdiff3</command>.</para>
belaran@999:       <programlisting format="linespecific">[extdiff]
belaran@999:  cmd.wibble = kdiff3</programlisting>
belaran@999: 
belaran@999:       <para id="x_52f">You can also specify the default options that you want to
belaran@999: 	invoke your diff viewing program with.  The prefix to use is
belaran@999: 	<quote><literal moreinfo="none">opts.</literal></quote>, followed by the name
belaran@999: 	of the command to which the options apply.  This example
belaran@999: 	defines a <quote><literal moreinfo="none">hg vimdiff</literal></quote> command
belaran@999: 	that runs the <command moreinfo="none">vim</command> editor's
belaran@999: 	<literal moreinfo="none">DirDiff</literal> extension.</para>
belaran@999:       <programlisting format="linespecific">[extdiff]
belaran@999:  cmd.vimdiff = vim
belaran@999: opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'</programlisting>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1 id="sec:hgext:transplant">
belaran@999:     <title>Cherrypicking changes with the <literal role="hg-ext" moreinfo="none">transplant</literal> extension</title>
belaran@999: 
belaran@999:     <para id="x_530">Need to have a long chat with Brendan about this.</para>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1 id="sec:hgext:patchbomb">
belaran@999:     <title>Send changes via email with the <literal role="hg-ext" moreinfo="none">patchbomb</literal> extension</title>
belaran@999: 
belaran@999:     <para id="x_531">Many projects have a culture of <quote>change
belaran@999: 	review</quote>, in which people send their modifications to a
belaran@999:       mailing list for others to read and comment on before they
belaran@999:       commit the final version to a shared repository.  Some projects
belaran@999:       have people who act as gatekeepers; they apply changes from
belaran@999:       other people to a repository to which those others don't have
belaran@999:       access.</para>
belaran@999: 
belaran@999:     <para id="x_532">Mercurial makes it easy to send changes over email for
belaran@999:       review or application, via its <literal role="hg-ext" moreinfo="none">patchbomb</literal> extension.  The extension is
belaran@999:       so named because changes are formatted as patches, and it's usual
belaran@999:       to send one changeset per email message.  Sending a long series
belaran@999:       of changes by email is thus much like <quote>bombing</quote> the
belaran@999:       recipient's inbox, hence <quote>patchbomb</quote>.</para>
belaran@999: 
belaran@999:     <para id="x_533">As usual, the basic configuration of the <literal role="hg-ext" moreinfo="none">patchbomb</literal> extension takes just one or
belaran@999:       two lines in your <filename role="special" moreinfo="none">
belaran@999: 	/.hgrc</filename>.</para>
belaran@999:     <programlisting format="linespecific">[extensions]
belaran@999: patchbomb =</programlisting>
belaran@999:     <para id="x_534">Once you've enabled the extension, you will have a new
belaran@999:       command available, named <command role="hg-ext-patchbomb" moreinfo="none">email</command>.</para>
belaran@999: 
belaran@999:     <para id="x_535">The safest and best way to invoke the <command role="hg-ext-patchbomb" moreinfo="none">email</command> command is to
belaran@999:       <emphasis>always</emphasis> run it first with the <option role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option.
belaran@999:       This will show you what the command <emphasis>would</emphasis>
belaran@999:       send, without actually sending anything.  Once you've had a
belaran@999:       quick glance over the changes and verified that you are sending
belaran@999:       the right ones, you can rerun the same command, with the <option role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option
belaran@999:       removed.</para>
belaran@999: 
belaran@999:     <para id="x_536">The <command role="hg-ext-patchbomb" moreinfo="none">email</command> command
belaran@999:       accepts the same kind of revision syntax as every other
belaran@999:       Mercurial command.  For example, this command will send every
belaran@999:       revision between 7 and <literal moreinfo="none">tip</literal>, inclusive.</para>
belaran@999:     <programlisting format="linespecific">hg email -n 7:tip</programlisting>
belaran@999:     <para id="x_537">You can also specify a <emphasis>repository</emphasis> to
belaran@999:       compare with.  If you provide a repository but no revisions, the
belaran@999:       <command role="hg-ext-patchbomb" moreinfo="none">email</command> command will
belaran@999:       send all revisions in the local repository that are not present
belaran@999:       in the remote repository.  If you additionally specify revisions
belaran@999:       or a branch name (the latter using the <option role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> option),
belaran@999:       this will constrain the revisions sent.</para>
belaran@999: 
belaran@999:     <para id="x_538">It's perfectly safe to run the <command role="hg-ext-patchbomb" moreinfo="none">email</command> command without the
belaran@999:       names of the people you want to send to: if you do this, it will
belaran@999:       just prompt you for those values interactively.  (If you're
belaran@999:       using a Linux or Unix-like system, you should have enhanced
belaran@999:       <literal moreinfo="none">readline</literal>-style editing capabilities when
belaran@999:       entering those headers, too, which is useful.)</para>
belaran@999: 
belaran@999:     <para id="x_539">When you are sending just one revision, the <command role="hg-ext-patchbomb" moreinfo="none">email</command> command will by
belaran@999:       default use the first line of the changeset description as the
belaran@999:       subject of the single email message it sends.</para>
belaran@999: 
belaran@999:     <para id="x_53a">If you send multiple revisions, the <command role="hg-ext-patchbomb" moreinfo="none">email</command> command will usually
belaran@999:       send one message per changeset.  It will preface the series with
belaran@999:       an introductory message, in which you should describe the
belaran@999:       purpose of the series of changes you're sending.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Changing the behavior of patchbombs</title>
belaran@999: 
belaran@999:       <para id="x_53b">Not every project has exactly the same conventions for
belaran@999: 	sending changes in email; the <literal role="hg-ext" moreinfo="none">patchbomb</literal> extension tries to
belaran@999: 	accommodate a number of variations through command line
belaran@999: 	options.</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_53c">You can write a subject for the introductory
belaran@999: 	    message on the command line using the <option role="hg-ext-patchbomb-cmd-email-opt">hg -s</option>
belaran@999: 	    option.  This takes one argument, the text of the subject
belaran@999: 	    to use.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_53d">To change the email address from which the
belaran@999: 	    messages originate, use the <option role="hg-ext-patchbomb-cmd-email-opt">hg -f</option>
belaran@999: 	    option.  This takes one argument, the email address to
belaran@999: 	    use.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_53e">The default behavior is to send unified diffs
belaran@999: 	    (see <xref linkend="sec:mq:patch"/> for a
belaran@999: 	    description of the
belaran@999: 	    format), one per message.  You can send a binary bundle
belaran@999: 	    instead with the <option role="hg-ext-patchbomb-cmd-email-opt">hg -b</option>
belaran@999: 	    option.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_53f">Unified diffs are normally prefaced with a
belaran@999: 	    metadata header.  You can omit this, and send unadorned
belaran@999: 	    diffs, with the <option role="hg-ext-patchbomb-cmd-email-opt">hg
belaran@999: 	      --plain</option> option.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_540">Diffs are normally sent <quote>inline</quote>,
belaran@999: 	    in the same body part as the description of a patch.  This
belaran@999: 	    makes it easiest for the largest number of readers to
belaran@999: 	    quote and respond to parts of a diff, as some mail clients
belaran@999: 	    will only quote the first MIME body part in a message. If
belaran@999: 	    you'd prefer to send the description and the diff in
belaran@999: 	    separate body parts, use the <option role="hg-ext-patchbomb-cmd-email-opt">hg -a</option>
belaran@999: 	    option.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_541">Instead of sending mail messages, you can
belaran@999: 	    write them to an <literal moreinfo="none">mbox</literal>-format mail
belaran@999: 	    folder using the <option role="hg-ext-patchbomb-cmd-email-opt">hg -m</option>
belaran@999: 	    option.  That option takes one argument, the name of the
belaran@999: 	    file to write to.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_542">If you would like to add a
belaran@999: 	    <command moreinfo="none">diffstat</command>-format summary to each patch,
belaran@999: 	    and one to the introductory message, use the <option role="hg-ext-patchbomb-cmd-email-opt">hg -d</option>
belaran@999: 	    option.  The <command moreinfo="none">diffstat</command> command displays
belaran@999: 	    a table containing the name of each file patched, the
belaran@999: 	    number of lines affected, and a histogram showing how much
belaran@999: 	    each file is modified.  This gives readers a qualitative
belaran@999: 	    glance at how complex a patch is.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: </chapter>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "chapter")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN appA -->
belaran@999:   
belaran@999: 
belaran@999: <appendix id="svn">
belaran@999:   <?dbhtml filename="migrating-to-mercurial.html"?>
belaran@999: <title>Migrer vers Mercurial</title>
belaran@999: 
belaran@999:   <para id="x_6e1">Une manière courante de s'essayer à un nouveau
belaran@999:   gestionnaire de révisions est d'expérimenter en migrant un
belaran@999:   projet existant, plutôt que le faire avec un nouveau projet.
belaran@999:   </para>
belaran@999: 
belaran@999:   <para id="x_6e2">Dans cette annexe, nous discuterons comment importer
belaran@999:   l'historique d'un projet dans Mercurial, et à quoi faire attention
belaran@999:   si vous êtes habitués à un autre outil de gestion de révisions.
belaran@999:    </para>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Importer l'historique depuis un autre système</title>
belaran@999: 
belaran@999:     <para id="x_6e3">Mercurial est livré avec une extension nommée
belaran@999:       <literal moreinfo="none">convert</literal>, qui permet d'importer un historique
belaran@999:       depuis les gestionnaire de révisions les plus courants. Au moment de 
belaran@999:       l'écriture de ce livre, il pouvait importer l'historique depuis:
belaran@999:       </para>
belaran@999:     <itemizedlist>
belaran@999:       <listitem>
belaran@999: 	<para id="x_6e4">Subversion</para>
belaran@999:       </listitem>
belaran@999:       <listitem>
belaran@999: 	<para id="x_6e5">CVS</para>
belaran@999:       </listitem>
belaran@999:       <listitem>
belaran@999: 	<para id="x_6e6">git</para>
belaran@999:       </listitem>
belaran@999:       <listitem>
belaran@999: 	<para id="x_6e7">Darcs</para>
belaran@999:       </listitem>
belaran@999:       <listitem>
belaran@999: 	<para id="x_6e8">Bazaar</para>
belaran@999:       </listitem>
belaran@999:       <listitem>
belaran@999: 	<para id="x_6e9">Monotone</para>
belaran@999:       </listitem>
belaran@999:       <listitem>
belaran@999: 	<para id="x_6ea">GNU Arch</para>
belaran@999:       </listitem>
belaran@999:       <listitem>
belaran@999: 	<para id="x_6eb">Mercurial</para>
belaran@999:       </listitem>
belaran@999:     </itemizedlist>
belaran@999: 
belaran@999:     <para id="x_6ec">(Pour savoir pourquoi Mercurial lui même est supporté
belaran@999:     comme source, voir <xref linkend="svn.filemap"/>.)</para>
belaran@999: 
belaran@999:     <para id="x_6ed">Vous pouvez activer l'extension de la manière
belaran@999:     habituelle, en éditant votre fichier <filename moreinfo="none">~/.hgrc</filename></para>
belaran@999: 
belaran@999:     <programlisting format="linespecific">[extensions]
belaran@999: convert =</programlisting>
belaran@999: 
belaran@999:     <para id="x_6ee">Ceci rendra la commande <command moreinfo="none">hg convert</command>
belaran@999:     disponible. La commande est facile à utiliser. Par exemple, la 
belaran@999:     commande suivante va importer l'historique Subversion du <emphasis remap="it">framework</emphasis> de test <quote>Nose Unit</quote> dans Mercurial.
belaran@999:       </para>
belaran@999: 
belaran@999:     <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen>
belaran@999: 
belaran@999:     <para id="x_6ef">L'extension <literal moreinfo="none">convert</literal> opère de 
belaran@999:     manière incrémentale. En d'autres mots, après une première exécution de
belaran@999:     la commande <command moreinfo="none">hg convert</command>, les exécutions ultérieures
belaran@999:     importeront les révisions ultérieures à l'exécution précédente.
belaran@999:     La conversion incrémentale ne réussira que si
belaran@999:     vous exécutez <command moreinfo="none">hg convert</command> dans le même dépôt que vous
belaran@999:     aviez utilisé à l'origine, ceci parce que l'extension <literal moreinfo="none">convert</literal> 
belaran@999:     sauvegarde un certain nombre de méta-données privées dans le fichier
belaran@999:     <filename moreinfo="none">.hg/shamap</filename> (non versioné) au sein du dépôt cible.
belaran@999:     </para>
belaran@999: 
belaran@999:     <para id="x_707">Lorsque vous voulez faire des modifications en utilisant
belaran@999:     Mercurial, le mieux est de faire un clone de l'ensemble de l'arborescence 
belaran@999:     que vous souhaitez convertir, et de laisser l'arborescence d'origine pour
belaran@999:     de futures conversions incrémentales. C'est la manière la plus sûre pour vous laisser
belaran@999:     récupérer et fusionner les modifications futures depuis l'outil de gestion
belaran@999:     de révisions dans votre nouveau dépôt Mercurial.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Convertir plusieurs branches</title>
belaran@999: 
belaran@999:       <para id="x_708">La commande <command moreinfo="none">hg convert</command> citée 
belaran@999:       ci-dessus convertit seulement l'historique de la <literal moreinfo="none">branche
belaran@999:       principale (trunk)</literal> du dépôt Subversion. Si nous utilisons
belaran@999:       à la place l'URL <literal moreinfo="none">http://python-nose.googlecode.com/svn</literal>,
belaran@999:       Mercurial va automatiquement détecter la  
belaran@999:       <literal moreinfo="none">branche principale (trunk)</literal>, les <literal moreinfo="none">étiquettes 
belaran@999:       (tags)</literal>, et les <literal moreinfo="none">branches</literal>  que les dépôts
belaran@999:       Subversion utilisent généralement, et les importera chacun dans
belaran@999:       une branche Mercurial distincte.</para>
belaran@999: 
belaran@999:       <para id="x_709">Par défaut, chaque branche Subversion importée 
belaran@999:      dans Mercurial se voit attribuer un nom de branche. Une fois la
belaran@999:      conversion achevée, vous pouvez obtenir la liste des noms des branches 
belaran@999:      actives dans le dépôt Mercurial en utilisant la commande
belaran@999:      <command moreinfo="none">hg branches -a</command>. Si vous préférez importer les 
belaran@999:      branches Subversion sans noms, ajoutez l'option <option>--config
belaran@999:      convert.hg.usebranches=false</option> à la commande 
belaran@999:      <command moreinfo="none">hg convert</command>.</para>
belaran@999: 
belaran@999:       <para id="x_70a">Une fois votre arborescence convertie, 
belaran@999:       si vous souhaitez travailler selon la pratique habituelle sous Mercurial
belaran@999:       avec une arborescence qui ne contient qu'une seule branche, vous pouvez cloner
belaran@999:       cette seule branche en utilisant 
belaran@999:       <command moreinfo="none">hg clone -r nomdemabranche</command>.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Associer les noms d'utilisateurs</title>
belaran@999: 
belaran@999:       <para id="x_6f0">Certains outils de gestion de révisions
belaran@999:       ne sauvegardent, avec les modifications, que les noms 
belaran@999:       d'utilisateurs raccourcis. Ceux-ci peuvent être difficiles à 
belaran@999:       interpréter. La norme avec Mercurial est de sauvegarder le 
belaran@999:       nom du <emphasis remap="it">committeur</emphasis> et son adresse
belaran@999:       mail, ce qui est beaucoup plus utile pour discuter avec lui
belaran@999:       par la suite.</para>
belaran@999: 
belaran@999:       <para id="x_6f1">Si vous convertissez une arborescence depuis
belaran@999:       un gestionnaire de révisions qui utilise seulement les noms
belaran@999:       raccourcis, vous pouvez associer ces noms à des équivalents 
belaran@999:       plus détaillés en passant l'option <option>--authors</option>
belaran@999:       à la commande <command moreinfo="none">hg convert</command>. Cette option
belaran@999:       attend un fichier qui contient des entrées sous la forme suivante:
belaran@999:       </para>
belaran@999: 
belaran@999:       <programlisting format="linespecific">arist = Aristotle &lt;aristotle@phil.example.gr&gt;
belaran@999: soc = Socrates &lt;socrates@phil.example.gr&gt;</programlisting>
belaran@999: 
belaran@999:       <para id="x_6f2">Quand <literal moreinfo="none">convert</literal> trouve une
belaran@999:       modification associée au nom <literal moreinfo="none">arist</literal> dans le
belaran@999:       dépôt de source, il va utiliser le nom <literal moreinfo="none">Aristotle
belaran@999:       &lt;aristotle@phil.example.gr&gt;</literal> dans les révisions
belaran@999:       Mercurial. Si aucune correspondance n'est trouvé, il utilise
belaran@999:       le nom tel quel.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2 id="svn.filemap">
belaran@999:       <title>Nettoyer l'arboresence</title>
belaran@999: 
belaran@999:       <para id="x_6f3">Tous les projets n'ont pas un historique parfait.
belaran@999:       Il peut y avoir des répertoires qui n'auraient jamais dû être ajoutés,
belaran@999:       un fichier qui est trop volumineux, ou même une partie de la
belaran@999:       hiérarchie qui devrait être réorganisée.</para>
belaran@999: 
belaran@999:       <para id="x_6f4">L'extension <literal moreinfo="none">convert</literal> permet
belaran@999:       d'utiliser un <quote>fichier d'association</quote> qui peut 
belaran@999:       réorganiser les fichiers et les répertoires dans un projet lors de
belaran@999:       l'importation de son historique. Ceci est utile non seulement quand vous
belaran@999:       importez l'historique d'un autre gestionnaire de révisions, mais
belaran@999:       aussi pour nettoyer ou réorganiser l'arborescence d'un projet
belaran@999:       Mercurial.</para>
belaran@999: 
belaran@999:       <para id="x_6f5">Pour indiquer le fichier d'association, on utilise
belaran@999:       l'option <option>--filemap</option> en lui fournissant un nom de
belaran@999:       fichier. Le fichier d'association contient des lignes de la forme
belaran@999:       suivante :</para>
belaran@999: 
belaran@999:       <programlisting format="linespecific"># Ceci est un commentaire.
belaran@999: # Les lignes vides sont ignorées.
belaran@999: 
belaran@999: include path/to/file
belaran@999: 
belaran@999: exclude path/to/file
belaran@999: 
belaran@999: rename from/some/path to/some/other/place
belaran@999: </programlisting>
belaran@999:       
belaran@999:       <para id="x_6f6">La directive <literal moreinfo="none">include</literal> inclut un
belaran@999:       fichier, ou l'ensemble des fichiers d'un répertoire, dans le dépôt
belaran@999:       de destination. La directive <literal moreinfo="none">exclude</literal> omet les
belaran@999:       fichiers ou répertoires du dépôt. Ceci inclut aussi les autres
belaran@999:       fichiers et répertoires qui ne sont pas explicitement inclus.
belaran@999:       La directive <literal moreinfo="none">exclude</literal> entraine l'omission
belaran@999:       des fichiers ou répertoires, et autres fichiers qui ne sont pas
belaran@999:       explicitement inclus.</para>
belaran@999: 
belaran@999:       <para id="x_6f7">Pour déplacer un fichier ou un répertoire d'un
belaran@999:       emplacement à un autre, utilisez la directive
belaran@999:       <literal moreinfo="none">rename</literal>. Si vous avez besoin de déplacer un 
belaran@999:       fichier ou un répertoire depuis un sous répertoire dans la racine
belaran@999:       du dépôt, utilisez <literal moreinfo="none">.</literal> comme second argument de 
belaran@999:       la directive <literal moreinfo="none">rename</literal>.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Améliorer les performances de la conversion Subversion</title>
belaran@999: 
belaran@999:       <para id="x_70b">Vous aurez souvent besoin de plusieurs essais
belaran@999:       avant d'arriver à la parfaite combinaison de fichier d'association de fichiers,
belaran@999:       de fichier d'association de noms d'utilisateurs et des autres paramètres. Or,
belaran@999:       convertir un dépôt Mercurial via un protocole comme <literal moreinfo="none">ssh</literal>
belaran@999:       ou <literal moreinfo="none">http</literal> peut être des milliers de fois plus long
belaran@999:       que ce dont le système d'exploitation est en fait capable de faire,
belaran@999:       à cause des latence réseau. Ceci peut rendre la conception de cette
belaran@999:       combinaison parfaite très douloureuse.</para>
belaran@999: 
belaran@999:       <para id="x_70c">La commande <ulink url="http://svn.collab.net/repos/svn/trunk/notes/svnsync.txt"><command moreinfo="none">svnsync</command></ulink> 
belaran@999: 	peut grandement améliorer la vitesse de conversion d'un dépôt
belaran@999:         Subversion. Il s'agit d'un programme de miroir de dépôt Subversion
belaran@999:         en lecture seule. L'idée est de créer un miroir local d'une
belaran@999:         arborescence Subversion, puis de convertir ce miroir en dépôt
belaran@999:         Mercurial.</para>
belaran@999:       
belaran@999:       <para id="x_70d">Supposez que nous voulions convertir le dépôt 
belaran@999:       Subversion du populaire projet Memcached en une arborescence Mercurial.
belaran@999:       Tout d'abord, nous créons un dépôt Subversion local.</para>
belaran@999: 
belaran@999:       <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">svnadmin create memcached-mirror</userinput></screen>
belaran@999: 
belaran@999:       <para id="x_70e">Puis, nous allons mettre en place un <quote>hook</quote> Subversion
belaran@999:       dont <command moreinfo="none">svnsync</command> a besoin.</para>
belaran@999: 
belaran@999:       <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo '#!/bin/sh' &gt; memcached-mirror/hooks/pre-revprop-change</userinput>
belaran@999: <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">chmod +x memcached-mirror/hooks/pre-revprop-change</userinput></screen>
belaran@999: 
belaran@999:       <para id="x_70f">Nous initialisons ensuite <command moreinfo="none">svnsync</command> dans ce
belaran@999:       dépôt.</para>
belaran@999: 
belaran@999:       <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">svnsync --init file://`pwd`/memcached-mirror \
belaran@999:   http://code.sixapart.com/svn/memcached</userinput></screen>
belaran@999: 
belaran@999:       <para id="x_710">La prochaine étape est de commencer le processus de
belaran@999:       mirroring de <command moreinfo="none">svnsync</command>.</para>
belaran@999: 
belaran@999:       <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">svnsync sync file://`pwd`/memcached-mirror</userinput></screen>
belaran@999: 
belaran@999:       <para id="x_711">Enfin, nous importons l'historique de notre dépôt
belaran@999:       local Subversion dans Mercurial.</para>
belaran@999: 
belaran@999:       <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg convert memcached-mirror</userinput></screen>
belaran@999:       
belaran@999:       <para id="x_712">Nous pouvons utiliser ce processus de manière
belaran@999:       incrémentale, si le dépôt Subversion est toujours en activité.
belaran@999:       Il suffit d'exécuter de nouveau <command moreinfo="none">svnsync</command> pour
belaran@999:       récupérer les récentes modifications dans notre miroir, puis <command moreinfo="none">hg 
belaran@999:       convert</command>
belaran@999:       les importe dans notre arborescence Mercurial.</para>
belaran@999: 
belaran@999:       <para id="x_713">Il y a deux avantages à utiliser un import à deux
belaran@999:       étages comme avec <command moreinfo="none">svnsync</command>. Le premier
belaran@999:       est qu'il utilise du code de synchronisation réseau de Subversion 
belaran@999:       plus efficace que la commande <command moreinfo="none">hg convert</command>,
belaran@999:       et donc transfère moins de données par le réseau. Le deuxième
belaran@999:       est que l'import depuis un dépôt Subversion local est si rapide que
belaran@999:       vous pouvez peaufiner et réitérer les paramètres de conversion de 
belaran@999:       ce dernier sans souffrir de la qualité de la connexion réseau.</para>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Migrer depuis Subversion</title>
belaran@999: 
belaran@999:     <para id="x_6f8">Subversion est le système de gestion de versions
belaran@999:     open source le plus populaire aujourd'hui. Bien qu'il y ait des
belaran@999:     différences entre Mercurial et Subversion, faire la transition de
belaran@999:     l'un à l'autre n'est pas très difficile. Les deux disposent en effet 
belaran@999:     de jeux de commandes similaires et d'interfaces similaires.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Différences philosophiques</title>
belaran@999: 
belaran@999:       <para id="x_6f9">La différence fondamentale entre Subversion et
belaran@999:       Mercurial est bien évidement que Subversion est centralisé, alors 
belaran@999:       que Mercurial est distribué. Puisque que Mercurial enregistre tout
belaran@999:       l'historique d'un projet sur votre disque dur local, il n'a besoin
belaran@999:       d'effectuer des accès au réseau que lorsque vous voulez
belaran@999:       explicitement communiquer avec un autre dépôt. Subversion, par contre,
belaran@999:       ne conserve que peu d'informations localement, et le client
belaran@999:       doit donc communiquer avec le serveur central pour la
belaran@999:       plupart des opérations communes.</para>
belaran@999: 
belaran@999:       <para id="x_6fa">Subversion s'en tire plus ou moins bien sans notion
belaran@999:       de branche réellement bien définie : quelle portion de l'espace de nommage
belaran@999:       du serveur est une branche est une simple question de convention, le
belaran@999:       logiciel n'imposant rien à ce sujet. Mercurial considère
belaran@999:       un dépôt comme un élément de la gestion des branches.</para>
belaran@999:       
belaran@999:       <sect3>
belaran@999: 	<title>Portée des commandes</title>
belaran@999: 
belaran@999: 	<para id="x_6fb">Puisque que Subversion ne sait pas réellement
belaran@999:         quelle partie de son espace de nommage est en fait une branche, il
belaran@999:         traite la plupart des commandes comme des requêtes à exécuter sur le
belaran@999:         répertoire où vous vous situez, et ses sous répertoires. Par exemple,
belaran@999:         si vous exécutez <command moreinfo="none">svn log</command>, vous verrez l'historique 
belaran@999:         de la partie de l'arborescence où vous vous situez, et non de la
belaran@999:         hiérarchie entière.</para>
belaran@999: 
belaran@999: 	<para id="x_6fc">Les commandes de Mercurial ont un comportement
belaran@999:         différent : toutes les commandes s'appliquent à l'ensemble de l'arborescence
belaran@999:         du dépôt. Exécutez la commande <command moreinfo="none">hg log</command> et elle vous
belaran@999:         donnera l'historique de l'ensemble de l'arborescence, quel que soit le
belaran@999:         sous-répertoire où vous vous situez. Si
belaran@999:         vous souhaitez obtenir l'historique d'un répertoire ou seulement d'un
belaran@999:         fichier, ajouter simplement le nom de celui-ci à la commande, par
belaran@999:         exemple <command moreinfo="none">hg log src</command>.</para>
belaran@999: 
belaran@999: 	<para id="x_6fd">De ma propre expérience, cette différence dans leur
belaran@999:         comportement par défaut est probablement ce qui risque de vous
belaran@999:         surprendre le plus si vous passez régulièrement d'un outil à l'autre.</para>
belaran@999:       </sect3>
belaran@999: 
belaran@999:       <sect3>
belaran@999: 	<title>Opération multi utilisateur et sécurité</title>
belaran@999: 
belaran@999: 	<para id="x_6fe">Avec Subversion, il est normal (bien que légèrement
belaran@999:         désapprouvé) que différentes personnes collaborent sur une seule
belaran@999:         branche. Si Alice et Bob travaillent ensemble, et Alice ajoute ses
belaran@999:         modifications à leur branche partagée, Bob doit alors mettre à jour
belaran@999:         sa vue de la branche avant de pouvoir appliquer un commit.
belaran@999:         Puisqu'il n'a, à ce moment, pas effectué de commit
belaran@999:         des modifications qu'il a faites, il se peut qu'il ne corrompe 
belaran@999:         ou ne perde
belaran@999:         ses modifications pendant ou après la mise à jour.</para>
belaran@999: 
belaran@999: 	<para id="x_6ff">Mercurial encourage, à l'inverse, un modèle 
belaran@999:         "commit-puis-merge". Avant de récupérer des modifications depuis le 
belaran@999:         serveur, ou avant d'y envoyer les siennes, Bob enregistre ses 
belaran@999:         modifications de manière locale en appliquant un commit. C'est à dire
belaran@999:         que si Alice avait envoyé ses modifications sur le serveur avant
belaran@999:         que Bob n'envoie les siennes, ce dernier ne pourra le faire
belaran@999:         qu'après avoir récupéré et fusionné celles d'Alice avec les siennes. 
belaran@999:         Si Bob fait alors une
belaran@999:         erreur lors de la fusion, il pourra toujours restaurer sa version, pour
belaran@999:         laquelle il avait appliqué le commit.</para>
belaran@999:           
belaran@999: 	<para id="x_700">Il est important de souligner qu'il s'agit de la
belaran@999:         manière habituelle de travailler avec ces outils. Subversion propose
belaran@999:         une manière plus sûre de "travailler-dans-votre-propre-branche", mais elle
belaran@999:         est assez complexe pour que, en pratique, elle ne soit que rarement utilisé.
belaran@999:         Mercurial propose de son côté un mode un peu moins sûr, permettant de
belaran@999:         récupérer des modifications par dessus des modifications non
belaran@999:         committées, qui reste toutefois très peu répandu.</para> 
belaran@999:       </sect3>
belaran@999: 
belaran@999:       <sect3>
belaran@999: 	<title>Publication vs changement locaux</title>
belaran@999: 
belaran@999: 	<para id="x_701">Une commande Subversion <command moreinfo="none">svn
belaran@999:         commit</command> publie immédiatement les modifications sur le
belaran@999:         serveur, où elles peuvent être vu par n'importe qui doté d'un privilège
belaran@999:         de lecture.</para>
belaran@999: 
belaran@999: 	<para id="x_702">Avec Mercurial, les modifications sont toujours d'abord
belaran@999:         enregistrées localement, et doivent être par la suite transférés par
belaran@999:         la commande <command moreinfo="none">hg push</command>.</para>
belaran@999: 
belaran@999: 	<para id="x_703">Chaque approche a ses avantages et ses inconvénients.
belaran@999:         Le modèle Subversion implique que les modifications soient publiées, et
belaran@999:         donc disponibles immédiatement. D'un autre coté, cela implique aussi
belaran@999:         que, pour pouvoir utiliser le logiciel normalement, un utilisateur doit 
belaran@999:         avoir les droits d'écriture dans le dépôt, et ce privilège n'est pas concédé 
belaran@999:         facilement par la plupart des projets Open Source.</para>
belaran@999: 
belaran@999: 	<para id="x_704">L'approche de Mercurial permet à quiconque de faire
belaran@999:         un clone du dépôt et d'y ajouter ses modifications sans jamais avoir
belaran@999:         besoin de la permission de quiconque, et l'on peut même publier ses
belaran@999:         modifications et continuer à participer comme on le désire. Toutefois, la
belaran@999:         distinction entre les commits et le transfert de ces derniers présente
belaran@999:         le risque que quelqu'un applique ses modifications par un commit local
belaran@999:         sur son portable et parte se promener pendant quelques jours en ayant
belaran@999:         oublié de les transférer, ce qui peut, dans certains rares cas,
belaran@999:         bloquer temporairement ses collaborateurs.</para>
belaran@999:       </sect3>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>Références des commandes</title>
belaran@999: 
belaran@999:       <table>
belaran@999: 	<title>Commandes Subversion et leurs équivalents Mercurial</title>
belaran@999: 	<tgroup cols="3">
belaran@999: 	  <thead>
belaran@999: 	    <row>
belaran@999: 	      <entry>Subversion</entry>
belaran@999: 	      <entry>Mercurial</entry>
belaran@999: 	      <entry>Notes</entry>
belaran@999: 	    </row>
belaran@999: 	  </thead>
belaran@999: 	  <tbody>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn add</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg add</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn blame</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg annotate</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn cat</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg cat</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn checkout</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg clone</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn cleanup</command></entry>
belaran@999: 	      <entry>n/a</entry>
belaran@999: 	      <entry>Aucun nettoyage nécessaire.</entry>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn commit</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg commit</command>; <command moreinfo="none">hg
belaran@999: 		  push</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg push</command> publie les modifications
belaran@999:               après un commit.</entry>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn copy</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg clone</command></entry>
belaran@999: 	      <entry>Pour créer une nouvelle branche</entry>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn copy</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg copy</command></entry>
belaran@999: 	      <entry>Pour copier des fichiers ou des répertoires</entry>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn delete</command> (<command moreinfo="none">svn
belaran@999: 		  remove</command>)</entry>
belaran@999: 	      <entry><command moreinfo="none">hg remove</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn diff</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg diff</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn export</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg archive</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn help</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg help</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn import</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg addremove</command>; <command moreinfo="none">hg
belaran@999: 		  commit</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn info</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg parents</command></entry>
belaran@999: 	      <entry>Affiche la version sur la base de laquelle on travaille</entry>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn info</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg showconfig
belaran@999: 		  paths.default</command></entry>
belaran@999: 	      <entry>Affiche de quelle URL est extrait ce dépôt</entry>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn list</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg manifest</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn log</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg log</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn merge</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg merge</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn mkdir</command></entry>
belaran@999: 	      <entry>n/a</entry>
belaran@999: 	      <entry>Mercurial ne versionne pas les répertoires</entry>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn move</command> (<command moreinfo="none">svn
belaran@999: 		  rename</command>)</entry>
belaran@999: 	      <entry><command moreinfo="none">hg rename</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn resolved</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg resolve -m</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn revert</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg revert</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn status</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg status</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	    <row>
belaran@999: 	      <entry><command moreinfo="none">svn update</command></entry>
belaran@999: 	      <entry><command moreinfo="none">hg pull -u</command></entry>
belaran@999: 	      <entry/>
belaran@999: 	    </row>
belaran@999: 	  </tbody>
belaran@999: 	</tgroup>
belaran@999:       </table>
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Conseils utiles pour les débutants</title>
belaran@999: 
belaran@999:     <para id="x_705">Avec la plupart des gestionnaire de versions, afficher
belaran@999:     un diff associé à une révision peut être assez douloureux. Par exemple,
belaran@999:     avec Subversion, pour voir ce qui a été modifiée dans la révision 104654,
belaran@999:     vous devez saisir <command moreinfo="none">svn diff -r104653:104654</command>. Mercurial
belaran@999:     élimine le besoin de saisir l'identifiant d'une révision deux fois dans
belaran@999:     ce cas classique. Pour un simple diff, <command moreinfo="none">hg
belaran@999:     export 104654</command> suffit. Pour obtenir une entrée du journal suivie d'un diff,
belaran@999:     <command moreinfo="none">hg log -r104654 -p</command>.</para>
belaran@999: 
belaran@999:     <para id="x_706">Quand vous exécutez la commande <command moreinfo="none">hg status</command>
belaran@999:     sans aucun argument, elle affiche l'état de l'ensemble de l'arborescence,
belaran@999:     avec des chemins relatifs partant de la racine du dépôt. Ceci rend
belaran@999:     difficile de copier un nom de fichier depuis la sortie de la commande
belaran@999:     <command moreinfo="none">hg status</command> dans une autre ligne de commande. Si vous
belaran@999:     fournissez un fichier ou un répertoire à la commande <command moreinfo="none">hg
belaran@999:     status</command>, elle va afficher les chemins relatif depuis votre
belaran@999:     répertoire courant à la place. Ainsi, pour avoir un état sur l'ensemble
belaran@999:     de l'arborescence à l'aide  de <command moreinfo="none">hg status</command>, avec des
belaran@999:     chemins relatifs à votre répertoire courant, et non la racine du dépôt,
belaran@999:     ajoutez la sortie de <command moreinfo="none">hg root</command> à la commande
belaran@999:     <command moreinfo="none">hg status</command>. Vous pouvez le faire aisément sur un
belaran@999:     système Unix ainsi :</para>
belaran@999: 
belaran@999:     <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status `hg root`</userinput></screen>
belaran@999:   </sect1>
belaran@999: </appendix>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "appendix")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN appB -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <appendix id="chap:mqref">
belaran@999:   <?dbhtml filename="mercurial-queues-reference.html"?>
belaran@999:   <title>Mercurial Queues reference</title>
belaran@999: 
belaran@999:   <sect1 id="sec:mqref:cmdref">
belaran@999:     <title>MQ command reference</title>
belaran@999: 
belaran@999:     <para id="x_5e8">For an overview of the commands provided by MQ, use the
belaran@999:       command <command role="hg-cmd" moreinfo="none">hg help mq</command>.</para>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qapplied</command>—print
belaran@999: 	applied patches</title>
belaran@999: 
belaran@999:       <para id="x_5e9">The <command role="hg-ext-mq" moreinfo="none">qapplied</command> command
belaran@999: 	prints the current stack of applied patches.  Patches are
belaran@999: 	printed in oldest-to-newest order, so the last patch in the
belaran@999: 	list is the <quote>top</quote> patch.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qcommit</command>—commit
belaran@999: 	changes in the queue repository</title>
belaran@999: 
belaran@999:       <para id="x_5ea">The <command role="hg-ext-mq" moreinfo="none">qcommit</command> command
belaran@999: 	commits any outstanding changes in the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename>
belaran@999: 	repository.  This command only works if the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename>
belaran@999: 	directory is a repository, i.e. you created the directory
belaran@999: 	using <command role="hg-cmd" moreinfo="none">hg qinit <option role="hg-ext-mq-cmd-qinit-opt">-c</option></command> or
belaran@999: 	ran <command role="hg-cmd" moreinfo="none">hg init</command> in the directory
belaran@999: 	after running <command role="hg-ext-mq" moreinfo="none">qinit</command>.</para>
belaran@999: 
belaran@999:       <para id="x_5eb">This command is shorthand for <command role="hg-cmd" moreinfo="none">hg
belaran@999: 	  commit --cwd .hg/patches</command>.</para>
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999: 	<title><command role="hg-ext-mq" moreinfo="none">qdelete</command>—delete a patch
belaran@999: 	from the <filename role="special" moreinfo="none">series</filename>
belaran@999: 	file</title>
belaran@999: 
belaran@999:       <para id="x_5ec">The <command role="hg-ext-mq" moreinfo="none">qdelete</command> command
belaran@999: 	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>
belaran@999: 	directory.  It does not pop the patch if the patch is already
belaran@999: 	applied.  By default, it does not delete the patch file; use
belaran@999: 	the <option role="hg-ext-mq-cmd-qdel-opt">-f</option> option
belaran@999: 	to do that.</para>
belaran@999: 
belaran@999:       <para id="x_5ed">Options:</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_5ee"><option role="hg-ext-mq-cmd-qdel-opt">-f</option>: Delete the
belaran@999: 	    patch file.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qdiff</command>—print a
belaran@999: 	diff of the topmost applied patch</title>
belaran@999: 
belaran@999:       <para id="x_5ef">The <command role="hg-ext-mq" moreinfo="none">qdiff</command> command
belaran@999: 	prints a diff of the topmost applied patch. It is equivalent
belaran@999: 	to <command role="hg-cmd" moreinfo="none">hg diff -r-2:-1</command>.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qfold</command>—move
belaran@999: 	applied patches into repository history</title>
belaran@999: 
belaran@999:       <para id="x_72d">The <command moreinfo="none">hg qfinish</command> command converts the
belaran@999: 	specified applied patches into permanent changes by moving
belaran@999: 	them out of MQ's control so that they will be treated as
belaran@999: 	normal repository history.</para>
belaran@999:     </sect2>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qfold</command>—merge
belaran@999: 	(<quote>fold</quote>) several patches into one</title>
belaran@999: 
belaran@999:       <para id="x_5f0">The <command role="hg-ext-mq" moreinfo="none">qfold</command> command
belaran@999: 	merges multiple patches into the topmost applied patch, so
belaran@999: 	that the topmost applied patch makes the union of all of the
belaran@999: 	changes in the patches in question.</para>
belaran@999: 
belaran@999:       <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
belaran@999: 	any is.  The order in which patches are folded is significant;
belaran@999: 	<command role="hg-cmd" moreinfo="none">hg qfold a b</command> means
belaran@999: 	<quote>apply the current topmost patch, followed by
belaran@999: 	  <literal moreinfo="none">a</literal>, followed by
belaran@999: 	  <literal moreinfo="none">b</literal></quote>.</para>
belaran@999: 
belaran@999:       <para id="x_5f2">The comments from the folded patches are appended to the
belaran@999: 	comments of the destination patch, with each block of comments
belaran@999: 	separated by three asterisk
belaran@999: 	(<quote><literal moreinfo="none">*</literal></quote>) characters.  Use the
belaran@999: 	<option role="hg-ext-mq-cmd-qfold-opt">-e</option> option to
belaran@999: 	edit the commit message for the combined patch/changeset after
belaran@999: 	the folding has completed.</para>
belaran@999: 
belaran@999:       <para id="x_5f3">Options:</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_5f4"><option role="hg-ext-mq-cmd-qfold-opt">-e</option>: Edit the
belaran@999: 	    commit message and patch description for the newly folded
belaran@999: 	    patch.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5f5"><option role="hg-ext-mq-cmd-qfold-opt">-l</option>: Use the
belaran@999: 	    contents of the given file as the new commit message and
belaran@999: 	    patch description for the folded patch.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_5f6"><option role="hg-ext-mq-cmd-qfold-opt">-m</option>: Use the
belaran@999: 	    given text as the new commit message and patch description
belaran@999: 	    for the folded patch.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qheader</command>—display the
belaran@999: 	header/description of a patch</title>
belaran@999: 
belaran@999:       <para id="x_5f7">The <command role="hg-ext-mq" moreinfo="none">qheader</command> command
belaran@999: 	prints the header, or description, of a patch.  By default, it
belaran@999: 	prints the header of the topmost applied patch. Given an
belaran@999: 	argument, it prints the header of the named patch.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qimport</command>—import
belaran@999: 	a third-party patch into the queue</title>
belaran@999: 
belaran@999:       <para id="x_5f8">The <command role="hg-ext-mq" moreinfo="none">qimport</command> command
belaran@999: 	adds an entry for an external patch to the <filename role="special" moreinfo="none">series</filename> file, and copies the patch
belaran@999: 	into the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory.  It adds
belaran@999: 	the entry immediately after the topmost applied patch, but
belaran@999: 	does not push the patch.</para>
belaran@999: 
belaran@999:       <para id="x_5f9">If the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory is a
belaran@999: 	repository, <command role="hg-ext-mq" moreinfo="none">qimport</command>
belaran@999: 	automatically does an <command role="hg-cmd" moreinfo="none">hg add</command>
belaran@999: 	of the imported patch.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qinit</command>—prepare
belaran@999: 	a repository to work with MQ</title>
belaran@999: 
belaran@999:       <para id="x_5fa">The <command role="hg-ext-mq" moreinfo="none">qinit</command> command
belaran@999: 	prepares a repository to work with MQ.  It creates a directory
belaran@999: 	called <filename role="special" class="directory" moreinfo="none">.hg/patches</filename>.</para>
belaran@999: 
belaran@999:       <para id="x_5fb">Options:</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_5fc"><option role="hg-ext-mq-cmd-qinit-opt">-c</option>: Create
belaran@999: 	    <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> as a repository
belaran@999: 	    in its own right.  Also creates a <filename role="special" moreinfo="none">.hgignore</filename> file that will
belaran@999: 	    ignore the <filename role="special" moreinfo="none">status</filename>
belaran@999: 	    file.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_5fd">When the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory is a
belaran@999: 	repository, the <command role="hg-ext-mq" moreinfo="none">qimport</command>
belaran@999: 	and <command role="hg-ext-mq" moreinfo="none">qnew</command> commands
belaran@999: 	automatically <command role="hg-cmd" moreinfo="none">hg add</command> new
belaran@999: 	patches.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qnew</command>—create a
belaran@999: 	new patch</title>
belaran@999: 
belaran@999:       <para id="x_5fe">The <command role="hg-ext-mq" moreinfo="none">qnew</command> command
belaran@999: 	creates a new patch.  It takes one mandatory argument, the
belaran@999: 	name to use for the patch file.  The newly created patch is
belaran@999: 	created empty by default.  It is added to the <filename role="special" moreinfo="none">series</filename> file after the current
belaran@999: 	topmost applied patch, and is immediately pushed on top of
belaran@999: 	that patch.</para>
belaran@999: 
belaran@999:       <para id="x_5ff">If <command role="hg-ext-mq" moreinfo="none">qnew</command> finds modified
belaran@999: 	files in the working directory, it will refuse to create a new
belaran@999: 	patch unless the <option role="hg-ext-mq-cmd-qnew-opt">-f</option> option is used
belaran@999: 	(see below).  This behavior allows you to <command role="hg-ext-mq" moreinfo="none">qrefresh</command> your topmost applied
belaran@999: 	patch before you apply a new patch on top of it.</para>
belaran@999: 
belaran@999:       <para id="x_600">Options:</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_601"><option role="hg-ext-mq-cmd-qnew-opt">-f</option>: Create a new
belaran@999: 	    patch if the contents of the working directory are
belaran@999: 	    modified.  Any outstanding modifications are added to the
belaran@999: 	    newly created patch, so after this command completes, the
belaran@999: 	    working directory will no longer be modified.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_602"><option role="hg-ext-mq-cmd-qnew-opt">-m</option>: Use the given
belaran@999: 	    text as the commit message. This text will be stored at
belaran@999: 	    the beginning of the patch file, before the patch
belaran@999: 	    data.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qnext</command>—print
belaran@999: 	the name of the next patch</title>
belaran@999: 
belaran@999:       <para id="x_603">The <command role="hg-ext-mq" moreinfo="none">qnext</command> command
belaran@999: 	prints the name name of the next patch in the <filename role="special" moreinfo="none">series</filename> file after the topmost
belaran@999: 	applied patch.  This patch will become the topmost applied
belaran@999: 	patch if you run <command role="hg-ext-mq" moreinfo="none">qpush</command>.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qpop</command>—pop
belaran@999: 	patches off the stack</title>
belaran@999: 
belaran@999:       <para id="x_604">The <command role="hg-ext-mq" moreinfo="none">qpop</command> command
belaran@999: 	removes applied patches from the top of the stack of applied
belaran@999: 	patches.  By default, it removes only one patch.</para>
belaran@999: 
belaran@999:       <para id="x_605">This command removes the changesets that represent the
belaran@999: 	popped patches from the repository, and updates the working
belaran@999: 	directory to undo the effects of the patches.</para>
belaran@999: 
belaran@999:       <para id="x_606">This command takes an optional argument, which it uses as
belaran@999: 	the name or index of the patch to pop to.  If given a name, it
belaran@999: 	will pop patches until the named patch is the topmost applied
belaran@999: 	patch.  If given a number, <command role="hg-ext-mq" moreinfo="none">qpop</command> treats the number as an
belaran@999: 	index into the entries in the series file, counting from zero
belaran@999: 	(empty lines and lines containing only comments do not count).
belaran@999: 	It pops patches until the patch identified by the given index
belaran@999: 	is the topmost applied patch.</para>
belaran@999: 
belaran@999:       <para id="x_607">The <command role="hg-ext-mq" moreinfo="none">qpop</command> command does
belaran@999: 	not read or write patches or the <filename role="special" moreinfo="none">series</filename> file.  It is thus safe to
belaran@999: 	<command role="hg-ext-mq" moreinfo="none">qpop</command> a patch that you have
belaran@999: 	removed from the <filename role="special" moreinfo="none">series</filename>
belaran@999: 	file, or a patch that you have renamed or deleted entirely.
belaran@999: 	In the latter two cases, use the name of the patch as it was
belaran@999: 	when you applied it.</para>
belaran@999: 
belaran@999:       <para id="x_608">By default, the <command role="hg-ext-mq" moreinfo="none">qpop</command>
belaran@999: 	command will not pop any patches if the working directory has
belaran@999: 	been modified.  You can override this behavior using the
belaran@999: 	<option role="hg-ext-mq-cmd-qpop-opt">-f</option> option,
belaran@999: 	which reverts all modifications in the working
belaran@999: 	directory.</para>
belaran@999: 
belaran@999:       <para id="x_609">Options:</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_60a"><option role="hg-ext-mq-cmd-qpop-opt">-a</option>: Pop all
belaran@999: 	    applied patches.  This returns the repository to its state
belaran@999: 	    before you applied any patches.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_60b"><option role="hg-ext-mq-cmd-qpop-opt">-f</option>: Forcibly
belaran@999: 	    revert any modifications to the working directory when
belaran@999: 	    popping.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_60c"><option role="hg-ext-mq-cmd-qpop-opt">-n</option>: Pop a patch
belaran@999: 	    from the named queue.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_60d">The <command role="hg-ext-mq" moreinfo="none">qpop</command> command
belaran@999: 	removes one line from the end of the <filename role="special" moreinfo="none">status</filename> file for each patch that it
belaran@999: 	pops.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qprev</command>—print
belaran@999: 	the name of the previous patch</title>
belaran@999: 
belaran@999:       <para id="x_60e">The <command role="hg-ext-mq" moreinfo="none">qprev</command> command
belaran@999: 	prints the name of the patch in the <filename role="special" moreinfo="none">series</filename> file that comes before the
belaran@999: 	topmost applied patch. This will become the topmost applied
belaran@999: 	patch if you run <command role="hg-ext-mq" moreinfo="none">qpop</command>.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2 id="sec:mqref:cmd:qpush">
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qpush</command>—push
belaran@999: 	patches onto the stack</title>
belaran@999: 
belaran@999:       <para id="x_60f">The <command role="hg-ext-mq" moreinfo="none">qpush</command> command adds
belaran@999: 	patches onto the applied stack.  By default, it adds only one
belaran@999: 	patch.</para>
belaran@999: 
belaran@999:       <para id="x_610">This command creates a new changeset to represent each
belaran@999: 	applied patch, and updates the working directory to apply the
belaran@999: 	effects of the patches.</para>
belaran@999: 
belaran@999:       <para id="x_611">The default data used when creating a changeset are as
belaran@999: 	follows:</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_612">The commit date and time zone are the current
belaran@999: 	    date and time zone.  Because these data are used to
belaran@999: 	    compute the identity of a changeset, this means that if
belaran@999: 	    you <command role="hg-ext-mq" moreinfo="none">qpop</command> a patch and
belaran@999: 	    <command role="hg-ext-mq" moreinfo="none">qpush</command> it again, the
belaran@999: 	    changeset that you push will have a different identity
belaran@999: 	    than the changeset you popped.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_613">The author is the same as the default used by
belaran@999: 	    the <command role="hg-cmd" moreinfo="none">hg commit</command>
belaran@999: 	    command.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_614">The commit message is any text from the patch
belaran@999: 	    file that comes before the first diff header.  If there is
belaran@999: 	    no such text, a default commit message is used that
belaran@999: 	    identifies the name of the patch.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999:       <para id="x_615">If a patch contains a Mercurial patch header,
belaran@999: 	the information in the patch header overrides these
belaran@999: 	defaults.</para>
belaran@999: 
belaran@999:       <para id="x_616">Options:</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_617"><option role="hg-ext-mq-cmd-qpush-opt">-a</option>: Push all
belaran@999: 	    unapplied patches from the <filename role="special" moreinfo="none">series</filename> file until there are
belaran@999: 	    none left to push.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_618"><option role="hg-ext-mq-cmd-qpush-opt">-l</option>: Add the name
belaran@999: 	    of the patch to the end of the commit message.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_619"><option role="hg-ext-mq-cmd-qpush-opt">-m</option>: If a patch
belaran@999: 	    fails to apply cleanly, use the entry for the patch in
belaran@999: 	    another saved queue to compute the parameters for a
belaran@999: 	    three-way merge, and perform a three-way merge using the
belaran@999: 	    normal Mercurial merge machinery.  Use the resolution of
belaran@999: 	    the merge as the new patch content.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_61a"><option role="hg-ext-mq-cmd-qpush-opt">-n</option>: Use the
belaran@999: 	    named queue if merging while pushing.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_61b">The <command role="hg-ext-mq" moreinfo="none">qpush</command> command
belaran@999: 	reads, but does not modify, the <filename role="special" moreinfo="none">series</filename> file.  It appends one line
belaran@999: 	to the <command role="hg-cmd" moreinfo="none">hg status</command> file for
belaran@999: 	each patch that it pushes.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qrefresh</command>—update the
belaran@999: 	topmost applied patch</title>
belaran@999: 
belaran@999:       <para id="x_61c">The <command role="hg-ext-mq" moreinfo="none">qrefresh</command> command
belaran@999: 	updates the topmost applied patch.  It modifies the patch,
belaran@999: 	removes the old changeset that represented the patch, and
belaran@999: 	creates a new changeset to represent the modified
belaran@999: 	patch.</para>
belaran@999: 
belaran@999:       <para id="x_61d">The <command role="hg-ext-mq" moreinfo="none">qrefresh</command> command
belaran@999: 	looks for the following modifications:</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_61e">Changes to the commit message, i.e. the text
belaran@999: 	    before the first diff header in the patch file, are
belaran@999: 	    reflected in the new changeset that represents the
belaran@999: 	    patch.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_61f">Modifications to tracked files in the working
belaran@999: 	    directory are added to the patch.</para>
belaran@999: 	</listitem>
belaran@999: 	<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
belaran@999: 	    and rename destinations are added to the patch, while
belaran@999: 	    removed files and rename sources are removed.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:       <para id="x_621">Even if <command role="hg-ext-mq" moreinfo="none">qrefresh</command>
belaran@999: 	detects no changes, it still recreates the changeset that
belaran@999: 	represents the patch.  This causes the identity of the
belaran@999: 	changeset to differ from the previous changeset that
belaran@999: 	identified the patch.</para>
belaran@999: 
belaran@999:       <para id="x_622">Options:</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_623"><option role="hg-ext-mq-cmd-qrefresh-opt">-e</option>: Modify
belaran@999: 	    the commit and patch description, using the preferred text
belaran@999: 	    editor.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_624"><option role="hg-ext-mq-cmd-qrefresh-opt">-m</option>: Modify
belaran@999: 	    the commit message and patch description, using the given
belaran@999: 	    text.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_625"><option role="hg-ext-mq-cmd-qrefresh-opt">-l</option>: Modify
belaran@999: 	    the commit message and patch description, using text from
belaran@999: 	    the given file.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qrename</command>—rename
belaran@999: 	a patch</title>
belaran@999: 
belaran@999:       <para id="x_626">The <command role="hg-ext-mq" moreinfo="none">qrename</command> command
belaran@999: 	renames a patch, and changes the entry for the patch in the
belaran@999: 	<filename role="special" moreinfo="none">series</filename> file.</para>
belaran@999: 
belaran@999:       <para id="x_627">With a single argument, <command role="hg-ext-mq" moreinfo="none">qrename</command> renames the topmost
belaran@999: 	applied patch.  With two arguments, it renames its first
belaran@999: 	argument to its second.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qseries</command>—print
belaran@999: 	the entire patch series</title>
belaran@999: 
belaran@999:       <para id="x_62a">The <command role="hg-ext-mq" moreinfo="none">qseries</command> command
belaran@999: 	prints the entire patch series from the <filename role="special" moreinfo="none">series</filename> file.  It prints only patch
belaran@999: 	names, not empty lines or comments.  It prints in order from
belaran@999: 	first to be applied to last.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qtop</command>—print the
belaran@999: 	name of the current patch</title>
belaran@999: 
belaran@999:       <para id="x_62b">The <command role="hg-ext-mq" moreinfo="none">qtop</command> prints the
belaran@999: 	name of the topmost currently applied patch.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-ext-mq" moreinfo="none">qunapplied</command>—print patches
belaran@999: 	not yet applied</title>
belaran@999: 
belaran@999:       <para id="x_62c">The <command role="hg-ext-mq" moreinfo="none">qunapplied</command> command
belaran@999: 	prints the names of patches from the <filename role="special" moreinfo="none">series</filename> file that are not yet
belaran@999: 	applied.  It prints them in order from the next patch that
belaran@999: 	will be pushed to the last.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title><command role="hg-cmd" moreinfo="none">hg strip</command>—remove a
belaran@999: 	revision and descendants</title>
belaran@999: 
belaran@999:       <para id="x_62d">The <command role="hg-cmd" moreinfo="none">hg strip</command> command
belaran@999: 	removes a revision, and all of its descendants, from the
belaran@999: 	repository.  It undoes the effects of the removed revisions
belaran@999: 	from the repository, and updates the working directory to the
belaran@999: 	first parent of the removed revision.</para>
belaran@999: 
belaran@999:       <para id="x_62e">The <command role="hg-cmd" moreinfo="none">hg strip</command> command
belaran@999: 	saves a backup of the removed changesets in a bundle, so that
belaran@999: 	they can be reapplied if removed in error.</para>
belaran@999: 
belaran@999:       <para id="x_62f">Options:</para>
belaran@999:       <itemizedlist>
belaran@999: 	<listitem><para id="x_630"><option role="hg-opt-strip">-b</option>: Save
belaran@999: 	    unrelated changesets that are intermixed with the stripped
belaran@999: 	    changesets in the backup bundle.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_631"><option role="hg-opt-strip">-f</option>: If a
belaran@999: 	    branch has multiple heads, remove all heads.</para>
belaran@999: 	</listitem>
belaran@999: 	<listitem><para id="x_632"><option role="hg-opt-strip">-n</option>: Do
belaran@999: 	    not save a backup bundle.</para>
belaran@999: 	</listitem></itemizedlist>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>MQ file reference</title>
belaran@999: 
belaran@999:     <sect2>
belaran@999:       <title>The <filename role="special" moreinfo="none">series</filename>
belaran@999: 	file</title>
belaran@999: 
belaran@999:       <para id="x_633">The <filename role="special" moreinfo="none">series</filename> file
belaran@999: 	contains a list of the names of all patches that MQ can apply.
belaran@999: 	It is represented as a list of names, with one name saved per
belaran@999: 	line.  Leading and trailing white space in each line are
belaran@999: 	ignored.</para>
belaran@999: 
belaran@999:       <para id="x_634">Lines may contain comments.  A comment begins with the
belaran@999: 	<quote><literal moreinfo="none">#</literal></quote> character, and extends to
belaran@999: 	the end of the line.  Empty lines, and lines that contain only
belaran@999: 	comments, are ignored.</para>
belaran@999: 
belaran@999:       <para id="x_635">You will often need to edit the <filename role="special" moreinfo="none">series</filename> file by hand, hence the
belaran@999: 	support for comments and empty lines noted above.  For
belaran@999: 	example, you can comment out a patch temporarily, and <command role="hg-ext-mq" moreinfo="none">qpush</command> will skip over that patch
belaran@999: 	when applying patches.  You can also change the order in which
belaran@999: 	patches are applied by reordering their entries in the
belaran@999: 	<filename role="special" moreinfo="none">series</filename> file.</para>
belaran@999: 
belaran@999:       <para id="x_636">Placing the <filename role="special" moreinfo="none">series</filename>
belaran@999: 	file under revision control is also supported; it is a good
belaran@999: 	idea to place all of the patches that it refers to under
belaran@999: 	revision control, as well.  If you create a patch directory
belaran@999: 	using the <option role="hg-ext-mq-cmd-qinit-opt">-c</option>
belaran@999: 	option to <command role="hg-ext-mq" moreinfo="none">qinit</command>, this will
belaran@999: 	be done for you automatically.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:     <sect2>
belaran@999:       <title>The <filename role="special" moreinfo="none">status</filename>
belaran@999: 	file</title>
belaran@999: 
belaran@999:       <para id="x_637">The <filename role="special" moreinfo="none">status</filename> file
belaran@999: 	contains the names and changeset hashes of all patches that MQ
belaran@999: 	currently has applied.  Unlike the <filename role="special" moreinfo="none">series</filename> file, this file is not
belaran@999: 	intended for editing.  You should not place this file under
belaran@999: 	revision control, or modify it in any way.  It is used by MQ
belaran@999: 	strictly for internal book-keeping.</para>
belaran@999: 
belaran@999:     </sect2>
belaran@999:   </sect1>
belaran@999: </appendix>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "appendix")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN appC -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <appendix id="chap:srcinstall">
belaran@999:   <?dbhtml filename="installing-mercurial-from-source.html"?>
belaran@999:   <title>Installer Mercurial à partir des sources</title>
belaran@999: 
belaran@999:   <sect1 id="sec:srcinstall:unixlike">
belaran@999:     <title>Pour un système Unix ou similaire</title>
belaran@999: 
belaran@999:     <para id="x_5e0">Si vous utilisez un système Unix ou similaire, pour lequel
belaran@999:       une version récente de Python (2.3 ou plus) est disponible, l'installation
belaran@999:       de Mercurial à partir des sources est simple.</para>
belaran@999:     <orderedlist inheritnum="ignore" continuation="restarts">
belaran@999:       <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>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5e2">Extrayez le paquet : </para>
belaran@999: 	<programlisting format="linespecific">gzip -dc mercurial-MYVERSION.tar.gz | tar xf -</programlisting>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_5e3">Allez dans le répertoires où les sources ont
belaran@999:     été extraites et exécutez le script d'installation. Ce dernier compilera
belaran@999:     Mercurial et l'installera dans votre répertoire utilisateur.</para>
belaran@999: 	<programlisting format="linespecific">cd mercurial-MYVERSION
belaran@999: python setup.py install --force --home=$HOME</programlisting>
belaran@999:       </listitem>
belaran@999:     </orderedlist>
belaran@999:     <para id="x_5e4">Lorsque l'installation est terminée, Mercurial se
belaran@999:       trouvera dans le répertoire <literal moreinfo="none">bin</literal> de votre répertoire
belaran@999:       utilisateur.
belaran@999:       N'oubliez pas de vérifier que ce répertoire se trouve dans la liste
belaran@999:       des répertoires où votre shell recherche les exécutables.</para>
belaran@999: 
belaran@999:     <para id="x_5e5">Vous devrez vraisemblablement définir la variable
belaran@999:       d'environnement <envar>PYTHONPATH</envar> de manière à ce que
belaran@999:       l'exécutable de Mercurial puisse trouver le reste des paquets logiciels.
belaran@999:       Par exemple, sur mon ordinateur portable, je dois le définir ainsi:
belaran@999:       <literal moreinfo="none">/home/bos/lib/python</literal>. Le chemin exact à utiliser
belaran@999:       dépendra de la manière dont Python aura été construit pour votre 
belaran@999:       système. Il ne devrait pas être difficile de le trouver. En cas de
belaran@999:       doute, lisez le texte généré lors de l'installation ci-dessus, et
belaran@999:       recherchez l'emplacement où le contenu du répertoire
belaran@999:       <literal moreinfo="none">mercurial</literal> a été installé.</para>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Pour Windows</title>
belaran@999: 
belaran@999:     <para id="x_5e6">Construire et installer Mercurial sous Windows nécessite
belaran@999:       des outils logiciels divers, une certaine connaissance technique et une
belaran@999:       bonne dose de patience. Je vous <emphasis>déconseille fortement</emphasis> 
belaran@999:       de tenter de le faire si vous êtes un <quote>simple utilisateur</quote>.
belaran@999:       A moins que vous n'ayez l'intention de "hacker" Mercurial, je vous
belaran@999:       suggère d'avoir recours à un paquet d'installation de la version binaire.</para>
belaran@999: 
belaran@999:     <para id="x_5e7">Si vous avez vraiment l'intention de construire
belaran@999:       Mercurial à partir des sources sous Windows, suivez les indications pour 
belaran@999:       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>, 
belaran@999:       et préparez vous à un travail épineux.</para>
belaran@999: 
belaran@999:   </sect1>
belaran@999: </appendix>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "appendix")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999:   <!-- BEGIN appD -->
belaran@999:   <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
belaran@999: 
belaran@999: <appendix id="cha:opl">
belaran@999:   <?dbhtml filename="open-publication-license.html"?>
belaran@999:   <title>Open Publication License</title>
belaran@999: 
belaran@999:   <para id="x_638">Version 1.0, 8 June 1999</para>
belaran@999: 
belaran@999:   <sect1>
belaran@999:     <title>Requirements on both unmodified and modified
belaran@999:       versions</title>
belaran@999: 
belaran@999:     <para id="x_639">The Open Publication works may be reproduced and distributed
belaran@999:       in whole or in part, in any medium physical or electronic,
belaran@999:       provided that the terms of this license are adhered to, and that
belaran@999:       this license or an incorporation of it by reference (with any
belaran@999:       options elected by the author(s) and/or publisher) is displayed
belaran@999:       in the reproduction.</para>
belaran@999: 
belaran@999:     <para id="x_63a">Proper form for an incorporation by reference is as
belaran@999:       follows:</para>
belaran@999: 
belaran@999:     <blockquote>
belaran@999:       <para id="x_63b">  Copyright (c) <emphasis>year</emphasis> by
belaran@999: 	<emphasis>author's name or designee</emphasis>. This material
belaran@999: 	may be distributed only subject to the terms and conditions
belaran@999: 	set forth in the Open Publication License,
belaran@999: 	v<emphasis>x.y</emphasis> or later (the latest version is
belaran@999: 	presently available at <ulink url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para>
belaran@999:     </blockquote>
belaran@999: 
belaran@999:     <para id="x_63c">The reference must be immediately followed with any options
belaran@999:       elected by the author(s) and/or publisher of the document (see
belaran@999:       <xref linkend="sec:opl:options"/>).</para>
belaran@999: 
belaran@999:     <para id="x_63d">Commercial redistribution of Open Publication-licensed
belaran@999:       material is permitted.</para>
belaran@999: 
belaran@999:     <para id="x_63e">Any publication in standard (paper) book form shall require
belaran@999:       the citation of the original publisher and author. The publisher
belaran@999:       and author's names shall appear on all outer surfaces of the
belaran@999:       book. On all outer surfaces of the book the original publisher's
belaran@999:       name shall be as large as the title of the work and cited as
belaran@999:       possessive with respect to the title.</para>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Copyright</title>
belaran@999: 
belaran@999:     <para id="x_63f">The copyright to each Open Publication is owned by its
belaran@999:       author(s) or designee.</para>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Scope of license</title>
belaran@999: 
belaran@999:     <para id="x_640">The following license terms apply to all Open Publication
belaran@999:       works, unless otherwise explicitly stated in the
belaran@999:       document.</para>
belaran@999: 
belaran@999:     <para id="x_641">Mere aggregation of Open Publication works or a portion of
belaran@999:       an Open Publication work with other works or programs on the
belaran@999:       same media shall not cause this license to apply to those other
belaran@999:       works. The aggregate work shall contain a notice specifying the
belaran@999:       inclusion of the Open Publication material and appropriate
belaran@999:       copyright notice.</para>
belaran@999: 
belaran@999:     <para id="x_642"><emphasis role="bold">Severability</emphasis>. If any part
belaran@999:       of this license is found to be unenforceable in any
belaran@999:       jurisdiction, the remaining portions of the license remain in
belaran@999:       force.</para>
belaran@999: 
belaran@999:     <para id="x_643"><emphasis role="bold">No warranty</emphasis>. Open
belaran@999:       Publication works are licensed and provided <quote>as is</quote>
belaran@999:       without warranty of any kind, express or implied, including, but
belaran@999:       not limited to, the implied warranties of merchantability and
belaran@999:       fitness for a particular purpose or a warranty of
belaran@999:       non-infringement.</para>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Requirements on modified works</title>
belaran@999: 
belaran@999:     <para id="x_644">All modified versions of documents covered by this license,
belaran@999:       including translations, anthologies, compilations and partial
belaran@999:       documents, must meet the following requirements:</para>
belaran@999: 
belaran@999:     <orderedlist inheritnum="ignore" continuation="restarts">
belaran@999:       <listitem><para id="x_645">The modified version must be labeled as
belaran@999: 	  such.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_646">The person making the modifications must be
belaran@999: 	  identified and the modifications dated.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_647">Acknowledgement of the original author and
belaran@999: 	  publisher if applicable must be retained according to normal
belaran@999: 	  academic citation practices.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_648">The location of the original unmodified document
belaran@999: 	  must be identified.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_649">The original author's (or authors') name(s) may
belaran@999: 	  not be used to assert or imply endorsement of the resulting
belaran@999: 	  document without the original author's (or authors')
belaran@999: 	  permission.</para>
belaran@999:       </listitem></orderedlist>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1>
belaran@999:     <title>Good-practice recommendations</title>
belaran@999: 
belaran@999:     <para id="x_64a">In addition to the requirements of this license, it is
belaran@999:       requested from and strongly recommended of redistributors
belaran@999:       that:</para>
belaran@999: 
belaran@999:     <orderedlist inheritnum="ignore" continuation="restarts">
belaran@999:       <listitem><para id="x_64b">If you are distributing Open Publication works
belaran@999: 	  on hardcopy or CD-ROM, you provide email notification to the
belaran@999: 	  authors of your intent to redistribute at least thirty days
belaran@999: 	  before your manuscript or media freeze, to give the authors
belaran@999: 	  time to provide updated documents. This notification should
belaran@999: 	  describe modifications, if any, made to the document.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_64c">All substantive modifications (including
belaran@999: 	  deletions) be either clearly marked up in the document or
belaran@999: 	  else described in an attachment to the document.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_64d">Finally, while it is not mandatory under this
belaran@999: 	  license, it is considered good form to offer a free copy of
belaran@999: 	  any hardcopy and CD-ROM expression of an Open
belaran@999: 	  Publication-licensed work to its author(s).</para>
belaran@999:       </listitem></orderedlist>
belaran@999: 
belaran@999:   </sect1>
belaran@999:   <sect1 id="sec:opl:options">
belaran@999:     <title>License options</title>
belaran@999: 
belaran@999:     <para id="x_64e">The author(s) and/or publisher of an Open
belaran@999:       Publication-licensed document may elect certain options by
belaran@999:       appending language to the reference to or copy of the license.
belaran@999:       These options are considered part of the license instance and
belaran@999:       must be included with the license (or its incorporation by
belaran@999:       reference) in derived works.</para>
belaran@999: 
belaran@999:     <orderedlist inheritnum="ignore" continuation="restarts">
belaran@999:       <listitem><para id="x_64f">To prohibit distribution of substantively
belaran@999: 	  modified versions without the explicit permission of the
belaran@999: 	  author(s). <quote>Substantive modification</quote> is
belaran@999: 	  defined as a change to the semantic content of the document,
belaran@999: 	  and excludes mere changes in format or typographical
belaran@999: 	  corrections.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_650">  To accomplish this, add the phrase
belaran@999: 	  <quote>Distribution of substantively modified versions of
belaran@999: 	    this document is prohibited without the explicit
belaran@999: 	    permission of the copyright holder.</quote> to the license
belaran@999: 	  reference or copy.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_651">To prohibit any publication of this work or
belaran@999: 	  derivative works in whole or in part in standard (paper)
belaran@999: 	  book form for commercial purposes is prohibited unless prior
belaran@999: 	  permission is obtained from the copyright holder.</para>
belaran@999:       </listitem>
belaran@999:       <listitem><para id="x_652">To accomplish this, add the phrase
belaran@999: 	  <quote>Distribution of the work or derivative of the work in
belaran@999: 	    any standard (paper) book form is prohibited unless prior
belaran@999: 	    permission is obtained from the copyright holder.</quote>
belaran@999: 	  to the license reference or copy.</para>
belaran@999:       </listitem></orderedlist>
belaran@999: 
belaran@999:   </sect1>
belaran@999: </appendix>
belaran@999: 
belaran@999: <!--
belaran@999: local variables: 
belaran@999: sgml-parent-document: ("00book.xml" "book" "appendix")
belaran@999: end:
belaran@999: -->
belaran@999: 
belaran@999: </book>