hgbook
view fr/complete.xml @ 999:a6b81cd31cfd
adding complete.xml - which generated but Bryan did add it also - as I have absolutly no personnality I do as he does
| author | Romain PELISSE <belaran@gmail.com> |
|---|---|
| date | Sat Sep 12 20:53:36 2009 +0200 (2009-09-12) |
| parents | |
| children |
line source
1 <?xml version="1.0"?>
3 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
4 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
5 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
6 <book id="hg">
7 <title>Mercurial: The Definitive Guide</title>
9 <!-- hg parents --template '{node|short} ({date|shortdate})'
10 <subtitle>Compiled from 8a1d3f1aff17 (2009-03-10)</subtitle>
11 -->
12 <subtitle>Compiled from $rev_id$</subtitle>
13 <bookinfo>
14 <edition>1</edition>
15 <isbn>9780596800673</isbn>
16 <authorgroup>
17 <author>
18 <firstname>Bryan</firstname>
19 <surname>O'Sullivan</surname>
20 </author>
21 </authorgroup>
23 <editor>
24 <firstname>Mike</firstname>
25 <surname>Loukides</surname>
26 </editor>
28 <copyright>
29 <year>2006</year>
30 <year>2007</year>
31 <year>2008</year>
32 <year>2009</year>
33 <holder>Bryan O'Sullivan</holder>
34 </copyright>
35 </bookinfo>
37 <!-- BEGIN ch00 -->
38 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
40 <preface id="chap:preface">
41 <?dbhtml filename="preface.html"?>
42 <title>Preface</title>
44 <sect1>
45 <title>Un conte technique</title>
47 <para id="x_72e">Il y a quelques années, quand j'ai voulu expliqué
48 pourquoi je pensais que le gestion de révision distribuée est importante,
49 le domaine était encore si nouveau qu'il n'y avait presque aucune
50 littérature publiée pour servir de référence aux personnes intéressées.</para>
52 <para id="x_72f">Bien qu'à cette époque je passais beaucoup de temps
53 à travailler sur les entrailles de Mercurial, je me suis mis à la
54 rédaction de ce livre parce qu'il me semblait la manière la plus efficace
55 d'aider notre logiciel à atteindre un vaste auditoire, toujours avec
56 l'idée que la gestion de révision devrait être distribuée par nature. J'ai
57 publié ce libre en ligne sous une licence libre pour la même raison : pour
58 diffuser la parole auprès du monde.</para>
60 <para id="x_730">Il y a un rythme familier à un bon livre sur un logiciel
61 qui ressemble de près au fait de conter une histoire : Pourquoi ceci est ?
62 Pourquoi ceci est important ? Comment peut il m'aider ? Comment m'en
63 servir ? Dans ce livre, j'essaye de répondre à toutes ces questions pour
64 la gestion de révision distribuée en général, et pour Mercurial en
65 particulier.</para>
66 </sect1>
68 <sect1>
69 <title>Merci de votre soutien à Mercurial</title>
71 <para id="x_731">En achetant une copie de ce livre, vous soutenez le
72 développement et la liberté de Mercurial en particulier, et dans
73 l'Open Source, au logiciel libre en général. O'Reilly Media et
74 moi-même donnons les revenus issus des ventes de ce livre à la
75 Software Freedom Conservancy (<ulink url="http://www.softwarefreedom.org/">http://www.softwarefreedom.org/</ulink>)
76 qui fournit un support juridique à Mercurial et à de
77 nombreux autres projets Open Source proéminents et de qualité.</para>
78 </sect1>
80 <sect1>
81 <title>Remerciements</title>
83 <para id="x_732">Ce livre n'aurait pas vu le jour sans les
84 efforts de Matt Mackal, l'auteur et le chef du projet Mercurial.
85 Il est assisté très efficacement par des centaines de contributeurs
86 volontaires à travers le monde.</para>
88 <para id="x_733">Les enfants, Cian et Ruairi, ont toujours été prêt
89 à m'aider à me reposer avec de merveilleux et impulsif jeux d'enfants.
90 Je tiens aussi à remercier mon ex-femme, Shannon, pour son soutien.
91 </para>
93 <para id="x_734">Mes collègues et amis m'ont aidé et assisté de
94 de nombreuses manières. Cette liste de personne est nécessaire mais très
95 incomplète : Stephen Hahn, Karyn Ritter, Bonnie Corwin, James Vasile,
96 Matt Norwood, Eben Moglen, Bradley Kuhn, Robert Walsh, Jeremy
97 Fitzhardinge, Rachel Chalmers.</para>
99 <para id="x_735">J'ai conçu ce livre de manière ouverte, en publiant
100 des brouillons des chapitres du livre sur des site web, au fur et à
101 mesure que je les réalisais. Leurs lecteurs m'ont fait des retours
102 utilisant l'application web que j'avais développée. A la fin de sa
103 conception, plus de 100 personnes m'avaient fait des commentaires,
104 un chiffre incroyable quand l'on considère que ce système de
105 commentaire n'a tourné que dans les deux derniers mois de la
106 rédaction du livre.</para>
108 <para id="x_736">J'aimerais particulièrement remercier les
109 personnes suivantes, dont les commentaires représentent plus
110 d'un tiers de l'ensemble de ces derniers. Je voudrais les
111 remercier pour leur attention et effort à me faire des retours
112 très détaillés.</para>
114 <para id="x_737">Martin Geisler, Damien Cassou, Alexey Bakhirkin, Till Plewe,
115 Dan Himes, Paul Sargent, Gokberk Hamurcu, Matthijs van der
116 Vleuten, Michael Chermside, John Mulligan, Jordi Fita, Jon
117 Parise.</para>
119 <para id="x_738">Je souhaite aussi remercier l'aide des personnes
120 qui ont découvert des erreurs et fournit des suggestions avisées
121 à travers tout le livre.</para>
123 <para id="x_739">Jeremy W. Sherman, Brian Mearns, Vincent Furia, Iwan
124 Luijks, Billy Edwards, Andreas Sliwka, Paweł Sołyga, Eric
125 Hanchrow, Steve Nicolai, Michał Masłowski, Kevin Fitch, Johan
126 Holmberg, Hal Wine, Volker Simonis, Thomas P Jakobsen, Ted
127 Stresen-Reuter, Stephen Rasku, Raphael Das Gupta, Ned
128 Batchelder, Lou Keeble, Li Linxiao, Kao Cardoso Félix, Joseph
129 Wecker, Jon Prescot, Jon Maken, John Yeary, Jason Harris,
130 Geoffrey Zheng, Fredrik Jonson, Ed Davies, David Zumbrunnen,
131 David Mercer, David Cabana, Ben Karel, Alan Franzoni, Yousry
132 Abdallah, Whitney Young, Vinay Sajip, Tom Towle, Tim Ottinger,
133 Thomas Schraitle, Tero Saarni, Ted Mielczarek, Svetoslav
134 Agafonkin, Shaun Rowland, Rocco Rutte, Polo-Francois Poli,
135 Philip Jenvey, Petr Tesałék, Peter R. Annema, Paul Bonser,
136 Olivier Scherler, Olivier Fournier, Nick Parker, Nick Fabry,
137 Nicholas Guarracino, Mike Driscoll, Mike Coleman, Mietek Bák,
138 Michael Maloney, László Nagy, Kent Johnson, Julio Nobrega, Jord
139 Fita, Jonathan March, Jonas Nockert, Jim Tittsler, Jeduan
140 Cornejo Legorreta, Jan Larres, James Murphy, Henri Wiechers,
141 Hagen Möbius, Gábor Farkas, Fabien Engels, Evert Rol, Evan
142 Willms, Eduardo Felipe Castegnaro, Dennis Decker Jensen, Deniz
143 Dogan, David Smith, Daed Lee, Christine Slotty, Charles Merriam,
144 Guillaume Catto, Brian Dorsey, Bob Nystrom, Benoit Boissinot,
145 Avi Rosenschein, Andrew Watts, Andrew Donkin, Alexey Rodriguez,
146 Ahmed Chaudhary.</para>
147 </sect1>
149 <sect1>
150 <title>Conventions utilisées dans ce livre</title>
152 <para id="x_73a">Les conventions typographiques suivantes sont utilisées dans ce livre :</para>
154 <variablelist>
155 <varlistentry>
156 <term>Italique</term>
158 <listitem>
159 <para id="x_73b">Indique les termes nouveaux, les URLs, les
160 adresses mail, les noms de fichiers et les extensions de
161 fichier.</para>
162 </listitem>
163 </varlistentry>
165 <varlistentry>
166 <term><literal moreinfo="none">Taille constante</literal></term>
168 <listitem>
169 <para id="x_73c">Utilisé pour les extraits de code, comme
170 dans les paragraphes pour référer aux éléments du programme,
171 tels que les variables ou les noms de fonctions, de bases
172 de données, de types de données, de variables d'environnement,
173 d'instructions, et de mots clés.</para>
174 </listitem>
175 </varlistentry>
177 <varlistentry>
178 <term><userinput moreinfo="none">Taille constante avec gras</userinput></term>
180 <listitem>
181 <para id="x_73d">Afficher les commandes ou autres textes qui
182 devraient être saisis par l'utilisateur.</para>
183 </listitem>
184 </varlistentry>
186 <varlistentry>
187 <term><replaceable>Constante avec italique</replaceable></term>
189 <listitem>
190 <para id="x_73e">Affiche les textes qui devraient être remplacés
191 par une valeur définie par l'utilisateur ou des valeurs définies
192 selon le contexte.</para>
193 </listitem>
194 </varlistentry>
195 </variablelist>
197 <tip>
198 <para id="x_73f">Cette icône indique une astuce, une suggestion ou
199 une note d'ordre général.</para>
200 </tip>
202 <caution>
203 <para id="x_740">Cette icône est un message d'alerte ou de prudence.</para>
204 </caution>
205 </sect1>
207 <sect1>
208 <title>Utiliser les exemples de code</title>
210 <para id="x_741">Ce livre est ici pour vous aider dans votre
211 travail. De manière générale, vous pouvez donc utiliser le code
212 de ce livre dans vos programmes et votre documentation. Vous
213 n'avez pas à nous contacter pour nous demander la permission
214 de le faire, à moins que vous ne reproduisiez une partie significative
215 du code. Par exemple, écrire un programme qui utilise plusieurs
216 extraits de code du livre ne demande aucune autorisation particulière.
217 Vendre ou distribuer un CD-ROM provenant des livres O'Reilly demande
218 à l'inverse une autorisation. Répondre à une question en citant ce
219 livre ou ses exemples de code ne demande aucune autorisation préalable.
220 Intégrer une grande quantité des codes d'exemples de ce livre dans
221 votre propre ouvrage demande une autorisation de notre part.</para>
223 <para id="x_742">Nous apprécions, sans l'exiger, que vous citiez
224 l'ouvrage dans vos écrits l'utilisant, en indiquant le titre,
225 l'auteur, l'éditeur et son ISBN. Par exemple: “<emphasis>Titre du
226 livre</emphasis> par Son Auteur. Copyright 2008 O’Reilly Media, Inc.,
227 978-0-596-xxxx-x.”</para>
229 <para id="x_743">Si vous estimez que votre usage des exemples de code
230 dépasse le cadre défini ci dessus, n'hésitez pas à nous contacter :
231 <email>permissions@oreilly.com</email>.</para>
232 </sect1>
234 <sect1>
235 <title>Safari® Books Online</title>
237 <note role="safarienabled">
238 <para id="x_744">Quand vous voyez l'icône de Safari® Books Online
239 sur la couverture d'un de vos livres techniques préférés, cela signifie
240 que le livre est disponible, en ligne, à travers le O’Reilly Network Safari
241 Bookshelf.</para>
242 </note>
244 <para id="x_745">Safari offre une solution qui est meilleure que
245 les e-books. C'est une bibliothèque virtuelle qui vous laisse
246 aisément rechercher dans des milliers de livres, mais aussi
247 copier-coller leurs exemples, télécharger des chapitres, et
248 trouver des réponses rapides quand vous avez besoin d'une
249 information précise et à jour. Essayez le gratuitement :
250 <ulink role="orm:hideurl:ital" url="http://my.safaribooksonline.com/?portal=oreilly">http://my.safaribooksonline.com</ulink>.</para>
251 </sect1>
253 <sect1>
254 <title>Comment nous contacter</title>
256 <para id="x_746">Merci d'adresser vos commentaires et vos questions
257 sur ce livre à son éditeur:</para>
259 <simplelist type="vert">
260 <member>O’Reilly Media, Inc.</member>
262 <member>1005 Gravenstein Highway North</member>
264 <member>Sebastopol, CA 95472</member>
266 <member>800-998-9938 (in the United States or Canada)</member>
268 <member>707-829-0515 (international or local)</member>
270 <member>707 829-0104 (fax)</member>
271 </simplelist>
273 <para id="x_747">Nous avons une page web pour cet ouvrage, où nous
274 publions des errata, des exemples, et encore d'autres informations
275 additionnelles. Vous pouvez accéder à cette page par l'URL suivante:
276 </para>
278 <simplelist type="vert">
279 <member><ulink url="http://www.oreilly.com/catalog/<catalog page>"/></member>
280 </simplelist>
282 <remark>N'oubliez pas de mettre à jour l'attribut <url> aussi.</remark>
284 <para id="x_748">Pour commenter ou poser des questions techniques
285 sur cet ouvrage, envoyez un email à :</para>
287 <simplelist type="vert">
288 <member><email>bookquestions@oreilly.com</email></member>
289 </simplelist>
291 <para id="x_749">Pour plus d'informations sur nos livres, nos
292 conférences, nos centres d'informations, et le réseau O’Reilly,
293 voyez notre site web :</para>
295 <simplelist type="vert">
296 <member><ulink url="http://www.oreilly.com"/></member>
297 </simplelist>
298 </sect1>
299 </preface>
301 <!--
302 local variables:
303 sgml-parent-document: ("00book.xml" "book" "preface")
304 end:
305 -->
307 <!-- BEGIN ch01 -->
308 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
310 <chapter id="chap:intro">
311 <?dbhtml filename="how-did-we-get-here.html"?>
312 <title>Comment en est on arrivé là ?</title>
314 <sect1>
315 <title>À propos de la gestion source</title>
317 <para id="x_6d">La gestion de sources est un processus permettant de gérer différentes
318 versions de la même information. Dans sa forme la plus simple, c'est
319 ce que tout le monde fait manuellement : quand vous modifiez
320 un fichier, vous le sauvegardez sous un nouveau nom contenant un numéro,
321 à chaque fois plus grand que celui de la version précédente.</para>
323 <para id="x_6e">Ce genre de gestion de version manuelle est cependant facilement sujette
324 aux erreurs, ainsi, depuis longtemps, des logiciels existent pour
325 résoudre cette problématique. Les premiers outils de gestion de sources
326 étaient destinés à aider un seul utilisateur, à automatiser la gestion
327 des versions d'un seul fichier. Dans les dernières décades, cette cible
328 s'est largement agrandie, ils gèrent désormais de multiples fichiers, et
329 aident un grand nombre de personnes à travailler ensemble. Les outils les
330 plus modernes n'ont aucune difficulté à gérer plusieurs milliers de
331 personnes travaillant ensemble sur des projets regroupant plusieurs
332 centaines de milliers de fichiers.</para>
334 <para id="x_6f">L'arrivée de la gestion de révision distribuée est
335 relativement récente, et, pour le moment, ce nouveau domaine a grandi
336 grâce à la volonté des gens d'explorer ces territoires encore inconnus.
337 </para>
339 <para id="x_70">J'écris un livre sur la gestion de révision distribuée
340 parce que je pense qu'il s'agit d'un sujet important qui mérite un guide
341 du terrain. J'ai choisi d'écrire un livre sur Mercurial car il est
342 l'outil le plus facile pour découvrir ce nouveau domaine, tout en étant
343 un outil efficace qui répond aux demandes d'environnements réels et
344 difficiles, là où d'autres outils de gestions de versions s'effondrent.</para>
346 <sect2>
347 <title>Pourquoi utiliser un gestionnaire de source ?</title>
349 <para id="x_71">Il y a de nombreuses raisons pour que vous ou votre équipe souhaitiez
350 utiliser un outil automatisant la gestion de version pour votre projet.</para>
352 <itemizedlist>
353 <listitem><para id="x_72">L'outil se chargera de suivre l'évolution de votre projet, sans
354 que vous ayez à le faire. Pour chaque modification, vous aurez à votre
355 disposition un journal indiquant <emphasis>qui</emphasis> a fait quoi, <emphasis>pourquoi</emphasis>
356 il l'a fait, <emphasis>quand</emphasis> il l'a fait, et
357 <emphasis>ce</emphasis> qu'il a modifié.</para>
358 </listitem>
359 <listitem><para id="x_73">Quand vous travaillez avec d'autres personnes, les logiciels de
360 gestion de source facilitent le travail collaboratif. Par exemple, quand
361 plusieurs personnes font, plus ou moins simultanément, des modifications
362 incompatibles, le logiciel vous aidera à identifier et à résoudre les conflits.</para>
363 </listitem>
364 <listitem><para id="x_74">L'outil vous aidera à réparer vos erreurs. Si vous effectuez un changement
365 qui se révèle être une erreur, vous pourrez revenir à une version
366 antérieure d'un fichier ou même d'un ensemble de fichiers. En fait, un outil de
367 gestion de source <emphasis>vraiment</emphasis> efficace vous permettra d'identifier à quel
368 moment le problème est apparu (voir la section <xref linkend="sec:undo:bisect"/> pour plus
369 de détails).</para>
370 </listitem>
371 <listitem><para id="x_75">L'outil vous permettra aussi de travailler sur plusieurs versions différentes
372 de votre projet et de gérer l'écart entre chacune.</para>
373 </listitem></itemizedlist>
374 <para id="x_76">La plupart de ces raisons ont autant d'importances —du
375 moins en théorie— que vous travailliez sur un projet pour vous, ou
376 avec une centaine d'autres personnes.
377 </para>
379 <para id="x_77">Une question fondamentale à propos des outils de gestion de
380 source, qu'il s'agisse du projet d'une personne ou d'une grande équipe, est
381 quels sont ses <emphasis>avantages</emphasis> par rapport à ses
382 <emphasis>coûts</emphasis>. Un outil qui est difficile à utiliser ou à
383 comprendre exigera un lourd effort d'adaptation.
384 </para>
386 <para id="x_78">)Un projet de cinq milles personnes s'effondrera très
387 certainement de lui même sans aucun processus et outil de gestion de
388 source. Dans ce cas, le coût d'utilisation d'un logiciel de gestion de
389 source est dérisoire puisque <emphasis>sans</emphasis>, l'échec est presque
390 garanti.
391 </para>
393 <para id="x_79">D'un autre coté, un <quote>rapide hack</quote> d'une personne
394 peut sembler un contexte bien pauvre pour utiliser un outil de gestion de
395 source, car, bien évidement le coût d'utilisation dépasse le coût total du
396 projet. N'est ce pas ?
397 </para>
399 <para id="x_7a">Mercurial supporte ces <emphasis>deux</emphasis>
400 échelles de travail. Vous pouvez apprendre les bases en quelques
401 minutes seulement, et, grâce à sa performance, vous pouvez l'utiliser
402 avec facilité sur le plus petit des projets. Cette simplicité
403 signifie que vous n'avez pas de concept obscurs ou de séquence de
404 commandes défiant l'imagination, sans aucune corrélation avec
405 <emphasis>ce que vous êtes entrain de faire</emphasis>. En même
406 temps, ces mêmes performances et sa nature
407 <quote>peer-to-peer</quote> vous permettent d'adapter, sans
408 difficulté, son utilisation à de très grands projets.
409 </para>
411 <para id="x_7b">Aucun outil de gestion de source ne peut sauver un
412 projet mal mené, mais un bon outil peut rendre beaucoup plus fluide
413 votre travail.
414 </para>
416 </sect2>
418 <sect2>
419 <title>Les multiples noms de la gestion de source</title>
421 <para id="x_7c">La gestion de source
422 <!-- TODO:<footnote><J'ai utilisé systématiquement le terme
423 <quote>gestion de source</quote> à travers tout l'ouvrage. Ce
424 n'est pas forcement la meilleure traduction, et ceci peut rendre
425 la lecture un peu lourde, mais je pense que le document y gagne
426 en clarté et en précision. -->
427 est un domaine tellement large qu'il n'existe pas qu'un seul nom ou
428 acronyme pour le désigner. Voici quelques noms ou acronymes que vous
429 rencontrerez le plus souvent.
430 <!-- TODO:<footnote> J'ai conservé la liste des noms en anglais pour
431 des raisons de commodité (ils sont plus <quote>googelable</quote>).
432 En outre, j'ai opté pour conserver l'ensemble des opérations de
433 Mercurial (\textit{commit},\textit{push}, \textit{pull},...) en
434 anglais, là aussi pour faciliter la lecture d'autres documents en
435 anglais, ainsi que l'utilisation de Mercurial. -->
436 </para>
438 <para>:
439 </para>
441 <itemizedlist>
442 <listitem><para id="x_7d">Revision control (RCS)</para></listitem>
443 <listitem><para id="x_7e">Software configuration management (SCM), ou
444 configuration management</para></listitem>
445 <listitem><para id="x_7f">Source code management</para></listitem>
446 <listitem><para id="x_80">Source code control, ou source control</para></listitem>
447 <listitem><para id="x_81">Version control (VCS)</para></listitem></itemizedlist>
449 <para id="x_82">Certaines personnes prétendent que ces termes ont en fait
450 des sens différents mais en pratique ils se recouvrent tellement qu'il n'y
451 a pas réellement de manière pertinente de les distinguer. </para>
453 </sect2>
454 </sect1>
456 <sect1>
458 <title>A propos des exemples dans ce livre</title>
460 <para id="x_84">Ce livre prend une approche non usuel pour les exemples
461 de code. Tous les exemples sont en <quote>live</quote> — Chacun
462 est actuellement le résultat d'un script shell qui exécute les
463 commandes Mercurial que vous voyez. A chaque fois qu'une image du livre
464 est construite à partir des sources, tous les scripts d'exemple sont
465 lancés automatiquement, et leurs résultats effectifs sont comparés aux
466 résultats attendus.</para>
468 <para id="x_85">L'avantage de dette approche est que les exemples sont
469 toujours précis ; ils décrivent <emphasis>exactement</emphasis> la
470 conduite de la version de Mercurial qui est mentionnée en entête du
471 livre. Si je met à jour la version de Mercurial que je suis en train de
472 documenter, et que la sortie de certaines commandes change, la
473 construction du livre échoue.</para>
475 <para id="x_86">
476 Il existe un petit désavantage à cette approche qui est que les dates et
477 heures que vous verrez dans les exemples tendent à être
478 <quote>écrasés</quote> ensemble, dans le sens où elles ne sont pas
479 celles qu'elles auraient été si un humain avait tapé les commandes. En
480 effet, humain ne peut pas taper plus d'une commande toutes les quelques
481 secondes, avec le temps qui s'écoule, mes scripts d'exemples exécutent
482 plusieurs commandes en une seconde.
483 </para>
485 <para id="x_87">Une circonstance de ceci est que plusieurs commits
486 consécutifs dans un exemple peuvent apparaître comme ayant eu lieu
487 durant la même seconde.
488 Vous pouvez observer le phénomène dans l'exemple <literal role="hg-ext" moreinfo="none">bisect</literal> dans <xref linkend="sec:undo:bisect"/>
489 </para>
491 <para id="x_88">Donc, lorsque vous lisez ces exemples, ne prêtez pas trop
492 d'importance aux dates et heures que vous voyez dans la sortie des
493 commandes. Cependant, <emphasis>soyez</emphasis> confiants que le
494 comportement que vous voyez est consistent et reproductible
495 </para>
497 </sect1>
499 <!-- The next section has disapper from this part of the book. it may be splaced somewhere else... t-->
501 <sect1>
502 <title>Tendances de la gestion de source</title>
504 <para id="x_89">Il y a eu une tendance évidente dans le développement et
505 l'utilisation d'outils de gestion de source depuis les quatre dernières
506 décades, au fur et à mesure que les utilisateurs se sont habitués à
507 leur outils et se sont sentis contraints par leurs limitations.
508 </para>
510 <para id="x_8a">La première génération commença simplement par gérer un
511 fichier unique sur un ordinateur individuel. Cependant, même si ces
512 outils présentaient une grande avancée par rapport à la gestion
513 manuelle des versions, leur modèle de verrouillage et leur utilisation
514 limitée à un seul ordinateur rendaient leur utilisation possible
515 uniquement dans une très petite équipe.
516 </para>
518 <para id="x_8b">La seconde génération a assoupli ces contraintes en
519 adoptant une architecture réseau et centralisée, permettant de gérer
520 plusieurs projets entiers en même temps. Alors que les projets
521 grandirent en taille, ils rencontrèrent de nouveaux problèmes. Avec les
522 clients discutant régulièrement avec le serveurs, la montée en charge
523 devint un réel problème sur les gros projets. Une connexion réseau peu
524 fiable pouvait complètement empêcher les utilisateurs distants de
525 dialoguer avec le serveur. Alors que les projets <emphasis remap="it">Open Source</emphasis> commencèrent à mettre en place des
526 accès en lecture seule disponible anonymement, les utilisateurs sans
527 les privilèges de <quote>commit</quote> réalisèrent qu'ils ne pouvaient
528 pas utiliser les outils pour collaborer naturellement avec le projet,
529 comme ils ne pouvaient pas non plus enregistrer leurs modifications.
530 </para>
532 <para id="x_8c">La génération actuelle des outils de gestion de source
533 est <quote>peer-to-peer</quote> par nature. Tous ces systèmes ont
534 abandonné la dépendance à un serveur central, et ont permis à leur
535 utilisateur de distribuer les données de leur gestion de source à qui
536 en a besoin. La collaboration à travers Internet a transformé la
537 contrainte technologique en une simple question de choix et de
538 consensus. Les outils modernes peuvent maintenant fonctionner en mode
539 déconnecté sans limite et de manière autonome, la connexion au réseau
540 n'étant nécessaire que pour synchroniser les modifications avec les
541 autres dépôts.
542 </para>
543 </sect1>
545 <sect1>
546 <title>Quelques avantages des gestionnaires de source distribués</title>
548 <para id="x_8d">Même si les gestionnaire de source distribués sont depuis
549 plusieurs années assez robustes et aussi utilisables que leurs
550 prédécesseurs, les utilisateurs d'autres outils n'y ont pas encore été
551 sensibilisés. Les gestionnaires de source distribués se distinguent
552 particulièrement de leurs équivalents centralisés de nombreuses
553 manières.
554 </para>
556 <para id="x_8e">Pour un développeur individuel, ils restent beaucoup plus
557 rapides que les outils centralisés. Cela pour une raison simple : un
558 outil centralisé doit toujours dialoguer à travers le réseau pour la
559 plupart des opérations, car presque toutes les métadonnées sont
560 stockées sur la seule copie du serveur central. Un outil distribué
561 stocke toute ses métadonnées localement. À tâche égale, effectuer un
562 échange avec le réseau ajoute un délai aux outils centralisés. Ne
563 sous-estimez pas la valeur d'un outil rapide : vous allez passer
564 beaucoup de temps à interagir avec un logiciel de gestion de source.
565 </para>
567 <para id="x_8f">Les outils distribués sont complètement indépendants des
568 aléas de votre serveur, d'autant plus qu'ils répliquent les métadonnées
569 à beaucoup d'endroits. Si votre serveur central prend feu, vous avez
570 intérêt à ce que les médias de sauvegardes soient fiables, et que votre
571 dernier <quote>backup</quote> soit récent et fonctionne sans problème.
572 Avec un outil distribué, vous avez autant de <quote>backup</quote> que
573 de contributeurs.
574 </para>
576 <para id="x_90">En outre, la fiabilité de votre réseau affectera beaucoup
577 moins les outils distribués. Vous ne pouvez même pas utiliser un outil
578 centralisé sans connexion réseau, à l'exception de quelques commandes,
579 très limitées. Avec un outil distribué, si votre connexion réseau tombe
580 pendant que vous travaillez, vous pouvez ne même pas vous en rendre
581 compte. La seule chose que vous ne serez pas capable de faire sera de
582 communiquer avec des dépôts distants, opération somme toute assez rare
583 en comparaison aux opérations locales. Si vous avez une équipe de
584 collaborateurs très dispersée ceci peut être significatif.
585 </para>
587 <sect2>
588 <title>Avantages pour les projets Open Source</title>
590 <para id="x_91">Si vous prenez goût à un projet <emphasis remap="it">Open Source</emphasis> et que vous décidez de commencer
591 à toucher à son code, et que le projet utilise un gestionnaire de
592 source distribué, vous êtes immédiatement un "pair" avec les
593 personnes formant le <quote>cœur</quote> du projet. S'ils publient
594 leurs dépôts, vous pouvez immédiatement copier leurs historiques de
595 projet, faire des modifications, enregistrer votre travail en
596 utilisant les mêmes outils qu'eux. Par comparaison avec un outil
597 centralisé, vous devez utiliser un logiciel en mode <quote>lecture
598 seule</quote> à moins que quelqu'un ne vous donne les privilèges de
599 <quote>commit</quote> sur le serveur central. Avant ça, vous ne serez
600 pas capable d'enregistrer vos modifications, et vos propres
601 modifications risqueront de se corrompre chaque fois que vous
602 essayerez de mettre à jour à votre espace de travail avec le serveur
603 central.
604 </para>
606 <sect3>
607 <title>Le non-problème du "fork"</title>
609 <para id="x_92">Il a été souvent suggéré que les gestionnaires de
610 source distribués posent un risque pour les projets <emphasis remap="it">Open Source</emphasis> car ils facilitent grandement la
611 création de <quote>fork</quote>.
612 <!--footnote{NdT:Création d'une <ulink url="version alternative du
613 logiciel">version alternative du
614 logiciel</ulink>{http://fr.wikipedia.org/wiki/Fork#Embranchement_d.27un_projet_informatique}
615 -->
616 Un <quote>fork</quote> apparait quand il y des divergences d'opinion
617 ou d'attitude au sein d'un groupe de développeurs qui aboutissent à
618 la décision de ne plus travailler ensemble. Chaque parti s'empare
619 d'une copie plus ou moins complète du code source du projet et
620 continue dans sa propre direction.
621 </para>
624 <para id="x_93">Parfois ces différents partis décident de se
625 réconcilier. Avec un serveur central, l'aspect
626 <emphasis>technique</emphasis> de cette réconciliation est un
627 processus douloureux, et essentiellement manuel. Vous devez décider
628 quelle modification est <quote>la gagnante</quote>, et replacer, par
629 un moyen ou un autre, les modifications de l'autre équipe dans
630 l'arborescence du projet. Ceci implique généralement la perte d'une
631 partie de l'historique d'un des partis, ou même des deux.
632 </para>
634 <para id="x_94">Ce que les outils distribués permettent à ce sujet est
635 probablement la <emphasis>meilleure</emphasis> façon de développer un
636 projet. Chaque modification que vous effectuez est potentiellement un
637 <quote>fork</quote>. La grande force de cette approche est que les
638 gestionnaires de source distribués doivent être vraiment très
639 efficaces pour <emphasis>fusionner (merge)</emphasis>
640 <!-- TODO footnote{NdT:j'ai choisi de traduire ici <emphasis
641 remap="it">merging</emphasis> par <quote>fusionner</quote> pour des
642 raisons de clarté} -->
643 des <quote>forks</quote>, car les <quote>forks</quote>, dans ce
644 contexte, arrivent tout le temps.
645 </para>
647 <para id="x_95">Si chaque altération que n'importe qui effectue, à tout
648 moment, est vue comme un <quote>fork</quote> à fusionner, alors ce
649 que le monde de l'<emphasis remap="it">Open Source</emphasis> voit
650 comme un <quote>fork</quote> devient <emphasis>uniquement</emphasis>
651 une problématique sociale. En fait, les outils de gestions de source
652 distribués <emphasis>réduisent</emphasis> les chances de
653 <quote>fork</quote> :
654 </para>
656 <itemizedlist>
657 <listitem>
658 <para>Ils éliminent la distinction sociale qu'imposent les outils
659 centralisés entre les membres du projets (ceux qui ont accès au
660 <quote>commit</quote>) et ceux de l'extérieur (ce qui ne l'ont
661 pas).
662 </para>
663 <para>Ils rendent plus facile la réconciliation après un
664 <quote>fork</quote> social, car tout ce qu'elle implique est une
665 simple fusion.
666 </para>
667 </listitem>
668 </itemizedlist>
670 <para id="x_98">Certaines personnes font de la résistance envers les
671 gestionnaires de source distribués parce qu'ils veulent garder un
672 contrôle ferme sur leur projet, et ils pensent que les outils
673 centralisés leur fournissent ce contrôle. Néanmoins, si c'est votre
674 cas, sachez que si vous publiez votre dépôt CVS ou Subversion de
675 manière publique, il existe une quantité d'outils disponibles pour
676 récupérer entièrement votre projet et son historique (quoique
677 lentement) et le récréer ailleurs, sans votre contrôle. En fait,
678 votre contrôle sur votre projet est illusoire, vous ne faites
679 qu'interdire à vos collaborateurs de travailler de manière fluide, en
680 disposant d'un miroir ou d'un <quote>fork</quote> de votre
681 historique.
682 </para>
684 </sect3>
685 </sect2>
686 <sect2>
687 <title>Avantages pour les projets commerciaux</title>
689 <para id="x_99">Beaucoup de projets commerciaux sont réalisés par des
690 équipes éparpillées à travers le globe. Les contributeurs qui sont
691 loin du serveur central devront subir des commandes lentes et même
692 parfois peu fiables. Les solutions propriétaires de gestion de source
693 tentent de palier ce problème avec des réplications de sites distants
694 qui sont à la fois coûteuses à mettre en place et lourdes à
695 administrer. Un système distribué ne souffre pas de ce genre de
696 problèmes. En outre, il est très aisé de mettre en place plusieurs
697 serveurs de références, disons un par site, de manière à ce qu'il n'y
698 ait pas de communication redondante entre les dépôts, sur une
699 connexion longue distance souvent onéreuse.
700 </para>
702 <para id="x_9a">Les systèmes de gestion de source supportent
703 généralement assez mal la monté en charge. Il n'est pas rare pour un
704 gestionnaire de source centralisé pourtant onéreux de s'effondrer
705 sous la charge combinée d'une douzaine d'utilisateurs concurrents
706 seulement. Une fois encore, la réponse à cette problématique est
707 généralement encore la mise en place d'un ensemble complexe de
708 serveurs synchronisés par un mécanisme de réplication. Dans le cas
709 d'un gestionnaire de source distribué, la charge du serveur central
710 — si vous avez un— est plusieurs fois inférieure (car
711 toutes les données sont déjà répliquées ailleurs), un simple serveur,
712 pas très cher, peut gérer les besoins d'une plus grande équipe, et la
713 réplication pour balancer la charge devient le travail d'un simple
714 script.
715 </para>
717 <para id="x_9b">Si vous avez des employés sur le terrain, en train de
718 chercher à résoudre un souci sur le site d'un client, ils
719 bénéficieront aussi d'un gestionnaire de source distribué. Cet outil
720 leur permettra de générer des versions personnalisées, d'essayer
721 différentes solutions, en les isolant aisément les unes des autres,
722 et de rechercher efficacement à travers l'historique des sources, la
723 cause des bugs ou des régressions, tout ceci sans avoir besoin de la
724 moindre connexion au réseau de votre compagnie.
725 </para>
727 </sect2>
728 </sect1>
729 <sect1>
730 <title>Pourquoi choisir Mercurial?</title>
732 <para id="x_9c">Mercurial a plusieurs caractéristiques qui en font un
733 choix particulièrement pertinent pour la gestion de source :
734 </para>
735 <itemizedlist>
736 <listitem><para id="x_9d">Il est simple à apprendre et à utiliser.</para></listitem>
737 <listitem><para id="x_9e">Il est léger.</para></listitem>
738 <listitem><para id="x_9f">Il s'adapte très bien à la charge.</para></listitem>
739 <listitem><para id="x_a0">Il se personnalise facilement.</para></listitem>
740 </itemizedlist>
742 <para id="x_a1">Si vous êtes déjà familier d'un outil de gestion de
743 source, vous serez capable de l'utiliser en moins de 5 minutes. Sinon,
744 ça ne sera pas beaucoup plus long. Les commandes utilisées par
745 Mercurial, comme ses fonctionnalités, sont généralement uniformes et
746 cohérentes, et vous pouvez ainsi garder en tête simplement quelques
747 règles générales, plutôt qu'un lot complexe d'exceptions.
748 </para>
750 <para id="x_a2">Sur un petit projet, vous pouvez commencer à travailler
751 avec Mercurial en quelques instants. Ajouter des modifications ou des
752 branches, transférer ces modifications (localement ou via le réseau),
753 et les opérations d'historique ou de statut sont aussi très rapides.
754 Mercurial reste hors de votre chemin grâce à sa simplicité
755 d'utilisation et sa rapidité d'exécution.
756 </para>
758 <para id="x_a3">L'utilité de Mercurial ne se limite pas à de petits
759 projets: il est aussi utilisé par des projets ayant des centaines ou
760 même des milliers de contributeurs, avec plusieurs dizaines de milliers
761 de fichiers, et des centaines de méga octets de code source.
762 </para>
764 <para id="x_a4">Si les fonctionnalités au cœur de Mercurial ne sont pas
765 suffisantes pour vous, il est très aisé d'en construire d'autres.
766 Mercurial est adapté à l'utilisation de scripts, et son implémentation
767 interne en Python, propre et claire, rend encore plus facile l'ajout de
768 fonctionnalités sous forme d'extensions. Il en existe déjà un certain
769 nombre de très populaires et très utiles, dont le périmètre va de la
770 recherche de bugs à l'amélioration des performances.
771 </para>
773 </sect1>
774 <sect1>
775 <title>Mercurial comparé aux autres outils</title>
777 <para id="x_a5">Avant que vous n'alliez plus loin, comprenez bien que
778 cette section reflète mes propres expériences, et elle est donc (j'ose
779 le dire) peu objective. Néanmoins, j'ai utilisé les outils de gestion
780 de source listés ci dessous, dans la plupart des cas, pendant plusieurs
781 années.
782 </para>
784 <sect2>
785 <title>Subversion</title>
787 <para id="x_a6">Subversion est un des outils de gestion de source les
788 plus populaire, il fût développé pour remplacer CVS. Il a une
789 architecture client/server centralisée.
790 </para>
792 <para id="x_a7">Subversion et Mercurial ont des noms de commandes très
793 similaires pour les mêmes opérations, ainsi si vous êtes familier
794 avec l'un, c'est facile d'apprendre l'autre. Ces deux outils sont
795 portables sur les systèmes d'exploitation les plus populaires.
796 </para>
798 <para id="x_a8">Avant la version 1.5, Subversion n'offrait aucune forme
799 de support pour les fusions. Lors de l'écriture de ce livre, ses
800 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">
801 complexes et buguées</ulink>.
802 </para>
804 <para id="x_a9">Mercurial dispose d'un avantage substantiel en terme de
805 performance par rapport à Subversion sur la plupart des opérations
806 que j'ai pu tester. J'ai mesuré une différence de performance allant
807 de deux à six fois plus rapide avec le système de stockage de fichier
808 local de Subversion 1.4.3 (<emphasis>ra_local</emphasis>), qui est la
809 méthode d'accès la plus rapide disponible. Dans un déploiement plus
810 réaliste, impliquant un stockage réseau, Subversion serait encore
811 plus désavantagé. Parce que la plupart des commandes Subversion
812 doivent communiquer avec le serveur et que Subversion n'a pas de
813 mécanisme de réplication, la capacité du serveur et la bande passante
814 sont devenues des goulots d'étranglement pour les projets de taille
815 moyenne ou grande.
816 </para>
818 <para id="x_aa">En outre, Subversion implique une surcharge
819 substantielle dans le stockage local de certaines données, pour
820 éviter des transactions avec le serveur, pour certaines opérations
821 communes, telles que la recherche des fichiers modifiés
822 (<literal moreinfo="none">status</literal>) et l'affichage des modifications par
823 rapport à la révision courante (<literal moreinfo="none">diff</literal>). En
824 conséquence, un répertoire de travail Subversion a souvent la même
825 taille, ou est plus grand, qu'un dépôt Mercurial et son espace de
826 travail, et ceci bien que le dépôt Mercurial contienne l'intégralité
827 de l'historique.
828 </para>
830 <para id="x_ab">Subversion est largement supporté par les outils
831 tierces. Mercurial est actuellement encore en retrait de ce point de
832 vue. L'écart se réduit néanmoins, en effet, certains des outils
833 graphiques sont maintenant supérieurs à leurs équivalents Subversion.
834 Comme Mercurial, Subversion dispose d'un excellent manuel
835 utilisateur.
836 </para>
838 <para id="x_ac">Parce que Subversion ne stocke pas l'historique chez
839 ses clients, il est parfaitement adapté à la gestion de projets qui
840 doivent suivre un ensemble de larges fichiers binaires et opaques. Si
841 vous suivez une cinquantaine de versions d'un fichier incompressible
842 de 10MB, l'occupation disque coté client d'un projet sous Subversion
843 restera à peu près constante. A l'inverse, l'occupation disque du
844 même projet sous n'importe lequel des gestionnaires de source
845 distribués grandira rapidement, proportionnellement aux nombres de
846 versions, car les différences entre chaque révisions seront très
847 grandes.
848 </para>
850 <para id="x_ad">En outre, c'est souvent difficile ou, généralement,
851 impossible de fusionner des différences dans un fichier binaire. La
852 capacité de Subversion de verrouiller des fichiers, pour permettre à
853 l'utilisateur d'être le seul à le mettre à jour
854 (<quote>commit</quote>) temporairement, est un avantage significatif
855 dans un projet doté de beaucoup de fichiers binaires.
856 </para>
858 <para id="x_ae">Mercurial peut importer l'historique depuis un dépôt
859 Subversion. Il peut aussi exporter l'ensemble des révisions d'un
860 projet vers un dépôt Subversion. Ceci rend très facile de
861 <quote>prendre la température</quote> et d'utiliser Mercurial et
862 Subversion en parallèle, avant de décider de migrer vers Mercurial.
863 La conversion de l'historique est incrémentale, donc vous pouvez
864 effectuer une conversion initiale, puis de petites additions par la
865 suite pour ajouter les nouvelle modifications.
866 </para>
869 </sect2>
870 <sect2>
871 <title>Git</title>
873 <para id="x_af">Git est un outil de gestion de source distribué qui fût
874 développé pour gérer le code source de noyau de Linux. Comme
875 Mercurial, sa conception initiale a été inspirée par Monotone.
876 </para>
878 <para id="x_b0">Git dispose d'un ensemble conséquent de commandes, avec
879 plus de 139 commandes individuelles pour la version 1.5.0. Il a aussi
880 la réputation d'être difficile à apprendre. Comparé à Git, le point
881 fort de Mercurial est clairement sa simplicité.
882 </para>
884 <para id="x_b1">En terme de performance, Git est extrêmement rapide.
885 Dans la plupart des cas, il est plus rapide que Mercurial, tout du
886 moins sur Linux, alors que Mercurial peut être plus performant sur
887 d'autres opérations. Néanmoins, sur Windows, les performances et le
888 niveau de support général fourni par Git, au moment de l'écriture de
889 cet ouvrage, est bien derrière celui de Mercurial.
890 </para>
892 <para id="x_b2">Alors que le dépôt Mercurial ne demande aucune
893 maintenance, un dépôt Git exige d'exécuter manuellement et
894 régulièrement la commande <quote>repacks</quote> sur ses métadonnées.
895 Sans ceci, les performances de git se dégradent et la consommation de
896 l'espace disque augmente rapidement. Un serveur qui contient
897 plusieurs dépôts Git qui ne sont pas régulièrement et fréquemment
898 <quote>repacked</quote> deviendra un vrai problème lors des
899 <quote>backups</quote> du disque, et il y eu des cas, où un
900 <quote>backup</quote> journalier pouvait durer plus de 24 heures. Un
901 dépôt fraichement <quote>repacked</quote> sera légèrement plus petit
902 qu'un dépôt Mercurial, mais un dépôt non <quote>repacked</quote> est
903 beaucoup plus grand.
904 </para>
906 <para id="x_b3">Le cœur de Git est écrit en C. La plupart des commandes
907 Git sont implémentées sous forme de scripts Shell ou Perl, et la
908 qualité de ces scripts varie grandement. J'ai plusieurs fois constaté
909 que certains de ces scripts étaient chargés en mémoire aveuglément et
910 que la présence d'erreurs pouvait s'avérer fatal.
911 </para>
913 <para id="x_b4">Mercurial peut importer l'historique d'un dépôt Git.</para>
915 </sect2>
916 <sect2>
917 <title>CVS</title>
919 <para id="x_b5">CVS est probablement l'outil de gestion de source le
920 plus utilisé aujourd'hui dans le monde. À cause de son manque de
921 clarté interne, il n'est plus maintenu depuis plusieurs années.
922 </para>
924 <para id="x_b6">Il a une architecture client/serveur centralisée. Il ne
925 regroupe pas les modifications de fichiers dans une opération de
926 <quote>commit</quote> atomique, ce qui permet à ses utilisateurs de
927 <quote>casser le <emphasis>build</emphasis></quote> assez facilement
928 : une personne peut effectuer une opération de <quote>commit</quote>
929 sans problème puis être bloquée par besoin de fusion, avec comme
930 conséquence néfaste, que les autres utilisateurs ne récupèreront
931 qu'une partie de ses modifications. Ce problème affecte aussi la
932 manière de travailler avec l'historique du projet. Si vous voulez
933 voir toutes les modifications d'une personne du projet, vous devrez
934 injecter manuellement les descriptions et les <emphasis remap="it">timestamps</emphasis> des modifications de chacun des
935 fichiers impliqués (si vous savez au moins quels sont ces fichiers).
936 </para>
938 <para id="x_b7">CVS a une notion étrange des <emphasis remap="it">tags</emphasis> et des branches que je n'essayerai même
939 pas de décrire ici. Il ne supporte pas bien les opérations de
940 renommage d'un fichier ou d'un répertoire, ce qui facilite la
941 corruption de son dépôt. Il n'a presque pas pour ainsi dire de
942 contrôle de cohérence interne, il est donc pratiquement impossible de
943 dire si un dépôt est corrompu ni à quel point. Je ne recommanderai
944 pas CVS pour un projet existant ou nouveau.
945 </para>
947 <para id="x_b8">Mercurial peut importer l'historique d'un projet CVS.
948 Néanmoins, il y a quelques principes à respecter; ce qui est vrai
949 aussi pour les autres outils d'import de projet CVS. À cause de
950 l'absence de <quote>commit</quote> atomique et gestion de version de
951 l'arborescence, il n'est pas possible de reconstruire de manière
952 précise l'ensemble de l'historique. Un travail de
953 <quote>devinette</quote> est donc nécessaire, et les fichiers
954 renommés ne sont pas détectés. Parce qu'une bonne part de
955 l'administration d'un dépôt CVS est effectuée manuellement, et est
956 donc, sujette à erreur, il est courant que les imports CVS
957 rencontrent de nombreux problèmes avec les dépôt corrompus (des
958 <emphasis remap="it">timestamps</emphasis> de révision complètement
959 buggés et des fichiers verrouillés depuis des années sont deux des
960 problèmes les moins intéressants dont je me souvienne).
961 </para>
963 <para id="x_b9">Mercurial peut importer l'historique depuis un dépôt CVS.
964 </para>
967 </sect2>
968 <sect2>
969 <title>Outils propriétaires</title>
971 <para id="x_ba">Perforce a une architecture client/serveur centralisée,
972 sans aucun mécanisme de mise en cache de données coté client.
973 Contrairement à la plupart des outils modernes de gestion de source,
974 Perforce exige de ses utilisateurs d'exécuter une commande pour
975 informer le serveur central de tout fichier qu'ils souhaitent
976 modifier.
977 </para>
979 <para id="x_bb">Les performances de Perforce sont plutôt bonnes pour
980 des petites équipes, mais elles s'effondrent rapidement lorsque le
981 nombre d'utilisateurs augmente au delà de la douzaine. Des
982 installations de Perforce assez larges nécessitent le déploiement de
983 proxies pour supporter la montée en charge associée.
984 </para>
986 </sect2>
987 <sect2>
988 <title>Choisir un outil de gestion de source</title>
990 <para id="x_bc">A l'exception de CVS, tous les outils listés ci-dessus
991 ont des forces qui leur sont propres et qui correspondent à certaines
992 formes de projet. Il n'y a pas un seul meilleur outil de gestion de
993 source qui correspondrait le mieux à toutes les situations.
994 </para>
996 <para id="x_bd">En guise exemple, Subversion est un très bon choix
997 lorsqu'on travaille avec beaucoup de fichiers binaires, qui évoluent
998 régulièrement, grâce à sa nature centralisée et sa capacité à
999 verrouiller des fichiers.
1000 </para>
1002 <para id="x_be">Personnellement, je préfère Mercurial pour sa
1003 simplicité, ses performances et sa bonne capacité de fusion, et il
1004 m'a très bien rendu service de plusieurs années maintenant.
1005 </para>
1007 </sect2>
1008 </sect1>
1009 <sect1>
1010 <title>Migrer depuis un outil à Mercurial</title>
1012 <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
1013 importer des révisions depuis différents autres outils de gestion de
1014 source. Par <quote>incrémental</quote>, j'entends que vous pouvez
1015 convertir l'historique entier du projet en une seule fois, puis
1016 relancer l'outil d'import plus tard pour obtenir les modifications
1017 effectuées depuis votre import initial.
1018 </para>
1020 <para id="x_c0">Les outils de gestion de source supportés par <literal role="hg-ext" moreinfo="none">convert</literal> sont :
1021 </para>
1022 <itemizedlist>
1023 <listitem><para id="x_c1">Subversion</para></listitem>
1024 <listitem><para id="x_c2">CVS</para></listitem>
1025 <listitem><para id="x_c3">Git</para></listitem>
1026 <listitem><para id="x_c4">Darcs</para></listitem>
1027 </itemizedlist>
1029 <para id="x_c5">En outre, <literal role="hg-ext" moreinfo="none">convert</literal> peut
1030 exporter les modifications depuis Mercurial vers Subversion. Ceci rend
1031 possible d'essayer Subversion en parallèle avant de choisir une
1032 solution définitive, sans aucun risque de perte de données.
1033 </para>
1035 <para id="x_c6">La commande <command role="hg-ext-conver" moreinfo="none">convert</command> est très simple à utiliser.
1036 Simplement, indiquez le chemin ou l'URL du dépôt de source, en lui
1037 indiquant éventuellement le nom du chemin de destination, et la
1038 conversion se met en route. Après cet import initial, il suffit de
1039 relancer la commande encore une fois pour importer les modifications
1040 effectuées depuis.
1041 </para>
1042 </sect1>
1044 <sect1>
1045 <title>Une courte histoire de la gestion de source</title>
1047 <para id="x_c7">Le plus célèbre des anciens outils de gestion de source
1048 est <emphasis remap="it">SCCS</emphasis> (Source Code Control System)},
1049 que Marc Rochkind conçu dans les laboratoires de recherche de Bell
1050 (<emphasis remap="it">Bell Labs</emphasis>), dans le début des années
1051 70. <emphasis remap="it">SCCS</emphasis> ne fonctionnait que sur des
1052 fichiers individuels, et obligeait chaque personne travaillant sur le
1053 projet d'avoir un accès à un répertoire de travail commun, sur le même
1054 système. Seulement une seule personne pouvait modifier un fichier au
1055 même moment, ce fonctionnement était assuré par l'utilisation de verrou
1056 (<quote>lock</quote>). Il était courant que des personnes verrouillent
1057 des fichiers, et plus tard, oublient de le déverrouiller ; empêchant
1058 n'importe qui d'autre de travailler sur ces fichiers sans l'aide de
1059 l'administrateur...
1060 </para>
1062 <para id="x_c8">Walter Tichy a développé une alternative libre à
1063 <emphasis remap="it">SCCS</emphasis> au début des années 80, qu'il
1064 nomma <emphasis remap="it">RCS (Revision Control System)</emphasis>.
1065 Comme <emphasis remap="it">SCCS</emphasis>, <emphasis remap="it">RCS</emphasis> demandait aux développeurs de travailler
1066 sur le même répertoire partagé, et de verrouiller les fichiers pour se
1067 prémunir de tout conflit issu de modifications concurrentes.
1068 </para>
1070 <para id="x_c9">Un peu plus tard dans les années 1980, Dick Grune utilisa
1071 <emphasis remap="it">RCS</emphasis> comme une brique de base pour un
1072 ensemble de scripts <emphasis remap="it">shell</emphasis> qu'il
1073 intitula cmt, avant de la renommer en <emphasis remap="it">CVS
1074 (Concurrent Versions System)</emphasis>. La grande innovation de CVS
1075 était que les développeurs pouvaient travailler simultanément et
1076 indépendamment dans leur propre espace de travail. Ces espaces de
1077 travail privés assuraient que les développeurs ne se marchent pas
1078 mutuellement sur les pieds, comme c'était souvent le cas avec RCS et
1079 SCCS. Tous les développeurs disposaient donc de leur copie de tous les
1080 fichiers du projet, et ils pouvaient donc librement les modifier. Ils
1081 devaient néanmoins effectuer la <quote>fusion</quote> (<emphasis remap="it"><quote>merge</quote></emphasis>) de leurs fichiers, avant
1082 d'effectuer le <quote>commit</quote> de leurs modifications sur le dépôt
1083 central.
1084 </para>
1086 <para>Brian Berliner reprit les scripts de Grune's et les réécrit en C,
1087 qu'il publia en 1989. Depuis, ce code a été modifié jusqu'à devenir la
1088 version moderne de CVS. CVS a acquis ainsi la capacité de fonctionner
1089 en réseau, transformant son architecture en client/serveur.
1090 L'architecture de CVS est centralisée, seul le serveur a une copie de
1091 l'historique du projet. L'espace de travail client ne contient qu'une
1092 copie de la dernière version du projet, et quelques métadonnées pour
1093 indiquer où le serveur se trouve. CVS a été un grand succès,
1094 aujourd'hui il est probablement l'outil de gestion de contrôle le plus
1095 utilisé au monde.
1096 </para>
1098 <para>Au début des années 1990, Sun Microsystems développa un premier
1099 outil de gestion de source distribué, nommé TeamWare. Un espace de
1100 travail TeamWare contient une copie complète de l'historique du projet.
1101 TeamWare n'a pas de notion de dépôt central. (CVS utilisait RCS pour le
1102 stockage de l'historique, TeamWare utilisait SCCS).
1103 </para>
1105 <para>Alors que les années 1990 avançaient, les utilisateurs ont pris
1106 conscience d'un certain nombre de problèmes avec CVS. Il enregistrait
1107 simultanément des modifications sur différents fichiers
1108 individuellement, au lieu de les regrouper dans une seule opération
1109 cohérente et atomique. Il ne gère pas bien sa hiérarchie de fichier, il
1110 est donc assez aisé de créer le chaos en renommant les fichiers et les
1111 répertoires. Pire encore, son code source est difficile à lire et à
1112 maintenir, ce qui agrandit largement le <quote>niveau de
1113 souffrance</quote> associé à la réparation de ces problèmes
1114 d'architecture de manière prohibitive.
1115 </para>
1117 <para>En 2001, Jim Blandy et Karl Fogel, deux développeurs qui avaient
1118 travaillé sur CVS, initièrent un projet pour le remplacer par un outil
1119 qui aurait une meilleure architecture et un code plus propre. Le
1120 résultat, Subversion, ne quitte pas le modèle centralisé et
1121 client/server de CVS, mais ajoute les opérations de
1122 <quote>commit</quote> atomique sur de multiples fichiers, une meilleure
1123 gestion des espaces de noms, et d'autres fonctionnalités qui en font un
1124 meilleur outil que CVS. Depuis sa première publication, il est
1125 rapidement devenu très populaire.
1126 </para>
1128 <para>Plus ou moins simultanément, Graydon Hoare a commencé sur
1129 l'ambitieux système de gestion distribué Monotone. Bien que Monotone
1130 corrige plusieurs défauts de CVS tout en offrant une architecture
1131 <quote>peer-to-peer</quote>, il va aussi plus loin que la plupart des
1132 outils de révision de manière assez innovante. Il utilise des
1133 <quote>hashs</quote> cryptographiques comme identifiants, et il a une
1134 notion complète de <quote>confiance</quote> du code issu des
1135 différentes sources.
1136 </para>
1138 <para>Mercurial est né en 2005. Bien que très influencé par Monotone,
1139 Mercurial se concentre sur la facilité d'utilisation, les performances
1140 et la capacité à monter en charge pour de très gros projets.
1141 </para>
1143 </sect1>
1145 </chapter>
1147 <!--
1148 local variables:
1149 sgml-parent-document: ("00book.xml" "book" "chapter")
1150 end:
1151 -->
1153 <!-- BEGIN ch02 -->
1154 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
1156 <chapter id="chap:tour-basic">
1157 <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?>
1158 <title>Une rapide présentation de Mercurial : les bases</title>
1160 <sect1>
1161 <title>Installer Mercurial sur votre système</title>
1163 <para id="x_1">Des paquetages binaires de Mercurial sont disponibles pour la
1164 plupart des systèmes d'exploitation, ce qui rend facile l'utilisation
1165 immédiate de Mercurial sur votre ordinateur.</para>
1167 <sect2>
1168 <title>Windows</title>
1170 <para id="x_c">La meilleur version de Mercurial pour Windows est
1171 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>.
1172 Ce logiciel n'a aucune dépendance exterieure; il fonctionne <quote>et
1173 c'est tout</quote>. Il fournit aussi bien les outils en ligne de
1174 commmande qu'une interface graphique.</para>
1176 </sect2>
1178 <sect2>
1179 <title>Mac OS X</title>
1181 <para id="x_a">Lee Cantey publie un installeur de Mercurial pour Mac OS
1182 X sur <ulink url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para>
1183 </sect2>
1185 <sect2>
1186 <title>Linux</title>
1188 <para id="x_2">Parce que chaque distribution de Linux a ses propres
1189 outils de gestion de paquets, politiques et rythmes de
1190 développements, il est difficile de donner un ensemble
1191 d'instructions unique pour installer les binaires de Mercurial. La
1192 version de Mercurial avec laquelle vous vous retrouverez dépendra
1193 grandement de l'activité de la personne en charge du paquetage pour
1194 la distribution.</para>
1196 <para id="x_3">Pour rester simple, je me concentrerai sur
1197 l'installation de Mercurial en ligne de commande, sous les
1198 distributions les plus courantes. La plupart des distributions
1199 fournissent des gestionnaires graphiques de paquetage qui vous
1200 permettront d'installer Mercurial en quelques clicks. Le paquetage
1201 devrait se nommer <literal moreinfo="none">mercurial</literal>.</para>
1203 <itemizedlist>
1204 <listitem><para id="x_4">Ubuntu et Debian:</para>
1205 <programlisting format="linespecific">apt-get install mercurial</programlisting></listitem>
1206 <listitem><para id="x_5">Fedora:</para>
1207 <programlisting format="linespecific">yum install mercurial</programlisting></listitem>
1208 <listitem><para id="x_6">Gentoo:</para>
1209 <programlisting format="linespecific">emerge mercurial</programlisting></listitem>
1210 <listitem><para id="x_715">OpenSUSE:</para>
1211 <programlisting format="linespecific">zypper install
1212 mercurial</programlisting></listitem>
1213 </itemizedlist>
1215 </sect2>
1216 <sect2>
1217 <title>Solaris</title>
1219 <para id="x_09">SunFreeWare, à <ulink url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>,
1220 fournit des paquets précompilés pour Mercurial.</para>
1221 </sect2>
1222 </sect1>
1224 <sect1>
1225 <title>Commencer à utiliser Mercurial</title>
1227 <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
1228 installé proprement. Les informations affichées sur la version ne sont
1229 pas réellement importantes en soit, c'est surtout de savoir si elles
1230 s'affichent qui nous intéresse.</para>
1232 <!-- BEGIN tour.version -->
1233 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg version</userinput>
1234 Mercurial Distributed SCM (version 1.2.1)
1236 Copyright (C) 2005-2009 Matt Mackall <mpm@selenic.com> and others
1237 This is free software; see the source for copying conditions. There is NO
1238 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
1239 </screen>
1240 <!-- END tour.version -->
1243 <sect2>
1244 <title>L'aide intégrée</title>
1246 <para id="x_f">Mercurial fournit un système d'aide intégré, ce qui est
1247 inestimable quand vous vous retrouvez coincé à essayer de vous
1248 rappeler comment lancer une commande. Si vous êtes bloqué, exécutez
1249 simplement <command role="hg-cmd" moreinfo="none">hg help</command>; elle affichera
1250 une brève liste des commandes, avec une description pour chacune. Si
1251 vous demandez de l'aide sur une commande spécifique (voir
1252 ci-dessous), elle affichera des informations plus détaillées.</para>
1254 <!-- BEGIN tour.help -->
1255 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg help init</userinput>
1256 hg init [-e CMD] [--remotecmd CMD] [DEST]
1258 create a new repository in the given directory
1260 Initialize a new repository in the given directory. If the given
1261 directory does not exist, it is created.
1263 If no directory is given, the current directory is used.
1265 It is possible to specify an ssh:// URL as the destination.
1266 See 'hg help urls' for more information.
1268 options:
1270 -e --ssh specify ssh command to use
1271 --remotecmd specify hg command to run on the remote side
1273 use "hg -v help init" to show global options
1274 </screen>
1275 <!-- END tour.help -->
1278 <para id="x_10">Pour un niveau d'informations encore plus détaillé
1279 (ce dont vous aurez rarement besoin), exécuter <command role="hg-cmd" moreinfo="none">hg
1280 help <option role="hg-opt-global">-v</option></command>. L'option
1281 <option role="hg-opt-global">-v</option> est l'abréviation de
1282 <option role="hg-opt-global">--verbose</option>, et indique à Mercurial
1283 d'ficher plus d'informations que d'habitude.</para>
1285 </sect2>
1286 </sect1>
1287 <sect1>
1288 <title>Travailler avec un dépôt</title>
1290 <para id="x_11">Avec Mercurial, tout se déroule au sein du
1291 <emphasis>dépôt</emphasis>. Le dépôt d'un projet contient tous
1292 les fichiers qui <quote>appartiennent</quote> au projet.</para>
1294 <para id="x_12">Il n'y a rien de particulièrement magique au sujet de
1295 ce dépôt, c'est simplement une arborescence sur votre système de fichiers
1296 que Mercurial traite de manière spéciale. Vous pouvez renommer ou effacer
1297 ce répertoire à n'impporte quel moment, en utilisant la ligne de commande
1298 ou votre explorateur de fichiers.</para>
1300 <sect2>
1301 <title>Faire une copie locale de votre dépôt</title>
1303 <para id="x_13"><emphasis>Copier</emphasis> un dépôt est juste un
1304 peu spécial. Bien que vous puissiez utiliser une commande habituelle de
1305 copie pour copier votre dépôt, il vaut mieux utiliser une commande fournie par
1306 Mercurial. Cette commande est appelée <command role="hg-cmd" moreinfo="none">hg clone</command>,
1307 car elle crée une copie identique à un dépôt existant.</para>
1309 <!-- BEGIN tour.clone -->
1310 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone http://hg.serpentine.com/tutorial/hello</userinput>
1311 destination directory: hello
1312 requesting all changes
1313 adding changesets
1314 adding manifests
1315 adding file changes
1316 added 5 changesets with 5 changes to 2 files
1317 updating working directory
1318 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
1319 </screen>
1320 <!-- END tour.clone -->
1323 <para id="x_67c">Un avantage de la commande <command role="hg-cmd" moreinfo="none">hg
1324 clone</command> est que, comme nous l'avons vu ci dessus, elle nous
1325 permet de faire de cloner les dépôts à travers le réseau. Un autre
1326 est qu'elle se rappelle d'où a été cloné un dépôt, ce qui est utile
1327 quand on veut mettre à jour le clone.</para>
1329 <para id="x_14">Si votre opération de clonage réussit, vous devriez maintenant
1330 avoir un répertoire local appelé <filename class="directory" moreinfo="none">hello</filename>.
1331 Ce répertoire contiendra quelques fichiers.</para>
1333 <!-- BEGIN tour.ls -->
1334 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls -l</userinput>
1335 total 4
1336 drwxr-xr-x 3 rpelisse rpelisse 4096 Aug 16 14:05 hello
1337 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls hello</userinput>
1338 Makefile hello.c
1339 </screen>
1340 <!-- END tour.ls -->
1343 <para id="x_15">Ces fichiers ont le même contenu et historique dans votre dépôt
1344 qu'ils ont dans le dépôt que vous avez cloné.</para>
1346 <para id="x_16">Chaque dépôt Mercurial est complet, autonome et
1347 indépendant. Il contient sa propre copie privée des fichiers du
1348 projet et de leur historique. Le clone d'un dépôt se souvient de la
1349 localisation du dépôt à partir duquel il a été clôné, mais il ne
1350 communique pas avec ce dernier, ou un autre, à moins que vous ne lui
1351 demandiez.</para>
1353 <para id="x_17">Ce que tout ceci signifie pour le moment est que nous
1354 sommes libres d'expérimenter avec ce dépôt, confiants dans le fait
1355 qu'il s'agit d'un <quote>bac à sable</quote> qui n'affectera personne
1356 d'autre.</para>
1358 </sect2>
1359 <sect2>
1360 <title>Quel est le contenu d'un dépôt ?</title>
1362 <para id="x_18">Prêtons plus attention un instant au contenu d'un dépôt.
1363 Nous voyons qu'il contient un répertoire nommé <filename class="directory" moreinfo="none">.hg
1364 </filename>. C'est ici que Mercurial conserve toutes ses
1365 métadonnées.</para>
1367 <!-- BEGIN tour.ls-a -->
1368 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd hello</userinput>
1369 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls -a</userinput>
1370 . .. .hg Makefile hello.c
1371 </screen>
1372 <!-- END tour.ls-a -->
1375 <para id="x_19">Le contenu du répertoire <filename class="directory" moreinfo="none">.hg
1376 </filename> et ses sous répertoires sont les seuls propres à Mercurial.
1377 Tous les autres fichiers et répertoires dans le dépôt sont à vous, et
1378 vous pouvez en faire ce que vous voulez.</para>
1380 <para id="x_1a">Pour introduire un peu de terminologie, le répertoire
1381 <filename class="directory" moreinfo="none">.hg</filename> est un <quote>vrai</quote>
1382 dépôt, et tous les fichiers et les répertoires qui coexistent avec lui,
1383 sont désignés sous le nom <emphasis>espace de travail</emphasis>. Une
1384 manière facile de se rappeler cette distinction est de retenir que le
1385 <emphasis>dépôt</emphasis> contient l'<emphasis>historique</emphasis>
1386 de votre projet, alors que l'<emphasis>espace de travail</emphasis>
1387 contient un "<emphasis>snapshot</emphasis>" de votre projet à un certain
1388 point de son historique.</para>
1390 </sect2>
1391 </sect1>
1392 <sect1>
1393 <title>Une promenade dans l'historique</title>
1395 <para id="x_1b">Une des premières choses que vous aurez envie
1396 de faire avec un nouveau dépôt, sera de comprendre son historique.
1397 La commande <command role="hg-cmd" moreinfo="none">hg log</command> vous donne une
1398 vue de l'historique.</para>
1400 <!-- BEGIN tour.log -->
1401 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log</userinput>
1402 changeset: 4:2278160e78d4
1403 tag: tip
1404 user: Bryan O'Sullivan <bos@serpentine.com>
1405 date: Sat Aug 16 22:16:53 2008 +0200
1406 summary: Trim comments.
1408 changeset: 3:0272e0d5a517
1409 user: Bryan O'Sullivan <bos@serpentine.com>
1410 date: Sat Aug 16 22:08:02 2008 +0200
1411 summary: Get make to generate the final binary from a .o file.
1413 changeset: 2:fef857204a0c
1414 user: Bryan O'Sullivan <bos@serpentine.com>
1415 date: Sat Aug 16 22:05:04 2008 +0200
1416 summary: Introduce a typo into hello.c.
1418 changeset: 1:82e55d328c8c
1419 user: mpm@selenic.com
1420 date: Fri Aug 26 01:21:28 2005 -0700
1421 summary: Create a makefile
1423 changeset: 0:0a04b987be5a
1424 user: mpm@selenic.com
1425 date: Fri Aug 26 01:20:50 2005 -0700
1426 summary: Create a standard "hello, world" program
1428 </screen>
1429 <!-- END tour.log -->
1432 <para id="x_1c">Par défaut, cette commande affiche à l'écran un bref paragraphe pour chaque
1433 révision enregistrée pour ce projet. Dans la terminologie de Mercurial, nous
1434 appelons chacun de ces évènements enregistrés un <emphasis>changeset</emphasis>, parce
1435 qu'il contient un ensemble de modifications sur plusieurs fichiers.</para>
1437 <para id="x_1d">La commande <command role="hg-cmd" moreinfo="none">hg log</command> affiche
1438 ainsi ces informations :</para>
1440 <itemizedlist>
1441 <listitem><para id="x_1e"><literal moreinfo="none">changeset</literal> : Ce champ contient
1442 un nombre, séparé par deux points (:), d'une chaine hexadécimale. Il
1443 s'agit en fait d'<emphasis>identifiants</emphasis> d'un changeset. Il y a
1444 deux identifiants car le numéro de la révision est plus court et plus à
1445 facile à saisir qu'une séquence hexadécimale.</para>
1446 </listitem>
1447 <listitem><para id="x_1f"><literal moreinfo="none">user</literal> : L'identité de la personne
1448 qui a créée ce %%% laisser le terme anglais car il sera affiché
1449 changeset. C'est un champ libre de forme, mais la plupart du
1450 temps il contient le nom et l'email de la personne.</para>
1451 </listitem>
1452 <listitem><para id="x_20"><literal moreinfo="none">date</literal> : La date et l'heure à
1453 laquelle le \textit{changeset} a été créé, ainsi que le fuseau horaire dans
1454 lequelle il a été créé. (La date et l'heure sont locales à ce
1455 \textit{fuseau}, elles indiquent donc quelle date et heure il était
1456 pour la personne qui a créé ce changeset.</para>
1457 </listitem>
1458 <listitem><para id="x_21"><literal moreinfo="none">résumé</literal>: La première ligne du
1459 message que le créateur a associé à son changeset pour le décrire.</para>
1460 </listitem>
1461 <listitem><para id="x_67d">Certains changesets, comme le premier de la
1462 liste ci-dessus ont un champ <literal moreinfo="none">tag</literal>. Le tag est une autre
1463 façon d'identifier un changeset en lui donnant un nom simple à retenir.
1464 (Le tag nommé <literal moreinfo="none">tip</literal> est spécial : il fait toujours
1465 référence aux derniers changements dans le dépôt.)</para></listitem>
1466 </itemizedlist>
1468 <para id="x_22">Par défaut, la commande <command role="hg-cmd" moreinfo="none">hg log</command>
1469 n'affiche qu'un résumé, il manque beaucoup de détails.</para>
1471 <para id="x_23">La figure <xref linkend="fig:tour-basic:history"/> fournit une
1472 représentation graphique de l'historique du dépôt <filename class="directory" moreinfo="none">hello
1473 </filename>, pour rendre plus facile de voir dans quelle direction
1474 l'historique se <quote>déroule</quote>. Nous reviendrons régulièrement
1475 sur cette représentation dans ce chapitre et ceux qui suivent.</para>
1478 <figure id="fig:tour-basic:history" float="0">
1479 <title>Graphical history of the <filename class="directory" moreinfo="none">hello</filename> repository</title>
1480 <mediaobject>
1481 <imageobject><imagedata fileref="figs/tour-history.png"/></imageobject>
1482 <textobject><phrase>XXX add text</phrase></textobject>
1483 </mediaobject>
1484 </figure>
1487 <sect2>
1488 <title>Changesets, révisions, et collaboration</title>
1490 <para id="x_25">Comme l'anglais est réputé pour être un langage maladroit,
1491 et que l'informatique est la source de bien des erreurs de terminologie
1492 (pourquoi utiliser un seul terme quand quatre feront l'affaire ?), la
1493 gestion de version a une variété de mots et de phrases qui veulent dire
1494 la même chose. Si vous discutez d'historique de Mercurial avec d'autres
1495 personnes, vous constaterez que souvent, le mot <quote>changeset</quote>
1496 est contracté simplement en <quote>change</quote> ou (à l'écrit)
1497 <quote>cset</quote>, et même parfois un changeset
1498 <quote>révision</quote>, abrégé en <quote>rev</quote>.</para>
1500 <para id="x_26">Bien que le <emphasis>mot</emphasis> que vous utilisez pour
1501 désigner le concept de changeset importe peu, l'<emphasis>identifiant</emphasis>
1502 que vous utilisez pour désigner un <emphasis>changeset</emphasis> spécifique
1503 a une grande importance. Rappelez vous que le champ changeset affiché par la
1504 commande <command role="hg-cmd" moreinfo="none">hg log</command> identifie un changeset à
1505 la fois avec un numéro de révision et une séquence hexadécimale.</para>
1507 <itemizedlist>
1508 <listitem><para id="x_27">Le numéro de révision est <emphasis>seulement
1509 valable dans ce dépôt</emphasis>,</para></listitem>
1510 <listitem><para id="x_28">La séquence hexadécimale est un
1511 <emphasis>identifiant permanent, et invariant</emphasis> qui
1512 pourra toujours être associé au changeset exact de <emphasis>chaque</emphasis>
1513 copie de votre dépôt.</para></listitem></itemizedlist>
1515 <para id="x_29">La distinction est importante. Si vous envoyez un email
1516 à quelqu'un en parlant de la <quote>révision 33</quote>, il est très
1517 probable que sa révision 33 <emphasis>ne sera pas la même</emphasis>
1518 que la votre. La raison de ceci est que le numéro de révision dépend
1519 de l'ordre dans lequel les modifications sont arrivées dans le dépôt,
1520 et il n'y a aucune garantie que les mêmes changements soient arrivés
1521 dans le même ordre dans différents dépôts. Trois modifications
1522 <literal moreinfo="none">a,b,c</literal> peuvent aisément apparaitre dans un dépôt
1523 comme <literal moreinfo="none">0,1,2</literal>, et dans un autre comme <literal moreinfo="none">0,2,1
1524 </literal>.</para>
1526 <para id="x_2a">Mercurial utilise les numéros de révision uniquement comme des raccourcis
1527 pratiques. Si vous devez discuter d'un \textit{changeset} avec quelqu'un,
1528 ou identifer un \textit{changeset} pour une quelconque raison (par exemple,
1529 un rapport de \textit{bug}), utilisez la séquence hexadécimale.</para>
1531 </sect2>
1532 <sect2>
1533 <title>Afficher une révision spécifique</title>
1535 <para id="x_2b">Pour réduire la sortie de <command role="hg-cmd" moreinfo="none">hg log
1536 </command> à une seule révision, utilisez l'option <option role="hg-opt-log">-r
1537 </option> (ou <option role="hg-opt-log">--rev</option>). Vous pouvez utiliser
1538 le numéro de révision ou la séquence hexadécimale comme identifiant, et
1539 demander autant de révisions que vous le souhaitez.</para>
1541 <!-- BEGIN tour.log-r -->
1542 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r 3</userinput>
1543 changeset: 3:0272e0d5a517
1544 user: Bryan O'Sullivan <bos@serpentine.com>
1545 date: Sat Aug 16 22:08:02 2008 +0200
1546 summary: Get make to generate the final binary from a .o file.
1548 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r 0272e0d5a517</userinput>
1549 changeset: 3:0272e0d5a517
1550 user: Bryan O'Sullivan <bos@serpentine.com>
1551 date: Sat Aug 16 22:08:02 2008 +0200
1552 summary: Get make to generate the final binary from a .o file.
1554 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r 1 -r 4</userinput>
1555 changeset: 1:82e55d328c8c
1556 user: mpm@selenic.com
1557 date: Fri Aug 26 01:21:28 2005 -0700
1558 summary: Create a makefile
1560 changeset: 4:2278160e78d4
1561 tag: tip
1562 user: Bryan O'Sullivan <bos@serpentine.com>
1563 date: Sat Aug 16 22:16:53 2008 +0200
1564 summary: Trim comments.
1566 </screen>
1567 <!-- END tour.log-r -->
1570 <para id="x_2c">Si vous voulez voir l'historique de plusieurs révisions
1571 sans avoir à les énumérer, vous pouvez utiliser la <emphasis>intervalle
1572 de numérotation</emphasis> qui vous permet d'exprimer l'idée <quote>je
1573 veux toutes les révisions entre $a$ et $b$, inclus</quote></para>
1575 <!-- BEGIN tour.log.range -->
1576 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r 2:4</userinput>
1577 changeset: 2:fef857204a0c
1578 user: Bryan O'Sullivan <bos@serpentine.com>
1579 date: Sat Aug 16 22:05:04 2008 +0200
1580 summary: Introduce a typo into hello.c.
1582 changeset: 3:0272e0d5a517
1583 user: Bryan O'Sullivan <bos@serpentine.com>
1584 date: Sat Aug 16 22:08:02 2008 +0200
1585 summary: Get make to generate the final binary from a .o file.
1587 changeset: 4:2278160e78d4
1588 tag: tip
1589 user: Bryan O'Sullivan <bos@serpentine.com>
1590 date: Sat Aug 16 22:16:53 2008 +0200
1591 summary: Trim comments.
1593 </screen>
1594 <!-- END tour.log.range -->
1597 <para id="x_2d">Mercurial respecte aussi l'ordre dans lequel vous spécifiez
1598 les révisions, ainsi <command role="hg-cmd" moreinfo="none">hg log -r 2:4</command>
1599 affichera <literal moreinfo="none">2,3,4</literal> alors que <command role="hg-cmd" moreinfo="none">hg
1600 log -r 4:2</command> affichera <literal moreinfo="none">4,3,2</literal>.</para>
1602 </sect2>
1603 <sect2>
1604 <title>Informations détaillées</title>
1606 <para id="x_2e">Le résumé affiché par <command role="hg-cmd" moreinfo="none">hg log</command>
1607 est suffisant si vous savez déjà ce que vous cherchez. En
1608 revanche, vous aurez probablement besoin de voir une description
1609 complète du changement, ou une liste des fichiers modifiés si vous
1610 cherchez à déterminer qu'un changeset est bien celui que vous
1611 recherchez. L'option \hgopt{-v} de la commande <command role="hg-cmd" moreinfo="none">hg
1612 log</command> (ou <option role="hp-opt-global">--verbose</option>) vous
1613 donne ces informations supplémentaires.</para>
1615 <!-- BEGIN tour.log-v -->
1616 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -v -r 3</userinput>
1617 changeset: 3:0272e0d5a517
1618 user: Bryan O'Sullivan <bos@serpentine.com>
1619 date: Sat Aug 16 22:08:02 2008 +0200
1620 files: Makefile
1621 description:
1622 Get make to generate the final binary from a .o file.
1625 </screen>
1626 <!-- END tour.log-v -->
1629 <para id="x_2f">Si vous voulez voir à la fois la description
1630 et le contenu d'une modification, ajouter l'option <option role="hg-opt-log">-p</option> (ou <option role="hg-opt-log">
1631 --patch</option>). Ceci affiche le contenu d'une modification
1632 comme un <emphasis>diff unifié</emphasis>
1633 <!-- \footnote{NdT: \textit{unified diff}} -->
1634 (si vous n'avez jamais vu de diff unifié avant, consultez la
1635 section <xref linkend="sec:mq:patch"/> pour un rapide
1636 survol).</para>
1638 <!-- BEGIN tour.log-vp -->
1639 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -v -p -r 2</userinput>
1640 changeset: 2:fef857204a0c
1641 user: Bryan O'Sullivan <bos@serpentine.com>
1642 date: Sat Aug 16 22:05:04 2008 +0200
1643 files: hello.c
1644 description:
1645 Introduce a typo into hello.c.
1648 diff -r 82e55d328c8c -r fef857204a0c hello.c
1649 --- a/hello.c Fri Aug 26 01:21:28 2005 -0700
1650 +++ b/hello.c Sat Aug 16 22:05:04 2008 +0200
1651 @@ -11,6 +11,6 @@
1653 int main(int argc, char **argv)
1654 {
1655 - printf("hello, world!\n");
1656 + printf("hello, world!\");
1657 return 0;
1658 }
1660 </screen>
1661 <!-- END tour.log-vp -->
1664 <para id="x_67e">L'option <option role="hg-opt-log">-p</option> est
1665 incroyablement utile, il est donc important dans s'en rappeller.</para>
1667 </sect2>
1668 </sect1>
1669 <sect1>
1670 <title>Tout sur les options de commandes</title>
1672 <para id="x_30">Avant d'aller plus loin sur le fonctionnement
1673 des commandes de Mercurial, étudions un moment comment elles
1674 fonctionnent de manière générale. Vous trouverez ça probablement
1675 utile pour la suite de notre parcours.</para>
1677 <para id="x_31">Mercurial utilise une approche directe et cohérente
1678 pour interpréter les options que vous passez aux commandes. Il suit une
1679 convention commune à la plupart des systèmes Unix et Linux modernes.</para>
1681 <itemizedlist>
1682 <listitem><para id="x_32">Chaque option a un nom complet. Par exemple,
1683 comme nous l'avons déjà vu, la commande <command role="hg-cmd" moreinfo="none">hg
1684 log</command> accepte l'option <option role="hg-opt-log">--rev
1685 </option>.</para>
1686 </listitem>
1687 <listitem><para id="x_33">La plupart des options disposent de
1688 noms abrégés. Aussi, au lieu d'utiliser <option role="hg-opt-log">--rev
1689 </option>, vous pouvez utiliser <option role="hg-opt-log">-r</option>.
1690 (Les options qui n'ont pas de noms abrégés sont généralement
1691 rarement utilisées).</para>
1692 </listitem>
1693 <listitem><para id="x_34">Les noms complets commencent par deux
1694 tirets (i.e. <option role="hg-opt-log">--rev</option>),
1695 alors que les options courtes commencent avec un seul (i.e.
1696 <option role="hg-opt-log">-r</option>).</para>
1697 </listitem>
1698 <listitem><para id="x_35">Les noms des options sont cohérents
1699 entre les commandes. Par exemple, chaque commande qui accepte
1700 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
1701 </option> comme arguments.</para>
1702 </listitem>
1703 </itemizedlist>
1705 <para id="x_36">Dans les exemples de ce livre, j'utilise les noms abrégés
1706 plutôt que les noms complets. Ceci est une préférence personnelle, pas
1707 une recommandation.</para>
1709 <para id="x_37">La plupart des commandes qui affichent une quelconque sortie
1710 à l'écran, afficheront davantage avec l'option <option role="hg-opt-global">
1711 -v</option> (ou <option role="hg-opt-global">--verbose</option>), et
1712 moins avec l'option <option role="hg-opt-global">-q</option> (ou
1713 <option role="hg-opt-global">--quiet</option>).</para>
1715 <note>
1716 <title>Option naming consistency</title>
1718 <para id="x_680">Presque toujours, les commandes de Mercurial utilisent
1719 des noms d'options cohérentes pour référer à des concepts identiques.
1720 Par exemple, si une commande concerne les changesets, vous les
1721 identifierez toujours avec l'option <option role="hg-opt-log">-r</option>.
1722 Cette utilisation cohérente des noms d'options permet de mémoriser plus
1723 facilement quelles options accepte une commande.</para>
1724 </note>
1727 </sect1>
1728 <sect1>
1729 <title>Faire et vérifier des modifications</title>
1731 <para id="x_38">Maintenant que nous avons une bonne idée des
1732 commandes pour consulter l'historique de Mercurial, regardons
1733 comment faire des modifications et les examiner.</para>
1735 <para id="x_39">La première chose que nous allons faire c'est isoler notre
1736 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
1737 une copie de dépôt distant. Comme nous avons déjà une copie locale, nous
1738 pouvons juste faire un clone de celle-ci à la place. C'est beaucoup plus
1739 rapide que de faire une copie à travers le réseau, et un dépôt cloné
1740 localement prend également moins d'espace disque<footnote>
1741 <para id="x_681">L'économie d'espace disque apparait clairement quand les
1742 dépôts source et destination sont sur le même système de fichier, où, dans
1743 ce cas, Mercurial utilisera des liens physiques pour effectuer des partages
1744 copie-lors-des-écritures de ses métadonnées internes. Si cette explication
1745 ne signifie rien pour vous, ne vous inquietez pas : tout ceci se passe de
1746 manière transparente et automatiquement. Vous n'avez pas du tout besoin de
1747 comprendre ceci.</para></footnote>.</para>
1749 <!-- BEGIN tour.reclone -->
1750 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
1751 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone hello my-hello</userinput>
1752 updating working directory
1753 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
1754 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-hello</userinput>
1755 </screen>
1756 <!-- END tour.reclone -->
1759 <para id="x_3a">On notera au passage qu'il est souvent considéré comme
1760 une bonne pratique de conserver une copie <quote>immaculée</quote>
1761 du dépôt distant, à partir de laquelle vous pourrez faire des
1762 copies locales temporaires pour créer des <quote>bacs à sable</quote>
1763 pour chaque tâche sur laquelle vous souhaitez travailler. Ceci
1764 vous permet de travailler sur plusieurs choses en parallèle,
1765 chacune isolée les unes des autres en attendant que ces tâches
1766 soient finies et que vous soyez prêt à les réintégrer. Parce
1767 que les copies locales sont peu coûteuses, il est très rapide
1768 de créer ou détruire des dépôts dès que vous n'en avez plus
1769 besoin.</para>
1771 <para id="x_3b">Dans notre dépôt <filename class="directory" moreinfo="none">my-hello</filename>, nous avons un fichier
1772 <filename moreinfo="none">hello.c</filename> qui contient le classique <quote>hello,
1773 world</quote>.</para>
1775 <!-- BEGIN tour.cat1 -->
1776 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat hello.c</userinput>
1777 /*
1778 * Placed in the public domain by Bryan O'Sullivan. This program is
1779 * not covered by patents in the United States or other countries.
1780 */
1782 #include <stdio.h>
1784 int main(int argc, char **argv)
1785 {
1786 printf("hello, world!\");
1787 return 0;
1788 }
1789 </screen>
1790 <!-- END tour.cat1 -->
1793 <para id="x_682">Editons ce fichier pour qu'il affiche une autre ligne
1794 sur la sortie standard.</para>
1796 <!-- BEGIN tour.cat2 -->
1797 <screen format="linespecific"># ... edit edit edit ...
1798 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat hello.c</userinput>
1799 /*
1800 * Placed in the public domain by Bryan O'Sullivan. This program is
1801 * not covered by patents in the United States or other countries.
1802 */
1804 #include <stdio.h>
1806 int main(int argc, char **argv)
1807 {
1808 printf("hello, world!\");
1809 printf("hello again!\n");
1810 return 0;
1811 }
1812 </screen>
1813 <!-- END tour.cat2 -->
1816 <para id="x_3c">La commande Mercurial <command role="hg-cmd" moreinfo="none">hg
1817 status</command> nous dira ce que Mercurial sait des fichiers du
1818 dépôts.</para>
1820 <!-- BEGIN tour.status -->
1821 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls</userinput>
1822 Makefile hello.c
1823 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
1824 M hello.c
1825 </screen>
1826 <!-- END tour.status -->
1829 <para id="x_3d">La commande <command role="hg-cmd" moreinfo="none">hg status</command>
1830 n'affichera pas le contenu des fichiers, mais une ligne commençant par
1831 <quote><literal moreinfo="none">M</literal></quote> pour <filename moreinfo="none">hello.c</filename>.
1832 A moins que vous lui demandiez, la commande <command role="hg-cmd" moreinfo="none">hg
1833 status</command> n'affichera aucune information sur les fichiers que
1834 vous n'avez pas modifiés.</para>
1836 <para id="x_3e">Le <quote><literal moreinfo="none">M</literal></quote> indique que
1837 Mercurial a remarqué que nous avons modifié le fichier
1838 <filename moreinfo="none">hello.c</filename>. Nous n'avons pas besoin
1839 <emphasis>d'informer</emphasis> Mercurial que nous allons modifier un
1840 fichier avant de commencer à le faire, ou que nous avons modifié un
1841 fichier après avoir commencé à le faire, il est capable de découvrir ça
1842 tout seul. </para>
1844 <para id="x_3f">C'est déjà pratique de savoir que nous avons modifié le
1845 fichier <filename moreinfo="none">hello.c</filename>, mais nous préférerions savoir
1846 exactement <emphasis>ce que</emphasis> nous avons changé. Pour ceci, nous
1847 utilisons la commande <command role="hg-cmd" moreinfo="none">hg diff</command>.</para>
1849 <!-- BEGIN tour.diff -->
1850 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
1851 diff -r 2278160e78d4 hello.c
1852 --- a/hello.c Sat Aug 16 22:16:53 2008 +0200
1853 +++ b/hello.c Sun Aug 16 14:05:26 2009 +0000
1854 @@ -8,5 +8,6 @@
1855 int main(int argc, char **argv)
1856 {
1857 printf("hello, world!\");
1858 + printf("hello again!\n");
1859 return 0;
1860 }
1861 </screen>
1862 <!-- END tour.diff -->
1865 <tip>
1866 <title>Comprendre les patches</title>
1868 <para id="x_683">Penser à jeter un oeil à <xref linkend="sec:mq:patch"/> si vous n'arrivez pas à lire la sortie
1869 ci-dessus.</para>
1870 </tip>
1871 </sect1>
1872 <sect1>
1873 <title>Enregister vos modifications dans une nouvelle révision</title>
1875 <para id="x_40">Nous pouvons modifier des fichiers, compiler et tester
1876 nos modifications, et utiliser les commandes <command role="hg-cmd" moreinfo="none">hg
1877 status</command> et <command role="hg-cmd" moreinfo="none">hg diff</command> pour
1878 voir les modifications effectuées, jusqu'à ce que nous soyons assez
1879 satisfaits pour décider d'enregistrer notre travail dans un
1880 \textit{changeset}.</para>
1882 <para id="x_41">La commande <command role="hg-cmd" moreinfo="none">hg commit</command>
1883 vous laisse créer une nouvelle révision, nous désignerons généralement
1884 cette opération par <quote>faire un commit</quote> ou
1885 <quote>committer</quote>.</para>
1887 <sect2>
1888 <title>Définir le nom d'utilisateur</title>
1890 <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
1891 pas garanti qu'elle réussisse du premier coup. En effet, Mercurial
1892 enregistre votre nom et votre adresse avec chaque modification que
1893 vous effectuez, de manière à ce que vous soyez capable (ou d'autres
1894 le soient) de savoir qui a fait quelle modification. Mercurial essaye
1895 automatiquement de découvrir un nom d'utilisateur qui ait un minimum
1896 de sens pour effectuer l'opération de commit avec. Il va essayer
1897 chacune des méthodes suivantes, dans l'ordre :</para>
1899 <orderedlist inheritnum="ignore" continuation="restarts">
1900 <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
1901 d'utilisateur, ceci aura toujours la priorité sur les autres
1902 méthodes ci dessous.</para></listitem>
1903 <listitem><para id="x_44">Si vous avez défini une variable
1904 d'environnement <envar>HGUSER</envar>, c'est cette valeur qui est
1905 alors utilisée.</para></listitem>
1906 <listitem><para id="x_45">Si vous créez un fichier nommé <filename role="special" moreinfo="none">.hgrc</filename> dans votre répertoire
1907 \textit{home}, avec une entrée <envar role="rc-item-ui">username</envar>, c'est la valeur associée
1908 qui sera utilisée. Pour voir à quoi ressemble le contenu de ce
1909 fichier regardez la section <xref linkend="sec:tour-basic:username"/>
1910 ci-dessous.</para></listitem>
1911 <listitem><para id="x_46">Si vous avez défini une variable
1912 d'environnement <envar>EMAIL</envar> celle ci sera utilisée
1913 ensuite.</para></listitem>
1914 <listitem><para id="x_47">Enfin, Mercurial interrogera votre système
1915 pour trouver votre nom d'utilisateur local ainsi que le nom de la
1916 machine hôte, et il fabriquera un nom d'utilisateur à partir de
1917 ces données. Comme il arrive souvent que ce genre de noms soit
1918 totalement inutile, il vous préviendra en affichant un message
1919 d'avertissement.</para></listitem>
1920 </orderedlist>
1922 <para id="x_48">Si tous ces mécanismes échouent, Mercurial n'exécutera
1923 pas la commande, affichant un message d'erreur. Dans ce cas, il ne
1924 vous laissera pas effectuer de commit tant que vous n'aurez pas
1925 défini un nom d'utilisateur.</para>
1927 <para id="x_49">Vous devriez penser à utiliser la variable
1928 d'environement <envar>HGUSER</envar> et l'option <option role="hg-opt-commit">-u</option> comme moyen pour
1929 <emphasis>changer</emphasis> le nom d'utilisateur par défaut. Pour
1930 une utilisation normale, la manière la plus simple et robuste
1931 d'opérer est de créer un fichier <filename role="special" moreinfo="none">.hgrc</filename>, voir ci-dessous pour les détails
1932 à ce sujet.</para>
1934 <sect3 id="sec:tour-basic:username">
1935 <title>Créer un fichier de configuration pour Mercurial</title>
1937 <para id="x_4a">Pour définir un nom d'utilisateur, utilisez votre
1938 éditeur de texte favori pour créer un fichier <filename role="special" moreinfo="none">.hgrc</filename> dans votre répertoire home.
1939 Mercurial va utiliser ce fichier pour retrouver votre
1940 configuration personnelle. Le contenu initial devrait
1941 ressembler à ceci :</para>
1943 <tip>
1944 <title><quote>Home directory</quote> sous Windows</title>
1946 <para id="x_716">Quand on parle de répertoire home, sur une version
1947 anglaise d'une installation de Windows, il s'agira habituellement
1948 d'un répertoire nommée comme votre nom dans <filename moreinfo="none">C:\Documents
1949 and Settings</filename>. Vous pouvez trouver de quelle répertoire
1950 il s'agit en lançant une fenêtre d'interpréteur de commande et en
1951 exécutant la commande suivante :</para>
1953 <screen format="linespecific"><prompt moreinfo="none">C:\</prompt> <userinput moreinfo="none">echo
1954 %UserProfile</userinput></screen>
1955 </tip>
1957 <programlisting format="linespecific"># This is a Mercurial configuration file.
1958 [ui]
1959 username = Firstname Lastname <email.address@domain.net></programlisting>
1961 <para id="x_4b">La ligne avec <literal moreinfo="none">[ui]</literal> commence une
1962 <emphasis>section</emphasis> du fichier de configuration, ainsi la ligne
1963 <quote><literal moreinfo="none">username = ...</literal></quote> signifie <quote>
1964 définir la valeur de l'élément <literal moreinfo="none">username</literal> dans la
1965 section <literal moreinfo="none">ui</literal></quote>. Une section continue jusqu'à ce
1966 qu'une nouvelle commence, ou que la fin du fichier soit atteinte.
1967 Mercurial ignore les lignes vides et traite tout texte situé à la suite
1968 d'un <quote><literal moreinfo="none">#</literal></quote> jusqu'à la fin de la ligne
1969 comme un commentaire.</para>
1971 </sect3>
1972 <sect3>
1973 <title>Choisir un nom d'utilisateur</title>
1975 <para id="x_4c">Vous pouvez utiliser n'importe quelle valeur
1976 pour votre <literal moreinfo="none">username</literal>, car cette information
1977 est destinée à d'autres personnes et non à être interprétée
1978 par Mercurial. La convention que la plupart des personnes
1979 suivent est d'utiliser leurs noms suivies de leurs adresses emails,
1980 comme montré ci-dessus :</para>
1981 <note>
1982 <para id="x_4d">Le mécanisme interne du serveur web intégré à Mercurial,
1983 masque les adresses emails, pour rendre plus difficile leurs
1984 récupérations par les outils utilisés par les spammmers.
1985 Ceci réduit la probabilité que de recevoir encore plus de
1986 spam si vous vous publiez un dépôt sur internet.</para>
1987 </note>
1988 </sect3>
1989 </sect2>
1990 <sect2>
1991 <title>Rédiger un message de \textit{commit}</title>
1993 <para id="x_4e">Lorsqu'on effectue une opération de commit, Mercurial
1994 lance automatiquement un éditeur de texte pour permettre de saisir
1995 un message qui décrira les modifications effectuées dans cette
1996 révision. Ce message est nommé le <emphasis>message de commit</emphasis>.
1997 Ce sera un enregistrement pour tout lecteur expliquant le pourquoi
1998 et le comment de vos modifications, et il sera affiché par la
1999 commande <command role="hg-cmd" moreinfo="none">hg log</command>.</para>
2001 <!-- BEGIN tour.commit -->
2002 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit</userinput>
2003 </screen>
2004 <!-- END tour.commit -->
2007 <para id="x_4f">L'éditeur que la commande <command role="hg-cmd" moreinfo="none">hg
2008 commit</command> déclenche ne contiendra qu'une ligne vide suivi
2009 d'un certain nombre de lignes commençant par <quote><literal moreinfo="none">HG:
2010 </literal></quote>.</para>
2012 <programlisting format="linespecific">
2013 This is where I type my commit comment.
2015 HG: Enter commit message. Lines beginning with 'HG:' are removed.
2016 HG: --
2017 HG: user: Bryan O'Sullivan <bos@serpentine.com>
2018 HG: branch 'default'
2019 HG: changed hello.c</programlisting>
2022 <para id="x_50">Mercurial ignore les lignes qui commencent
2023 avec <quote><literal moreinfo="none">HG:</literal></quote>, il ne les
2024 utilise que pour nous indiquer quels fichiers modifiés il se
2025 prépare à \textit{commiter}. Modifier ou effacer ces lignes n'a
2026 aucune conséquence sur l'opération de commit.
2027 </para>
2029 </sect2>
2030 <sect2>
2031 <title>Rédiger un message \textit{approprié}</title>
2033 <para id="x_51">Comme <command role="hg-cmd" moreinfo="none">hg log</command> n'affiche
2034 que la première ligne du message de commit par défaut, il est souvent
2035 considéré comme une bonne pratique de rédiger des messages de commit
2036 qui tiennent sur une seule ligne. Voilà un exemple concret de message
2037 de commit qui <emphasis>ne suit pas</emphasis> cette directive, et
2038 qui a donc un résumé peu lisible.</para>
2040 <programlisting format="linespecific">
2041 changeset: 73:584af0e231be
2042 user: Censored Person <censored.person@example.org>
2043 date: Tue Sep 26 21:37:07 2006 -0700
2044 summary: include buildmeister/commondefs. Add an exports and install
2045 </programlisting>
2047 <para id="x_52">A ce sujet, il faut noter qu'il n'existe pas de règle
2048 absolue dans ce domaine. Mercurial lui-même n'interprète pas les
2049 contenus des messages de commit, ainsi votre projet est libre de
2050 concevoir différentes politiques de mise en page des messages.</para>
2052 <para id="x_53">Ma préférence personnelle va au message court, mais
2053 informatif, qui offre des précisions supplémentaires par rapport à ce
2054 que pourrait m'apprendre une commande <command role="hg-cmd" moreinfo="none">hg log
2055 --patch</command>.</para>
2057 <para id="x_55">Si vous exécutez la commande <command role="hg-cmd" moreinfo="none">hg
2058 commit</command> sans aucun argument, elle enregistre tous les
2059 changements qui ont été fait, et qui sont indiqué par les commandes
2060 <command role="hg-cmd" moreinfo="none">hg status</command> et <command role="hg-cmd" moreinfo="none">hg diff</command>.</para>
2062 <note>
2063 <title>Une surprise pour les utilisateurs habitués à Subversion</title>
2065 <para id="x_717">Comme n'importe quel autre commande de Mercurial, si
2066 vous soumettez pas de manière explicite les noms des fichiers à
2067 committer à la commande <command role="hg-cmd" moreinfo="none">hg commit</command>, elle
2068 va travailler sur l'ensemble du répertoire de travail. Soyez conscient
2069 de ceci si vous venez du monde Subversion ou CVS, car vous pourriez
2070 attendre qu'elle opère uniquement le répertoire courant et ses sous
2071 répertoires.</para>
2072 </note>
2073 </sect2>
2074 <sect2>
2075 <title>Annuler un \textit{commit}</title>
2077 <para id="x_54">Si, en rédigeant le message, vous décidez que
2078 finalement vous ne voulez pas effectuer ce commit, il suffit
2079 de quitter simplement l'éditeur sans sauver. Ceci n'aura aucune
2080 conséquence sur le dépôt ou les fichiers du répertoire de
2081 travail.</para>
2082 </sect2>
2084 <sect2>
2085 <title>Admirer votre travail</title>
2087 <para id="x_56">Une fois que votre \textit{commit} est terminé, vous
2088 pouvez utiliser la commande <command role="hg-cmd" moreinfo="none">hg tip</command>
2089 pour afficher le \textit{changeset} que vous venez de créer. Cette
2090 commande produit une sortie à l'écran qui est identique à celle du
2091 <command role="hg-cmd" moreinfo="none">hg log</command>, mais qui n'affiche que la
2092 dernière révision du dépôt.</para>
2094 <!-- BEGIN tour.tip -->
2095 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip -vp</userinput>
2096 changeset: 5:c94f208d1dfb
2097 tag: tip
2098 user: Bryan O'Sullivan <bos@serpentine.com>
2099 date: Sun Aug 16 14:05:26 2009 +0000
2100 files: hello.c
2101 description:
2102 Added an extra line of output
2105 diff -r 2278160e78d4 -r c94f208d1dfb hello.c
2106 --- a/hello.c Sat Aug 16 22:16:53 2008 +0200
2107 +++ b/hello.c Sun Aug 16 14:05:26 2009 +0000
2108 @@ -8,5 +8,6 @@
2109 int main(int argc, char **argv)
2110 {
2111 printf("hello, world!\");
2112 + printf("hello again!\n");
2113 return 0;
2114 }
2116 </screen>
2117 <!-- END tour.tip -->
2120 <para id="x_57">On fait couramment référence à la dernière révision
2121 du dépôt comme étant la <emphasis>révision tip</emphasis>, ou plus
2122 simplement le <emphasis>tip</emphasis>.</para>
2124 <para id="x_684">Au passage, la commande <command role="hg-cmd" moreinfo="none">hg
2125 tip</command> accepte la plupart des options qu'accepte
2126 <command role="hg-cmd" moreinfo="none">hg log</command>. Ainsi <option role="hg-opt-global">-v</option> ci dessus implique <quote>soit
2127 verbeux</quote>, <option role="hg-opt-tip">-p</option>
2128 veux dire <quote>affiche le patch</quote>. L'utilisation de l'option
2129 <option role="hg-opt-tip">-p</option> pour afficher un patch est un
2130 autre exemple de la cohérence des commandes évoquée plus tôt.</para>
2132 </sect2>
2133 </sect1>
2134 <sect1>
2135 <title>Partager ses modifications</title>
2137 <para id="x_58">Nous avons mentionné plus haut que les dépôts
2138 de Mercurial sont autosuffisants. Ce qui signifie que la nouvelle
2139 révision que vous venez de créer existe seulement dans votre
2140 répertoire <filename class="directory" moreinfo="none">my-hello</filename>. Étudions
2141 comment propager cette modification dans d'autres dépôts.</para>
2143 <sect2 id="sec:tour:pull">
2144 <title>Récupérer les modifications d'autres dépôts</title>
2146 <para id="x_59">Pour commencer, construisons un clone de notre dépôt
2147 <filename class="directory" moreinfo="none">hello</filename> qui ne contiendra pas
2148 le changement que nous venons d'effectuer. Nous l'appellerons notre
2149 dépôt temporaire <filename class="directory" moreinfo="none">hello-pull</filename>.</para>
2151 <!-- BEGIN tour.clone-pull -->
2152 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
2153 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone hello hello-pull</userinput>
2154 updating working directory
2155 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
2156 </screen>
2157 <!-- END tour.clone-pull -->
2160 <para id="x_5a">Nous allons utiliser la commande <command role="hg-cmd" moreinfo="none">hg pull</command> pour envoyer les modifications
2161 depuis <filename class="directory" moreinfo="none">my-hello</filename> dans <filename class="directory" moreinfo="none">hello-pull</filename>. Néanmoins, récupérer
2162 aveuglement des modifications depuis un dépôt a quelque chose d'un
2163 peu effrayant. Mercurial propose donc une commande <command role="hg-cmd" moreinfo="none">hg incoming</command> qui permet de savoir quelles
2164 modifications la commande <command role="hg-cmd" moreinfo="none">hg pull</command>
2165 <emphasis>pourrait</emphasis> entraîner dans notre dépôt, et ceci
2166 sans effectuer réellement de modification dessus.</para>
2168 <!-- BEGIN tour.incoming -->
2169 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd hello-pull</userinput>
2170 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg incoming ../my-hello</userinput>
2171 comparing with ../my-hello
2172 searching for changes
2173 changeset: 5:c94f208d1dfb
2174 tag: tip
2175 user: Bryan O'Sullivan <bos@serpentine.com>
2176 date: Sun Aug 16 14:05:26 2009 +0000
2177 summary: Added an extra line of output
2179 </screen>
2180 <!-- END tour.incoming -->
2183 <para id="x_5c">Apporter les modifications rapatriées dans un dépôt se
2184 résume donc à exécuter la commande <command role="hg-cmd" moreinfo="none">hg
2185 pull</command>, et préciser depuis quel dépôt effectuer le <command role="hg-cmd" moreinfo="none">hg pull</command>.</para>
2187 <!-- BEGIN tour.pull -->
2188 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
2189 changeset: 4:2278160e78d4
2190 tag: tip
2191 user: Bryan O'Sullivan <bos@serpentine.com>
2192 date: Sat Aug 16 22:16:53 2008 +0200
2193 summary: Trim comments.
2195 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../my-hello</userinput>
2196 pulling from ../my-hello
2197 searching for changes
2198 adding changesets
2199 adding manifests
2200 adding file changes
2201 added 1 changesets with 1 changes to 1 files
2202 (run 'hg update' to get a working copy)
2203 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
2204 changeset: 5:c94f208d1dfb
2205 tag: tip
2206 user: Bryan O'Sullivan <bos@serpentine.com>
2207 date: Sun Aug 16 14:05:26 2009 +0000
2208 summary: Added an extra line of output
2210 </screen>
2211 <!-- END tour.pull -->
2214 <para id="x_5d">Comme vous le voyez avec une sortie avant et après de la
2215 commande <command role="hg-cmd" moreinfo="none">hg tip</command>, nous avons réussi à
2216 récupérer aisément les modifications dans notre dépôt. Il reste néanmoins
2217 quelque chose à faire avant de placer ces modifications dans l'espace de
2218 travail.</para>
2220 <tip>
2221 <title>Récupérer des changements précis</title>
2223 <para id="x_5b">Il est possible à cause du délai entre l'exécution de la
2224 commande <command role="hg-cmd" moreinfo="none">hg incoming</command> et l'exécution de
2225 la commande <command role="hg-cmd" moreinfo="none">hg pull</command>, que vous ne
2226 puissiez pas voir toutes les modifications que vous rapporterez d'un
2227 autre dépôt. Supposons que vous récupériez les modifications d'un dépôt
2228 situé quelque part sur le réseau. Alors que vous regardez le résultat de
2229 la commande <command role="hg-cmd" moreinfo="none">hg incoming</command>, et avant que
2230 vous ne décidiez de récupérer ces modifications, quelqu'un peut ajouter
2231 de nouvelles révisions dans le dépôt distant. Ce qui signifie que vous
2232 récupérez plus de révision que ce que vous aviez regardées en utilisant
2233 la commande <command role="hg-cmd" moreinfo="none">hg incoming</command>.</para>
2235 <para id="x_718">Si vous voulez seulement récupérer ce que vous aviez
2236 vérifier à l'aide de la commande <command role="hg-cmd" moreinfo="none">hg
2237 incoming</command>, ou que pour d'autres raisons vous souhaitiez ne
2238 récupérer qu'un sous ensemble des révisions supplémentaires
2239 disponibles, indiquant simplement les modifications que vous souhaitez
2240 récupérer par leurs ID de révision, soit <command moreinfo="none">hg pull
2241 -r7e95bb</command>. </para>
2242 </tip>
2244 </sect2>
2245 <sect2>
2246 <title>Mise à jour de l'espace de travail</title>
2248 <para id="x_5e">Nous avons jusqu'à maintenant grossièrement défini la
2249 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
2250 <xref linkend="sec:tour:pull"/> a apporté des modifications, que nous
2251 avons vérifiées, dans notre dépôt, mais il n'y a aucune trace de ces
2252 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
2253 de travail. C'est la commande <command role="hg-cmd" moreinfo="none">hg update</command>
2254 qui s'en charge.</para>
2256 <!-- BEGIN tour.update -->
2257 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">grep printf hello.c</userinput>
2258 printf("hello, world!\");
2259 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update tip</userinput>
2260 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
2261 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">grep printf hello.c</userinput>
2262 printf("hello, world!\");
2263 printf("hello again!\n");
2264 </screen>
2265 <!-- END tour.update -->
2268 <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
2269 automatiquement. Il y a en fait une très bonne raison à cela : vous
2270 pouvez utilisez la commande <command role="hg-cmd" moreinfo="none">hg update</command>
2271 pour mettre à jour votre espace de travail à l'état dans lequel il était
2272 à <emphasis>n'importe quelle révision</emphasis> de l'historique du dépôt.
2273 Si vous aviez un espace de travail contenant une ancienne
2274 révision—pour chercher l'origine d'un bug, par exemple—et
2275 que vous effectuiez un <command role="hg-cmd" moreinfo="none">hg pull</command> qui
2276 mettrait à jour automatiquement votre espace de travail, vous ne seriez
2277 probablement pas très satisfait.</para>
2279 <para id="x_60">Néanmoins, comme les opérations de pull sont très souvent
2280 suivies d'un update, Mercurial vous permet de combiner les
2281 deux aisément en passant l'option <option role="hg-opt-pull">-u</option>
2282 à la commande <command role="hg-cmd" moreinfo="none">hg pull</command>.</para>
2284 <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
2285 <option role="hg-opt-pull">-u</option>, vous pouvez constater qu'elle a
2286 affiché un rappel assez utile : vous devez encore effectuer une
2287 opération pour mettre à jour votre espace de travail.</para>
2289 <para id="x_62">Pour découvrir sur quelle révision de l'espace de
2290 travail on se trouve, utilisez la commande <command role="hg-cmd" moreinfo="none">hg
2291 parents</command>.</para>
2293 <!-- BEGIN tour.parents -->
2294 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
2295 changeset: 5:c94f208d1dfb
2296 tag: tip
2297 user: Bryan O'Sullivan <bos@serpentine.com>
2298 date: Sun Aug 16 14:05:26 2009 +0000
2299 summary: Added an extra line of output
2301 </screen>
2302 <!-- END tour.parents -->
2305 <para id="x_63">Si vous regardez de nouveau le dessin <xref linkend="fig:tour-basic:history"/>, vous verrez les flèches reliant
2306 entre elles les révisions. Le nœud d'où la flèche
2307 <emphasis>part</emphasis> est dans chaque cas un parent,
2308 et le nœud où la flèche <emphasis>arrive</emphasis> est un
2309 enfant.</para>
2311 <para id="x_64">Pour mettre à jour l'espace de travail d'une révision
2312 particulière, indiquez un numéro de révision ou un \textit{changeset
2313 ID} à la commande <command role="hg-cmd" moreinfo="none">hg update</command>.</para>
2315 <!-- BEGIN tour.older -->
2316 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update 2</userinput>
2317 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
2318 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
2319 changeset: 2:fef857204a0c
2320 user: Bryan O'Sullivan <bos@serpentine.com>
2321 date: Sat Aug 16 22:05:04 2008 +0200
2322 summary: Introduce a typo into hello.c.
2324 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update</userinput>
2325 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
2326 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
2327 changeset: 5:c94f208d1dfb
2328 tag: tip
2329 user: Bryan O'Sullivan <bos@serpentine.com>
2330 date: Sun Aug 16 14:05:26 2009 +0000
2331 summary: Added an extra line of output
2333 </screen>
2334 <!-- END tour.older -->
2337 <para id="x_65">Si vous ne précisez pas de manière explicite de numéro
2338 de révision la commande <command role="hg-cmd" moreinfo="none">hg update</command>
2339 mettra à jour votre espace de travail avec le contenu de la révison
2340 \textit{tip}, comme montré dans l'exemple ci dessus lors du second
2341 appel à <command role="hg-cmd" moreinfo="none">hg update</command>.</para>
2343 </sect2>
2344 <sect2>
2345 <title>Transférer les modifications vers un autre dépôt</title>
2347 <para id="x_66">Mercurial vous laisse transférer les modifications vers
2348 un autre dépôt, depuis votre dépôt actuel. Comme dans l'exemple du
2349 <command role="hg-cmd" moreinfo="none">hg pull</command> ci-dessus, nous allons créer
2350 un dépôt temporaire vers lequel transférer nos modifications.</para>
2352 <!-- BEGIN tour.clone-push -->
2353 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
2354 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone hello hello-push</userinput>
2355 updating working directory
2356 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
2357 </screen>
2358 <!-- END tour.clone-push -->
2361 <para id="x_67">La commande <command role="hg-cmd" moreinfo="none">hg outgoing</command>
2362 nous indique quels changements nous allons transférer vers l'autre
2363 serveur.</para>
2365 <!-- BEGIN tour.outgoing -->
2366 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-hello</userinput>
2367 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg outgoing ../hello-push</userinput>
2368 comparing with ../hello-push
2369 searching for changes
2370 changeset: 5:c94f208d1dfb
2371 tag: tip
2372 user: Bryan O'Sullivan <bos@serpentine.com>
2373 date: Sun Aug 16 14:05:26 2009 +0000
2374 summary: Added an extra line of output
2376 </screen>
2377 <!-- END tour.outgoing -->
2380 <para id="x_68">Et la commande <command role="hg-cmd" moreinfo="none">hg push</command>
2381 effectue réellement le transfert.</para>
2383 <!-- BEGIN tour.push -->
2384 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push ../hello-push</userinput>
2385 pushing to ../hello-push
2386 searching for changes
2387 adding changesets
2388 adding manifests
2389 adding file changes
2390 added 1 changesets with 1 changes to 1 files
2391 </screen>
2392 <!-- END tour.push -->
2395 <para id="x_69">Comme avec <command role="hg-cmd" moreinfo="none">hg pull</command>, la
2396 commande <command role="hg-cmd" moreinfo="none">hg push</command> ne met pas à jour
2397 le répertoire de travail du dépôt dans lequel il transfère les
2398 modifications. À l'inverse de <command role="hg-cmd" moreinfo="none">hg
2399 pull</command>, <command role="hg-cmd" moreinfo="none">hg push</command> ne fournit
2400 pas d'option <literal moreinfo="none">-u</literal> pour forcer la mise à jour de
2401 l'espace de travail cible. Cette asymétrie est délibéré : le dépot
2402 vers lequel nous transférons peut très bien être un serveur distant
2403 et partagé par plusieurs personnes. Si nous devions mettre à jour son
2404 répertoire de travail alors que quelqu'un d'autre travaille dessus,
2405 nous risquerions de perturber son travail.</para>
2407 <para id="x_6a">Qu'est ce qui se passe lorsque vous essayez de récupérer
2408 ou de transférer vos modifications et que le dépôt cible a déjà reçu
2409 ces modifications ? Rien de bien excitant.</para>
2411 <!-- BEGIN tour.push.nothing -->
2412 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push ../hello-push</userinput>
2413 pushing to ../hello-push
2414 searching for changes
2415 no changes found
2416 </screen>
2417 <!-- END tour.push.nothing -->
2420 </sect2>
2422 <sect2>
2423 <title>Emplacements par défaut</title>
2425 <para id="x_719">Quand nous faisons un clone d'un dépôt, Mercurial
2426 enregistre l'emplacement du dépôt d'origine dans le fichier
2427 <filename moreinfo="none">.hg/hgrc</filename> de notre nouveau dépôt. Si nous ne
2428 fournissons pas d'emplacement à la commande <command moreinfo="none">hg
2429 pull</command> ou à la commande <command moreinfo="none">hg push</command>, ces
2430 commandes utiliseront alors cet emplacement comme valeur par défaut.
2431 Les commandes <command moreinfo="none">hg incoming</command> et <command moreinfo="none">hg
2432 outgoing</command> feront de même.</para>
2434 <para id="x_71a">Si vous regardez le fichier
2435 <filename moreinfo="none">.hg/hgrc</filename>, vous constaterez que son contenu
2436 ressemble à ce qui suit.</para>
2438 <programlisting format="linespecific">[paths]
2439 default = http://www.selenic.com/repo/hg</programlisting>
2441 <para id="x_71b">Il est possible—et souvent
2442 pratique—d'avoir un emplacement par défaut pour les commandes
2443 <command moreinfo="none">hg push</command> et <command moreinfo="none">hg outgoing</command>
2444 différent de celui des commandes <command moreinfo="none">hg pull</command> et
2445 <command moreinfo="none">hg incoming</command>. C'est faisable en ajoutant une entrée
2446 <literal moreinfo="none">default-push</literal> à la section
2447 <literal moreinfo="none">[paths]</literal> du <filename moreinfo="none">.hg/hgrc</filename>, comme
2448 suit.</para>
2450 <programlisting format="linespecific">[paths]
2451 default = http://www.selenic.com/repo/hg
2452 default-push = http://hg.example.com/hg</programlisting>
2454 </sect2>
2455 <sect2>
2456 <title>Partager ses modifications à travers le réseau</title>
2458 <para id="x_6b">Les commandes que nous avons étudiées dans les sections
2459 précédentes ne sont pas limitées aux dépôts locaux. Chacune fonctionne
2460 de la même manière à travers une connexion réseau, il suffit de lui
2461 passer une URL à la place d'un chemin de fichier local.</para>
2463 <!-- BEGIN tour.outgoing.net -->
2464 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg outgoing http://hg.serpentine.com/tutorial/hello</userinput>
2465 comparing with http://hg.serpentine.com/tutorial/hello
2466 searching for changes
2467 changeset: 5:c94f208d1dfb
2468 tag: tip
2469 user: Bryan O'Sullivan <bos@serpentine.com>
2470 date: Sun Aug 16 14:05:26 2009 +0000
2471 summary: Added an extra line of output
2473 </screen>
2474 <!-- END tour.outgoing.net -->
2477 <para id="x_6c">Dans cet exemple, nous allons voir quels changements
2478 nous pourrions transférer vers le dépôt distant, mais le dépôt est,
2479 de manière tout à fait compréhensible, pas configuré pour accepter
2480 des modifications d'utilisateurs anonymes.</para>
2482 <!-- BEGIN tour.push.net -->
2483 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push http://hg.serpentine.com/tutorial/hello</userinput>
2484 pushing to http://hg.serpentine.com/tutorial/hello
2485 searching for changes
2486 ssl required
2487 </screen>
2488 <!-- END tour.push.net -->
2491 </sect2>
2493 </sect1>
2495 <sect1>
2496 <title>Commencer un nouveau projet</title>
2498 <para id="x_71c">Il est tout aussi aisé de commencer un nouveau projet
2499 que de travailler sur un qui existe déjà. La commande <command moreinfo="none">hg
2500 init</command> crée un nouveau dépôt Mercurial vide.</para>
2502 <!-- BEGIN ch01/new.init -->
2503 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init myproject</userinput>
2504 </screen>
2505 <!-- END ch01/new.init -->
2508 <para id="x_71d">Ceci crée simplement un répertoire nommé
2509 <filename moreinfo="none">myproject</filename> dans le répertoire courant.</para>
2511 <!-- BEGIN ch01/new.ls -->
2512 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls -l</userinput>
2513 total 12
2514 -rw-r--r-- 1 rpelisse rpelisse 47 Aug 16 14:04 goodbye.c
2515 -rw-r--r-- 1 rpelisse rpelisse 45 Aug 16 14:04 hello.c
2516 drwxr-xr-x 3 rpelisse rpelisse 4096 Aug 16 14:04 myproject
2517 </screen>
2518 <!-- END ch01/new.ls -->
2521 <para id="x_71e">Nous pouvons dire que <filename moreinfo="none">myproject</filename> est
2522 un dépôt Mercurial car il contient un répertoire
2523 <filename moreinfo="none">.hg</filename>.</para>
2525 <!-- BEGIN ch01/new.ls2 -->
2526 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls -al myproject</userinput>
2527 total 12
2528 drwxr-xr-x 3 rpelisse rpelisse 4096 Aug 16 14:04 .
2529 drwx------ 3 rpelisse rpelisse 4096 Aug 16 14:04 ..
2530 drwxr-xr-x 3 rpelisse rpelisse 4096 Aug 16 14:04 .hg
2531 </screen>
2532 <!-- END ch01/new.ls2 -->
2535 <para id="x_71f">Si vous voulons ajouter quelques fichiers préexistants
2536 dans ce dépôt, il suffit de les recopier dans le répertoire de travail,
2537 et demander à Mercurial de commencer à les suivre en utilisant la
2538 commande <command moreinfo="none">hg add</command>.</para>
2540 <!-- BEGIN ch01/new.add -->
2541 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd myproject</userinput>
2542 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cp ../hello.c .</userinput>
2543 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cp ../goodbye.c .</userinput>
2544 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add</userinput>
2545 adding goodbye.c
2546 adding hello.c
2547 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
2548 A goodbye.c
2549 A hello.c
2550 </screen>
2551 <!-- END ch01/new.add -->
2554 <para id="x_720">Une fois que nous sommes satisfaits de notre projet,
2555 nous pouvons commencer à ajouter nos révisions.</para>
2557 <!-- BEGIN ch01/new.commit -->
2558 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Initial commit'</userinput>
2559 </screen>
2560 <!-- END ch01/new.commit -->
2563 <para id="x_721">Il ne prend que quelques instants pour commencer à
2564 utiliser Mercurial sur un nouveau projet, ce qui fait aussi de ses
2565 points forts. Travailler avec une gestion de révision devient très
2566 facile, nous pouvons même l'utiliser pour les plus petits projets où
2567 nous aurions probablement jamais penser utiliser un outils aussi
2568 complexe.</para>
2569 </sect1>
2570 </chapter>
2572 <!--
2573 local variables:
2574 sgml-parent-document: ("00book.xml" "book" "chapter")
2575 end:
2576 -->
2578 <!-- BEGIN ch03 -->
2579 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
2581 <chapter id="chap:tour-merge">
2582 <?dbhtml filename="a-tour-of-mercurial-merging-work.html"?>
2583 <title>Un rapide tour de Mercurial: fusionner les travaux</title>
2585 <para id="x_338">Nous avons maintenant étudié comment cloner un dépôt, effectuer
2586 des changements dedans, et récupérer ou transférer depuis un
2587 autre dépôt. La prochaine étape est donc de <emphasis>fusionner</emphasis> les
2588 modifications de différents dépôts.</para>
2590 <sect1>
2591 <title>Fusionner différents travaux</title>
2592 <para id="x_339">La fusion est un aspect fondamental lorsqu'on
2593 travaille iavec un gestionnaire de source distribué.</para>
2595 <itemizedlist>
2596 <listitem>
2597 <para id="x_33a">Alice et Bob ont chacun une copie personnelle du dépôt d'un
2598 projet sur lequel ils collaborent. Alice corrige un bug
2599 dans son dépôt, et Bob ajoute une nouvelle fonctionnalité dans le
2600 sien. Ils veulent un dépôt partagé avec à la fois le correctif du
2601 bug et la nouvelle fonctionnalité.</para>
2602 </listitem>
2603 <listitem>
2604 <para id="x_33b">Je travaille régulièrement sur plusieurs tâches différentes sur
2605 un seul projet en même temps, chacun isolé dans son propre dépôt.
2606 Travailler ainsi signifie que je dois régulièrement fusionner une
2607 partie de mon code avec celui des autres.</para>
2608 </listitem>
2609 </itemizedlist>
2611 <para id="x_33c">Parce que la fusion est une opération si commune à réaliser,
2612 Mercurial la rend facile. Étudions ensemble le déroulement des
2613 opérations. Nous commencerons encore par faire un clone d'un autre
2614 dépôt (vous voyez que l'on fait ça tout le temps ?) puis nous ferons
2615 quelques modifications dessus.</para>
2617 <!-- BEGIN tour.merge.clone -->
2618 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
2619 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone hello my-new-hello</userinput>
2620 updating working directory
2621 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
2622 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-new-hello</userinput>
2623 # Make some simple edits to hello.c.
2624 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">my-text-editor hello.c</userinput>
2625 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'A new hello for a new day.'</userinput>
2626 </screen>
2627 <!-- END tour.merge.clone -->
2630 <para id="x_33d">Nous devrions avoir maintenant deux copies de
2631 <filename moreinfo="none">hello.c</filename> avec des contenus différents. Les
2632 historiques de ces deux dépôts ont aussi divergés, comme illustré dans
2633 la figure <xref linkend="fig:tour-merge:sep-repos"/>.</para>
2635 <!-- BEGIN tour.merge.cat1 -->
2636 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat hello.c</userinput>
2637 /*
2638 * Placed in the public domain by Bryan O'Sullivan. This program is
2639 * not covered by patents in the United States or other countries.
2640 */
2642 #include <stdio.h>
2644 int main(int argc, char **argv)
2645 {
2646 printf("once more, hello.\n");
2647 printf("hello, world!\");
2648 printf("hello again!\n");
2649 return 0;
2650 }
2651 </screen>
2652 <!-- END tour.merge.cat1 -->
2655 <para id="x_722">Et ici est notre légèrement différente version du
2656 dépôt.</para>
2658 <!-- BEGIN tour.merge.cat2 -->
2659 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat ../my-hello/hello.c</userinput>
2660 /*
2661 * Placed in the public domain by Bryan O'Sullivan. This program is
2662 * not covered by patents in the United States or other countries.
2663 */
2665 #include <stdio.h>
2667 int main(int argc, char **argv)
2668 {
2669 printf("hello, world!\");
2670 printf("hello again!\n");
2671 return 0;
2672 }
2673 </screen>
2674 <!-- END tour.merge.cat2 -->
2677 <figure id="fig:tour-merge:sep-repos" float="0">
2678 <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>
2679 <mediaobject>
2680 <imageobject><imagedata fileref="figs/tour-merge-sep-repos.png"/></imageobject>
2681 <textobject><phrase>XXX ajoute un test</phrase></textobject>
2682 </mediaobject>
2683 </figure>
2685 <para id="x_33f">Nous savons déjà que récupérer les modifications depuis
2686 notre dépôt <filename class="directory" moreinfo="none">my-hello</filename> n'aura
2687 aucun effet sur l'espace de travail.</para>
2689 <!-- BEGIN tour.merge.pull -->
2690 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../my-hello</userinput>
2691 pulling from ../my-hello
2692 searching for changes
2693 adding changesets
2694 adding manifests
2695 adding file changes
2696 added 1 changesets with 1 changes to 1 files (+1 heads)
2697 (run 'hg heads' to see heads, 'hg merge' to merge)
2698 </screen>
2699 <!-- END tour.merge.pull -->
2702 <para id="x_340">Néanmoins, la commande <command role="hg-cmd" moreinfo="none">hg
2703 pull</command> nous indique quelque chose au sujet des
2704 <quote>heads</quote>.</para>
2706 <sect2>
2707 <title>Les révisions 'heads'</title>
2709 <para id="x_341">Rappellez vous que Mercurial enregistre quelle révision
2710 est le parent de chaque révision. Si une révision a un parent, nous
2711 l'appelons un enfant(child) ou un descendant de ce parent. Une
2712 "head" est une révision qui n'a donc pas d'enfant. La révision tip
2713 est donc une "head", car c'est la révision la plus récente du dépôt
2714 qui n'a pas d'enfant. Il y a des moments où un dépôt peut contenir
2715 plusieurs "head".</para>
2717 <figure id="fig:tour-merge:pull" float="0">
2718 <title>Contenu du dépôt après une récupération ("pull") depuis le
2719 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>
2720 <mediaobject>
2721 <imageobject>
2722 <imagedata fileref="tour-merge-pull"/>
2723 </imageobject>
2724 <textobject><phrase>XXX ajoute un texte</phrase></textobject>
2725 </mediaobject>
2726 </figure>
2728 <para id="x_343">Dans la figure <xref linkend="fig:tour-merge:pull"/>,
2729 vous pouvez constater l'effet d'un \textit{pull} depuis le dépôt
2730 <filename class="directory" moreinfo="none">my-hello</filename> dans le dépôt
2731 <filename class="directory" moreinfo="none">my-new-hello</filename>. L'historique qui
2732 était déjà présent dans le dépôt <filename class="directory" moreinfo="none">my-new-hello</filename> reste intact, mais une
2733 nouvelle révision a été ajoutée. En vous reportant à la figure <xref linkend="fig:tour-merge:sep-repos"/>, vous pouvez voir que le
2734 <emphasis>ID de révision (changeset ID)</emphasis> reste le même dans
2735 le nouveau dépôt, mais que le <emphasis>numéro de
2736 révision</emphasis> reste le même. (Ceci est un parfait exemple de
2737 pourquoi il n'est fiable d'utiliser les numéros de révision lorsque
2738 l'on discute d'un \textit{changeset}.) Vous pouvez voir les "heads"
2739 présentes dans le dépôt en utilisant la commande <command role="hg-cmd" moreinfo="none">hg heads</command>.</para>
2741 <!-- BEGIN tour.merge.heads -->
2742 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg heads</userinput>
2743 changeset: 6:c94f208d1dfb
2744 tag: tip
2745 parent: 4:2278160e78d4
2746 user: Bryan O'Sullivan <bos@serpentine.com>
2747 date: Sun Aug 16 14:05:26 2009 +0000
2748 summary: Added an extra line of output
2750 changeset: 5:5f06f94fbeca
2751 user: Bryan O'Sullivan <bos@serpentine.com>
2752 date: Sun Aug 16 14:05:31 2009 +0000
2753 summary: A new hello for a new day.
2755 </screen>
2756 <!-- END tour.merge.heads -->
2758 </sect2>
2760 <sect2>
2761 <title>Effectuer la fusion</title>
2763 <para id="x_344">Que se passe-t-il quand vous essayez d'utiliser la
2764 commande <command role="hg-cmd" moreinfo="none">hg update</command> pour mettre à
2765 jour votre espace de travail au nouveau "tip"</para>
2767 <!-- BEGIN tour.merge.update -->
2768 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update</userinput>
2769 abort: crosses branches (use 'hg merge' or 'hg update -C')
2770 </screen>
2771 <!-- END tour.merge.update -->
2775 <para id="x_345">Mercurial nous prévient que la commande <command role="hg-cmd" moreinfo="none">hg update</command> n'effectuera pas
2776 la fusion, il ne veut pas mettre à jour l'espace de travail quand il
2777 estime que nous pourrions avoir besoin d'une fusion, à moins de lui
2778 forcer la main. À la place, il faut utiliser la commande <command role="hg-cmd" moreinfo="none">hg merge</command> pour fusionner les deux
2779 "heads".</para>
2781 <para id="x_723">Pour commencer une fusion (merge) entre deux "heads",
2782 nous utilisons la commande <command role="hg-cmd" moreinfo="none">hg merge</command>.</para>
2784 <!-- BEGIN tour.merge.merge -->
2785 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
2786 merging hello.c
2787 0 files updated, 1 files merged, 0 files removed, 0 files unresolved
2788 (branch merge, don't forget to commit)
2789 </screen>
2790 <!-- END tour.merge.merge -->
2793 <para id="x_347">Nous résolvons les conflits dans le fichier
2794 <filename moreinfo="none">hello.c</filename>. Ceci met à jour le répertoire de travail
2795 de sorte qu'il ne contienne les modifications ne provenance des
2796 <emphasis>deux</emphasis> "heads", ce qui est indiqué par la
2797 la sortie de la commande <command role="hg-cmd" moreinfo="none">hg
2798 parents</command> et le contenu du fichier
2799 <filename moreinfo="none">hello.c</filename>.</para>
2801 <!-- BEGIN tour.merge.parents -->
2802 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
2803 changeset: 5:5f06f94fbeca
2804 user: Bryan O'Sullivan <bos@serpentine.com>
2805 date: Sun Aug 16 14:05:31 2009 +0000
2806 summary: A new hello for a new day.
2808 changeset: 6:c94f208d1dfb
2809 tag: tip
2810 parent: 4:2278160e78d4
2811 user: Bryan O'Sullivan <bos@serpentine.com>
2812 date: Sun Aug 16 14:05:26 2009 +0000
2813 summary: Added an extra line of output
2815 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat hello.c</userinput>
2816 /*
2817 * Placed in the public domain by Bryan O'Sullivan. This program is
2818 * not covered by patents in the United States or other countries.
2819 */
2821 #include <stdio.h>
2823 int main(int argc, char **argv)
2824 {
2825 printf("once more, hello.\n");
2826 printf("hello, world!\");
2827 printf("hello again!\n");
2828 return 0;
2829 }
2830 </screen>
2831 <!-- END tour.merge.parents -->
2833 </sect2>
2835 <sect2>
2836 <title>Effectuer l'ajout (commit) du résultat de la fusion</title>
2838 <para id="x_348">Dès l'instant où vous avez effectué une fusion
2839 (merge), <command role="hg-cmd" moreinfo="none">hg parents</command> vous
2840 affichera deux parents, avant que vous n'exécutiez la commande
2841 <command role="hg-cmd" moreinfo="none">hg commit</command> sur le résultat de la
2842 fusion.</para>
2844 <!-- BEGIN tour.merge.commit -->
2845 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Merged changes'</userinput>
2846 </screen>
2847 <!-- END tour.merge.commit -->
2850 <para id="x_349">Nous avons maintenant un nouveau tip, remarquer qu'il
2851 contient <emphasis>à la fois</emphasis> nos anciennes "heads" et leurs
2852 parents. Ce sont les mêmes révisions que nous avions affichées avec
2853 la commande <command role="hg-cmd" moreinfo="none">hg parents</command>.</para>
2855 <!-- BEGIN tour.merge.tip -->
2856 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
2857 changeset: 7:b8e1e756ef55
2858 tag: tip
2859 parent: 5:5f06f94fbeca
2860 parent: 6:c94f208d1dfb
2861 user: Bryan O'Sullivan <bos@serpentine.com>
2862 date: Sun Aug 16 14:05:33 2009 +0000
2863 summary: Merged changes
2865 </screen>
2866 <!-- END tour.merge.tip -->
2869 <para id="x_34a">Dans la figure <xref linkend="fig:tour-merge:merge"/>,
2870 vous pouvez voir une représentation de ce qui se passe dans l'espace
2871 de travail pendant la fusion, et comment ceci affecte le dépôt lors
2872 du "commit". Pendant la fusion, l'espace de travail, qui a deux
2873 révisions (changesets) comme parents, voit ces derniers devenir le parent
2874 d'une nouvelle révision (changeset).</para>
2876 <figure id="fig:tour-merge:merge" float="0">
2877 <title>Working directory and repository during merge, and
2878 following commit</title>
2879 <mediaobject>
2880 <imageobject>
2881 <imagedata fileref="figs/tour-merge-merge.png"/>
2882 </imageobject>
2883 <textobject><phrase>XXX ajoute texte</phrase></textobject>
2884 </mediaobject>
2885 </figure>
2887 </sect2>
2888 </sect1>
2890 <sect1>
2891 <title>Fusionner les modifications en conflit</title>
2893 <para id="x_34b">La plupart des fusions sont assez simple à réaliser, mais
2894 parfois vous vous retrouverez à fusionner des fichiers où la modification
2895 touche la même portion de code, au sein d'un même fichier. À moins
2896 que ces modification ne soient identiques, ceci aboutira à un
2897 <emphasis>conflit</emphasis>, et vous devrez décider comment réconcilier
2898 les différentes modifications dans un tout cohérent.</para>
2900 <figure id="fig:tour-merge:conflict" float="0">
2901 <title>Modifications en conflits dans un document</title>
2902 <mediaobject>
2903 <imageobject><imagedata fileref="tour-merge-conflict"/></imageobject>
2904 <textobject><phrase>XXX ajoute texte</phrase></textobject>
2905 </mediaobject>
2906 </figure>
2908 <para id="x_34d">La figure <xref linkend="fig:tour-merge:conflict"/>
2909 illustre un cas de modifications conflictuelles dans un document. Nous
2910 avons commencé avec une version simple de ce fichier, puis nous avons
2911 ajouté des modifications, pendant que quelqu'un d'autre modifiait le même
2912 texte. Notre tâche dans la résolution du conflit est de décider à quoi le
2913 fichier devrait ressembler.</para>
2915 <para id="x_34e">Mercurial n'a pas de mécanisme interne pour gérer
2916 les conflits. À la place, il exécute un programme externe appelé
2917 <command moreinfo="none">hgmerge</command>. Il s'agit d'un script shell qui est
2918 embarqué par Mercurial, vous pouvez le modifier si vous le voulez.
2919 Ce qu'il fait par défaut est d'essayer de trouver un des différents
2920 outils de fusion qui seront probablement installés sur le système.
2921 Il commence par les outils totalement automatiques, et si ils
2922 échouent (parce que la résolution du conflit nécessite une
2923 intervention humaine) ou si ils sont absents, le script tente
2924 d'exécuter certains outils graphiques de fusion.</para>
2926 <para id="x_34f">Il est aussi possible de demander à Mercurial d'exécuter
2927 un autre programme ou un autre script en définissant la variable
2928 d'environnement <envar>HGMERGE</envar> avec le nom
2929 du programme de votre choix.</para>
2931 <sect2>
2932 <title>Utiliser un outil graphique de fusion</title>
2934 <para id="x_350">Mon outil de fusion préféré est
2935 <command moreinfo="none">kdiff3</command>, que j'utilise ici pour illustrer les
2936 fonctionnalités classiques des outils graphiques de fusion. Vous pouvez
2937 voir une capture d'écran de l'utilisation de <command moreinfo="none">kdiff3</command>
2938 dans la figure <xref linkend="fig:tour-merge:kdiff3"/>. Cet outil
2939 effectue une <emphasis>fusion \textit{three-way</emphasis>}, car il y a
2940 trois différentes versions du fichier qui nous intéresse. Le fichier
2941 découpe la partie supérieure de la fenêtre en trois panneaux:</para>
2942 <itemizedlist>
2943 <listitem><para id="x_351">A gauche on la version de
2944 <emphasis>base</emphasis> du fichier, soit la plus récente version
2945 des deux versions qu'on souhaite fusionner.</para></listitem>
2946 <listitem><para id="x_352">Au centre, il y a <quote>notre</quote>
2947 version du fichier, avec le contenu que nous avons modifié.</para></listitem>
2948 <listitem><para id="x_353">Sur la droite, on trouve
2949 <quote>leur</quote> version du fichier, celui qui contient la
2950 révision que nous souhaitons intégré.</para>
2951 </listitem></itemizedlist>
2952 <para id="x_354">Dans le panneau en dessous, on trouve le
2953 <emphasis>résultat</emphasis> actuel de notre fusion. Notre tâche
2954 consiste donc à remplacement tous les textes en rouges,
2955 qui indiquent des conflits non résolus, avec une fusion manuelle et
2956 pertinente de <quote>notre</quote> version et de la <quote>leur</quote>.
2957 </para>
2959 <para id="x_355">Tous les quatre panneaux sont <emphasis>accrochés ensemble</emphasis>,
2960 si nous déroulons les ascenseurs verticalement ou horizontalement dans chacun
2961 d'entre eux, les autres sont mis à jour avec la section correspondante dans leurs
2962 fichiers respectifs.</para>
2964 <figure id="fig:tour-merge:kdiff3" float="0">
2965 <title>Utiliser <command moreinfo="none">kdiff3</command> pour fusionner les
2966 différentes version d'un fichier.</title>
2967 <mediaobject>
2968 <imageobject>
2969 <imagedata width="100%" fileref="figs/kdiff3.png"/></imageobject>
2970 <textobject>
2971 <phrase>XXX ajoute texte</phrase>
2972 </textobject>
2973 </mediaobject>
2974 </figure>
2976 <para id="x_357">Pour chaque portion de fichier posant problème, nous
2977 pouvons choisir de résoudre le conflit en utilisant une combinaison de
2978 texte depuis la version de base, la notre, ou la leur. Nous pouvons
2979 aussi éditer manuellement les fichiers à tout moment, si c'est nécessaire.</para>
2981 <para id="x_358">Il y a <emphasis>beaucoup</emphasis> d'outils de
2982 fusion disponibles, bien trop pour en parler de tous ici. Leurs
2983 disponibilités varient selon les plate formes ainsi que leurs
2984 avantages et inconvénients. La plupart sont optimisé pour
2985 la fusion de fichier contenant un texte plat, certains sont spécialisé
2986 dans un format de fichier précis (généralement XML).</para>
2987 </sect2>
2989 <sect2>
2990 <title>Un exemple concret</title>
2992 <para id="x_359">Dans cet exemple, nous allons reproduire la
2993 modification de l'historique du fichier de la figure <xref linkend="fig:tour-merge:conflict"/> ci dessus. Commençons par créer
2994 un dépôt avec une version de base de notre document.</para>
2996 <!-- BEGIN tour-merge-conflict.wife -->
2997 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat > letter.txt <<EOF</userinput>
2998 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">Greetings!</userinput>
2999 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">I am Mariam Abacha, the wife of former</userinput>
3000 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">Nigerian dictator Sani Abacha.</userinput>
3001 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">EOF</userinput>
3002 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add letter.txt</userinput>
3003 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m '419 scam, first draft'</userinput>
3004 </screen>
3005 <!-- END tour-merge-conflict.wife -->
3008 <para id="x_35a">Créons un clone de ce dépôt et faisons une
3009 modification dans le fichier.</para>
3011 <!-- BEGIN tour-merge-conflict.cousin -->
3012 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
3013 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone scam scam-cousin</userinput>
3014 updating working directory
3015 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
3016 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd scam-cousin</userinput>
3017 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat > letter.txt <<EOF</userinput>
3018 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">Greetings!</userinput>
3019 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">I am Shehu Musa Abacha, cousin to the former</userinput>
3020 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">Nigerian dictator Sani Abacha.</userinput>
3021 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">EOF</userinput>
3022 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m '419 scam, with cousin'</userinput>
3023 </screen>
3024 <!-- END tour-merge-conflict.cousin -->
3027 <para id="x_35b">Et un autre clone, pour simuler que quelqu'un d'autre effectue une
3028 modification sur le fichier. (Ceci pour suggérer qu'il n'est pas rare
3029 de devoir effectuer des fusions (merges) avec vos propres travaux quand
3030 vous isolez les tâches dans des dépôts distincts. En effet, vous
3031 aurez alors à trouver et résoudre certains conflits).</para>
3033 <!-- BEGIN tour-merge-conflict.son -->
3034 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
3035 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone scam scam-son</userinput>
3036 updating working directory
3037 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
3038 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd scam-son</userinput>
3039 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat > letter.txt <<EOF</userinput>
3040 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">Greetings!</userinput>
3041 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">I am Alhaji Abba Abacha, son of the former</userinput>
3042 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">Nigerian dictator Sani Abacha.</userinput>
3043 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">EOF</userinput>
3044 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m '419 scam, with son'</userinput>
3045 </screen>
3046 <!-- END tour-merge-conflict.son -->
3049 <para id="x_35c">Maintenant que ces deux versions différentes du même fichier sont
3050 créées, nous allons configurer l'environnement de manière appropriée pour
3051 exécuter notre fusion (merge).</para>
3053 <!-- BEGIN tour-merge-conflict.pull -->
3054 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
3055 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone scam-cousin scam-merge</userinput>
3056 updating working directory
3057 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
3058 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd scam-merge</userinput>
3059 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull -u ../scam-son</userinput>
3060 pulling from ../scam-son
3061 searching for changes
3062 adding changesets
3063 adding manifests
3064 adding file changes
3065 added 1 changesets with 1 changes to 1 files (+1 heads)
3066 not updating, since new heads added
3067 (run 'hg heads' to see heads, 'hg merge' to merge)
3068 </screen>
3069 <!-- END tour-merge-conflict.pull -->
3072 <para id="x_35d">Dans cette exemple, je n'utiliserais pas la commande Mercurial
3073 habituelle <command moreinfo="none">hgmerge</command> pour effectuer le
3074 fusion (merge), car il me faudrait abandonner ce joli petit exemple automatisé
3075 pour utiliser un outil graphique. À la place, je vais définir la
3076 variable d'environnement <envar>HGMERGE</envar> pour indiquer à
3077 Mercurial d'utiliser la commande non-interactive <command moreinfo="none">merge</command>.
3078 Cette dernière est embarquée par de nombreux systèmes <quote>à la Unix</quote>.
3079 Si vous exécutez cet exemple depuis votre ordinateur, ne vous
3080 occupez pas de définir <envar>HGMERGE</envar>.</para>
3082 <!-- BEGIN tour-merge-conflict.merge -->
3083 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">export HGMERGE=merge</userinput>
3084 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
3085 merging letter.txt
3086 merge: warning: conflicts during merge
3087 merging letter.txt failed!
3088 0 files updated, 0 files merged, 0 files removed, 1 files unresolved
3089 use 'hg resolve' to retry unresolved file merges or 'hg up --clean' to abandon
3090 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat letter.txt</userinput>
3091 Greetings!
3092 <<<<<<< /tmp/tour-merge-conflictk3twLJ/scam-merge/letter.txt
3093 I am Shehu Musa Abacha, cousin to the former
3094 =======
3095 I am Alhaji Abba Abacha, son of the former
3096 >>>>>>> /tmp/letter.txt~other.4O623C
3097 Nigerian dictator Sani Abacha.
3098 </screen>
3099 <!-- END tour-merge-conflict.merge -->
3103 <para id="x_35f">Parce que <command moreinfo="none">merge</command> ne peut pas résoudre
3104 les modifications conflictuelles, il laisse des <emphasis>marqueurs de
3105 différences</emphasis> à l'intérieur du fichier qui a des conflits,
3106 indiquant clairement quelles lignes sont en conflits, et si elles
3107 viennent de notre fichier ou du fichier externe.
3108 </para>
3110 <para id="x_360">Mercurial peut distinguer, à la manière dont la
3111 commande <command moreinfo="none">merge</command> se termine, qu'elle n'a pas été
3112 capable d'effectuer la fusion (merge), alors il nous indique que nous
3113 devons effectuer de nouveau cette opération. Ceci peut être très utile
3114 si, par exemple, nous exécutons un outil graphique de fusion et que
3115 nous le quittons sans nous rendre compte qu'il reste des conflits ou
3116 simplement par erreur.</para>
3118 <para id="x_361">Si la fusion (merge) automatique ou manuelle échoue,
3119 il n'y a rien pour nous empêcher de <quote>corriger le tir</quote> en
3120 modifiant nous même les fichiers, et enfin effectuer le "commit" du
3121 fichier:</para>
3123 <!-- BEGIN tour-merge-conflict.commit -->
3124 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat > letter.txt <<EOF</userinput>
3125 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">Greetings!</userinput>
3126 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">I am Bryan O'Sullivan, no relation of the former</userinput>
3127 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">Nigerian dictator Sani Abacha.</userinput>
3128 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">EOF</userinput>
3129 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg resolve -m letter.txt</userinput>
3130 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Send me your money'</userinput>
3131 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
3132 changeset: 3:0954bda76c6b
3133 tag: tip
3134 parent: 1:1ac156b6e708
3135 parent: 2:7ee20631b33b
3136 user: Bryan O'Sullivan <bos@serpentine.com>
3137 date: Sun Aug 16 14:05:34 2009 +0000
3138 summary: Send me your money
3140 </screen>
3141 <!-- END tour-merge-conflict.commit -->
3144 <note>
3145 <title>Où est la <command moreinfo="none">hg resolve</command> ?</title>
3147 <para id="x_724">La commande <command moreinfo="none">hg resolve</command> a été
3148 introduit dans la version 1.1 de Mercurial, qui a été publié en
3149 décembre 2008. Si vous utilisez une version plus anciennne de
3150 Mercurial (exécutez la command <command moreinfo="none">hg version</command> pour en
3151 avoir le coeur net), cette commande ne sera pas disponible. Si votre
3152 version de Mercurial est plus ancienne que la 1.1, vous devriez très
3153 fortement considérer une mise à jour à une version plus récente avant
3154 d'essayer de régler des fusions complexes.</para>
3155 </note>
3156 </sect2>
3157 </sect1>
3159 <sect1 id="sec:tour-merge:fetch">
3160 <title>Simplification de la séquence pull-merge-commit</title>
3162 <para id="x_362">La procédure pour effectuer la fusion indiquée
3163 ci-dessus est simple, mais requiert le lancement de trois commandes à la
3164 suite.</para>
3166 <programlisting format="linespecific">hg pull -u
3167 hg merge
3168 hg commit -m 'Merged remote changes'</programlisting>
3170 <para id="x_363">Lors du "commit" final, vous devez également saisir un
3171 message, qui aura vraisemblablement assez peu d'intérêt.</para>
3173 <para id="x_364">Il serait assez sympathique de pouvoir réduire le
3174 nombre d'opérations nécessaire, si possible. De fait Mercurial est
3175 fourni avec une extension appelé <literal role="hg-ext" moreinfo="none">fetch</literal>
3176 qui fait justement cela.</para>
3178 <para id="x_365">Mercurial fourni un mécanisme d'extension flexible qui permet à chacun
3179 d'étendre ces fonctionnalités, tout en conservant le cœur de Mercurial
3180 léger et facile à utiliser. Certains extensions ajoutent de nouvelles
3181 commandes que vous pouvez utiliser en ligne de commande, alors que
3182 d'autres travaillent <quote>en coulisse,</quote> par exemple en ajoutant des
3183 possibilités au serveur.</para>
3185 <para id="x_366">L'extension <literal role="hg-ext" moreinfo="none">fetch</literal>
3186 ajoute une nouvelle commande nommée, sans surprise, <command role="hg-cmd" moreinfo="none">hg fetch</command>. Cette extension résulte en une
3187 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
3188 merge</command>. Elle commence par récupérer les modifications d'un
3189 autre dépôt dans le dépôt courant. Si elle trouve que les
3190 modifications ajoutent une nouvelle "head", elle effectue un "merge",
3191 et ensuite "commit" le résultat du "merge" avec un message généré
3192 automatiquement. Si aucune "head" n'ont été ajouté, elle met à jour le
3193 répertoire de travail au niveau de la nouvelle révision tip.</para>
3195 <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
3196 <literal role="rc-extensions" moreinfo="none">extensions</literal>. Ensuite ajoutez
3197 une ligne qui consiste simplement en <quote>\Verb+fetch =</quote>.</para>
3199 <programlisting format="linespecific">[extensions]
3200 fetch =</programlisting>
3202 <para id="x_368">(Normalement, sur la partie droite de
3203 <quote><literal moreinfo="none">=</literal></quote> devrait apparaître le chemin de
3204 l'extension, mais étant donné que l'extension <literal role="hg-ext" moreinfo="none">fetch</literal> fait partie de la distribution standard,
3205 Mercurial sait où la trouver.) </para>
3207 </sect1>
3209 <sect1>
3210 <title>Renommer, copier, et fusionner (merge)</title>
3212 <para id="x_729">En cours de la vie d'un projet, nous allons souvent
3213 vouloir changer la disposition de ses fichiers et de ses répertoires.
3214 Ceci peut être aussi simple que de changer le nom d'un seul fichier,
3215 et aussi compliqué que de restructurer une hiérarchie entiere de fichier
3216 au sein du projet.</para>
3218 <para id="x_72a">Mercurial permet de faire ce genre de modification de
3219 manière fluide, à condition de l'informer de ce que nous faisons. Si
3220 vous voulez renommenr un ficher, vous devriez utiliser les commande
3221 <command moreinfo="none">hg rename</command><footnote>
3222 <para id="x_72b">Si vous un utilisateur de Unix, vous serez content
3223 de savoir que la commande <command moreinfo="none">hg rename</command> command
3224 peut être abrégée en <command moreinfo="none">hg mv</command>.</para>
3225 </footnote> pour changer son nom, ainsi Mercurial peut ensuite prendre
3226 la bonne décision, plus tard, en cas de fusionv (merge).</para>
3228 <para id="x_72c">Nous étudierojns en détail l'utilisation de ces commandes,
3229 en détail, dans le chapitre <xref linkend="chap:daily.copy"/>.</para>
3230 </sect1>
3231 </chapter>
3233 <!--
3234 local variables:
3235 sgml-parent-document: ("00book.xml" "book" "chapter")
3236 end:
3237 -->
3239 <!-- BEGIN ch04 -->
3240 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
3242 <chapter id="chap:concepts">
3243 <?dbhtml filename="behind-the-scenes.html"?>
3244 <title>Derrière le décor</title>
3246 <para id="x_2e8">À la différence de beaucoup d'outils de gestion de versions,
3247 les concepts sur lesquels se base Mercurial sont assez simples pour
3248 qu'il soit facile de comprendre comment le logiciel fonctionne.
3249 Bien que leur connaissance ne soit pas nécéssaire, je trouve utile
3250 d'avoir un <quote>modèle mental</quote> de ce qui se passe.</para>
3252 <para id="x_2e9">En effet, cette compréhension m'apporte la confiance que
3253 Mercurial a été développé avec soin pour être à la fois
3254 <emphasis>sûr</emphasis> et <emphasis>efficace</emphasis>. De surcroît,
3255 si il m'est facile de garder en tête ce que le logiciel fait lorsque
3256 j'accompli des tâches de révision, j'aurai moins de risques d'être
3257 surpris par son comportement.</para>
3259 <para id="x_2ea">Dans ce chapitre, nous décrirons tout d'abord les concepts
3260 essentiels de l'architecture de Mercurial, pour ensuite discuter quelques
3261 uns des détails intéressants de son implémentation.</para>
3263 <sect1>
3264 <title>Conservation de l'historique sous Mercurial</title>
3265 <sect2>
3266 <title>Suivi de l'historique pour un seul fichier</title>
3268 <para id="x_2eb">Lorsque Mercurial effectue un suivi des modifications
3269 faites à un fichier, il conserve l'historique pour ce fichier dans un
3270 <emphasis>filelog</emphasis> sous forme de métadonnées. Chaque entrée
3271 dans le filelog contient assez d'informations pour reconstituer une
3272 révision du fichier correspondant. Les filelogs sont des fichiers
3273 stockés dans le répertoire <filename role="special" class="directory" moreinfo="none">.hg/store/data</filename>. Un filelog contient
3274 des informations de deux types: les données de révision, et un index
3275 pour permettre à Mercurial une recherche efficace d'une révision
3276 donnée.</para>
3278 <para id="x_2ec">Lorsqu'un fichier devient trop gros ou a un long
3279 historique, son filelog se voit stocker dans un fichier de données
3280 (avec un suffixe <quote><literal moreinfo="none">.d</literal></quote>) et un fichier
3281 index (avec un suffixe<quote><literal moreinfo="none">.i</literal></quote>)
3282 distincts. La relation entre un fichier dans le répertoire de travail
3283 et le filelog couvrant le suivi de son historique dans le dépôt est
3284 illustré à la figure <xref linkend="fig:concepts:filelog"/>.</para>
3286 <figure id="fig:concepts:filelog" float="0">
3287 <title>Relations entre les fichiers dans le répertoire de travail et
3288 leurs filelogs dans le dépôt</title>
3289 <mediaobject> <imageobject><imagedata fileref="figs/filelog.png"/></imageobject>
3290 <textobject><phrase>XXX add text</phrase></textobject>
3291 </mediaobject> </figure>
3293 </sect2>
3294 <sect2>
3295 <title>Gestion des fichiers suivis</title>
3297 <para id="x_2ee">Mercurial a recours à une structure nommée
3298 <emphasis>manifest</emphasis> pour rassembler les informations sur
3299 les fichiers dont il gère le suivi. Chaque entrée dans ce manifest
3300 contient des informations sur les fichiers présents dans une révision
3301 donnée. Une entrée store la liste des fichiers faisant partie de la
3302 révision, la version de chaque fichier, et quelques autres
3303 métadonnées sur ces fichiers.</para>
3305 </sect2>
3306 <sect2>
3307 <title>Recording changeset information</title>
3309 <para id="x_2ef">The <emphasis>changelog</emphasis> contains
3310 information about each changeset. Each revision records who
3311 committed a change, the changeset comment, other pieces of
3312 changeset-related information, and the revision of the manifest to
3313 use.</para>
3315 </sect2>
3316 <sect2>
3317 <title>Relationships between revisions</title>
3319 <para id="x_2f0">Within a changelog, a manifest, or a filelog, each
3320 revision stores a pointer to its immediate parent (or to its
3321 two parents, if it's a merge revision). As I mentioned above,
3322 there are also relationships between revisions
3323 <emphasis>across</emphasis> these structures, and they are
3324 hierarchical in nature.</para>
3326 <para id="x_2f1">For every changeset in a repository, there is exactly one
3327 revision stored in the changelog. Each revision of the
3328 changelog contains a pointer to a single revision of the
3329 manifest. A revision of the manifest stores a pointer to a
3330 single revision of each filelog tracked when that changeset
3331 was created. These relationships are illustrated in
3332 <xref linkend="fig:concepts:metadata"/>.</para>
3334 <figure id="fig:concepts:metadata" float="0">
3335 <title>Metadata relationships</title>
3336 <mediaobject>
3337 <imageobject><imagedata fileref="figs/metadata.png"/></imageobject>
3338 <textobject><phrase>XXX add text</phrase></textobject>
3339 </mediaobject>
3340 </figure>
3342 <para id="x_2f3">As the illustration shows, there is
3343 <emphasis>not</emphasis> a <quote>one to one</quote>
3344 relationship between revisions in the changelog, manifest, or
3345 filelog. If a file that
3346 Mercurial tracks hasn't changed between two changesets, the
3347 entry for that file in the two revisions of the manifest will
3348 point to the same revision of its filelog<footnote>
3349 <para id="x_725">It is possible (though unusual) for the manifest to
3350 remain the same between two changesets, in which case the
3351 changelog entries for those changesets will point to the
3352 same revision of the manifest.</para>
3353 </footnote>.</para>
3355 </sect2>
3356 </sect1>
3357 <sect1>
3358 <title>Safe, efficient storage</title>
3360 <para id="x_2f4">The underpinnings of changelogs, manifests, and filelogs are
3361 provided by a single structure called the
3362 <emphasis>revlog</emphasis>.</para>
3364 <sect2>
3365 <title>Efficient storage</title>
3367 <para id="x_2f5">The revlog provides efficient storage of revisions using a
3368 <emphasis>delta</emphasis> mechanism. Instead of storing a
3369 complete copy of a file for each revision, it stores the
3370 changes needed to transform an older revision into the new
3371 revision. For many kinds of file data, these deltas are
3372 typically a fraction of a percent of the size of a full copy
3373 of a file.</para>
3375 <para id="x_2f6">Some obsolete revision control systems can only work with
3376 deltas of text files. They must either store binary files as
3377 complete snapshots or encoded into a text representation, both
3378 of which are wasteful approaches. Mercurial can efficiently
3379 handle deltas of files with arbitrary binary contents; it
3380 doesn't need to treat text as special.</para>
3382 </sect2>
3383 <sect2 id="sec:concepts:txn">
3384 <title>Safe operation</title>
3386 <para id="x_2f7">Mercurial only ever <emphasis>appends</emphasis> data to
3387 the end of a revlog file. It never modifies a section of a
3388 file after it has written it. This is both more robust and
3389 efficient than schemes that need to modify or rewrite
3390 data.</para>
3392 <para id="x_2f8">In addition, Mercurial treats every write as part of a
3393 <emphasis>transaction</emphasis> that can span a number of
3394 files. A transaction is <emphasis>atomic</emphasis>: either
3395 the entire transaction succeeds and its effects are all
3396 visible to readers in one go, or the whole thing is undone.
3397 This guarantee of atomicity means that if you're running two
3398 copies of Mercurial, where one is reading data and one is
3399 writing it, the reader will never see a partially written
3400 result that might confuse it.</para>
3402 <para id="x_2f9">The fact that Mercurial only appends to files makes it
3403 easier to provide this transactional guarantee. The easier it
3404 is to do stuff like this, the more confident you should be
3405 that it's done correctly.</para>
3407 </sect2>
3408 <sect2>
3409 <title>Fast retrieval</title>
3411 <para id="x_2fa">Mercurial cleverly avoids a pitfall common to
3412 all earlier revision control systems: the problem of
3413 <emphasis>inefficient retrieval</emphasis>. Most revision
3414 control systems store the contents of a revision as an
3415 incremental series of modifications against a
3416 <quote>snapshot</quote>. (Some base the snapshot on the
3417 oldest revision, others on the newest.) To reconstruct a
3418 specific revision, you must first read the snapshot, and then
3419 every one of the revisions between the snapshot and your
3420 target revision. The more history that a file accumulates,
3421 the more revisions you must read, hence the longer it takes to
3422 reconstruct a particular revision.</para>
3424 <figure id="fig:concepts:snapshot" float="0">
3425 <title>Snapshot of a revlog, with incremental deltas</title>
3426 <mediaobject>
3427 <imageobject><imagedata fileref="figs/snapshot.png"/></imageobject>
3428 <textobject><phrase>XXX add text</phrase></textobject>
3429 </mediaobject>
3430 </figure>
3432 <para id="x_2fc">The innovation that Mercurial applies to this problem is
3433 simple but effective. Once the cumulative amount of delta
3434 information stored since the last snapshot exceeds a fixed
3435 threshold, it stores a new snapshot (compressed, of course),
3436 instead of another delta. This makes it possible to
3437 reconstruct <emphasis>any</emphasis> revision of a file
3438 quickly. This approach works so well that it has since been
3439 copied by several other revision control systems.</para>
3441 <para id="x_2fd"><xref linkend="fig:concepts:snapshot"/> illustrates
3442 the idea. In an entry in a revlog's index file, Mercurial
3443 stores the range of entries from the data file that it must
3444 read to reconstruct a particular revision.</para>
3446 <sect3>
3447 <title>Aside: the influence of video compression</title>
3449 <para id="x_2fe">If you're familiar with video compression or
3450 have ever watched a TV feed through a digital cable or
3451 satellite service, you may know that most video compression
3452 schemes store each frame of video as a delta against its
3453 predecessor frame.</para>
3455 <para id="x_2ff">Mercurial borrows this idea to make it
3456 possible to reconstruct a revision from a snapshot and a
3457 small number of deltas.</para>
3459 </sect3>
3460 </sect2>
3461 <sect2>
3462 <title>Identification and strong integrity</title>
3464 <para id="x_300">Along with delta or snapshot information, a revlog entry
3465 contains a cryptographic hash of the data that it represents.
3466 This makes it difficult to forge the contents of a revision,
3467 and easy to detect accidental corruption.</para>
3469 <para id="x_301">Hashes provide more than a mere check against corruption;
3470 they are used as the identifiers for revisions. The changeset
3471 identification hashes that you see as an end user are from
3472 revisions of the changelog. Although filelogs and the
3473 manifest also use hashes, Mercurial only uses these behind the
3474 scenes.</para>
3476 <para id="x_302">Mercurial verifies that hashes are correct when it
3477 retrieves file revisions and when it pulls changes from
3478 another repository. If it encounters an integrity problem, it
3479 will complain and stop whatever it's doing.</para>
3481 <para id="x_303">In addition to the effect it has on retrieval efficiency,
3482 Mercurial's use of periodic snapshots makes it more robust
3483 against partial data corruption. If a revlog becomes partly
3484 corrupted due to a hardware error or system bug, it's often
3485 possible to reconstruct some or most revisions from the
3486 uncorrupted sections of the revlog, both before and after the
3487 corrupted section. This would not be possible with a
3488 delta-only storage model.</para>
3489 </sect2>
3490 </sect1>
3492 <sect1>
3493 <title>Revision history, branching, and merging</title>
3495 <para id="x_304">Every entry in a Mercurial revlog knows the identity of its
3496 immediate ancestor revision, usually referred to as its
3497 <emphasis>parent</emphasis>. In fact, a revision contains room
3498 for not one parent, but two. Mercurial uses a special hash,
3499 called the <quote>null ID</quote>, to represent the idea
3500 <quote>there is no parent here</quote>. This hash is simply a
3501 string of zeroes.</para>
3503 <para id="x_305">In <xref linkend="fig:concepts:revlog"/>, you can see
3504 an example of the conceptual structure of a revlog. Filelogs,
3505 manifests, and changelogs all have this same structure; they
3506 differ only in the kind of data stored in each delta or
3507 snapshot.</para>
3509 <para id="x_306">The first revision in a revlog (at the bottom of the image)
3510 has the null ID in both of its parent slots. For a
3511 <quote>normal</quote> revision, its first parent slot contains
3512 the ID of its parent revision, and its second contains the null
3513 ID, indicating that the revision has only one real parent. Any
3514 two revisions that have the same parent ID are branches. A
3515 revision that represents a merge between branches has two normal
3516 revision IDs in its parent slots.</para>
3518 <figure id="fig:concepts:revlog" float="0">
3519 <title>The conceptual structure of a revlog</title>
3520 <mediaobject>
3521 <imageobject><imagedata fileref="figs/revlog.png"/></imageobject>
3522 <textobject><phrase>XXX add text</phrase></textobject>
3523 </mediaobject>
3524 </figure>
3526 </sect1>
3527 <sect1>
3528 <title>The working directory</title>
3530 <para id="x_307">In the working directory, Mercurial stores a snapshot of the
3531 files from the repository as of a particular changeset.</para>
3533 <para id="x_308">The working directory <quote>knows</quote> which changeset
3534 it contains. When you update the working directory to contain a
3535 particular changeset, Mercurial looks up the appropriate
3536 revision of the manifest to find out which files it was tracking
3537 at the time that changeset was committed, and which revision of
3538 each file was then current. It then recreates a copy of each of
3539 those files, with the same contents it had when the changeset
3540 was committed.</para>
3542 <para id="x_309">The <emphasis>dirstate</emphasis> is a special
3543 structure that contains Mercurial's knowledge of the working
3544 directory. It is maintained as a file named
3545 <filename moreinfo="none">.hg/dirstate</filename> inside a repository. The
3546 dirstate details which changeset the working directory is
3547 updated to, and all of the files that Mercurial is tracking in
3548 the working directory. It also lets Mercurial quickly notice
3549 changed files, by recording their checkout times and
3550 sizes.</para>
3552 <para id="x_30a">Just as a revision of a revlog has room for two parents, so
3553 that it can represent either a normal revision (with one parent)
3554 or a merge of two earlier revisions, the dirstate has slots for
3555 two parents. When you use the <command role="hg-cmd" moreinfo="none">hg
3556 update</command> command, the changeset that you update to is
3557 stored in the <quote>first parent</quote> slot, and the null ID
3558 in the second. When you <command role="hg-cmd" moreinfo="none">hg
3559 merge</command> with another changeset, the first parent
3560 remains unchanged, and the second parent is filled in with the
3561 changeset you're merging with. The <command role="hg-cmd" moreinfo="none">hg
3562 parents</command> command tells you what the parents of the
3563 dirstate are.</para>
3565 <sect2>
3566 <title>What happens when you commit</title>
3568 <para id="x_30b">The dirstate stores parent information for more than just
3569 book-keeping purposes. Mercurial uses the parents of the
3570 dirstate as <emphasis>the parents of a new
3571 changeset</emphasis> when you perform a commit.</para>
3573 <figure id="fig:concepts:wdir" float="0">
3574 <title>The working directory can have two parents</title>
3575 <mediaobject>
3576 <imageobject><imagedata fileref="figs/wdir.png"/></imageobject>
3577 <textobject><phrase>XXX add text</phrase></textobject>
3578 </mediaobject>
3579 </figure>
3581 <para id="x_30d"><xref linkend="fig:concepts:wdir"/> shows the
3582 normal state of the working directory, where it has a single
3583 changeset as parent. That changeset is the
3584 <emphasis>tip</emphasis>, the newest changeset in the
3585 repository that has no children.</para>
3587 <figure id="fig:concepts:wdir-after-commit" float="0">
3588 <title>The working directory gains new parents after a
3589 commit</title>
3590 <mediaobject>
3591 <imageobject><imagedata fileref="figs/wdir-after-commit.png"/></imageobject>
3592 <textobject><phrase>XXX add text</phrase></textobject>
3593 </mediaobject>
3594 </figure>
3596 <para id="x_30f">It's useful to think of the working directory as
3597 <quote>the changeset I'm about to commit</quote>. Any files
3598 that you tell Mercurial that you've added, removed, renamed,
3599 or copied will be reflected in that changeset, as will
3600 modifications to any files that Mercurial is already tracking;
3601 the new changeset will have the parents of the working
3602 directory as its parents.</para>
3604 <para id="x_310">After a commit, Mercurial will update the
3605 parents of the working directory, so that the first parent is
3606 the ID of the new changeset, and the second is the null ID.
3607 This is shown in <xref linkend="fig:concepts:wdir-after-commit"/>. Mercurial
3608 doesn't touch any of the files in the working directory when
3609 you commit; it just modifies the dirstate to note its new
3610 parents.</para>
3612 </sect2>
3613 <sect2>
3614 <title>Creating a new head</title>
3616 <para id="x_311">It's perfectly normal to update the working directory to a
3617 changeset other than the current tip. For example, you might
3618 want to know what your project looked like last Tuesday, or
3619 you could be looking through changesets to see which one
3620 introduced a bug. In cases like this, the natural thing to do
3621 is update the working directory to the changeset you're
3622 interested in, and then examine the files in the working
3623 directory directly to see their contents as they were when you
3624 committed that changeset. The effect of this is shown in
3625 <xref linkend="fig:concepts:wdir-pre-branch"/>.</para>
3627 <figure id="fig:concepts:wdir-pre-branch" float="0">
3628 <title>The working directory, updated to an older
3629 changeset</title>
3630 <mediaobject>
3631 <imageobject><imagedata fileref="figs/wdir-pre-branch.png"/></imageobject>
3632 <textobject><phrase>XXX add text</phrase></textobject>
3633 </mediaobject>
3634 </figure>
3636 <para id="x_313">Having updated the working directory to an
3637 older changeset, what happens if you make some changes, and
3638 then commit? Mercurial behaves in the same way as I outlined
3639 above. The parents of the working directory become the
3640 parents of the new changeset. This new changeset has no
3641 children, so it becomes the new tip. And the repository now
3642 contains two changesets that have no children; we call these
3643 <emphasis>heads</emphasis>. You can see the structure that
3644 this creates in <xref linkend="fig:concepts:wdir-branch"/>.</para>
3646 <figure id="fig:concepts:wdir-branch" float="0">
3647 <title>After a commit made while synced to an older
3648 changeset</title>
3649 <mediaobject>
3650 <imageobject><imagedata fileref="figs/wdir-branch.png"/></imageobject>
3651 <textobject><phrase>XXX add text</phrase></textobject>
3652 </mediaobject>
3653 </figure>
3655 <note>
3656 <para id="x_315">If you're new to Mercurial, you should keep
3657 in mind a common <quote>error</quote>, which is to use the
3658 <command role="hg-cmd" moreinfo="none">hg pull</command> command without any
3659 options. By default, the <command role="hg-cmd" moreinfo="none">hg
3660 pull</command> command <emphasis>does not</emphasis>
3661 update the working directory, so you'll bring new changesets
3662 into your repository, but the working directory will stay
3663 synced at the same changeset as before the pull. If you
3664 make some changes and commit afterwards, you'll thus create
3665 a new head, because your working directory isn't synced to
3666 whatever the current tip is. To combine the operation of a
3667 pull, followed by an update, run <command moreinfo="none">hg pull
3668 -u</command>.</para>
3670 <para id="x_316">I put the word <quote>error</quote> in quotes
3671 because all that you need to do to rectify the situation
3672 where you created a new head by accident is
3673 <command role="hg-cmd" moreinfo="none">hg merge</command>, then <command role="hg-cmd" moreinfo="none">hg commit</command>. In other words, this
3674 almost never has negative consequences; it's just something
3675 of a surprise for newcomers. I'll discuss other ways to
3676 avoid this behavior, and why Mercurial behaves in this
3677 initially surprising way, later on.</para>
3678 </note>
3680 </sect2>
3681 <sect2>
3682 <title>Merging changes</title>
3684 <para id="x_317">When you run the <command role="hg-cmd" moreinfo="none">hg
3685 merge</command> command, Mercurial leaves the first parent
3686 of the working directory unchanged, and sets the second parent
3687 to the changeset you're merging with, as shown in <xref linkend="fig:concepts:wdir-merge"/>.</para>
3689 <figure id="fig:concepts:wdir-merge" float="0">
3690 <title>Merging two heads</title>
3691 <mediaobject>
3692 <imageobject>
3693 <imagedata fileref="figs/wdir-merge.png"/>
3694 </imageobject>
3695 <textobject><phrase>XXX add text</phrase></textobject>
3696 </mediaobject>
3697 </figure>
3699 <para id="x_319">Mercurial also has to modify the working directory, to
3700 merge the files managed in the two changesets. Simplified a
3701 little, the merging process goes like this, for every file in
3702 the manifests of both changesets.</para>
3703 <itemizedlist>
3704 <listitem><para id="x_31a">If neither changeset has modified a file, do
3705 nothing with that file.</para>
3706 </listitem>
3707 <listitem><para id="x_31b">If one changeset has modified a file, and the
3708 other hasn't, create the modified copy of the file in the
3709 working directory.</para>
3710 </listitem>
3711 <listitem><para id="x_31c">If one changeset has removed a file, and the
3712 other hasn't (or has also deleted it), delete the file
3713 from the working directory.</para>
3714 </listitem>
3715 <listitem><para id="x_31d">If one changeset has removed a file, but the
3716 other has modified the file, ask the user what to do: keep
3717 the modified file, or remove it?</para>
3718 </listitem>
3719 <listitem><para id="x_31e">If both changesets have modified a file,
3720 invoke an external merge program to choose the new
3721 contents for the merged file. This may require input from
3722 the user.</para>
3723 </listitem>
3724 <listitem><para id="x_31f">If one changeset has modified a file, and the
3725 other has renamed or copied the file, make sure that the
3726 changes follow the new name of the file.</para>
3727 </listitem></itemizedlist>
3728 <para id="x_320">There are more details—merging has plenty of corner
3729 cases—but these are the most common choices that are
3730 involved in a merge. As you can see, most cases are
3731 completely automatic, and indeed most merges finish
3732 automatically, without requiring your input to resolve any
3733 conflicts.</para>
3735 <para id="x_321">When you're thinking about what happens when you commit
3736 after a merge, once again the working directory is <quote>the
3737 changeset I'm about to commit</quote>. After the <command role="hg-cmd" moreinfo="none">hg merge</command> command completes, the
3738 working directory has two parents; these will become the
3739 parents of the new changeset.</para>
3741 <para id="x_322">Mercurial lets you perform multiple merges, but
3742 you must commit the results of each individual merge as you
3743 go. This is necessary because Mercurial only tracks two
3744 parents for both revisions and the working directory. While
3745 it would be technically feasible to merge multiple changesets
3746 at once, Mercurial avoids this for simplicity. With multi-way
3747 merges, the risks of user confusion, nasty conflict
3748 resolution, and making a terrible mess of a merge would grow
3749 intolerable.</para>
3751 </sect2>
3753 <sect2>
3754 <title>Merging and renames</title>
3756 <para id="x_69a">A surprising number of revision control systems pay little
3757 or no attention to a file's <emphasis>name</emphasis> over
3758 time. For instance, it used to be common that if a file got
3759 renamed on one side of a merge, the changes from the other
3760 side would be silently dropped.</para>
3762 <para id="x_69b">Mercurial records metadata when you tell it to perform a
3763 rename or copy. It uses this metadata during a merge to do the
3764 right thing in the case of a merge. For instance, if I rename
3765 a file, and you edit it without renaming it, when we merge our
3766 work the file will be renamed and have your edits
3767 applied.</para>
3768 </sect2>
3769 </sect1>
3771 <sect1>
3772 <title>Other interesting design features</title>
3774 <para id="x_323">In the sections above, I've tried to highlight some of the
3775 most important aspects of Mercurial's design, to illustrate that
3776 it pays careful attention to reliability and performance.
3777 However, the attention to detail doesn't stop there. There are
3778 a number of other aspects of Mercurial's construction that I
3779 personally find interesting. I'll detail a few of them here,
3780 separate from the <quote>big ticket</quote> items above, so that
3781 if you're interested, you can gain a better idea of the amount
3782 of thinking that goes into a well-designed system.</para>
3784 <sect2>
3785 <title>Clever compression</title>
3787 <para id="x_324">When appropriate, Mercurial will store both snapshots and
3788 deltas in compressed form. It does this by always
3789 <emphasis>trying to</emphasis> compress a snapshot or delta,
3790 but only storing the compressed version if it's smaller than
3791 the uncompressed version.</para>
3793 <para id="x_325">This means that Mercurial does <quote>the right
3794 thing</quote> when storing a file whose native form is
3795 compressed, such as a <literal moreinfo="none">zip</literal> archive or a JPEG
3796 image. When these types of files are compressed a second
3797 time, the resulting file is usually bigger than the
3798 once-compressed form, and so Mercurial will store the plain
3799 <literal moreinfo="none">zip</literal> or JPEG.</para>
3801 <para id="x_326">Deltas between revisions of a compressed file are usually
3802 larger than snapshots of the file, and Mercurial again does
3803 <quote>the right thing</quote> in these cases. It finds that
3804 such a delta exceeds the threshold at which it should store a
3805 complete snapshot of the file, so it stores the snapshot,
3806 again saving space compared to a naive delta-only
3807 approach.</para>
3809 <sect3>
3810 <title>Network recompression</title>
3812 <para id="x_327">When storing revisions on disk, Mercurial uses the
3813 <quote>deflate</quote> compression algorithm (the same one
3814 used by the popular <literal moreinfo="none">zip</literal> archive format),
3815 which balances good speed with a respectable compression
3816 ratio. However, when transmitting revision data over a
3817 network connection, Mercurial uncompresses the compressed
3818 revision data.</para>
3820 <para id="x_328">If the connection is over HTTP, Mercurial recompresses
3821 the entire stream of data using a compression algorithm that
3822 gives a better compression ratio (the Burrows-Wheeler
3823 algorithm from the widely used <literal moreinfo="none">bzip2</literal>
3824 compression package). This combination of algorithm and
3825 compression of the entire stream (instead of a revision at a
3826 time) substantially reduces the number of bytes to be
3827 transferred, yielding better network performance over most
3828 kinds of network.</para>
3830 <para id="x_329">If the connection is over
3831 <command moreinfo="none">ssh</command>, Mercurial
3832 <emphasis>doesn't</emphasis> recompress the stream, because
3833 <command moreinfo="none">ssh</command> can already do this itself. You can
3834 tell Mercurial to always use <command moreinfo="none">ssh</command>'s
3835 compression feature by editing the
3836 <filename moreinfo="none">.hgrc</filename> file in your home directory as
3837 follows.</para>
3839 <programlisting format="linespecific">[ui]
3840 ssh = ssh -C</programlisting>
3842 </sect3>
3843 </sect2>
3844 <sect2>
3845 <title>Read/write ordering and atomicity</title>
3847 <para id="x_32a">Appending to files isn't the whole story when
3848 it comes to guaranteeing that a reader won't see a partial
3849 write. If you recall <xref linkend="fig:concepts:metadata"/>,
3850 revisions in the changelog point to revisions in the manifest,
3851 and revisions in the manifest point to revisions in filelogs.
3852 This hierarchy is deliberate.</para>
3854 <para id="x_32b">A writer starts a transaction by writing filelog and
3855 manifest data, and doesn't write any changelog data until
3856 those are finished. A reader starts by reading changelog
3857 data, then manifest data, followed by filelog data.</para>
3859 <para id="x_32c">Since the writer has always finished writing filelog and
3860 manifest data before it writes to the changelog, a reader will
3861 never read a pointer to a partially written manifest revision
3862 from the changelog, and it will never read a pointer to a
3863 partially written filelog revision from the manifest.</para>
3865 </sect2>
3866 <sect2>
3867 <title>Concurrent access</title>
3869 <para id="x_32d">The read/write ordering and atomicity guarantees mean that
3870 Mercurial never needs to <emphasis>lock</emphasis> a
3871 repository when it's reading data, even if the repository is
3872 being written to while the read is occurring. This has a big
3873 effect on scalability; you can have an arbitrary number of
3874 Mercurial processes safely reading data from a repository
3875 all at once, no matter whether it's being written to or
3876 not.</para>
3878 <para id="x_32e">The lockless nature of reading means that if you're
3879 sharing a repository on a multi-user system, you don't need to
3880 grant other local users permission to
3881 <emphasis>write</emphasis> to your repository in order for
3882 them to be able to clone it or pull changes from it; they only
3883 need <emphasis>read</emphasis> permission. (This is
3884 <emphasis>not</emphasis> a common feature among revision
3885 control systems, so don't take it for granted! Most require
3886 readers to be able to lock a repository to access it safely,
3887 and this requires write permission on at least one directory,
3888 which of course makes for all kinds of nasty and annoying
3889 security and administrative problems.)</para>
3891 <para id="x_32f">Mercurial uses locks to ensure that only one process can
3892 write to a repository at a time (the locking mechanism is safe
3893 even over filesystems that are notoriously hostile to locking,
3894 such as NFS). If a repository is locked, a writer will wait
3895 for a while to retry if the repository becomes unlocked, but
3896 if the repository remains locked for too long, the process
3897 attempting to write will time out after a while. This means
3898 that your daily automated scripts won't get stuck forever and
3899 pile up if a system crashes unnoticed, for example. (Yes, the
3900 timeout is configurable, from zero to infinity.)</para>
3902 <sect3>
3903 <title>Safe dirstate access</title>
3905 <para id="x_330">As with revision data, Mercurial doesn't take a lock to
3906 read the dirstate file; it does acquire a lock to write it.
3907 To avoid the possibility of reading a partially written copy
3908 of the dirstate file, Mercurial writes to a file with a
3909 unique name in the same directory as the dirstate file, then
3910 renames the temporary file atomically to
3911 <filename moreinfo="none">dirstate</filename>. The file named
3912 <filename moreinfo="none">dirstate</filename> is thus guaranteed to be
3913 complete, not partially written.</para>
3915 </sect3>
3916 </sect2>
3917 <sect2>
3918 <title>Avoiding seeks</title>
3920 <para id="x_331">Critical to Mercurial's performance is the avoidance of
3921 seeks of the disk head, since any seek is far more expensive
3922 than even a comparatively large read operation.</para>
3924 <para id="x_332">This is why, for example, the dirstate is stored in a
3925 single file. If there were a dirstate file per directory that
3926 Mercurial tracked, the disk would seek once per directory.
3927 Instead, Mercurial reads the entire single dirstate file in
3928 one step.</para>
3930 <para id="x_333">Mercurial also uses a <quote>copy on write</quote> scheme
3931 when cloning a repository on local storage. Instead of
3932 copying every revlog file from the old repository into the new
3933 repository, it makes a <quote>hard link</quote>, which is a
3934 shorthand way to say <quote>these two names point to the same
3935 file</quote>. When Mercurial is about to write to one of a
3936 revlog's files, it checks to see if the number of names
3937 pointing at the file is greater than one. If it is, more than
3938 one repository is using the file, so Mercurial makes a new
3939 copy of the file that is private to this repository.</para>
3941 <para id="x_334">A few revision control developers have pointed out that
3942 this idea of making a complete private copy of a file is not
3943 very efficient in its use of storage. While this is true,
3944 storage is cheap, and this method gives the highest
3945 performance while deferring most book-keeping to the operating
3946 system. An alternative scheme would most likely reduce
3947 performance and increase the complexity of the software, but
3948 speed and simplicity are key to the <quote>feel</quote> of
3949 day-to-day use.</para>
3951 </sect2>
3952 <sect2>
3953 <title>Other contents of the dirstate</title>
3955 <para id="x_335">Because Mercurial doesn't force you to tell it when you're
3956 modifying a file, it uses the dirstate to store some extra
3957 information so it can determine efficiently whether you have
3958 modified a file. For each file in the working directory, it
3959 stores the time that it last modified the file itself, and the
3960 size of the file at that time.</para>
3962 <para id="x_336">When you explicitly <command role="hg-cmd" moreinfo="none">hg
3963 add</command>, <command role="hg-cmd" moreinfo="none">hg remove</command>,
3964 <command role="hg-cmd" moreinfo="none">hg rename</command> or <command role="hg-cmd" moreinfo="none">hg copy</command> files, Mercurial updates the
3965 dirstate so that it knows what to do with those files when you
3966 commit.</para>
3968 <para id="x_337">The dirstate helps Mercurial to efficiently
3969 check the status of files in a repository.</para>
3971 <itemizedlist>
3972 <listitem>
3973 <para id="x_726">When Mercurial checks the state of a file in the
3974 working directory, it first checks a file's modification
3975 time against the time in the dirstate that records when
3976 Mercurial last wrote the file. If the last modified time
3977 is the same as the time when Mercurial wrote the file, the
3978 file must not have been modified, so Mercurial does not
3979 need to check any further.</para>
3980 </listitem>
3981 <listitem>
3982 <para id="x_727">If the file's size has changed, the file must have
3983 been modified. If the modification time has changed, but
3984 the size has not, only then does Mercurial need to
3985 actually read the contents of the file to see if it has
3986 changed.</para>
3987 </listitem>
3988 </itemizedlist>
3990 <para id="x_728">Storing the modification time and size dramatically
3991 reduces the number of read operations that Mercurial needs to
3992 perform when we run commands like <command moreinfo="none">hg status</command>.
3993 This results in large performance improvements.</para>
3994 </sect2>
3995 </sect1>
3996 </chapter>
3998 <!--
3999 local variables:
4000 sgml-parent-document: ("00book.xml" "book" "chapter")
4001 end:
4002 -->
4004 <!-- BEGIN ch05 -->
4005 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
4007 <chapter id="chap:daily">
4008 <?dbhtml filename="mercurial-in-daily-use.html"?>
4009 <title>Mercurial pour une utilisation de tous les jours</title>
4011 <sect1>
4012 <title>Informer Mercurial des fichier à suivre</title>
4014 <para id="x_1a3">Mercurial ne suit pas les fichiers de votre dépôt tant
4015 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
4016 inconnus de Mercurial. Il utilise un
4017 <quote><literal moreinfo="none">?</literal></quote> pour montrer ces fichiers.</para>
4019 <para id="x_1a4">Pour informer Mercurial de suivre un fichier, utilisez
4020 la commande <command role="hg-cmd" moreinfo="none">hg add</command>. Une fois que vous
4021 avez ajouté un fichier, la ligne correspondante à ce fichier dans la
4022 sortie de <command role="hg-cmd" moreinfo="none">hg status</command> change de
4023 <quote><literal moreinfo="none">?</literal></quote> à
4024 <quote><literal moreinfo="none">A</literal></quote>.</para>
4026 <!-- BEGIN daily.files.add -->
4027 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init add-example</userinput>
4028 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd add-example</userinput>
4029 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a > myfile.txt</userinput>
4030 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
4031 ? myfile.txt
4032 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add myfile.txt</userinput>
4033 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
4034 A myfile.txt
4035 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Added one file'</userinput>
4036 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
4037 </screen>
4038 <!-- END daily.files.add -->
4041 <para id="x_1a5">Après avoir exécuté un <command role="hg-cmd" moreinfo="none">hg
4042 commit</command>, les fichiers que vous avez ajoutés avant le commit
4043 ne seront plus listés dans la sortie de <command role="hg-cmd" moreinfo="none">hg
4044 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
4045 <quote>intéressants</quote> —ceux que vous avez (par exemple)
4046 modifiés, supprimés ou renommés. Si vous aviez un dépôt qui contient un
4047 millier de fichiers, vous ne voudriez certainement que rarement entendre
4048 parler des fichiers que Mercurial suit, mais qui n'ont pas changés.
4049 (Vous pouvez quand même avoir cette information, nous y reviendrons
4050 plus tard.)</para>
4052 <para id="x_1a6">Une fois que vous ajoutez un fichier, Mercurial ne fait
4053 rien du tout avec celui-ci immédiatement. Au lieu de ça, il va prendre
4054 un "snapshot" de l'état du fichier la prochaine fois que vous
4055 exécuterez un commit. Il continuera ensuite à suivre les changements
4056 que vous avez fait au fichier chaque fois que vous committerez, et ce,
4057 jusqu'à ce que vous supprimiez le fichier.</para>
4059 <sect2>
4060 <title>Nommage des fichiers explicite versus implicite</title>
4062 <para id="x_1a7">Un comportement utile que Mercurial possède est que si
4063 vous passez le nom d'un répertoire à une commande, toute commande
4064 Mercurial la traitera comme : <quote>Je veux opérer sur chaque fichier
4065 dans ce répertoire et ses sous-répertoires</quote>.</para>
4067 <!-- BEGIN daily.files.add-dir -->
4068 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir b</userinput>
4069 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b > b/somefile.txt</userinput>
4070 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo c > b/source.cpp</userinput>
4071 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir b/d</userinput>
4072 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo d > b/d/test.h</userinput>
4073 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add b</userinput>
4074 adding b/d/test.h
4075 adding b/somefile.txt
4076 adding b/source.cpp
4077 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Added all files in subdirectory'</userinput>
4078 </screen>
4079 <!-- END daily.files.add-dir -->
4082 <para id="x_1a8">Remarquez que dans cet exemple, Mercurial affiche le
4083 nom des fichiers qu'il a ajouté, alors qu'il ne l'a pas fait lorsque
4084 nous avons ajouté le fichier nommé <filename moreinfo="none">myfile.txt</filename>
4085 dans l'exemple précédent.</para>
4087 <para id="x_1a9">Ce qu'il se passe est que dans le premier cas, nous
4088 avons nommé explicitement le fichier à ajouter sur la ligne de
4089 commande. Ce que Mercurial suppose dans ce cas est que nous savons ce
4090 que nous faisons, il n'affiche donc rien en sortie.</para>
4092 <para id="x_1aa">Cependant, lorsque nous avons
4093 <emphasis>implicitement</emphasis> donné les fichiers à l'aide du nom
4094 d'un répertoire, Mercurial prend l'initiative d'afficher le nom de
4095 chaque fichier avec lequel il fait quelque chose. Ceci clarifie ce
4096 qu'il se passe et réduit la probabilité d'une mauvaise surprise
4097 restée silencieuse. Ce comportement est commun à la plupart des
4098 commandes Mercurial.</para>
4099 </sect2>
4100 <sect2>
4101 <title>Mercurial suit les fichiers, pas les répertoires</title>
4103 <para id="x_1ab">Mercurial ne suit pas les informations sur les
4104 répertoires. En contrepartie, il suit le chemin vers un fichier. Avant
4105 de créer un fichier, il crée au préalable les répertoires manquants
4106 dans le chemin. Après avoir supprimé un fichier, il supprime chaque
4107 répertoire vide qui apparaît dans le chemin du fichier. Ceci apparaît
4108 comme une distinction triviale, cependant, cela a une conséquence
4109 pratique mineure : il n'est pas possible de représenter un répertoire
4110 totalement vide dans Mercurial.</para>
4112 <para id="x_1ac">Les répertoires vides sont rarement utiles. Il existe
4113 cependant des solutions alternatives et non intrusives que vous
4114 pouvez utiliser pour obtenir l'effet approprié. Les développeurs de
4115 Mercurial ont ainsi pensé que la complexité requise pour gérer les
4116 répertoires n'était pas aussi importante que le bénéfice que cette
4117 fonctionnalité apporterait.</para>
4119 <para id="x_1ad">Si vous avez besoin d'un répertoire vide dans votre
4120 dépôt, il existe quelques façons d'y arriver. L'une d'elles est de
4121 créer un répertoire et ensuite, de faire un <command role="hg-cmd" moreinfo="none">hg
4122 add</command> sur un fichier <quote>caché</quote> dans ce
4123 répertoire. Sur les systèmes de type Unix, tout fichier dont le nom
4124 commence avec un point (<quote><literal moreinfo="none">.</literal></quote>) est
4125 considéré comme caché par la plupart des commandes et outils
4126 graphiques. Cette approche est illustrée ci-après.</para>
4128 <!-- BEGIN daily.files.hidden -->
4129 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init hidden-example</userinput>
4130 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd hidden-example</userinput>
4131 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir empty</userinput>
4132 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">touch empty/.hidden</userinput>
4133 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add empty/.hidden</userinput>
4134 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Manage an empty-looking directory'</userinput>
4135 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls empty</userinput>
4136 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
4137 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone hidden-example tmp</userinput>
4138 updating working directory
4139 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
4140 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls tmp</userinput>
4141 empty
4142 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls tmp/empty</userinput>
4143 </screen>
4144 <!-- END daily.files.hidden -->
4147 <para id="x_1ae">Une autre façon de s'attaquer au besoin d'un
4148 répertoire vide est de simplement d'en créer un dans vos scripts
4149 de construction avant qu'ils n'en aient le besoin.</para>
4150 </sect2>
4151 </sect1>
4153 <sect1>
4154 <title>Comment arrêter de suivre un fichier</title>
4156 <para id="x_1af">Une fois que vous décidez qu'un fichier n'appartient
4157 plus à votre dépôt, utilisez la commande <command role="hg-cmd" moreinfo="none">hg
4158 remove</command>. Ceci supprime le fichier et informe Mercurial
4159 d'arrêter de le suivre (ce qui prendra effet lors du prochain commit).
4160 Un fichier supprimé est représenté dans la sortie de la commande
4161 <command role="hg-cmd" moreinfo="none">hg status</command> par un
4162 <quote><literal moreinfo="none">R</literal></quote>.</para>
4164 <!-- BEGIN daily.files.remove -->
4165 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init remove-example</userinput>
4166 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd remove-example</userinput>
4167 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a > a</userinput>
4168 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir b</userinput>
4169 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b > b/b</userinput>
4170 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a b</userinput>
4171 adding b/b
4172 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Small example for file removal'</userinput>
4173 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg remove a</userinput>
4174 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
4175 R a
4176 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg remove b</userinput>
4177 removing b/b
4178 </screen>
4179 <!-- END daily.files.remove -->
4182 <para id="x_1b0">Après avoir fait un <command role="hg-cmd" moreinfo="none">hg
4183 remove</command> sur un fichier, Mercurial ne suivra plus aucun
4184 changement sur ce fichier, même si vous recréez un fichier avec le même
4185 nom dans votre répertoire de travail. Si vous recréez un fichier avec le
4186 même nom et que vous désirez que Mercurial suive ce dernier, faite
4187 simplement un <command role="hg-cmd" moreinfo="none">hg add</command> sur celui-ci.
4188 Mercurial saura alors que le nouveau fichier ne fait pas référence à
4189 l'ancien fichier qui portait le même nom.</para>
4191 <sect2>
4192 <title>Supprimer un fichier n'affecte pas son historique</title>
4194 <para id="x_1b1">Il est important de comprendre que supprimer un fichier
4195 n'a que deux effets.</para>
4197 <itemizedlist>
4198 <listitem><para id="x_1b2">Il supprime la version actuelle de ce
4199 fichier du répertoire de travail.</para>
4200 </listitem>
4201 <listitem><para id="x_1b3">Il arrête, à partir du prochain commit, le
4202 suivi de Mercurial sur les changements qui ont lieu sur ce
4203 fichier.</para>
4204 </listitem></itemizedlist>
4206 <para id="x_1b4">Supprimer un fichier <emphasis>n'</emphasis>affecte en
4207 <emphasis>aucun</emphasis> cas l'<emphasis>historique</emphasis> du
4208 fichier.</para>
4210 <para id="x_1b5">Si vous mettez à jour le répertoire de travail à un
4211 changeset qui a été committé alors que le fichier que vous venez de
4212 supprimer était encore suivi, ce fichier réapparaîtra dans le
4213 répertoire de travail, avec le contenu qu'il avait lorsque vous aviez
4214 committé ce changeset. Si vous mettez à jour (update) le répertoire de
4215 travail à un changeset ultérieur dans lequel le fichier a été
4216 supprimé, Mercurial supprimera une nouvelle fois le fichier du
4217 répertoire de travail.</para>
4218 </sect2>
4220 <sect2>
4221 <title>Fichiers manquants</title>
4223 <para id="x_1b6">Mercurial considère qu'un fichier que vous avez
4224 supprimé sans utiliser<command role="hg-cmd" moreinfo="none">hg remove</command>
4225 comme étant <emphasis>manquant</emphasis>. Un fichier manquant est
4226 représenté avec un <quote><literal moreinfo="none">!</literal></quote> en sortie de
4227 <command role="hg-cmd" moreinfo="none">hg status</command>.
4228 Les commandes Mercurial ne feront rien avec les fichiers
4229 manquants.</para>
4231 <!-- BEGIN daily.files.missing -->
4232 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init missing-example</userinput>
4233 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd missing-example</userinput>
4234 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a > a</userinput>
4235 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a</userinput>
4236 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'File about to be missing'</userinput>
4237 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">rm a</userinput>
4238 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
4239 ! a
4240 </screen>
4241 <!-- END daily.files.missing -->
4244 <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
4245 vous voulez que ce fichier reste supprimé, vous pouvez exécuter
4246 <command role="hg-cmd" moreinfo="none">hg remove <option role="hg-opt-remove">--after</option></command> à tout moment
4247 pour dire à Mercurial que vous aviez bien voulu supprimer ce
4248 fichier.</para>
4250 <!-- BEGIN daily.files.remove-after -->
4251 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg remove --after a</userinput>
4252 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
4253 R a
4254 </screen>
4255 <!-- END daily.files.remove-after -->
4258 <para id="x_1b8">D'un autre coté, si vous avez supprimé le fichier
4259 manquant par accident, donnez à la commande <command role="hg-cmd" moreinfo="none">hg
4260 revert</command> le nom du fichier à retrouver. Il réapparaitra dans
4261 sa forme non modifiée.</para>
4263 <!-- BEGIN daily.files.recover-missing -->
4264 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert a</userinput>
4265 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat a</userinput>
4266 a
4267 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
4268 </screen>
4269 <!-- END daily.files.recover-missing -->
4272 </sect2>
4274 <sect2>
4275 <title>Entre nous : Pourquoi dire explicitement à Mercurial de supprimer un
4276 fichier ?</title>
4278 <para id="x_1b9">Vous pourriez vous demander pourquoi il est nécessaire
4279 de dire explicitement à Mercurial que vous souhaitez supprimer un
4280 fichier. Au début du développement de Mercurial, celui ci vous
4281 laissait pourtant supprimer un fichier sans soucis ; Mercurial vous
4282 aurait automatiquement informé de l'absence du fichier lorsque vous
4283 auriez lancé un <command role="hg-cmd" moreinfo="none">hg commit</command> et arrêté
4284 de le suivre. En pratique, ceci a montré qu'il était trop facile de
4285 supprimer accidentellement un fichier sans le remarquer.</para>
4286 </sect2>
4288 <sect2>
4289 <title>Raccourci utile—ajouter et supprimer des fichiers en une
4290 seule étape.</title>
4292 <para id="x_1ba">Mercurial offre une commande combinée, <command role="hg-cmd" moreinfo="none">hg addremove</command>, qui ajoute les fichiers non
4293 suivis et marque les fichiers manquants comme supprimés.</para>
4295 <!-- BEGIN daily.files.addremove -->
4296 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init addremove-example</userinput>
4297 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd addremove-example</userinput>
4298 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a > a</userinput>
4299 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b > b</userinput>
4300 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg addremove</userinput>
4301 adding a
4302 adding b
4303 </screen>
4304 <!-- END daily.files.addremove -->
4307 <para id="x_1bb">La commande <command role="hg-cmd" moreinfo="none">hg commit</command>
4308 fournit aussi une option <option role="hg-opt-commit">-A</option> qui
4309 exécute le même ajouter-et-supprimer, immédiatement suivi d'un
4310 commit.</para>
4312 <!-- BEGIN daily.files.commit-addremove -->
4313 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo c > c</userinput>
4314 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'Commit with addremove'</userinput>
4315 adding c
4316 </screen>
4317 <!-- END daily.files.commit-addremove -->
4320 </sect2>
4321 </sect1>
4323 <sect1 id="chap:daily.copy">
4324 <title>Copier des fichiers</title>
4326 <para id="x_1bc">Mercurial fournit une commande <command role="hg-cmd" moreinfo="none">hg
4327 copy</command> qui vous permet de faire une nouvelle copie d'un
4328 fichier. Lorsque vous copiez un fichier en utilisant cette commande,
4329 Mercurial crée un enregistrement du fait que ce nouveau fichier est une
4330 copie du fichier originel. Il traite ces fichiers copiés spécialement
4331 lorsque vous fusionnez (merge) votre travail avec quelqu'un
4332 d'autre.</para>
4334 <sect2>
4335 <title>Les résultats d'une copie durant une fusion (merge)</title>
4337 <para id="x_1bd">Ce qu'il se passe durant une fusion (merge) est que
4338 les changements <quote>suivent</quote> une copie. Pour illustrer ce
4339 que cela veut dire de la meilleure façon, créons un exemple. Nous
4340 allons commencer avec le mini dépôt usuel qui contient un simple
4341 fichier.</para>
4343 <!-- BEGIN daily.copy.init -->
4344 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init my-copy</userinput>
4345 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-copy</userinput>
4346 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo line > file</userinput>
4347 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add file</userinput>
4348 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Added a file'</userinput>
4349 </screen>
4350 <!-- END daily.copy.init -->
4353 <para id="x_1be">Nous devons faire du travail en parallèle, ainsi,
4354 nous aurons quelque chose à fusionner (merge). Donc clonons notre
4355 dépôt.</para>
4357 <!-- BEGIN daily.copy.clone -->
4358 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
4359 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone my-copy your-copy</userinput>
4360 updating working directory
4361 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
4362 </screen>
4363 <!-- END daily.copy.clone -->
4366 <para id="x_1bf">De retour dans notre dépôt initial, utilisons la
4367 commande <command role="hg-cmd" moreinfo="none">hg copy</command> pour faire une
4368 copie du premier fichier que nous avons créé.</para>
4370 <!-- BEGIN daily.copy.copy -->
4371 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-copy</userinput>
4372 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy file new-file</userinput>
4373 </screen>
4374 <!-- END daily.copy.copy -->
4377 <para id="x_1c0">Si nous regardons ensuite à la sortie de la commande
4378 <command role="hg-cmd" moreinfo="none">hg status</command>, les fichiers copiés
4379 ont l'air de fichiers normalement ajoutés.</para>
4381 <!-- BEGIN daily.copy.status -->
4382 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
4383 A new-file
4384 </screen>
4385 <!-- END daily.copy.status -->
4388 <para id="x_1c1">Mais si nous passons l'option <option role="hg-opt-status">-C</option> à <command role="hg-cmd" moreinfo="none">hg
4389 status</command>, il affiche une autre ligne de sortie : il s'agit
4390 du fichier <emphasis>source</emphasis> pour notre copie.</para>
4392 <!-- BEGIN daily.copy.status-copy -->
4393 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status -C</userinput>
4394 A new-file
4395 file
4396 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Copied file'</userinput>
4397 </screen>
4398 <!-- END daily.copy.status-copy -->
4401 <para id="x_1c2">Maintenant, de retour dans le dépôt que nous avons
4402 cloné, créons un changement en parallèle. Nous allons ajouter une
4403 ligne de contenu au fichier original qui a été créé.</para>
4405 <!-- BEGIN daily.copy.other -->
4406 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../your-copy</userinput>
4407 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'new contents' >> file</userinput>
4408 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Changed file'</userinput>
4409 </screen>
4410 <!-- END daily.copy.other -->
4413 <para id="x_1c3">Nous avons alors un fichier <filename moreinfo="none">file</filename>
4414 modifié dans ce dépôt. Lorsque nous récupérons (pull) les changements
4415 depuis le premier répertoire et fusionnons (merge) les deux "heads",
4416 Mercurial propagera les changements que nous avons faits localement
4417 au fichier <filename moreinfo="none">file</filename> dans sa copie
4418 <filename moreinfo="none">new-file</filename>.</para>
4420 <!-- BEGIN daily.copy.merge -->
4421 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../my-copy</userinput>
4422 pulling from ../my-copy
4423 searching for changes
4424 adding changesets
4425 adding manifests
4426 adding file changes
4427 added 1 changesets with 1 changes to 1 files (+1 heads)
4428 (run 'hg heads' to see heads, 'hg merge' to merge)
4429 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
4430 merging file and new-file to new-file
4431 0 files updated, 1 files merged, 0 files removed, 0 files unresolved
4432 (branch merge, don't forget to commit)
4433 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat new-file</userinput>
4434 line
4435 new contents
4436 </screen>
4437 <!-- END daily.copy.merge -->
4440 </sect2>
4441 <sect2 id="sec:daily:why-copy">
4442 <title>Pourquoi est-ce que les changements devraient suivre les copies
4443 ?</title>
4445 <para id="x_1c4">Ce comportement—des changements d'un fichiers
4446 qui se propagent aux copies de ce fichier—peut sembler
4447 ésotérique, mais, dans la plupart des cas, c'est hautement
4448 désirable.</para>
4450 <para id="x_1c5">Pour commencer, souvenez vous que cette propagation
4451 a lieue <emphasis>seulement</emphasis> lors des fusions (merge).
4452 Donc, si vous faites un <command role="hg-cmd" moreinfo="none">hg copy</command> sur
4453 un fichier, et par la suite modifiez le fichier original durant le
4454 cours normal de votre travail, rien n'a lieu.</para>
4456 <para id="x_1c6">La deuxième chose à savoir c'est que les modifications
4457 ne se propageront à travers une copie que si le changeset à partir
4458 duquel vous faites une fusion (merge) <emphasis>n'a pas encore
4459 vu</emphasis> la copie.</para>
4461 <para id="x_1c7">La raison pour laquelle Mercurial fait ainsi est une
4462 règle. Imaginons que je corrige un important bug dans un fichier source
4463 et que je commit mes changements. Pendant ce temps, vous avez décidé de
4464 faire un <command role="hg-cmd" moreinfo="none">hg copy</command> du fichier dans
4465 votre dépôt, sans rien savoir au sujet du bug ou à propos de la
4466 correction. Vous avez alors commencé à "hacker" sur votre copie du
4467 fichier.</para>
4469 <para id="x_1c8">Si vous aviez récupéré (pull) et fusionné (merge) mes
4470 changements, et que Mercurial <emphasis>n'avait pas</emphasis>
4471 propagé les changements à travers les copies, votre nouveau fichier
4472 source contiendrait maintenant le bug, et à moins que vous ne sachiez
4473 qu'il faille propager la correction du bug à la main, le bug aurait
4474 <emphasis>subsisté</emphasis> dans votre copie du fichier.</para>
4476 <para id="x_1c9">En propageant automatiquement les changements qui
4477 fixent les bugs à partir du fichier original vers les copies,
4478 Mercurial prévient ce type de problèmes. A ma connaissance, Mercurial
4479 est le <emphasis>seul</emphasis> système de gestion de révisions qui
4480 propage les changements à travers les copies comme ceci.</para>
4482 <para id="x_1ca">Une fois que votre historique des changements a un
4483 enregistrement concernant une copie et qu'une fusion postérieure a
4484 eu lieue, il n'y a d'habitude pas d'autre besoin de propager les
4485 changements du fichier originel vers le fichier copié. C'est pourquoi
4486 Mercurial ne propage les changements à travers les copies qu'à la
4487 première fusion, et pas d'avantage.</para>
4488 </sect2>
4490 <sect2>
4491 <title>Comment faire des changements qui <emphasis>ne</emphasis>
4492 suivent <emphasis>pas</emphasis> une copie</title>
4494 <para id="x_1cb">Si pour une raison ou une autre, vous décidez que
4495 cette fonctionnalité de propager automatiquement les changements à
4496 travers les copies n'est pas pour vous, utilisez simplement la
4497 commande normale de copie de votre système (sur les systèmes de type
4498 Unix, il s'agit de <command moreinfo="none">cp</command>) pour faire une copie d'un
4499 fichier. Utilisez ensuite <command role="hg-cmd" moreinfo="none">hg add</command>
4500 pour ajouter les nouveaux fichiers à la main. Cependant, avant d'en
4501 faire ainsi, relisez <xref linkend="sec:daily:why-copy"/>, et faites
4502 un choix en connaissance de cause comme quoi cette fonctionnalité
4503 n'est pas appropriée à votre cas spécifique.</para>
4505 </sect2>
4506 <sect2>
4507 <title>Comportement de la commande <command role="hg-cmd" moreinfo="none">hg copy</command></title>
4509 <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
4510 fichier source tel qu'il est actuellement dans le répertoire de
4511 travail. Cela signifie que si vous effectuez des modifications sur un
4512 fichier, puis faites un <command role="hg-cmd" moreinfo="none">hg copy</command> sur
4513 celui-ci sans avoir au préalable committé ces changements, la nouvelle
4514 copie contiendra aussi les modifications que vous avez fait jusqu'à
4515 ce point. (Je trouve ce comportement quelque peu contre intuitif,
4516 c'est pourquoi j'en fais mention ici.)</para>
4517 <!-- Vérifier que je n'ai pas fait de contre sens en relisant la
4518 version anglaise, ce que je comprend ici me paraît un peu bizarre -->
4520 <para id="x_1cd">La commande <command role="hg-cmd" moreinfo="none">hg copy</command>
4521 agit comme la commande Unix <command moreinfo="none">cp</command> (vous pouvez
4522 utilisez l'alias <command role="hg-cmd" moreinfo="none">hg cp</command> si vous
4523 préférez). Nous devons lui donner deux ou plus arguments où le
4524 dernier est considéré comme la <emphasis>destination</emphasis>, et
4525 les autres comme les <emphasis>sources</emphasis>.</para>
4527 <para id="x_685">Si vous passez à <command role="hg-cmd" moreinfo="none">hg
4528 copy</command> un seul fichier source, et que la destination
4529 n'existe pas, ceci créera un nouveau fichier avec ce nom.</para>
4531 <!-- BEGIN daily.copy.simple -->
4532 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir k</userinput>
4533 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy a k</userinput>
4534 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls k</userinput>
4535 a
4536 </screen>
4537 <!-- END daily.copy.simple -->
4540 <para id="x_1ce">Si la destination est un répertoire, Mercurial copie
4541 les sources dans ce répertoire.</para>
4543 <!-- BEGIN daily.copy.dir-dest -->
4544 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir d</userinput>
4545 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy a b d</userinput>
4546 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls d</userinput>
4547 a b
4548 </screen>
4549 <!-- END daily.copy.dir-dest -->
4552 <para id="x_1cf">La copie de répertoire est récursive et préserve la
4553 structure du répertoire source.</para>
4555 <!-- BEGIN daily.copy.dir-src -->
4556 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy z e</userinput>
4557 copying z/a/c to e/a/c
4558 </screen>
4559 <!-- END daily.copy.dir-src -->
4562 <para id="x_1d0">Si la source et la destination sont tous deux des
4563 répertoires, l'arborescence de la source est recréée dans le
4564 répertoire destination.</para>
4566 <!-- BEGIN daily.copy.dir-src-dest -->
4567 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy z d</userinput>
4568 copying z/a/c to d/z/a/c
4569 </screen>
4570 <!-- END daily.copy.dir-src-dest -->
4573 <para id="x_1d1">Comme avec la commande <command role="hg-cmd" moreinfo="none">hg
4574 remove</command>, si vous copiez un fichier manuellement et voulez
4575 que Mercurial sache qu'il s'agit d'une copie, utilisez simplement
4576 l'option <option role="hg-opt-copy">--after</option> avec <command role="hg-cmd" moreinfo="none">hg copy</command>.</para>
4578 <!-- BEGIN daily.copy.after -->
4579 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cp a n</userinput>
4580 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy --after a n</userinput>
4581 </screen>
4582 <!-- END daily.copy.after -->
4584 </sect2>
4585 </sect1>
4587 <sect1>
4588 <title>Renommer les fichiers</title>
4590 <para id="x_1d2">Il est plus commun d'avoir besoin de renommer un
4591 fichier que d'en faire une copie. La raison pour laquelle j'ai discuté
4592 de la commande <command role="hg-cmd" moreinfo="none">hg copy</command> avant de parler
4593 de renommage des fichiers est que Mercurial traite les renommages
4594 essentiellement comme une copie. Ainsi, savoir comment Mercurial traite
4595 les copies de fichiers vous informe sur ce que vous êtes en droit
4596 d'attendre lorsque vous renommez un fichier.</para>
4598 <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
4599 les fichiers sources, les supprime et marque ces fichiers comme étant
4600 supprimés.</para>
4602 <!-- BEGIN daily.rename.rename -->
4603 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rename a b</userinput>
4604 </screen>
4605 <!-- END daily.rename.rename -->
4608 <para id="x_1d4">La commande <command role="hg-cmd" moreinfo="none">hg status</command>
4609 montre les nouveaux fichiers comme ajoutés et les fichiers originaux
4610 comme supprimés.</para>
4612 <!-- BEGIN daily.rename.status -->
4613 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
4614 A b
4615 R a
4616 </screen>
4617 <!-- END daily.rename.status -->
4620 <para id="x_1d5">A cause du <command role="hg-cmd" moreinfo="none">hg copy</command>,
4621 nous devons utiliser l'option <option role="hg-opt-status">-C</option>
4622 pour la commande <command role="hg-cmd" moreinfo="none">hg status</command> afin
4623 d'observer que le fichier ajouté est bien suivi par Mercurial comme
4624 étant une copie de l'original maintenant supprimé.</para>
4626 <!-- BEGIN daily.rename.status-copy -->
4627 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status -C</userinput>
4628 A b
4629 a
4630 R a
4631 </screen>
4632 <!-- END daily.rename.status-copy -->
4635 <para id="x_1d6">Comme avec <command role="hg-cmd" moreinfo="none">hg remove</command> et
4636 <command role="hg-cmd" moreinfo="none">hg copy</command>, vous pouvez informer
4637 Mercurial au sujet d'un renommage après coup en utilisant l'option
4638 <option role="hg-opt-rename">--after</option>. Dans le plus grand
4639 respect, le comportement de la commande <command role="hg-cmd" moreinfo="none">hg
4640 rename</command>, et les options qu'il accepte sont similaires à la
4641 commande <command role="hg-cmd" moreinfo="none">hg copy</command>.</para>
4643 <para id="x_686">Si vous êtes familier avec la ligne de commande Unix,
4644 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>
4646 <sect2>
4647 <title>Renommer les fichiers et fusionner (merge) les changements</title>
4649 <para id="x_1d7">Puise que le "rename" de Mercurial est implanté comme un
4650 "copy-and-remove", la même propagation des changements a lieue après
4651 un "rename" qu'après un "copy" lorsque vous fusionnez (merge).</para>
4653 <para id="x_1d8">Si je modifie un fichier et que vous le renommez, si
4654 ensuite nous fusionnons nos changements respectifs, mes modifications
4655 sur le fichier sous son nom originel seront propagés vers le même
4656 fichier sous son nouveau nom. (C'est quelque chose que vous pourriez
4657 espérer voir <quote>fonctionner simplement</quote>, mais tous les
4658 systèmes de gestion de version ne le font pas.)</para>
4660 <para id="x_1d9">Tandis qu'avoir des changements qui suivent une copie
4661 est une fonctionnalité où vous hocheriez sûrement la tête en disant
4662 <quote>oui, cela pourrait être utile</quote>, il est clair que les
4663 voir suivre un renommage est définitivement important. Sans cette
4664 aptitude, il serait vraiment trop facile d'avoir des changements
4665 qui deviennent orphelins lorsque des fichiers sont renommés.</para>
4666 </sect2>
4668 <sect2>
4669 <title>Renommages divergeants et fusion (merge)</title>
4671 <para id="x_1da">Le cas de noms divergeants a lieu lorsque deux
4672 développeurs commencent avec un fichier—appelons le
4673 <filename moreinfo="none">foo</filename>—dans leurs dépôts respectifs.</para>
4675 <!-- BEGIN rename.divergent.clone -->
4676 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone orig anne</userinput>
4677 updating working directory
4678 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
4679 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone orig bob</userinput>
4680 updating working directory
4681 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
4682 </screen>
4683 <!-- END rename.divergent.clone -->
4686 <para id="x_1db">Anne renomme le fichier en
4687 <filename moreinfo="none">bar</filename>.</para>
4689 <!-- BEGIN rename.divergent.rename.anne -->
4690 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd anne</userinput>
4691 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rename foo bar</userinput>
4692 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -m 'Rename foo to bar'</userinput>
4693 </screen>
4694 <!-- END rename.divergent.rename.anne -->
4697 <para id="x_1dc">Pendant ce temps, Bob le renomme en
4698 <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>
4700 <!-- BEGIN rename.divergent.rename.bob -->
4701 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../bob</userinput>
4702 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg mv foo quux</userinput>
4703 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -m 'Rename foo to quux'</userinput>
4704 </screen>
4705 <!-- END rename.divergent.rename.bob -->
4708 <para id="x_1dd">J'aime à penser qu'il s'agit d'un conflit puisque
4709 chaque développeur a exprimé différentes intentions au sujet de ce
4710 que le nom de ce fichier aurait du être.</para>
4712 <para id="x_1de">Que pensez vous qu'il devrait se produire lorsqu'ils
4713 fusionnent (merge) leurs travaux ? Le comportement actuel de
4714 Mercurial est qu'il préserve toujours les <emphasis>deux</emphasis>
4715 noms lorsqu'il fusionne (merge) des changesets qui contiennent des
4716 renommages divergeants.</para>
4718 <!-- BEGIN rename.divergent.merge -->
4719 <screen format="linespecific"># See http://www.selenic.com/mercurial/bts/issue455
4720 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../orig</userinput>
4721 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull -u ../anne</userinput>
4722 pulling from ../anne
4723 searching for changes
4724 adding changesets
4725 adding manifests
4726 adding file changes
4727 added 1 changesets with 1 changes to 1 files
4728 1 files updated, 0 files merged, 1 files removed, 0 files unresolved
4729 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../bob</userinput>
4730 pulling from ../bob
4731 searching for changes
4732 adding changesets
4733 adding manifests
4734 adding file changes
4735 added 1 changesets with 1 changes to 1 files (+1 heads)
4736 (run 'hg heads' to see heads, 'hg merge' to merge)
4737 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
4738 warning: detected divergent renames of foo to:
4739 bar
4740 quux
4741 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
4742 (branch merge, don't forget to commit)
4743 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls</userinput>
4744 bar quux
4745 </screen>
4746 <!-- END rename.divergent.merge -->
4749 <para id="x_1df">Remarquez que bien que Mercurial vous avertisse au
4750 sujet de la divergeance des renommages, il vous laisse faire quelque
4751 chose au sujet de la divergeance après la fusion (merge).</para>
4752 </sect2>
4754 <sect2>
4755 <title>Renommages et fusion convergeants</title>
4757 <para id="x_1e0">Un autre type de conflit de renommage intervient
4758 lorsque deux personne choisissent de renommer différents fichiers
4759 <emphasis>source</emphasis> vers la même
4760 <emphasis>destination</emphasis>. Dans ce cas, Mercurial exécute la
4761 machinerie normale de fusion (merge) et vous guide vers une
4762 solution convenable.</para>
4763 </sect2>
4765 <sect2>
4766 <title>Autres cas anguleux relatifs aux noms</title>
4768 <para id="x_1e1">Mercurial possède un bug de longue date dans lequel il
4769 échoue à traiter une fusion (merge) où un coté a un fichier avec un
4770 nom donné, alors que l'autre coté possède un répertoire avec le même nom.
4771 Ceci est documenté dans l'<ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue29">issue
4772 29</ulink>.</para>
4774 <!-- BEGIN issue29.go -->
4775 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init issue29</userinput>
4776 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd issue29</userinput>
4777 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a > a</userinput>
4778 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -Ama</userinput>
4779 adding a
4780 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b > b</userinput>
4781 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -Amb</userinput>
4782 adding b
4783 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg up 0</userinput>
4784 0 files updated, 0 files merged, 1 files removed, 0 files unresolved
4785 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mkdir b</userinput>
4786 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b > b/b</userinput>
4787 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -Amc</userinput>
4788 adding b/b
4789 created new head
4790 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
4791 abort: Is a directory: /tmp/issue29vhrzWD/issue29/b
4792 </screen>
4793 <!-- END issue29.go -->
4796 </sect2>
4797 </sect1>
4799 <sect1>
4800 <title>Récupération d'erreurs</title>
4802 <para id="x_1e2">Mercurial possède certaines commandes utiles qui vont
4803 vous aider à récupérer de certaines erreurs communes.</para>
4805 <para id="x_1e3">La commande <command role="hg-cmd" moreinfo="none">hg revert</command>
4806 vous permet d'annuler les changements que vous avez faits dans votre
4807 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
4808 juste <command role="hg-cmd" moreinfo="none">hg revert</command> avec le nom du fichier
4809 que vous avez ajouté et tandis que le fichier ne sera touché d'une
4810 quelconque manière, il ne sera plus suivi comme ajouté par Mercurial.
4811 Vous pouvez aussi utiliser la commande <command role="hg-cmd" moreinfo="none">hg
4812 revert</command> pour vous débarrasser de modifications erronés
4813 apportées à un fichier.</para>
4815 <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
4816 qui n'ont pas encore été committées. Une fois que vous avez committé un
4817 changement, si vous décidez qu'il s'agissait d'une erreur, vous pouvez
4818 toujours faire quelque chose à ce sujet, bien que vos options soient
4819 un peu plus limitées.</para>
4821 <para id="x_1e5">Pour plus d'informations au sujet de la commande
4822 <command role="hg-cmd" moreinfo="none">hg revert</command>, et des détails sur comment
4823 traiter les modifications que vous avez déjà committées, référez vous à
4824 <xref linkend="chap:undo"/>.</para>
4825 </sect1>
4827 <sect1>
4828 <title>Traiter avec les fusions (merge) malicieuses</title>
4830 <para id="x_687">Dans des projets compliqués ou conséquents, il n'est pas
4831 rare qu'une fusion (merge) de deux changesets finisse par une migraine.
4832 Supposez qu'il y ait un gros fichier source qui ait été largement édité de
4833 chaque coté de la fusion (merge) : ceci va inévitablement résulter en
4834 conflits, dont certains peuvent prendre plusieurs essais pour s'en
4835 sortir.</para>
4837 <para id="x_688">Développons en un cas simple pour voir comment le gérer.
4838 Nous allons commencer avec un dépôt contenant un fichier, et le
4839 cloner deux fois.</para>
4841 <!-- BEGIN ch04/resolve.init -->
4842 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init conflict</userinput>
4843 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd conflict</userinput>
4844 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo first > myfile.txt</userinput>
4845 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -A -m first</userinput>
4846 adding myfile.txt
4847 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
4848 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone conflict left</userinput>
4849 updating working directory
4850 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
4851 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone conflict right</userinput>
4852 updating working directory
4853 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
4854 </screen>
4855 <!-- END ch04/resolve.init -->
4858 <para id="x_689">Dans un des clones, nous allons modifier le fichier
4859 d'une façon.</para>
4861 <!-- BEGIN ch04/resolve.left -->
4862 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd left</userinput>
4863 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo left >> myfile.txt</userinput>
4864 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -m left</userinput>
4865 </screen>
4866 <!-- END ch04/resolve.left -->
4869 <para id="x_68a">Dans un autre, nous allons modifier le fichier
4870 différemment.</para>
4872 <!-- BEGIN ch04/resolve.right -->
4873 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../right</userinput>
4874 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo right >> myfile.txt</userinput>
4875 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg ci -m right</userinput>
4876 </screen>
4877 <!-- END ch04/resolve.right -->
4880 <para id="x_68b">Ensuite, nous allons récupérer (pull) chaque ensemble de
4881 changement dans notre dépôt original.</para>
4883 <!-- BEGIN ch04/resolve.pull -->
4884 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../conflict</userinput>
4885 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull -u ../left</userinput>
4886 pulling from ../left
4887 searching for changes
4888 adding changesets
4889 adding manifests
4890 adding file changes
4891 added 1 changesets with 1 changes to 1 files
4892 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
4893 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull -u ../right</userinput>
4894 pulling from ../right
4895 searching for changes
4896 adding changesets
4897 adding manifests
4898 adding file changes
4899 added 1 changesets with 1 changes to 1 files (+1 heads)
4900 not updating, since new heads added
4901 (run 'hg heads' to see heads, 'hg merge' to merge)
4902 </screen>
4903 <!-- END ch04/resolve.pull -->
4906 <para id="x_68c">Nous nous attendons à ce que notre dépôt contienne deux
4907 "heads".</para>
4909 <!-- BEGIN ch04/resolve.heads -->
4910 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg heads</userinput>
4911 changeset: 2:85f1afc84c33
4912 tag: tip
4913 parent: 0:14a820f81f48
4914 user: Bryan O'Sullivan <bos@serpentine.com>
4915 date: Sun Aug 16 14:04:51 2009 +0000
4916 summary: right
4918 changeset: 1:085ebbf44348
4919 user: Bryan O'Sullivan <bos@serpentine.com>
4920 date: Sun Aug 16 14:04:51 2009 +0000
4921 summary: left
4923 </screen>
4924 <!-- END ch04/resolve.heads -->
4927 <para id="x_68d">Normalement, si nous lançons <command role="hg-cmd" moreinfo="none">hg
4928 merge</command> à ce point, il nous renverra vers une interface
4929 utilisateur qui nous permettra de résoudre manuellement les éditions
4930 conflictuelles sur le fichier <filename moreinfo="none">myfile.txt</filename>.
4931 Cependant, pour simplifier ici les choses dans la présentation, nous
4932 aimerions plutôt que la fusion (merge) échoue immédiatement. Voici une
4933 façon de le faire.</para>
4935 <!-- BEGIN ch04/resolve.export -->
4936 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">export HGMERGE=false</userinput>
4937 </screen>
4938 <!-- END ch04/resolve.export -->
4941 <para id="x_68e">Nous avons dit au processus de fusion de Mercurial
4942 d'exécuter la commande <command moreinfo="none">false</command> (qui échoue
4943 immédiatement, à la demande) s'il détecte une fusion (merge) qu'il ne
4944 peut pas arranger automatiquement.</para>
4946 <para id="x_68f">Si nous appelons maintenant <command role="hg-cmd" moreinfo="none">hg
4947 merge</command>, il devrait échouer et reporter une erreur.</para>
4949 <!-- BEGIN ch04/resolve.merge -->
4950 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
4951 merging myfile.txt
4952 merging myfile.txt failed!
4953 0 files updated, 0 files merged, 0 files removed, 1 files unresolved
4954 use 'hg resolve' to retry unresolved file merges or 'hg up --clean' to abandon
4955 </screen>
4956 <!-- END ch04/resolve.merge -->
4959 <para id="x_690">Même si nous ne remarquons pas qu'une fusion (merge) a
4960 échoué, Mercurial nous empêchera de committer le résultat d'une fusion
4961 ratée.</para>
4963 <!-- BEGIN ch04/resolve.cifail -->
4964 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Attempt to commit a failed merge'</userinput>
4965 abort: unresolved merge conflicts (see hg resolve)
4966 </screen>
4967 <!-- END ch04/resolve.cifail -->
4970 <para id="x_691">Lorsque <command role="hg-cmd" moreinfo="none">hg commit</command>
4971 échoue dans ce cas, il suggère que nous utilisons la commande peu
4972 connue <command role="hg-cmd" moreinfo="none">hg resolve</command>. Comme d'habitude,
4973 <command role="hg-cmd" moreinfo="none">hg help resolve</command> affichera une aide
4974 sommaire.</para>
4976 <sect2>
4977 <title>États de résolution des fichiers</title>
4978 <!-- TODO Vérifier traduction : File resolution states -->
4980 <para id="x_692">Lorsqu'une fusion intervient, la plupart des fichiers
4981 vont, la plupart du temps, rester sans modification. Pour chaque
4982 fichier sur lequel Mercurial doit faire quelque chose, il suit l'état
4983 de celui-ci.</para>
4985 <itemizedlist>
4986 <listitem><para id="x_693">Un fichier
4987 <quote><emphasis>resolved</emphasis></quote> a été fusionné
4988 (merge) avec succès, que ce soit automatiquement par Mercurial ou
4989 manuellement par une intervention humaine.</para></listitem>
4990 <listitem><para id="x_694">Un fichier
4991 <quote><emphasis>unresolved</emphasis></quote> n'a pas été
4992 fusionné (merge) correctement et a besoin de plus
4993 d'attention.</para>
4994 </listitem>
4995 </itemizedlist>
4997 <para id="x_695">Si Mercurial voit un fichier
4998 <emphasis>quelconque</emphasis> dans un état
4999 <quote>unresolved</quote> après une fusion (merge), il considère que
5000 la fusion (merge) a échoué. Heureusement, nous n'avons pas à
5001 recommencer la procédure à partir du début.</para>
5003 <para id="x_696">L'option <option role="hg-opt-resolve">--list</option>
5004 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
5005 fusionné (merge).</para>
5007 <!-- BEGIN ch04/resolve.list -->
5008 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg resolve -l</userinput>
5009 U myfile.txt
5010 </screen>
5011 <!-- END ch04/resolve.list -->
5014 <para id="x_697">En sortie de <command role="hg-cmd" moreinfo="none">hg
5015 resolve</command>, un fichier "resolved" est marqué avec un
5016 <literal moreinfo="none">R</literal>, alors qu'un fichier "unresolved" est marqué
5017 d'un <literal moreinfo="none">U</literal>. S'il existe un fichier listé avec un
5018 <literal moreinfo="none">U</literal>, nous savons qu'essayer de committer le résultat
5019 de la fusion (merge) échouera.</para>
5020 </sect2>
5022 <sect2>
5023 <title>Résoudre une fusion de fichier</title>
5025 <para id="x_698">Nous avons plusieurs options pour changer l'état d'un
5026 fichier de "unresolved" à "resolved". Le plus commun est de relancer
5027 <command role="hg-cmd" moreinfo="none">hg resolve</command>. Si nous passons les noms
5028 des fichiers individuels ou des répertoires, ceci retentera la fusion
5029 de tous les fichiers présents à cet endroit. Nous pouvons aussi
5030 passer l'option <option role="hg-opt-resolve">--all</option> ou
5031 <option role="hg-opt-resolve">-a</option> qui tentera de fusionner
5032 <emphasis>tous</emphasis> les fichiers "unresolved".</para>
5034 <para id="x_699">Mercurial nous laisse aussi modifier la résolution
5035 d'un fichier directement. Nous pouvons marquer un fichier "resolved"
5036 en utilisant l'option <option role="hg-opt-resolve">--mark</option>,
5037 ou "unresolved" en utilisant l'option <option role="hg-opt-resolve">--unmark</option>. Ceci nous autorise à
5038 nettoyer une fusion particulièrement compliquée à la main, et de
5039 garder un suivi de nos progrès avec chaque fichier pendant que nous
5040 procédons.</para>
5041 </sect2>
5042 </sect1>
5044 <sect1>
5045 <title>Des "diffs" plus utiles</title>
5047 <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
5048 la commande régulière <command moreinfo="none">diff</command>, mais ceci a quelques
5049 inconvénients.</para>
5051 <para id="x_6c8">Considérez le cas où nous utilisons <command role="hg-cmd" moreinfo="none">hg
5052 rename</command> pour renommer un fichier.</para>
5054 <!-- BEGIN ch04/diff.rename.basic -->
5055 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rename a b</userinput>
5056 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
5057 diff -r f5deb7868663 a
5058 --- a/a Sun Aug 16 14:04:49 2009 +0000
5059 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
5060 @@ -1,1 +0,0 @@
5061 -a
5062 diff -r f5deb7868663 b
5063 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5064 +++ b/b Sun Aug 16 14:04:49 2009 +0000
5065 @@ -0,0 +1,1 @@
5066 +a
5067 </screen>
5068 <!-- END ch04/diff.rename.basic -->
5071 <para id="x_6c9">La sortie de <command role="hg-cmd" moreinfo="none">hg diff</command>
5072 ci-dessus cache le fait que nous avons simplement renommé un fichier.
5073 La commande <command role="hg-cmd" moreinfo="none">hg diff</command> accepte l'option
5074 <option>--git</option> ou <option>-g</option> pour utiliser un nouveau
5075 format de diff qui montre ces informations sous une forme plus
5076 expressive.</para>
5078 <!-- BEGIN ch04/diff.rename.git -->
5079 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff -g</userinput>
5080 diff --git a/a b/b
5081 rename from a
5082 rename to b
5083 </screen>
5084 <!-- END ch04/diff.rename.git -->
5087 <para id="x_6ca">Cette option peut aussi aider avec le cas autrement
5088 confus : un fichier qui apparaît comme étant modifié en accord avec
5089 <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
5090 survenir si nous changeons les permissions d'exécution du
5091 fichier.</para>
5093 <!-- BEGIN ch04/diff.chmod -->
5094 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">chmod +x a</userinput>
5095 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg st</userinput>
5096 M a
5097 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
5098 </screen>
5099 <!-- END ch04/diff.chmod -->
5102 <para id="x_6cb">La commande normale <command moreinfo="none">diff</command> ne fait pas
5103 attention aux permissions des fichiers, ce qui explique pourquoi
5104 <command role="hg-cmd" moreinfo="none">hg diff</command> n'affiche rien du tout par
5105 défaut. Si nous lui passons l'option <option>-g</option>, ceci nous
5106 informe de ce qu'il s'est vraiment passé.</para>
5108 <!-- BEGIN ch04/diff.chmod.git -->
5109 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff -g</userinput>
5110 diff --git a/a b/a
5111 old mode 100644
5112 new mode 100755
5113 </screen>
5114 <!-- END ch04/diff.chmod.git -->
5116 </sect1>
5118 <sect1>
5119 <title>Quels fichiers suivre et lesquels éviter</title>
5121 <para id="x_6cc">Les systèmes de gestion de révisions sont en général
5122 meilleurs pour gérer les fichiers textes qui sont écrits par les
5123 humains, comme le code source, où les fichiers ne changent pas
5124 énormément d'une révision à l'autre. Certains systèmes de gestion de
5125 révisions centralisés peuvent aussi traiter très convenablement les
5126 fichiers binaires, tels que les images bitmap.</para>
5128 <para id="x_6cd">Par exemple, une équipe de développement de jeux va
5129 probablement gérer les deux types : ses codes source et tous ses binaires
5130 (ex. données géométriques, textures, schémas de cartes) dans un système
5131 de contrôle de révisions.</para>
5132 <!-- Vérifier la traduction de map layouts que j'ai traduit par schémas
5133 de cartes -->
5135 <para id="x_6ce">Puisqu'il est d'habitude impossible de fusionner (merge)
5136 deux modifications conflictuelles sur un fichier binaire, les systèmes
5137 de version centralisés offrent souvent un mécanisme de verrou (lock) qui
5138 permet à un utilisateur de dire <quote>Je suis la seule personne qui
5139 peut éditer ce fichier</quote>.</para>
5141 <para id="x_6cf">En comparaison avec un système centralisé, un système
5142 décentralisé de gestion de révision change certains facteurs qui
5143 guident les décisions sur quels fichiers gérer et comment.</para>
5145 <para id="x_6d0">Par exemple, un système distribué de gestion de révisions
5146 ne peut pas, par sa nature, offrir un système de véroux (lock) sur les
5147 fichiers. Il n'y a donc pas de mécanisme inclus pour empêcher deux
5148 personnes de faire des modifications conflictuelles sur un fichier
5149 binaire. Si vous avez une équipe où plusieurs personnes peuvent souvent
5150 éditer un fichier binaire, cela ne serait pas une très bonne idée
5151 d'utiliser Mercurial —ou tout autre système distribué de gestion
5152 de révisions—pour gérer ces fichiers.</para>
5154 <para id="x_6d1">Lorsque vous sauvegardez les modifications sur un
5155 fichier, Mercurial ne sauvegarde d'habitude que les différences entre
5156 la version précédente et la version actuelle d'un fichier. Pour la
5157 plupart des fichiers texte, ceci est très efficace. Cependant, certains
5158 fichiers (en particulier les fichiers binaires) sont construits d'une
5159 façon que même un petit changement sur un contenu logique résulte sur
5160 un changement de la plupart des octets du fichier. Par exemple, les
5161 fichiers compressés sont particulièrement sujets à ce comportement. Si
5162 les différences entre deux versions successives d'un fichier sont
5163 toujours très grandes, Mercurial ne sera pas capable de sauvegarder
5164 l'historique des révisions sur le fichier très efficacement. Ceci peut
5165 affecter aussi bien les besoins pour la sauvegarde locale que le temps
5166 nécessaire à cloner le dépôt.</para>
5168 <para id="x_6d2">Pour avoir une idée de comment ceci pourrait vous
5169 affecter en pratique, supposez que nous voulions que Mercurial gère des
5170 documents OpenOffice. OpenOffice sauvegarde les documents sur le disque
5171 comme des fichiers compressés zip. Même le fait d'éditer ces fichiers
5172 d'une seule lettre, changera les bits de la quasi totalité du fichier
5173 lorsque vous le sauvegarderez. Maintenant, supposez que ce fichier
5174 fasse une taille de 2Mo. Puisque la plupart du fichier change à chaque
5175 fois que vous sauvegardez, Mercurial aura à sauvegarder tous les 2Mo du
5176 fichier à chaque commit, alors que de votre point de vue, il n'y a
5177 que peu de mots qui changent à chaque fois. Un seul fichier
5178 souvent édité qui n'est pas bien traité par les hypothèses que Mercurial
5179 fait sur les sauvegardes peut facilement avoir un effet colossal sur la
5180 taille du dépôt.</para>
5182 <para id="x_6d3">Même pire, si vous et quelqu'un d'autre éditez le même
5183 document OpenOffice sur lequel vous travaillez, il n'y a pas de façon
5184 utile pour fusionner votre travail. En fait, il n'y a pas de moyen
5185 utile de montrer que les différences sont faites à partir de votre
5186 vision des modifications.</para>
5188 <para id="x_6d4">Il y a ainsi quelques recommandations claires sur les
5189 types de fichiers spécifiques avec lesquels faire très
5190 attention.</para>
5192 <itemizedlist>
5193 <listitem><para id="x_6d5">Les fichier qui sont très gros et
5194 incompressibles, comme les images ISO de CD-ROM, sont, par
5195 construction très gros et les cloner à travers un réseau sera très
5196 long.</para></listitem>
5197 <!-- TODO : Trouver une meilleure traduction pour : ISO CD-ROM images, will by
5198 virtue of sheer size make clones over a network very slow. -->
5199 <listitem><para id="x_6d6">Les fichiers qui changent beaucoup d'une
5200 révision à l'autre peuvent être très chers à sauvegarder si vous
5201 les éditez fréquemment, de même que les conflits entre deux éditions
5202 concurrentes peuvent être difficiles à résoudre.</para>
5203 </listitem>
5204 </itemizedlist>
5205 </sect1>
5207 <sect1>
5208 <title>Sauvegardes et miroirs</title>
5210 <para id="x_6d7">Puisque Mercurial maintient une copie complète de
5211 l'historique de chaque clone, toute personne qui utilise Mercurial pour
5212 collaborer à un projet peut potentiellement agir comme une source de
5213 sauvegarde si une catastrophe survenait. Si un dépôt central devient
5214 indisponible, vous pouvez construire un remplaçant en clonant une copie
5215 du dépôt à partir d'un des contributeurs en récupérant (pull) tous les
5216 changements qui n'auraient pas été vus par les autres.</para>
5218 <para id="x_6d8">Il est simple d'utiliser Mercurial pour construire des
5219 serveurs hors site de sauvegarde et des miroirs distants. Initiez une
5220 tâche périodique (ex. via la commande <command moreinfo="none">cron</command>) sur un
5221 serveur distant pour récupérer (pull) les changements de votre dépôt
5222 distant chaque heure. Ceci sera difficile seulement dans le cas
5223 improbable où le nombre des dépôts maîtres que vous maintenez change
5224 souvent, auquel cas vous aurez besoin de faire un peu de scripting pour
5225 rafraichir la liste des dépôt à sauvegarder.</para>
5227 <para id="x_6d9">Si vous exécutez des sauvegardes traditionnelles de
5228 votre dépôt maître sur bande ou disque, et que vous voulez sauvegarder
5229 un dépôt nommé <filename moreinfo="none">myrepo</filename>, utilisez la commande
5230 <command moreinfo="none">hg clone -U myrepo myrepo.bak</command> pour créer un clone de
5231 <filename moreinfo="none">myrepo</filename> avant de commencer vos backups.
5232 L'option <option>-U</option> ne crée pas de répertoire de travail après
5233 que le clone soit accompli, puisque ceci serait superflu et ferait que
5234 la sauvegarde prenne plus de temps.</para>
5236 <para id="x_6da">Si vous voulez ensuite sauvegarder
5237 <filename moreinfo="none">myrepo.bak</filename> au lieu de <filename moreinfo="none">myrepo</filename>,
5238 vous aurez la garantie d'avoir une image (snapshot) consistante de
5239 votre dépôt sur lequel un développeur insomniaque n'enverra (push) pas de
5240 changements en milieu de sauvegarde.</para>
5241 </sect1>
5242 </chapter>
5244 <!--
5245 local variables:
5246 sgml-parent-document: ("00book.xml" "book" "chapter")
5247 end:
5248 -->
5250 <!-- BEGIN ch06 -->
5251 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
5253 <chapter id="cha:collab">
5254 <?dbhtml filename="collaborating-with-other-people.html"?>
5255 <title>Collaborating with other people</title>
5257 <para id="x_44a">As a completely decentralised tool, Mercurial doesn't impose
5258 any policy on how people ought to work with each other. However,
5259 if you're new to distributed revision control, it helps to have
5260 some tools and examples in mind when you're thinking about
5261 possible workflow models.</para>
5263 <sect1>
5264 <title>Mercurial's web interface</title>
5266 <para id="x_44b">Mercurial has a powerful web interface that provides several
5267 useful capabilities.</para>
5269 <para id="x_44c">For interactive use, the web interface lets you browse a
5270 single repository or a collection of repositories. You can view
5271 the history of a repository, examine each change (comments and
5272 diffs), and view the contents of each directory and file. You
5273 can even get a view of history that gives a graphical view of
5274 the relationships between individual changes and merges.</para>
5276 <para id="x_44d">Also for human consumption, the web interface provides
5277 Atom and RSS feeds of the changes in a repository. This lets you
5278 <quote>subscribe</quote> to a repository using your favorite
5279 feed reader, and be automatically notified of activity in that
5280 repository as soon as it happens. I find this capability much
5281 more convenient than the model of subscribing to a mailing list
5282 to which notifications are sent, as it requires no additional
5283 configuration on the part of whoever is serving the
5284 repository.</para>
5286 <para id="x_44e">The web interface also lets remote users clone a repository,
5287 pull changes from it, and (when the server is configured to
5288 permit it) push changes back to it. Mercurial's HTTP tunneling
5289 protocol aggressively compresses data, so that it works
5290 efficiently even over low-bandwidth network connections.</para>
5292 <para id="x_44f">The easiest way to get started with the web interface is to
5293 use your web browser to visit an existing repository, such as
5294 the master Mercurial repository at <ulink url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para>
5296 <para id="x_450">If you're interested in providing a web interface
5297 to your own repositories, there are several good ways to do
5298 this.</para>
5300 <para id="x_69d">The easiest and fastest way to get started in an informal
5301 environment is to use the <command role="hg-cmd" moreinfo="none">hg
5302 serve</command> command, which is best suited to short-term
5303 <quote>lightweight</quote> serving. See <xref linkend="sec:collab:serve"/> below for details of how to use
5304 this command.</para>
5306 <para id="x_69e">For longer-lived repositories that you'd like to
5307 have permanently available, there are several public hosting
5308 services available. Some are free to open source projects,
5309 while others offer paid commercial hosting. An up-to-date list
5310 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>
5312 <para id="x_6a0">If you would prefer to host your own repositories, Mercurial
5313 has built-in support for several popular hosting technologies,
5314 most notably CGI (Common Gateway Interface), and WSGI (Web
5315 Services Gateway Interface). See <xref linkend="sec:collab:cgi"/> for details of CGI and WSGI
5316 configuration.</para>
5317 </sect1>
5319 <sect1>
5320 <title>Collaboration models</title>
5322 <para id="x_451">With a suitably flexible tool, making decisions about
5323 workflow is much more of a social engineering challenge than a
5324 technical one. Mercurial imposes few limitations on how you can
5325 structure the flow of work in a project, so it's up to you and
5326 your group to set up and live with a model that matches your own
5327 particular needs.</para>
5329 <sect2>
5330 <title>Factors to keep in mind</title>
5332 <para id="x_452">The most important aspect of any model that you must keep
5333 in mind is how well it matches the needs and capabilities of
5334 the people who will be using it. This might seem
5335 self-evident; even so, you still can't afford to forget it for
5336 a moment.</para>
5338 <para id="x_453">I once put together a workflow model that seemed to make
5339 perfect sense to me, but that caused a considerable amount of
5340 consternation and strife within my development team. In spite
5341 of my attempts to explain why we needed a complex set of
5342 branches, and how changes ought to flow between them, a few
5343 team members revolted. Even though they were smart people,
5344 they didn't want to pay attention to the constraints we were
5345 operating under, or face the consequences of those constraints
5346 in the details of the model that I was advocating.</para>
5348 <para id="x_454">Don't sweep foreseeable social or technical problems under
5349 the rug. Whatever scheme you put into effect, you should plan
5350 for mistakes and problem scenarios. Consider adding automated
5351 machinery to prevent, or quickly recover from, trouble that
5352 you can anticipate. As an example, if you intend to have a
5353 branch with not-for-release changes in it, you'd do well to
5354 think early about the possibility that someone might
5355 accidentally merge those changes into a release branch. You
5356 could avoid this particular problem by writing a hook that
5357 prevents changes from being merged from an inappropriate
5358 branch.</para>
5359 </sect2>
5361 <sect2>
5362 <title>Informal anarchy</title>
5364 <para id="x_455">I wouldn't suggest an <quote>anything goes</quote>
5365 approach as something sustainable, but it's a model that's
5366 easy to grasp, and it works perfectly well in a few unusual
5367 situations.</para>
5369 <para id="x_456">As one example, many projects have a loose-knit group of
5370 collaborators who rarely physically meet each other. Some
5371 groups like to overcome the isolation of working at a distance
5372 by organizing occasional <quote>sprints</quote>. In a sprint,
5373 a number of people get together in a single location (a
5374 company's conference room, a hotel meeting room, that kind of
5375 place) and spend several days more or less locked in there,
5376 hacking intensely on a handful of projects.</para>
5378 <para id="x_457">A sprint or a hacking session in a coffee shop are the perfect places to use the
5379 <command role="hg-cmd" moreinfo="none">hg serve</command> command, since
5380 <command role="hg-cmd" moreinfo="none">hg serve</command> does not require any
5381 fancy server infrastructure. You can get started with
5382 <command role="hg-cmd" moreinfo="none">hg serve</command> in moments, by
5383 reading <xref linkend="sec:collab:serve"/> below. Then simply
5384 tell the person next to you that you're running a server, send
5385 the URL to them in an instant message, and you immediately
5386 have a quick-turnaround way to work together. They can type
5387 your URL into their web browser and quickly review your
5388 changes; or they can pull a bugfix from you and verify it; or
5389 they can clone a branch containing a new feature and try it
5390 out.</para>
5392 <para id="x_458">The charm, and the problem, with doing things
5393 in an ad hoc fashion like this is that only people who know
5394 about your changes, and where they are, can see them. Such an
5395 informal approach simply doesn't scale beyond a handful
5396 people, because each individual needs to know about
5397 <emphasis>n</emphasis> different repositories to pull
5398 from.</para>
5399 </sect2>
5401 <sect2>
5402 <title>A single central repository</title>
5404 <para id="x_459">For smaller projects migrating from a centralised revision
5405 control tool, perhaps the easiest way to get started is to
5406 have changes flow through a single shared central repository.
5407 This is also the most common <quote>building block</quote> for
5408 more ambitious workflow schemes.</para>
5410 <para id="x_45a">Contributors start by cloning a copy of this repository.
5411 They can pull changes from it whenever they need to, and some
5412 (perhaps all) developers have permission to push a change back
5413 when they're ready for other people to see it.</para>
5415 <para id="x_45b">Under this model, it can still often make sense for people
5416 to pull changes directly from each other, without going
5417 through the central repository. Consider a case in which I
5418 have a tentative bug fix, but I am worried that if I were to
5419 publish it to the central repository, it might subsequently
5420 break everyone else's trees as they pull it. To reduce the
5421 potential for damage, I can ask you to clone my repository
5422 into a temporary repository of your own and test it. This
5423 lets us put off publishing the potentially unsafe change until
5424 it has had a little testing.</para>
5426 <para id="x_45c">If a team is hosting its own repository in this
5427 kind of scenario, people will usually use the
5428 <command moreinfo="none">ssh</command> protocol to securely push changes to
5429 the central repository, as documented in <xref linkend="sec:collab:ssh"/>. It's also usual to publish a
5430 read-only copy of the repository over HTTP, as in
5431 <xref linkend="sec:collab:cgi"/>. Publishing over HTTP
5432 satisfies the needs of people who don't have push access, and
5433 those who want to use web browsers to browse the repository's
5434 history.</para>
5435 </sect2>
5437 <sect2>
5438 <title>A hosted central repository</title>
5440 <para id="x_6a1">A wonderful thing about public hosting services like
5441 <ulink url="http://bitbucket.org/">Bitbucket</ulink> is that
5442 not only do they handle the fiddly server configuration
5443 details, such as user accounts, authentication, and secure
5444 wire protocols, they provide additional infrastructure to make
5445 this model work well.</para>
5447 <para id="x_6a2">For instance, a well-engineered hosting service will let
5448 people clone their own copies of a repository with a single
5449 click. This lets people work in separate spaces and share
5450 their changes when they're ready.</para>
5452 <para id="x_6a3">In addition, a good hosting service will let people
5453 communicate with each other, for instance to say <quote>there
5454 are changes ready for you to review in this
5455 tree</quote>.</para>
5456 </sect2>
5458 <sect2>
5459 <title>Working with multiple branches</title>
5461 <para id="x_45d">Projects of any significant size naturally tend to make
5462 progress on several fronts simultaneously. In the case of
5463 software, it's common for a project to go through periodic
5464 official releases. A release might then go into
5465 <quote>maintenance mode</quote> for a while after its first
5466 publication; maintenance releases tend to contain only bug
5467 fixes, not new features. In parallel with these maintenance
5468 releases, one or more future releases may be under
5469 development. People normally use the word
5470 <quote>branch</quote> to refer to one of these many slightly
5471 different directions in which development is
5472 proceeding.</para>
5474 <para id="x_45e">Mercurial is particularly well suited to managing a number
5475 of simultaneous, but not identical, branches. Each
5476 <quote>development direction</quote> can live in its own
5477 central repository, and you can merge changes from one to
5478 another as the need arises. Because repositories are
5479 independent of each other, unstable changes in a development
5480 branch will never affect a stable branch unless someone
5481 explicitly merges those changes into the stable branch.</para>
5483 <para id="x_45f">Here's an example of how this can work in practice. Let's
5484 say you have one <quote>main branch</quote> on a central
5485 server.</para>
5487 <!-- BEGIN branching.init -->
5488 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init main</userinput>
5489 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd main</userinput>
5490 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'This is a boring feature.' > myfile</userinput>
5491 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'We have reached an important milestone!'</userinput>
5492 adding myfile
5493 </screen>
5494 <!-- END branching.init -->
5497 <para id="x_460">People clone it, make changes locally, test them, and push
5498 them back.</para>
5500 <para id="x_461">Once the main branch reaches a release milestone, you can
5501 use the <command role="hg-cmd" moreinfo="none">hg tag</command> command to
5502 give a permanent name to the milestone revision.</para>
5504 <!-- BEGIN branching.tag -->
5505 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag v1.0</userinput>
5506 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
5507 changeset: 1:5e447fdaf941
5508 tag: tip
5509 user: Bryan O'Sullivan <bos@serpentine.com>
5510 date: Sun Aug 16 14:04:47 2009 +0000
5511 summary: Added tag v1.0 for changeset 6412b791fd06
5513 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tags</userinput>
5514 tip 1:5e447fdaf941
5515 v1.0 0:6412b791fd06
5516 </screen>
5517 <!-- END branching.tag -->
5520 <para id="x_462">Let's say some ongoing
5521 development occurs on the main branch.</para>
5523 <!-- BEGIN branching.main -->
5524 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../main</userinput>
5525 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'This is exciting and new!' >> myfile</userinput>
5526 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Add a new feature'</userinput>
5527 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
5528 This is a boring feature.
5529 This is exciting and new!
5530 </screen>
5531 <!-- END branching.main -->
5534 <para id="x_463">Using the tag that was recorded at the milestone, people
5535 who clone that repository at any time in the future can use
5536 <command role="hg-cmd" moreinfo="none">hg update</command> to get a copy of
5537 the working directory exactly as it was when that tagged
5538 revision was committed.</para>
5540 <!-- BEGIN branching.update -->
5541 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
5542 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone -U main main-old</userinput>
5543 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd main-old</userinput>
5544 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update v1.0</userinput>
5545 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
5546 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
5547 This is a boring feature.
5548 </screen>
5549 <!-- END branching.update -->
5552 <para id="x_464">In addition, immediately after the main branch is tagged,
5553 we can then clone the main branch on the server to a new
5554 <quote>stable</quote> branch, also on the server.</para>
5556 <!-- BEGIN branching.clone -->
5557 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
5558 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone -rv1.0 main stable</userinput>
5559 requesting all changes
5560 adding changesets
5561 adding manifests
5562 adding file changes
5563 added 1 changesets with 1 changes to 1 files
5564 updating working directory
5565 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
5566 </screen>
5567 <!-- END branching.clone -->
5570 <para id="x_465">If we need to make a change to the stable
5571 branch, we can then clone <emphasis>that</emphasis>
5572 repository, make our changes, commit, and push our changes
5573 back there.</para>
5575 <!-- BEGIN branching.stable -->
5576 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone stable stable-fix</userinput>
5577 updating working directory
5578 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
5579 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd stable-fix</userinput>
5580 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'This is a fix to a boring feature.' > myfile</userinput>
5581 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Fix a bug'</userinput>
5582 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push</userinput>
5583 pushing to /tmp/branchingPsTziR/stable
5584 searching for changes
5585 adding changesets
5586 adding manifests
5587 adding file changes
5588 added 1 changesets with 1 changes to 1 files
5589 </screen>
5590 <!-- END branching.stable -->
5593 <para id="x_466">Because Mercurial repositories are independent, and
5594 Mercurial doesn't move changes around automatically, the
5595 stable and main branches are <emphasis>isolated</emphasis>
5596 from each other. The changes that we made on the main branch
5597 don't <quote>leak</quote> to the stable branch, and vice
5598 versa.</para>
5600 <para id="x_467">We'll often want all of our bugfixes on the stable
5601 branch to show up on the main branch, too. Rather than
5602 rewrite a bugfix on the main branch, we can simply pull and
5603 merge changes from the stable to the main branch, and
5604 Mercurial will bring those bugfixes in for us.</para>
5606 <!-- BEGIN branching.merge -->
5607 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../main</userinput>
5608 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../stable</userinput>
5609 pulling from ../stable
5610 searching for changes
5611 adding changesets
5612 adding manifests
5613 adding file changes
5614 added 1 changesets with 1 changes to 1 files (+1 heads)
5615 (run 'hg heads' to see heads, 'hg merge' to merge)
5616 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
5617 merging myfile
5618 0 files updated, 1 files merged, 0 files removed, 0 files unresolved
5619 (branch merge, don't forget to commit)
5620 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Bring in bugfix from stable branch'</userinput>
5621 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
5622 This is a fix to a boring feature.
5623 This is exciting and new!
5624 </screen>
5625 <!-- END branching.merge -->
5628 <para id="x_468">The main branch will still contain changes that
5629 are not on the stable branch, but it will also contain all of
5630 the bugfixes from the stable branch. The stable branch
5631 remains unaffected by these changes, since changes are only
5632 flowing from the stable to the main branch, and not the other
5633 way.</para>
5634 </sect2>
5636 <sect2>
5637 <title>Feature branches</title>
5639 <para id="x_469">For larger projects, an effective way to manage change is
5640 to break up a team into smaller groups. Each group has a
5641 shared branch of its own, cloned from a single
5642 <quote>master</quote> branch used by the entire project.
5643 People working on an individual branch are typically quite
5644 isolated from developments on other branches.</para>
5646 <figure id="fig:collab:feature-branches" float="0">
5647 <title>Feature branches</title>
5648 <mediaobject>
5649 <imageobject><imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject>
5650 <textobject><phrase>XXX add text</phrase></textobject>
5651 </mediaobject>
5652 </figure>
5654 <para id="x_46b">When a particular feature is deemed to be in suitable
5655 shape, someone on that feature team pulls and merges from the
5656 master branch into the feature branch, then pushes back up to
5657 the master branch.</para>
5658 </sect2>
5660 <sect2>
5661 <title>The release train</title>
5663 <para id="x_46c">Some projects are organized on a <quote>train</quote>
5664 basis: a release is scheduled to happen every few months, and
5665 whatever features are ready when the <quote>train</quote> is
5666 ready to leave are allowed in.</para>
5668 <para id="x_46d">This model resembles working with feature branches. The
5669 difference is that when a feature branch misses a train,
5670 someone on the feature team pulls and merges the changes that
5671 went out on that train release into the feature branch, and
5672 the team continues its work on top of that release so that
5673 their feature can make the next release.</para>
5674 </sect2>
5676 <sect2>
5677 <title>The Linux kernel model</title>
5679 <para id="x_46e">The development of the Linux kernel has a shallow
5680 hierarchical structure, surrounded by a cloud of apparent
5681 chaos. Because most Linux developers use
5682 <command moreinfo="none">git</command>, a distributed revision control tool
5683 with capabilities similar to Mercurial, it's useful to
5684 describe the way work flows in that environment; if you like
5685 the ideas, the approach translates well across tools.</para>
5687 <para id="x_46f">At the center of the community sits Linus Torvalds, the
5688 creator of Linux. He publishes a single source repository
5689 that is considered the <quote>authoritative</quote> current
5690 tree by the entire developer community. Anyone can clone
5691 Linus's tree, but he is very choosy about whose trees he pulls
5692 from.</para>
5694 <para id="x_470">Linus has a number of <quote>trusted lieutenants</quote>.
5695 As a general rule, he pulls whatever changes they publish, in
5696 most cases without even reviewing those changes. Some of
5697 those lieutenants are generally agreed to be
5698 <quote>maintainers</quote>, responsible for specific
5699 subsystems within the kernel. If a random kernel hacker wants
5700 to make a change to a subsystem that they want to end up in
5701 Linus's tree, they must find out who the subsystem's
5702 maintainer is, and ask that maintainer to take their change.
5703 If the maintainer reviews their changes and agrees to take
5704 them, they'll pass them along to Linus in due course.</para>
5706 <para id="x_471">Individual lieutenants have their own approaches to
5707 reviewing, accepting, and publishing changes; and for deciding
5708 when to feed them to Linus. In addition, there are several
5709 well known branches that people use for different purposes.
5710 For example, a few people maintain <quote>stable</quote>
5711 repositories of older versions of the kernel, to which they
5712 apply critical fixes as needed. Some maintainers publish
5713 multiple trees: one for experimental changes; one for changes
5714 that they are about to feed upstream; and so on. Others just
5715 publish a single tree.</para>
5717 <para id="x_472">This model has two notable features. The first is that
5718 it's <quote>pull only</quote>. You have to ask, convince, or
5719 beg another developer to take a change from you, because there
5720 are almost no trees to which more than one person can push,
5721 and there's no way to push changes into a tree that someone
5722 else controls.</para>
5724 <para id="x_473">The second is that it's based on reputation and acclaim.
5725 If you're an unknown, Linus will probably ignore changes from
5726 you without even responding. But a subsystem maintainer will
5727 probably review them, and will likely take them if they pass
5728 their criteria for suitability. The more <quote>good</quote>
5729 changes you contribute to a maintainer, the more likely they
5730 are to trust your judgment and accept your changes. If you're
5731 well-known and maintain a long-lived branch for something
5732 Linus hasn't yet accepted, people with similar interests may
5733 pull your changes regularly to keep up with your work.</para>
5735 <para id="x_474">Reputation and acclaim don't necessarily cross subsystem
5736 or <quote>people</quote> boundaries. If you're a respected
5737 but specialised storage hacker, and you try to fix a
5738 networking bug, that change will receive a level of scrutiny
5739 from a network maintainer comparable to a change from a
5740 complete stranger.</para>
5742 <para id="x_475">To people who come from more orderly project backgrounds,
5743 the comparatively chaotic Linux kernel development process
5744 often seems completely insane. It's subject to the whims of
5745 individuals; people make sweeping changes whenever they deem
5746 it appropriate; and the pace of development is astounding.
5747 And yet Linux is a highly successful, well-regarded piece of
5748 software.</para>
5749 </sect2>
5751 <sect2>
5752 <title>Pull-only versus shared-push collaboration</title>
5754 <para id="x_476">A perpetual source of heat in the open source community is
5755 whether a development model in which people only ever pull
5756 changes from others is <quote>better than</quote> one in which
5757 multiple people can push changes to a shared
5758 repository.</para>
5760 <para id="x_477">Typically, the backers of the shared-push model use tools
5761 that actively enforce this approach. If you're using a
5762 centralised revision control tool such as Subversion, there's
5763 no way to make a choice over which model you'll use: the tool
5764 gives you shared-push, and if you want to do anything else,
5765 you'll have to roll your own approach on top (such as applying
5766 a patch by hand).</para>
5768 <para id="x_478">A good distributed revision control tool will
5769 support both models. You and your collaborators can then
5770 structure how you work together based on your own needs and
5771 preferences, not on what contortions your tools force you
5772 into.</para>
5773 </sect2>
5774 <sect2>
5775 <title>Where collaboration meets branch management</title>
5777 <para id="x_479">Once you and your team set up some shared
5778 repositories and start propagating changes back and forth
5779 between local and shared repos, you begin to face a related,
5780 but slightly different challenge: that of managing the
5781 multiple directions in which your team may be moving at once.
5782 Even though this subject is intimately related to how your
5783 team collaborates, it's dense enough to merit treatment of its
5784 own, in <xref linkend="chap:branch"/>.</para>
5785 </sect2>
5786 </sect1>
5788 <sect1>
5789 <title>The technical side of sharing</title>
5791 <para id="x_47a">The remainder of this chapter is devoted to the question of
5792 sharing changes with your collaborators.</para>
5793 </sect1>
5795 <sect1 id="sec:collab:serve">
5796 <title>Informal sharing with <command role="hg-cmd" moreinfo="none">hg
5797 serve</command></title>
5799 <para id="x_47b">Mercurial's <command role="hg-cmd" moreinfo="none">hg serve</command>
5800 command is wonderfully suited to small, tight-knit, and
5801 fast-paced group environments. It also provides a great way to
5802 get a feel for using Mercurial commands over a network.</para>
5804 <para id="x_47c">Run <command role="hg-cmd" moreinfo="none">hg serve</command> inside a
5805 repository, and in under a second it will bring up a specialised
5806 HTTP server; this will accept connections from any client, and
5807 serve up data for that repository until you terminate it.
5808 Anyone who knows the URL of the server you just started, and can
5809 talk to your computer over the network, can then use a web
5810 browser or Mercurial to read data from that repository. A URL
5811 for a <command role="hg-cmd" moreinfo="none">hg serve</command> instance running
5812 on a laptop is likely to look something like
5813 <literal moreinfo="none">http://my-laptop.local:8000/</literal>.</para>
5815 <para id="x_47d">The <command role="hg-cmd" moreinfo="none">hg serve</command> command is
5816 <emphasis>not</emphasis> a general-purpose web server. It can do
5817 only two things:</para>
5818 <itemizedlist>
5819 <listitem><para id="x_47e">Allow people to browse the history of the
5820 repository it's serving, from their normal web
5821 browsers.</para>
5822 </listitem>
5823 <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people
5824 can <command role="hg-cmd" moreinfo="none">hg clone</command> or <command role="hg-cmd" moreinfo="none">hg pull</command> changes from that
5825 repository.</para>
5826 </listitem></itemizedlist>
5827 <para id="x_480">In particular, <command role="hg-cmd" moreinfo="none">hg serve</command>
5828 won't allow remote users to <emphasis>modify</emphasis> your
5829 repository. It's intended for read-only use.</para>
5831 <para id="x_481">If you're getting started with Mercurial, there's nothing to
5832 prevent you from using <command role="hg-cmd" moreinfo="none">hg serve</command>
5833 to serve up a repository on your own computer, then use commands
5834 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
5835 server as if the repository was hosted remotely. This can help
5836 you to quickly get acquainted with using commands on
5837 network-hosted repositories.</para>
5839 <sect2>
5840 <title>A few things to keep in mind</title>
5842 <para id="x_482">Because it provides unauthenticated read access to all
5843 clients, you should only use <command role="hg-cmd" moreinfo="none">hg
5844 serve</command> in an environment where you either don't
5845 care, or have complete control over, who can access your
5846 network and pull data from your repository.</para>
5848 <para id="x_483">The <command role="hg-cmd" moreinfo="none">hg serve</command> command
5849 knows nothing about any firewall software you might have
5850 installed on your system or network. It cannot detect or
5851 control your firewall software. If other people are unable to
5852 talk to a running <command role="hg-cmd" moreinfo="none">hg serve</command>
5853 instance, the second thing you should do
5854 (<emphasis>after</emphasis> you make sure that they're using
5855 the correct URL) is check your firewall configuration.</para>
5857 <para id="x_484">By default, <command role="hg-cmd" moreinfo="none">hg serve</command>
5858 listens for incoming connections on port 8000. If another
5859 process is already listening on the port you want to use, you
5860 can specify a different port to listen on using the <option role="hg-opt-serve">-p</option> option.</para>
5862 <para id="x_485">Normally, when <command role="hg-cmd" moreinfo="none">hg serve</command>
5863 starts, it prints no output, which can be a bit unnerving. If
5864 you'd like to confirm that it is indeed running correctly, and
5865 find out what URL you should send to your collaborators, start
5866 it with the <option role="hg-opt-global">-v</option>
5867 option.</para>
5868 </sect2>
5869 </sect1>
5871 <sect1 id="sec:collab:ssh">
5872 <title>Using the Secure Shell (ssh) protocol</title>
5874 <para id="x_486">You can pull and push changes securely over a network
5875 connection using the Secure Shell (<literal moreinfo="none">ssh</literal>)
5876 protocol. To use this successfully, you may have to do a little
5877 bit of configuration on the client or server sides.</para>
5879 <para id="x_487">If you're not familiar with ssh, it's the name of
5880 both a command and a network protocol that let you securely
5881 communicate with another computer. To use it with Mercurial,
5882 you'll be setting up one or more user accounts on a server so
5883 that remote users can log in and execute commands.</para>
5885 <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll
5886 probably find some of the material that follows to be elementary
5887 in nature.)</para>
5889 <sect2>
5890 <title>How to read and write ssh URLs</title>
5892 <para id="x_489">An ssh URL tends to look like this:</para>
5893 <programlisting format="linespecific">ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting>
5894 <orderedlist inheritnum="ignore" continuation="restarts">
5895 <listitem><para id="x_48a">The <quote><literal moreinfo="none">ssh://</literal></quote>
5896 part tells Mercurial to use the ssh protocol.</para>
5897 </listitem>
5898 <listitem><para id="x_48b">The <quote><literal moreinfo="none">bos@</literal></quote>
5899 component indicates what username to log into the server
5900 as. You can leave this out if the remote username is the
5901 same as your local username.</para>
5902 </listitem>
5903 <listitem><para id="x_48c">The
5904 <quote><literal moreinfo="none">hg.serpentine.com</literal></quote> gives
5905 the hostname of the server to log into.</para>
5906 </listitem>
5907 <listitem><para id="x_48d">The <quote>:22</quote> identifies the port
5908 number to connect to the server on. The default port is
5909 22, so you only need to specify a colon and port number if
5910 you're <emphasis>not</emphasis> using port 22.</para>
5911 </listitem>
5912 <listitem><para id="x_48e">The remainder of the URL is the local path to
5913 the repository on the server.</para>
5914 </listitem></orderedlist>
5916 <para id="x_48f">There's plenty of scope for confusion with the path
5917 component of ssh URLs, as there is no standard way for tools
5918 to interpret it. Some programs behave differently than others
5919 when dealing with these paths. This isn't an ideal situation,
5920 but it's unlikely to change. Please read the following
5921 paragraphs carefully.</para>
5923 <para id="x_490">Mercurial treats the path to a repository on the server as
5924 relative to the remote user's home directory. For example, if
5925 user <literal moreinfo="none">foo</literal> on the server has a home directory
5926 of <filename class="directory" moreinfo="none">/home/foo</filename>, then an
5927 ssh URL that contains a path component of <filename class="directory" moreinfo="none">bar</filename> <emphasis>really</emphasis>
5928 refers to the directory <filename class="directory" moreinfo="none">/home/foo/bar</filename>.</para>
5930 <para id="x_491">If you want to specify a path relative to another user's
5931 home directory, you can use a path that starts with a tilde
5932 character followed by the user's name (let's call them
5933 <literal moreinfo="none">otheruser</literal>), like this.</para>
5934 <programlisting format="linespecific">ssh://server/~otheruser/hg/repo</programlisting>
5936 <para id="x_492">And if you really want to specify an
5937 <emphasis>absolute</emphasis> path on the server, begin the
5938 path component with two slashes, as in this example.</para>
5939 <programlisting format="linespecific">ssh://server//absolute/path</programlisting>
5940 </sect2>
5942 <sect2>
5943 <title>Finding an ssh client for your system</title>
5945 <para id="x_493">Almost every Unix-like system comes with OpenSSH
5946 preinstalled. If you're using such a system, run
5947 <literal moreinfo="none">which ssh</literal> to find out if the
5948 <command moreinfo="none">ssh</command> command is installed (it's usually in
5949 <filename class="directory" moreinfo="none">/usr/bin</filename>). In the
5950 unlikely event that it isn't present, take a look at your
5951 system documentation to figure out how to install it.</para>
5953 <para id="x_494">On Windows, the TortoiseHg package is bundled
5954 with a version of Simon Tatham's excellent
5955 <command moreinfo="none">plink</command> command, and you should not need to
5956 do any further configuration.</para>
5957 </sect2>
5959 <sect2>
5960 <title>Generating a key pair</title>
5962 <para id="x_499">To avoid the need to repetitively type a
5963 password every time you need to use your ssh client, I
5964 recommend generating a key pair.</para>
5966 <tip>
5967 <title>Key pairs are not mandatory</title>
5969 <para id="x_6a4">Mercurial knows nothing about ssh authentication or key
5970 pairs. You can, if you like, safely ignore this section and
5971 the one that follows until you grow tired of repeatedly
5972 typing ssh passwords.</para>
5973 </tip>
5975 <itemizedlist>
5976 <listitem>
5977 <para id="x_6a5">On a Unix-like system, the
5978 <command moreinfo="none">ssh-keygen</command> command will do the
5979 trick.</para>
5980 <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need
5981 to download a command named <command moreinfo="none">puttygen</command>
5982 from <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the
5983 PuTTY web site</ulink> to generate a key pair. See
5984 <ulink url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the
5985 <command moreinfo="none">puttygen</command> documentation</ulink> for
5986 details of how use the command.</para>
5987 </listitem>
5988 </itemizedlist>
5990 <para id="x_49a">When you generate a key pair, it's usually
5991 <emphasis>highly</emphasis> advisable to protect it with a
5992 passphrase. (The only time that you might not want to do this
5993 is when you're using the ssh protocol for automated tasks on a
5994 secure network.)</para>
5996 <para id="x_49b">Simply generating a key pair isn't enough, however.
5997 You'll need to add the public key to the set of authorised
5998 keys for whatever user you're logging in remotely as. For
5999 servers using OpenSSH (the vast majority), this will mean
6000 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>
6001 directory.</para>
6003 <para id="x_49c">On a Unix-like system, your public key will have a
6004 <filename moreinfo="none">.pub</filename> extension. If you're using
6005 <command moreinfo="none">puttygen</command> on Windows, you can save the
6006 public key to a file of your choosing, or paste it from the
6007 window it's displayed in straight into the <filename role="special" moreinfo="none">authorized_keys</filename> file.</para>
6008 </sect2>
6009 <sect2>
6010 <title>Using an authentication agent</title>
6012 <para id="x_49d">An authentication agent is a daemon that stores
6013 passphrases in memory (so it will forget passphrases if you
6014 log out and log back in again). An ssh client will notice if
6015 it's running, and query it for a passphrase. If there's no
6016 authentication agent running, or the agent doesn't store the
6017 necessary passphrase, you'll have to type your passphrase
6018 every time Mercurial tries to communicate with a server on
6019 your behalf (e.g. whenever you pull or push changes).</para>
6021 <para id="x_49e">The downside of storing passphrases in an agent is that
6022 it's possible for a well-prepared attacker to recover the
6023 plain text of your passphrases, in some cases even if your
6024 system has been power-cycled. You should make your own
6025 judgment as to whether this is an acceptable risk. It
6026 certainly saves a lot of repeated typing.</para>
6028 <itemizedlist>
6029 <listitem>
6030 <para id="x_49f">On Unix-like systems, the agent is called
6031 <command moreinfo="none">ssh-agent</command>, and it's often run
6032 automatically for you when you log in. You'll need to use
6033 the <command moreinfo="none">ssh-add</command> command to add passphrases
6034 to the agent's store.</para>
6035 </listitem>
6036 <listitem>
6037 <para id="x_6a7">On Windows, if you're using TortoiseHg, the
6038 <command moreinfo="none">pageant</command> command acts as the agent. As
6039 with <command moreinfo="none">puttygen</command>, you'll need to <ulink url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download
6040 <command moreinfo="none">pageant</command></ulink> from the PuTTY web
6041 site and read <ulink url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its
6042 documentation</ulink>. The <command moreinfo="none">pageant</command>
6043 command adds an icon to your system tray that will let you
6044 manage stored passphrases.</para>
6045 </listitem>
6046 </itemizedlist>
6047 </sect2>
6049 <sect2>
6050 <title>Configuring the server side properly</title>
6052 <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
6053 a variety of things can go wrong. Add Mercurial
6054 on top, and there's plenty more scope for head-scratching.
6055 Most of these potential problems occur on the server side, not
6056 the client side. The good news is that once you've gotten a
6057 configuration working, it will usually continue to work
6058 indefinitely.</para>
6060 <para id="x_4a1">Before you try using Mercurial to talk to an ssh server,
6061 it's best to make sure that you can use the normal
6062 <command moreinfo="none">ssh</command> or <command moreinfo="none">putty</command> command to
6063 talk to the server first. If you run into problems with using
6064 these commands directly, Mercurial surely won't work. Worse,
6065 it will obscure the underlying problem. Any time you want to
6066 debug ssh-related Mercurial problems, you should drop back to
6067 making sure that plain ssh client commands work first,
6068 <emphasis>before</emphasis> you worry about whether there's a
6069 problem with Mercurial.</para>
6071 <para id="x_4a2">The first thing to be sure of on the server side is that
6072 you can actually log in from another machine at all. If you
6073 can't use <command moreinfo="none">ssh</command> or <command moreinfo="none">putty</command>
6074 to log in, the error message you get may give you a few hints
6075 as to what's wrong. The most common problems are as
6076 follows.</para>
6077 <itemizedlist>
6078 <listitem><para id="x_4a3">If you get a <quote>connection refused</quote>
6079 error, either there isn't an SSH daemon running on the
6080 server at all, or it's inaccessible due to firewall
6081 configuration.</para>
6082 </listitem>
6083 <listitem><para id="x_4a4">If you get a <quote>no route to host</quote>
6084 error, you either have an incorrect address for the server
6085 or a seriously locked down firewall that won't admit its
6086 existence at all.</para>
6087 </listitem>
6088 <listitem><para id="x_4a5">If you get a <quote>permission denied</quote>
6089 error, you may have mistyped the username on the server,
6090 or you could have mistyped your key's passphrase or the
6091 remote user's password.</para>
6092 </listitem></itemizedlist>
6093 <para id="x_4a6">In summary, if you're having trouble talking to the
6094 server's ssh daemon, first make sure that one is running at
6095 all. On many systems it will be installed, but disabled, by
6096 default. Once you're done with this step, you should then
6097 check that the server's firewall is configured to allow
6098 incoming connections on the port the ssh daemon is listening
6099 on (usually 22). Don't worry about more exotic possibilities
6100 for misconfiguration until you've checked these two
6101 first.</para>
6103 <para id="x_4a7">If you're using an authentication agent on the client side
6104 to store passphrases for your keys, you ought to be able to
6105 log into the server without being prompted for a passphrase or
6106 a password. If you're prompted for a passphrase, there are a
6107 few possible culprits.</para>
6108 <itemizedlist>
6109 <listitem><para id="x_4a8">You might have forgotten to use
6110 <command moreinfo="none">ssh-add</command> or <command moreinfo="none">pageant</command>
6111 to store the passphrase.</para>
6112 </listitem>
6113 <listitem><para id="x_4a9">You might have stored the passphrase for the
6114 wrong key.</para>
6115 </listitem></itemizedlist>
6116 <para id="x_4aa">If you're being prompted for the remote user's password,
6117 there are another few possible problems to check.</para>
6118 <itemizedlist>
6119 <listitem><para id="x_4ab">Either the user's home directory or their
6120 <filename role="special" class="directory" moreinfo="none">.ssh</filename>
6121 directory might have excessively liberal permissions. As
6122 a result, the ssh daemon will not trust or read their
6123 <filename role="special" moreinfo="none">authorized_keys</filename> file.
6124 For example, a group-writable home or <filename role="special" class="directory" moreinfo="none">.ssh</filename>
6125 directory will often cause this symptom.</para>
6126 </listitem>
6127 <listitem><para id="x_4ac">The user's <filename role="special" moreinfo="none">authorized_keys</filename> file may have
6128 a problem. If anyone other than the user owns or can write
6129 to that file, the ssh daemon will not trust or read
6130 it.</para>
6131 </listitem></itemizedlist>
6133 <para id="x_4ad">In the ideal world, you should be able to run the
6134 following command successfully, and it should print exactly
6135 one line of output, the current date and time.</para>
6136 <programlisting format="linespecific">ssh myserver date</programlisting>
6138 <para id="x_4ae">If, on your server, you have login scripts that print
6139 banners or other junk even when running non-interactive
6140 commands like this, you should fix them before you continue,
6141 so that they only print output if they're run interactively.
6142 Otherwise these banners will at least clutter up Mercurial's
6143 output. Worse, they could potentially cause problems with
6144 running Mercurial commands remotely. Mercurial tries to
6145 detect and ignore banners in non-interactive
6146 <command moreinfo="none">ssh</command> sessions, but it is not foolproof. (If
6147 you're editing your login scripts on your server, the usual
6148 way to see if a login script is running in an interactive
6149 shell is to check the return code from the command
6150 <literal moreinfo="none">tty -s</literal>.)</para>
6152 <para id="x_4af">Once you've verified that plain old ssh is working with
6153 your server, the next step is to ensure that Mercurial runs on
6154 the server. The following command should run
6155 successfully:</para>
6157 <programlisting format="linespecific">ssh myserver hg version</programlisting>
6159 <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
6160 because you haven't installed Mercurial to <filename class="directory" moreinfo="none">/usr/bin</filename>. Don't worry if this
6161 is the case; you don't need to do that. But you should check
6162 for a few possible problems.</para>
6163 <itemizedlist>
6164 <listitem><para id="x_4b1">Is Mercurial really installed on the server at
6165 all? I know this sounds trivial, but it's worth
6166 checking!</para>
6167 </listitem>
6168 <listitem><para id="x_4b2">Maybe your shell's search path (usually set
6169 via the <envar>PATH</envar> environment variable) is
6170 simply misconfigured.</para>
6171 </listitem>
6172 <listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment
6173 variable is only being set to point to the location of the
6174 <command moreinfo="none">hg</command> executable if the login session is
6175 interactive. This can happen if you're setting the path
6176 in the wrong shell login script. See your shell's
6177 documentation for details.</para>
6178 </listitem>
6179 <listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment
6180 variable may need to contain the path to the Mercurial
6181 Python modules. It might not be set at all; it could be
6182 incorrect; or it may be set only if the login is
6183 interactive.</para>
6184 </listitem></itemizedlist>
6186 <para id="x_4b5">If you can run <command role="hg-cmd" moreinfo="none">hg version</command>
6187 over an ssh connection, well done! You've got the server and
6188 client sorted out. You should now be able to use Mercurial to
6189 access repositories hosted by that username on that server.
6190 If you run into problems with Mercurial and ssh at this point,
6191 try using the <option role="hg-opt-global">--debug</option>
6192 option to get a clearer picture of what's going on.</para>
6193 </sect2>
6194 <sect2>
6195 <title>Using compression with ssh</title>
6197 <para id="x_4b6">Mercurial does not compress data when it uses the ssh
6198 protocol, because the ssh protocol can transparently compress
6199 data. However, the default behavior of ssh clients is
6200 <emphasis>not</emphasis> to request compression.</para>
6202 <para id="x_4b7">Over any network other than a fast LAN (even a wireless
6203 network), using compression is likely to significantly speed
6204 up Mercurial's network operations. For example, over a WAN,
6205 someone measured compression as reducing the amount of time
6206 required to clone a particularly large repository from 51
6207 minutes to 17 minutes.</para>
6209 <para id="x_4b8">Both <command moreinfo="none">ssh</command> and <command moreinfo="none">plink</command>
6210 accept a <option role="cmd-opt-ssh">-C</option> option which
6211 turns on compression. You can easily edit your <filename role="special" moreinfo="none">~/.hgrc</filename> to enable compression for
6212 all of Mercurial's uses of the ssh protocol. Here is how to
6213 do so for regular <command moreinfo="none">ssh</command> on Unix-like systems,
6214 for example.</para>
6215 <programlisting format="linespecific">[ui]
6216 ssh = ssh -C</programlisting>
6218 <para id="x_4b9">If you use <command moreinfo="none">ssh</command> on a
6219 Unix-like system, you can configure it to always use
6220 compression when talking to your server. To do this, edit
6221 your <filename role="special" moreinfo="none">.ssh/config</filename> file
6222 (which may not yet exist), as follows.</para>
6224 <programlisting format="linespecific">Host hg
6225 Compression yes
6226 HostName hg.example.com</programlisting>
6228 <para id="x_4ba">This defines a hostname alias,
6229 <literal moreinfo="none">hg</literal>. When you use that hostname on the
6230 <command moreinfo="none">ssh</command> command line or in a Mercurial
6231 <literal moreinfo="none">ssh</literal>-protocol URL, it will cause
6232 <command moreinfo="none">ssh</command> to connect to
6233 <literal moreinfo="none">hg.example.com</literal> and use compression. This
6234 gives you both a shorter name to type and compression, each of
6235 which is a good thing in its own right.</para>
6236 </sect2>
6237 </sect1>
6239 <sect1 id="sec:collab:cgi">
6240 <title>Serving over HTTP using CGI</title>
6242 <para id="x_6a8">The simplest way to host one or more repositories in a
6243 permanent way is to use a web server and Mercurial's CGI
6244 support.</para>
6246 <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
6247 CGI interface can take anything from a few moments to several
6248 hours.</para>
6250 <para id="x_4bc">We'll begin with the simplest of examples, and work our way
6251 towards a more complex configuration. Even for the most basic
6252 case, you're almost certainly going to need to read and modify
6253 your web server's configuration.</para>
6255 <note>
6256 <title>High pain tolerance required</title>
6258 <para id="x_4bd">Configuring a web server is a complex, fiddly,
6259 and highly system-dependent activity. I can't possibly give
6260 you instructions that will cover anything like all of the
6261 cases you will encounter. Please use your discretion and
6262 judgment in following the sections below. Be prepared to make
6263 plenty of mistakes, and to spend a lot of time reading your
6264 server's error logs.</para>
6266 <para id="x_6a9">If you don't have a strong stomach for tweaking
6267 configurations over and over, or a compelling need to host
6268 your own services, you might want to try one of the public
6269 hosting services that I mentioned earlier.</para>
6270 </note>
6272 <sect2>
6273 <title>Web server configuration checklist</title>
6275 <para id="x_4be">Before you continue, do take a few moments to check a few
6276 aspects of your system's setup.</para>
6278 <orderedlist inheritnum="ignore" continuation="restarts">
6279 <listitem><para id="x_4bf">Do you have a web server installed
6280 at all? Mac OS X and some Linux distributions ship with
6281 Apache, but many other systems may not have a web server
6282 installed.</para>
6283 </listitem>
6284 <listitem><para id="x_4c0">If you have a web server installed, is it
6285 actually running? On most systems, even if one is
6286 present, it will be disabled by default.</para>
6287 </listitem>
6288 <listitem><para id="x_4c1">Is your server configured to allow you to run
6289 CGI programs in the directory where you plan to do so?
6290 Most servers default to explicitly disabling the ability
6291 to run CGI programs.</para>
6292 </listitem></orderedlist>
6294 <para id="x_4c2">If you don't have a web server installed, and don't have
6295 substantial experience configuring Apache, you should consider
6296 using the <literal moreinfo="none">lighttpd</literal> web server instead of
6297 Apache. Apache has a well-deserved reputation for baroque and
6298 confusing configuration. While <literal moreinfo="none">lighttpd</literal> is
6299 less capable in some ways than Apache, most of these
6300 capabilities are not relevant to serving Mercurial
6301 repositories. And <literal moreinfo="none">lighttpd</literal> is undeniably
6302 <emphasis>much</emphasis> easier to get started with than
6303 Apache.</para>
6304 </sect2>
6306 <sect2>
6307 <title>Basic CGI configuration</title>
6309 <para id="x_4c3">On Unix-like systems, it's common for users to have a
6310 subdirectory named something like <filename class="directory" moreinfo="none">public_html</filename> in their home
6311 directory, from which they can serve up web pages. A file
6312 named <filename moreinfo="none">foo</filename> in this directory will be
6313 accessible at a URL of the form
6314 <literal moreinfo="none">http://www.example.com/username/foo</literal>.</para>
6316 <para id="x_4c4">To get started, find the <filename role="special" moreinfo="none">hgweb.cgi</filename> script that should be
6317 present in your Mercurial installation. If you can't quickly
6318 find a local copy on your system, simply download one from the
6319 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>
6321 <para id="x_4c5">You'll need to copy this script into your <filename class="directory" moreinfo="none">public_html</filename> directory, and
6322 ensure that it's executable.</para>
6323 <programlisting format="linespecific">cp .../hgweb.cgi ~/public_html
6324 chmod 755 ~/public_html/hgweb.cgi</programlisting>
6325 <para id="x_4c6">The <literal moreinfo="none">755</literal> argument to
6326 <command moreinfo="none">chmod</command> is a little more general than just
6327 making the script executable: it ensures that the script is
6328 executable by anyone, and that <quote>group</quote> and
6329 <quote>other</quote> write permissions are
6330 <emphasis>not</emphasis> set. If you were to leave those
6331 write permissions enabled, Apache's <literal moreinfo="none">suexec</literal>
6332 subsystem would likely refuse to execute the script. In fact,
6333 <literal moreinfo="none">suexec</literal> also insists that the
6334 <emphasis>directory</emphasis> in which the script resides
6335 must not be writable by others.</para>
6336 <programlisting format="linespecific">chmod 755 ~/public_html</programlisting>
6338 <sect3 id="sec:collab:wtf">
6339 <title>What could <emphasis>possibly</emphasis> go
6340 wrong?</title>
6342 <para id="x_4c7">Once you've copied the CGI script into place,
6343 go into a web browser, and try to open the URL
6344 <literal moreinfo="none">http://myhostname/~myuser/hgweb.cgi</literal>,
6345 <emphasis>but</emphasis> brace yourself for instant failure.
6346 There's a high probability that trying to visit this URL
6347 will fail, and there are many possible reasons for this. In
6348 fact, you're likely to stumble over almost every one of the
6349 possible errors below, so please read carefully. The
6350 following are all of the problems I ran into on a system
6351 running Fedora 7, with a fresh installation of Apache, and a
6352 user account that I created specially to perform this
6353 exercise.</para>
6355 <para id="x_4c8">Your web server may have per-user directories disabled.
6356 If you're using Apache, search your config file for a
6357 <literal moreinfo="none">UserDir</literal> directive. If there's none
6358 present, per-user directories will be disabled. If one
6359 exists, but its value is <literal moreinfo="none">disabled</literal>, then
6360 per-user directories will be disabled. Otherwise, the
6361 string after <literal moreinfo="none">UserDir</literal> gives the name of
6362 the subdirectory that Apache will look in under your home
6363 directory, for example <filename class="directory" moreinfo="none">public_html</filename>.</para>
6365 <para id="x_4c9">Your file access permissions may be too restrictive.
6366 The web server must be able to traverse your home directory
6367 and directories under your <filename class="directory" moreinfo="none">public_html</filename> directory, and
6368 read files under the latter too. Here's a quick recipe to
6369 help you to make your permissions more appropriate.</para>
6370 <programlisting format="linespecific">chmod 755 ~
6371 find ~/public_html -type d -print0 | xargs -0r chmod 755
6372 find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting>
6374 <para id="x_4ca">The other possibility with permissions is that you might
6375 get a completely empty window when you try to load the
6376 script. In this case, it's likely that your access
6377 permissions are <emphasis>too permissive</emphasis>. Apache's
6378 <literal moreinfo="none">suexec</literal> subsystem won't execute a script
6379 that's group- or world-writable, for example.</para>
6381 <para id="x_4cb">Your web server may be configured to disallow execution
6382 of CGI programs in your per-user web directory. Here's
6383 Apache's default per-user configuration from my Fedora
6384 system.</para>
6386 <!-- BEGIN ch06/apache-config.lst -->
6387 <programlisting format="linespecific"><Directory /home/*/public_html>
6388 AllowOverride FileInfo AuthConfig Limit
6389 Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
6390 <Limit GET POST OPTIONS>
6391 Order allow,deny
6392 Allow from all
6393 </Limit>
6394 <LimitExcept GET POST OPTIONS>
6395 Order deny,allow Deny from all
6396 </LimitExcept>
6397 </Directory></programlisting>
6398 <!-- END ch06/apache-config.lst -->
6401 <para id="x_4cc">If you find a similar-looking
6402 <literal moreinfo="none">Directory</literal> group in your Apache
6403 configuration, the directive to look at inside it is
6404 <literal moreinfo="none">Options</literal>. Add <literal moreinfo="none">ExecCGI</literal>
6405 to the end of this list if it's missing, and restart the web
6406 server.</para>
6408 <para id="x_4cd">If you find that Apache serves you the text of the CGI
6409 script instead of executing it, you may need to either
6410 uncomment (if already present) or add a directive like
6411 this.</para>
6412 <programlisting format="linespecific">AddHandler cgi-script .cgi</programlisting>
6414 <para id="x_4ce">The next possibility is that you might be served with a
6415 colourful Python backtrace claiming that it can't import a
6416 <literal moreinfo="none">mercurial</literal>-related module. This is
6417 actually progress! The server is now capable of executing
6418 your CGI script. This error is only likely to occur if
6419 you're running a private installation of Mercurial, instead
6420 of a system-wide version. Remember that the web server runs
6421 the CGI program without any of the environment variables
6422 that you take for granted in an interactive session. If
6423 this error happens to you, edit your copy of <filename role="special" moreinfo="none">hgweb.cgi</filename> and follow the
6424 directions inside it to correctly set your
6425 <envar>PYTHONPATH</envar> environment variable.</para>
6427 <para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be
6428 served with another colourful Python backtrace: this one
6429 will complain that it can't find <filename class="directory" moreinfo="none">/path/to/repository</filename>. Edit
6430 your <filename role="special" moreinfo="none">hgweb.cgi</filename> script
6431 and replace the <filename class="directory" moreinfo="none">/path/to/repository</filename> string
6432 with the complete path to the repository you want to serve
6433 up.</para>
6435 <para id="x_4d0">At this point, when you try to reload the page, you
6436 should be presented with a nice HTML view of your
6437 repository's history. Whew!</para>
6438 </sect3>
6440 <sect3>
6441 <title>Configuring lighttpd</title>
6443 <para id="x_4d1">To be exhaustive in my experiments, I tried configuring
6444 the increasingly popular <literal moreinfo="none">lighttpd</literal> web
6445 server to serve the same repository as I described with
6446 Apache above. I had already overcome all of the problems I
6447 outlined with Apache, many of which are not server-specific.
6448 As a result, I was fairly sure that my file and directory
6449 permissions were good, and that my <filename role="special" moreinfo="none">hgweb.cgi</filename> script was properly
6450 edited.</para>
6452 <para id="x_4d2">Once I had Apache running, getting
6453 <literal moreinfo="none">lighttpd</literal> to serve the repository was a
6454 snap (in other words, even if you're trying to use
6455 <literal moreinfo="none">lighttpd</literal>, you should read the Apache
6456 section). I first had to edit the
6457 <literal moreinfo="none">mod_access</literal> section of its config file to
6458 enable <literal moreinfo="none">mod_cgi</literal> and
6459 <literal moreinfo="none">mod_userdir</literal>, both of which were disabled
6460 by default on my system. I then added a few lines to the
6461 end of the config file, to configure these modules.</para>
6462 <programlisting format="linespecific">userdir.path = "public_html"
6463 cgi.assign = (".cgi" => "" )</programlisting>
6464 <para id="x_4d3">With this done, <literal moreinfo="none">lighttpd</literal> ran
6465 immediately for me. If I had configured
6466 <literal moreinfo="none">lighttpd</literal> before Apache, I'd almost
6467 certainly have run into many of the same system-level
6468 configuration problems as I did with Apache. However, I
6469 found <literal moreinfo="none">lighttpd</literal> to be noticeably easier to
6470 configure than Apache, even though I've used Apache for over
6471 a decade, and this was my first exposure to
6472 <literal moreinfo="none">lighttpd</literal>.</para>
6473 </sect3>
6474 </sect2>
6476 <sect2>
6477 <title>Sharing multiple repositories with one CGI script</title>
6479 <para id="x_4d4">The <filename role="special" moreinfo="none">hgweb.cgi</filename> script
6480 only lets you publish a single repository, which is an
6481 annoying restriction. If you want to publish more than one
6482 without wracking yourself with multiple copies of the same
6483 script, each with different names, a better choice is to use
6484 the <filename role="special" moreinfo="none">hgwebdir.cgi</filename>
6485 script.</para>
6487 <para id="x_4d5">The procedure to configure <filename role="special" moreinfo="none">hgwebdir.cgi</filename> is only a little more
6488 involved than for <filename role="special" moreinfo="none">hgweb.cgi</filename>. First, you must obtain
6489 a copy of the script. If you don't have one handy, you can
6490 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>
6492 <para id="x_4d6">You'll need to copy this script into your <filename class="directory" moreinfo="none">public_html</filename> directory, and
6493 ensure that it's executable.</para>
6495 <programlisting format="linespecific">cp .../hgwebdir.cgi ~/public_html
6496 chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
6498 <para id="x_4d7">With basic configuration out of the way, try to
6499 visit <literal moreinfo="none">http://myhostname/~myuser/hgwebdir.cgi</literal>
6500 in your browser. It should
6501 display an empty list of repositories. If you get a blank
6502 window or error message, try walking through the list of
6503 potential problems in <xref linkend="sec:collab:wtf"/>.</para>
6505 <para id="x_4d8">The <filename role="special" moreinfo="none">hgwebdir.cgi</filename>
6506 script relies on an external configuration file. By default,
6507 it searches for a file named <filename role="special" moreinfo="none">hgweb.config</filename> in the same directory
6508 as itself. You'll need to create this file, and make it
6509 world-readable. The format of the file is similar to a
6510 Windows <quote>ini</quote> file, as understood by Python's
6511 <literal moreinfo="none">ConfigParser</literal>
6512 <citation>web:configparser</citation> module.</para>
6514 <para id="x_4d9">The easiest way to configure <filename role="special" moreinfo="none">hgwebdir.cgi</filename> is with a section
6515 named <literal moreinfo="none">collections</literal>. This will automatically
6516 publish <emphasis>every</emphasis> repository under the
6517 directories you name. The section should look like
6518 this:</para>
6519 <programlisting format="linespecific">[collections]
6520 /my/root = /my/root</programlisting>
6521 <para id="x_4da">Mercurial interprets this by looking at the directory name
6522 on the <emphasis>right</emphasis> hand side of the
6523 <quote><literal moreinfo="none">=</literal></quote> sign; finding repositories
6524 in that directory hierarchy; and using the text on the
6525 <emphasis>left</emphasis> to strip off matching text from the
6526 names it will actually list in the web interface. The
6527 remaining component of a path after this stripping has
6528 occurred is called a <quote>virtual path</quote>.</para>
6530 <para id="x_4db">Given the example above, if we have a
6531 repository whose local path is <filename class="directory" moreinfo="none">/my/root/this/repo</filename>, the CGI
6532 script will strip the leading <filename class="directory" moreinfo="none">/my/root</filename> from the name, and
6533 publish the repository with a virtual path of <filename class="directory" moreinfo="none">this/repo</filename>. If the base URL for
6534 our CGI script is
6535 <literal moreinfo="none">http://myhostname/~myuser/hgwebdir.cgi</literal>, the
6536 complete URL for that repository will be
6537 <literal moreinfo="none">http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para>
6539 <para id="x_4dc">If we replace <filename class="directory" moreinfo="none">/my/root</filename> on the left hand side
6540 of this example with <filename class="directory" moreinfo="none">/my</filename>, then <filename role="special" moreinfo="none">hgwebdir.cgi</filename> will only strip off
6541 <filename class="directory" moreinfo="none">/my</filename> from the repository
6542 name, and will give us a virtual path of <filename class="directory" moreinfo="none">root/this/repo</filename> instead of
6543 <filename class="directory" moreinfo="none">this/repo</filename>.</para>
6545 <para id="x_4dd">The <filename role="special" moreinfo="none">hgwebdir.cgi</filename>
6546 script will recursively search each directory listed in the
6547 <literal moreinfo="none">collections</literal> section of its configuration
6548 file, but it will <literal moreinfo="none">not</literal> recurse into the
6549 repositories it finds.</para>
6551 <para id="x_4de">The <literal moreinfo="none">collections</literal> mechanism makes it easy
6552 to publish many repositories in a <quote>fire and
6553 forget</quote> manner. You only need to set up the CGI
6554 script and configuration file one time. Afterwards, you can
6555 publish or unpublish a repository at any time by simply moving
6556 it into, or out of, the directory hierarchy in which you've
6557 configured <filename role="special" moreinfo="none">hgwebdir.cgi</filename> to
6558 look.</para>
6560 <sect3>
6561 <title>Explicitly specifying which repositories to
6562 publish</title>
6564 <para id="x_4df">In addition to the <literal moreinfo="none">collections</literal>
6565 mechanism, the <filename role="special" moreinfo="none">hgwebdir.cgi</filename> script allows you
6566 to publish a specific list of repositories. To do so,
6567 create a <literal moreinfo="none">paths</literal> section, with contents of
6568 the following form.</para>
6569 <programlisting format="linespecific">[paths]
6570 repo1 = /my/path/to/some/repo
6571 repo2 = /some/path/to/another</programlisting>
6572 <para id="x_4e0">In this case, the virtual path (the component that will
6573 appear in a URL) is on the left hand side of each
6574 definition, while the path to the repository is on the
6575 right. Notice that there does not need to be any
6576 relationship between the virtual path you choose and the
6577 location of a repository in your filesystem.</para>
6579 <para id="x_4e1">If you wish, you can use both the
6580 <literal moreinfo="none">collections</literal> and <literal moreinfo="none">paths</literal>
6581 mechanisms simultaneously in a single configuration
6582 file.</para>
6584 <note>
6585 <title>Beware duplicate virtual paths</title>
6587 <para id="x_4e2"> If several repositories have the same
6588 virtual path, <filename role="special" moreinfo="none">hgwebdir.cgi</filename> will not report
6589 an error. Instead, it will behave unpredictably.</para>
6590 </note>
6591 </sect3>
6592 </sect2>
6594 <sect2>
6595 <title>Downloading source archives</title>
6597 <para id="x_4e3">Mercurial's web interface lets users download an archive
6598 of any revision. This archive will contain a snapshot of the
6599 working directory as of that revision, but it will not contain
6600 a copy of the repository data.</para>
6602 <para id="x_4e4">By default, this feature is not enabled. To enable it,
6603 you'll need to add an <envar role="rc-item-web">allow_archive</envar> item to the
6604 <literal role="rc-web" moreinfo="none">web</literal> section of your <filename role="special" moreinfo="none">~/.hgrc</filename>; see below for details.</para>
6605 </sect2>
6606 <sect2>
6607 <title>Web configuration options</title>
6609 <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd" moreinfo="none">hg
6610 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
6611 number of configuration options that you can set. These
6612 belong in a section named <literal role="rc-web" moreinfo="none">web</literal>.</para>
6613 <itemizedlist>
6614 <listitem><para id="x_4e6"><envar role="rc-item-web">allow_archive</envar>: Determines
6615 which (if any) archive download mechanisms Mercurial
6616 supports. If you enable this feature, users of the web
6617 interface will be able to download an archive of whatever
6618 revision of a repository they are viewing. To enable the
6619 archive feature, this item must take the form of a
6620 sequence of words drawn from the list below.</para>
6621 <itemizedlist>
6622 <listitem><para id="x_4e7"><literal moreinfo="none">bz2</literal>: A
6623 <command moreinfo="none">tar</command> archive, compressed using
6624 <literal moreinfo="none">bzip2</literal> compression. This has the
6625 best compression ratio, but uses the most CPU time on
6626 the server.</para>
6627 </listitem>
6628 <listitem><para id="x_4e8"><literal moreinfo="none">gz</literal>: A
6629 <command moreinfo="none">tar</command> archive, compressed using
6630 <literal moreinfo="none">gzip</literal> compression.</para>
6631 </listitem>
6632 <listitem><para id="x_4e9"><literal moreinfo="none">zip</literal>: A
6633 <command moreinfo="none">zip</command> archive, compressed using LZW
6634 compression. This format has the worst compression
6635 ratio, but is widely used in the Windows world.</para>
6636 </listitem>
6637 </itemizedlist>
6638 <para id="x_4ea"> If you provide an empty list, or don't have an
6639 <envar role="rc-item-web">allow_archive</envar> entry at
6640 all, this feature will be disabled. Here is an example of
6641 how to enable all three supported formats.</para>
6642 <programlisting format="linespecific">[web]
6643 allow_archive = bz2 gz zip</programlisting>
6644 </listitem>
6645 <listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>:
6646 Boolean. Determines whether the web interface allows
6647 remote users to <command role="hg-cmd" moreinfo="none">hg pull</command>
6648 and <command role="hg-cmd" moreinfo="none">hg clone</command> this
6649 repository over HTTP. If set to <literal moreinfo="none">no</literal> or
6650 <literal moreinfo="none">false</literal>, only the
6651 <quote>human-oriented</quote> portion of the web interface
6652 is available.</para>
6653 </listitem>
6654 <listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>:
6655 String. A free-form (but preferably brief) string
6656 identifying the person or group in charge of the
6657 repository. This often contains the name and email
6658 address of a person or mailing list. It often makes sense
6659 to place this entry in a repository's own <filename role="special" moreinfo="none">.hg/hgrc</filename> file, but it can make
6660 sense to use in a global <filename role="special" moreinfo="none">~/.hgrc</filename> if every repository
6661 has a single maintainer.</para>
6662 </listitem>
6663 <listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>:
6664 Integer. The default maximum number of changesets to
6665 display in a single page of output.</para>
6666 </listitem>
6667 <listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>:
6668 Integer. The default maximum number of modified files to
6669 display in a single page of output.</para>
6670 </listitem>
6671 <listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>:
6672 Integer. If the web interface displays alternating
6673 <quote>stripes</quote> to make it easier to visually align
6674 rows when you are looking at a table, this number controls
6675 the number of rows in each stripe.</para>
6676 </listitem>
6677 <listitem><para id="x_4f0"><envar role="rc-item-web">style</envar>: Controls the template
6678 Mercurial uses to display the web interface. Mercurial
6679 ships with several web templates.</para>
6680 <itemizedlist>
6681 <listitem>
6682 <para id="x_6aa"><literal moreinfo="none">coal</literal> is monochromatic.</para>
6683 </listitem>
6684 <listitem>
6685 <para id="x_6ab"><literal moreinfo="none">gitweb</literal> emulates the visual
6686 style of git's web interface.</para>
6687 </listitem>
6688 <listitem>
6689 <para id="x_6ac"><literal moreinfo="none">monoblue</literal> uses solid blues and
6690 greys.</para>
6691 </listitem>
6692 <listitem>
6693 <para id="x_6ad"><literal moreinfo="none">paper</literal> is the default.</para>
6694 </listitem>
6695 <listitem>
6696 <para id="x_6ae"><literal moreinfo="none">spartan</literal> was the default for a
6697 long time.</para>
6698 </listitem>
6699 </itemizedlist>
6700 <para id="x_6af">You can
6701 also specify a custom template of your own; see
6702 <xref linkend="chap:template"/> for details. Here, you can
6703 see how to enable the <literal moreinfo="none">gitweb</literal>
6704 style.</para>
6705 <programlisting format="linespecific">[web]
6706 style = gitweb</programlisting>
6707 </listitem>
6708 <listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>:
6709 Path. The directory in which to search for template
6710 files. By default, Mercurial searches in the directory in
6711 which it was installed.</para>
6712 </listitem></itemizedlist>
6713 <para id="x_4f2">If you are using <filename role="special" moreinfo="none">hgwebdir.cgi</filename>, you can place a few
6714 configuration items in a <literal role="rc-web" moreinfo="none">web</literal>
6715 section of the <filename role="special" moreinfo="none">hgweb.config</filename> file instead of a
6716 <filename role="special" moreinfo="none">~/.hgrc</filename> file, for
6717 convenience. These items are <envar role="rc-item-web">motd</envar> and <envar role="rc-item-web">style</envar>.</para>
6719 <sect3>
6720 <title>Options specific to an individual repository</title>
6722 <para id="x_4f3">A few <literal role="rc-web" moreinfo="none">web</literal> configuration
6723 items ought to be placed in a repository's local <filename role="special" moreinfo="none">.hg/hgrc</filename>, rather than a user's
6724 or global <filename role="special" moreinfo="none">~/.hgrc</filename>.</para>
6725 <itemizedlist>
6726 <listitem><para id="x_4f4"><envar role="rc-item-web">description</envar>: String. A
6727 free-form (but preferably brief) string that describes
6728 the contents or purpose of the repository.</para>
6729 </listitem>
6730 <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>:
6731 String. The name to use for the repository in the web
6732 interface. This overrides the default name, which is
6733 the last component of the repository's path.</para>
6734 </listitem></itemizedlist>
6735 </sect3>
6737 <sect3>
6738 <title>Options specific to the <command role="hg-cmd" moreinfo="none">hg
6739 serve</command> command</title>
6741 <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
6742 with the <command role="hg-cmd" moreinfo="none">hg serve</command>
6743 command.</para>
6744 <itemizedlist>
6745 <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>:
6746 Path. The name of a file into which to write an access
6747 log. By default, the <command role="hg-cmd" moreinfo="none">hg
6748 serve</command> command writes this information to
6749 standard output, not to a file. Log entries are written
6750 in the standard <quote>combined</quote> file format used
6751 by almost all web servers.</para>
6752 </listitem>
6753 <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>:
6754 String. The local address on which the server should
6755 listen for incoming connections. By default, the server
6756 listens on all addresses.</para>
6757 </listitem>
6758 <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>:
6759 Path. The name of a file into which to write an error
6760 log. By default, the <command role="hg-cmd" moreinfo="none">hg
6761 serve</command> command writes this information to
6762 standard error, not to a file.</para>
6763 </listitem>
6764 <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>:
6765 Boolean. Whether to use the IPv6 protocol. By default,
6766 IPv6 is not used.</para>
6767 </listitem>
6768 <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>:
6769 Integer. The TCP port number on which the server should
6770 listen. The default port number used is 8000.</para>
6771 </listitem></itemizedlist>
6772 </sect3>
6774 <sect3>
6775 <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>
6777 <para id="x_4fc">It is important to remember that a web server like
6778 Apache or <literal moreinfo="none">lighttpd</literal> will run under a user
6779 ID that is different to yours. CGI scripts run by your
6780 server, such as <filename role="special" moreinfo="none">hgweb.cgi</filename>, will usually also run
6781 under that user ID.</para>
6783 <para id="x_4fd">If you add <literal role="rc-web" moreinfo="none">web</literal> items to
6784 your own personal <filename role="special" moreinfo="none">~/.hgrc</filename> file, CGI scripts won't read that
6785 <filename role="special" moreinfo="none">~/.hgrc</filename> file. Those
6786 settings will thus only affect the behavior of the <command role="hg-cmd" moreinfo="none">hg serve</command> command when you run it.
6787 To cause CGI scripts to see your settings, either create a
6788 <filename role="special" moreinfo="none">~/.hgrc</filename> file in the
6789 home directory of the user ID that runs your web server, or
6790 add those settings to a system-wide <filename role="special" moreinfo="none">hgrc</filename> file.</para>
6791 </sect3>
6792 </sect2>
6793 </sect1>
6795 <sect1>
6796 <title>System-wide configuration</title>
6798 <para id="x_6b0">On Unix-like systems shared by multiple users (such as a
6799 server to which people publish changes), it often makes sense to
6800 set up some global default behaviors, such as what theme to use
6801 in web interfaces.</para>
6803 <para id="x_6b1">If a file named <filename moreinfo="none">/etc/mercurial/hgrc</filename>
6804 exists, Mercurial will read it at startup time and apply any
6805 configuration settings it finds in that file. It will also look
6806 for files ending in a <literal moreinfo="none">.rc</literal> extension in a
6807 directory named <filename moreinfo="none">/etc/mercurial/hgrc.d</filename>, and
6808 apply any configuration settings it finds in each of those
6809 files.</para>
6811 <sect2>
6812 <title>Making Mercurial more trusting</title>
6814 <para id="x_6b2">One situation in which a global <filename moreinfo="none">hgrc</filename>
6815 can be useful is if users are pulling changes owned by other
6816 users. By default, Mercurial will not trust most of the
6817 configuration items in a <filename moreinfo="none">.hg/hgrc</filename> file
6818 inside a repository that is owned by a different user. If we
6819 clone or pull changes from such a repository, Mercurial will
6820 print a warning stating that it does not trust their
6821 <filename moreinfo="none">.hg/hgrc</filename>.</para>
6823 <para id="x_6b3">If everyone in a particular Unix group is on the same team
6824 and <emphasis>should</emphasis> trust each other's
6825 configuration settings, or we want to trust particular users,
6826 we can override Mercurial's skeptical defaults by creating a
6827 system-wide <filename moreinfo="none">hgrc</filename> file such as the
6828 following:</para>
6830 <programlisting format="linespecific"># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
6831 [trusted]
6832 # Trust all entries in any hgrc file owned by the "editors" or
6833 # "www-data" groups.
6834 groups = editors, www-data
6836 # Trust entries in hgrc files owned by the following users.
6837 users = apache, bobo
6838 </programlisting>
6839 </sect2>
6840 </sect1>
6841 </chapter>
6843 <!--
6844 local variables:
6845 sgml-parent-document: ("00book.xml" "book" "chapter")
6846 end:
6847 -->
6849 <!-- BEGIN ch07 -->
6850 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
6852 <chapter id="chap:names">
6853 <?dbhtml filename="file-names-and-pattern-matching.html"?>
6854 <title>File names and pattern matching</title>
6856 <para id="x_543">Mercurial provides mechanisms that let you work with file
6857 names in a consistent and expressive way.</para>
6859 <sect1>
6860 <title>Simple file naming</title>
6862 <para id="x_544">Mercurial uses a unified piece of machinery <quote>under the
6863 hood</quote> to handle file names. Every command behaves
6864 uniformly with respect to file names. The way in which commands
6865 work with file names is as follows.</para>
6867 <para id="x_545">If you explicitly name real files on the command line,
6868 Mercurial works with exactly those files, as you would expect.
6869 <!-- BEGIN filenames.files -->
6870 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add COPYING README examples/simple.py</userinput>
6871 </screen>
6872 <!-- END filenames.files -->
6873 </para>
6875 <para id="x_546">When you provide a directory name, Mercurial will interpret
6876 this as <quote>operate on every file in this directory and its
6877 subdirectories</quote>. Mercurial traverses the files and
6878 subdirectories in a directory in alphabetical order. When it
6879 encounters a subdirectory, it will traverse that subdirectory
6880 before continuing with the current directory.</para>
6882 <!-- BEGIN filenames.dirs -->
6883 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status src</userinput>
6884 ? src/main.py
6885 ? src/watcher/_watcher.c
6886 ? src/watcher/watcher.py
6887 ? src/xyzzy.txt
6888 </screen>
6889 <!-- END filenames.dirs -->
6891 </sect1>
6893 <sect1>
6894 <title>Running commands without any file names</title>
6896 <para id="x_547">Mercurial's commands that work with file names have useful
6897 default behaviors when you invoke them without providing any
6898 file names or patterns. What kind of behavior you should
6899 expect depends on what the command does. Here are a few rules
6900 of thumb you can use to predict what a command is likely to do
6901 if you don't give it any names to work with.</para>
6902 <itemizedlist>
6903 <listitem><para id="x_548">Most commands will operate on the entire working
6904 directory. This is what the <command role="hg-cmd" moreinfo="none">hg
6905 add</command> command does, for example.</para>
6906 </listitem>
6907 <listitem><para id="x_549">If the command has effects that are difficult or
6908 impossible to reverse, it will force you to explicitly
6909 provide at least one name or pattern (see below). This
6910 protects you from accidentally deleting files by running
6911 <command role="hg-cmd" moreinfo="none">hg remove</command> with no
6912 arguments, for example.</para>
6913 </listitem></itemizedlist>
6915 <para id="x_54a">It's easy to work around these default behaviors if they
6916 don't suit you. If a command normally operates on the whole
6917 working directory, you can invoke it on just the current
6918 directory and its subdirectories by giving it the name
6919 <quote><filename class="directory" moreinfo="none">.</filename></quote>.</para>
6921 <!-- BEGIN filenames.wdir-subdir -->
6922 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd src</userinput>
6923 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add -n</userinput>
6924 adding ../MANIFEST.in
6925 adding ../examples/performant.py
6926 adding ../setup.py
6927 adding main.py
6928 adding watcher/_watcher.c
6929 adding watcher/watcher.py
6930 adding xyzzy.txt
6931 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add -n .</userinput>
6932 adding main.py
6933 adding watcher/_watcher.c
6934 adding watcher/watcher.py
6935 adding xyzzy.txt
6936 </screen>
6937 <!-- END filenames.wdir-subdir -->
6940 <para id="x_54b">Along the same lines, some commands normally print file
6941 names relative to the root of the repository, even if you're
6942 invoking them from a subdirectory. Such a command will print
6943 file names relative to your subdirectory if you give it explicit
6944 names. Here, we're going to run <command role="hg-cmd" moreinfo="none">hg
6945 status</command> from a subdirectory, and get it to operate on
6946 the entire working directory while printing file names relative
6947 to our subdirectory, by passing it the output of the <command role="hg-cmd" moreinfo="none">hg root</command> command.</para>
6949 <!-- BEGIN filenames.wdir-relname -->
6950 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
6951 A COPYING
6952 A README
6953 A examples/simple.py
6954 ? MANIFEST.in
6955 ? examples/performant.py
6956 ? setup.py
6957 ? src/main.py
6958 ? src/watcher/_watcher.c
6959 ? src/watcher/watcher.py
6960 ? src/xyzzy.txt
6961 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status `hg root`</userinput>
6962 A ../COPYING
6963 A ../README
6964 A ../examples/simple.py
6965 ? ../MANIFEST.in
6966 ? ../examples/performant.py
6967 ? ../setup.py
6968 ? main.py
6969 ? watcher/_watcher.c
6970 ? watcher/watcher.py
6971 ? xyzzy.txt
6972 </screen>
6973 <!-- END filenames.wdir-relname -->
6975 </sect1>
6977 <sect1>
6978 <title>Telling you what's going on</title>
6980 <para id="x_54c">The <command role="hg-cmd" moreinfo="none">hg add</command> example in the
6981 preceding section illustrates something else that's helpful
6982 about Mercurial commands. If a command operates on a file that
6983 you didn't name explicitly on the command line, it will usually
6984 print the name of the file, so that you will not be surprised
6985 what's going on.</para>
6987 <para id="x_54d">The principle here is of <emphasis>least
6988 surprise</emphasis>. If you've exactly named a file on the
6989 command line, there's no point in repeating it back at you. If
6990 Mercurial is acting on a file <emphasis>implicitly</emphasis>, e.g.
6991 because you provided no names, or a directory, or a pattern (see
6992 below), it is safest to tell you what files it's operating on.</para>
6994 <para id="x_54e">For commands that behave this way, you can silence them
6995 using the <option role="hg-opt-global">-q</option> option. You
6996 can also get them to print the name of every file, even those
6997 you've named explicitly, using the <option role="hg-opt-global">-v</option> option.</para>
6998 </sect1>
7000 <sect1>
7001 <title>Using patterns to identify files</title>
7003 <para id="x_54f">In addition to working with file and directory names,
7004 Mercurial lets you use <emphasis>patterns</emphasis> to identify
7005 files. Mercurial's pattern handling is expressive.</para>
7007 <para id="x_550">On Unix-like systems (Linux, MacOS, etc.), the job of
7008 matching file names to patterns normally falls to the shell. On
7009 these systems, you must explicitly tell Mercurial that a name is
7010 a pattern. On Windows, the shell does not expand patterns, so
7011 Mercurial will automatically identify names that are patterns,
7012 and expand them for you.</para>
7014 <para id="x_551">To provide a pattern in place of a regular name on the
7015 command line, the mechanism is simple:</para>
7016 <programlisting format="linespecific">syntax:patternbody</programlisting>
7017 <para id="x_552">That is, a pattern is identified by a short text string that
7018 says what kind of pattern this is, followed by a colon, followed
7019 by the actual pattern.</para>
7021 <para id="x_553">Mercurial supports two kinds of pattern syntax. The most
7022 frequently used is called <literal moreinfo="none">glob</literal>; this is the
7023 same kind of pattern matching used by the Unix shell, and should
7024 be familiar to Windows command prompt users, too.</para>
7026 <para id="x_554">When Mercurial does automatic pattern matching on Windows,
7027 it uses <literal moreinfo="none">glob</literal> syntax. You can thus omit the
7028 <quote><literal moreinfo="none">glob:</literal></quote> prefix on Windows, but
7029 it's safe to use it, too.</para>
7031 <para id="x_555">The <literal moreinfo="none">re</literal> syntax is more powerful; it lets
7032 you specify patterns using regular expressions, also known as
7033 regexps.</para>
7035 <para id="x_556">By the way, in the examples that follow, notice that I'm
7036 careful to wrap all of my patterns in quote characters, so that
7037 they won't get expanded by the shell before Mercurial sees
7038 them.</para>
7040 <sect2>
7041 <title>Shell-style <literal moreinfo="none">glob</literal> patterns</title>
7043 <para id="x_557">This is an overview of the kinds of patterns you can use
7044 when you're matching on glob patterns.</para>
7046 <para id="x_558">The <quote><literal moreinfo="none">*</literal></quote> character matches
7047 any string, within a single directory.</para>
7049 <!-- BEGIN filenames.glob.star -->
7050 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add 'glob:*.py'</userinput>
7051 adding main.py
7052 </screen>
7053 <!-- END filenames.glob.star -->
7056 <para id="x_559">The <quote><literal moreinfo="none">**</literal></quote> pattern matches
7057 any string, and crosses directory boundaries. It's not a
7058 standard Unix glob token, but it's accepted by several popular
7059 Unix shells, and is very useful.</para>
7061 <!-- BEGIN filenames.glob.starstar -->
7062 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
7063 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:**.py'</userinput>
7064 A examples/simple.py
7065 A src/main.py
7066 ? examples/performant.py
7067 ? setup.py
7068 ? src/watcher/watcher.py
7069 </screen>
7070 <!-- END filenames.glob.starstar -->
7073 <para id="x_55a">The <quote><literal moreinfo="none">?</literal></quote> pattern matches
7074 any single character.</para>
7076 <!-- BEGIN filenames.glob.question -->
7077 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:**.?'</userinput>
7078 ? src/watcher/_watcher.c
7079 </screen>
7080 <!-- END filenames.glob.question -->
7083 <para id="x_55b">The <quote><literal moreinfo="none">[</literal></quote> character begins a
7084 <emphasis>character class</emphasis>. This matches any single
7085 character within the class. The class ends with a
7086 <quote><literal moreinfo="none">]</literal></quote> character. A class may
7087 contain multiple <emphasis>range</emphasis>s of the form
7088 <quote><literal moreinfo="none">a-f</literal></quote>, which is shorthand for
7089 <quote><literal moreinfo="none">abcdef</literal></quote>.</para>
7091 <!-- BEGIN filenames.glob.range -->
7092 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:**[nr-t]'</userinput>
7093 ? MANIFEST.in
7094 ? src/xyzzy.txt
7095 </screen>
7096 <!-- END filenames.glob.range -->
7099 <para id="x_55c">If the first character after the
7100 <quote><literal moreinfo="none">[</literal></quote> in a character class is a
7101 <quote><literal moreinfo="none">!</literal></quote>, it
7102 <emphasis>negates</emphasis> the class, making it match any
7103 single character not in the class.</para>
7105 <para id="x_55d">A <quote><literal moreinfo="none">{</literal></quote> begins a group of
7106 subpatterns, where the whole group matches if any subpattern
7107 in the group matches. The <quote><literal moreinfo="none">,</literal></quote>
7108 character separates subpatterns, and
7109 <quote><literal moreinfo="none">}</literal></quote> ends the group.</para>
7111 <!-- BEGIN filenames.glob.group -->
7112 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:*.{in,py}'</userinput>
7113 ? MANIFEST.in
7114 ? setup.py
7115 </screen>
7116 <!-- END filenames.glob.group -->
7119 <sect3>
7120 <title>Watch out!</title>
7122 <para id="x_55e">Don't forget that if you want to match a pattern in any
7123 directory, you should not be using the
7124 <quote><literal moreinfo="none">*</literal></quote> match-any token, as this
7125 will only match within one directory. Instead, use the
7126 <quote><literal moreinfo="none">**</literal></quote> token. This small
7127 example illustrates the difference between the two.</para>
7129 <!-- BEGIN filenames.glob.star-starstar -->
7130 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:*.py'</userinput>
7131 ? setup.py
7132 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status 'glob:**.py'</userinput>
7133 A examples/simple.py
7134 A src/main.py
7135 ? examples/performant.py
7136 ? setup.py
7137 ? src/watcher/watcher.py
7138 </screen>
7139 <!-- END filenames.glob.star-starstar -->
7141 </sect3>
7142 </sect2>
7144 <sect2>
7145 <title>Regular expression matching with <literal moreinfo="none">re</literal>
7146 patterns</title>
7148 <para id="x_55f">Mercurial accepts the same regular expression syntax as
7149 the Python programming language (it uses Python's regexp
7150 engine internally). This is based on the Perl language's
7151 regexp syntax, which is the most popular dialect in use (it's
7152 also used in Java, for example).</para>
7154 <para id="x_560">I won't discuss Mercurial's regexp dialect in any detail
7155 here, as regexps are not often used. Perl-style regexps are
7156 in any case already exhaustively documented on a multitude of
7157 web sites, and in many books. Instead, I will focus here on a
7158 few things you should know if you find yourself needing to use
7159 regexps with Mercurial.</para>
7161 <para id="x_561">A regexp is matched against an entire file name, relative
7162 to the root of the repository. In other words, even if you're
7163 already in subbdirectory <filename class="directory" moreinfo="none">foo</filename>, if you want to match files
7164 under this directory, your pattern must start with
7165 <quote><literal moreinfo="none">foo/</literal></quote>.</para>
7167 <para id="x_562">One thing to note, if you're familiar with Perl-style
7168 regexps, is that Mercurial's are <emphasis>rooted</emphasis>.
7169 That is, a regexp starts matching against the beginning of a
7170 string; it doesn't look for a match anywhere within the
7171 string. To match anywhere in a string, start your pattern
7172 with <quote><literal moreinfo="none">.*</literal></quote>.</para>
7173 </sect2>
7174 </sect1>
7176 <sect1>
7177 <title>Filtering files</title>
7179 <para id="x_563">Not only does Mercurial give you a variety of ways to
7180 specify files; it lets you further winnow those files using
7181 <emphasis>filters</emphasis>. Commands that work with file
7182 names accept two filtering options.</para>
7183 <itemizedlist>
7184 <listitem><para id="x_564"><option role="hg-opt-global">-I</option>, or
7185 <option role="hg-opt-global">--include</option>, lets you
7186 specify a pattern that file names must match in order to be
7187 processed.</para>
7188 </listitem>
7189 <listitem><para id="x_565"><option role="hg-opt-global">-X</option>, or
7190 <option role="hg-opt-global">--exclude</option>, gives you a
7191 way to <emphasis>avoid</emphasis> processing files, if they
7192 match this pattern.</para>
7193 </listitem></itemizedlist>
7194 <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,
7195 and intermix them as you please. Mercurial interprets the
7196 patterns you provide using glob syntax by default (but you can
7197 use regexps if you need to).</para>
7199 <para id="x_567">You can read a <option role="hg-opt-global">-I</option>
7200 filter as <quote>process only the files that match this
7201 filter</quote>.</para>
7203 <!-- BEGIN filenames.filter.include -->
7204 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status -I '*.in'</userinput>
7205 ? MANIFEST.in
7206 </screen>
7207 <!-- END filenames.filter.include -->
7210 <para id="x_568">The <option role="hg-opt-global">-X</option> filter is best
7211 read as <quote>process only the files that don't match this
7212 pattern</quote>.</para>
7214 <!-- BEGIN filenames.filter.exclude -->
7215 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status -X '**.py' src</userinput>
7216 ? src/watcher/_watcher.c
7217 ? src/xyzzy.txt
7218 </screen>
7219 <!-- END filenames.filter.exclude -->
7221 </sect1>
7223 <sect1>
7224 <title>Permanently ignoring unwanted files and directories</title>
7226 <para id="x_569">When you create a new repository, the chances are
7227 that over time it will grow to contain files that ought to
7228 <emphasis>not</emphasis> be managed by Mercurial, but which you
7229 don't want to see listed every time you run <command moreinfo="none">hg
7230 status</command>. For instance, <quote>build products</quote>
7231 are files that are created as part of a build but which should
7232 not be managed by a revision control system. The most common
7233 build products are output files produced by software tools such
7234 as compilers. As another example, many text editors litter a
7235 directory with lock files, temporary working files, and backup
7236 files, which it also makes no sense to manage.</para>
7238 <para id="x_6b4">To have Mercurial permanently ignore such files, create a
7239 file named <filename moreinfo="none">.hgignore</filename> in the root of your
7240 repository. You <emphasis>should</emphasis> <command moreinfo="none">hg
7241 add</command> this file so that it gets tracked with the rest of
7242 your repository contents, since your collaborators will probably
7243 find it useful too.</para>
7245 <para id="x_6b5">By default, the <filename moreinfo="none">.hgignore</filename> file should
7246 contain a list of regular expressions, one per line. Empty
7247 lines are skipped. Most people prefer to describe the files they
7248 want to ignore using the <quote>glob</quote> syntax that we
7249 described above, so a typical <filename moreinfo="none">.hgignore</filename>
7250 file will start with this directive:</para>
7252 <programlisting format="linespecific">syntax: glob</programlisting>
7254 <para id="x_6b6">This tells Mercurial to interpret the lines that follow as
7255 glob patterns, not regular expressions.</para>
7257 <para id="x_6b7">Here is a typical-looking <filename moreinfo="none">.hgignore</filename>
7258 file.</para>
7260 <programlisting format="linespecific">syntax: glob
7261 # This line is a comment, and will be skipped.
7262 # Empty lines are skipped too.
7264 # Backup files left behind by the Emacs editor.
7265 *~
7267 # Lock files used by the Emacs editor.
7268 # Notice that the "#" character is quoted with a backslash.
7269 # This prevents it from being interpreted as starting a comment.
7270 .\#*
7272 # Temporary files used by the vim editor.
7273 .*.swp
7275 # A hidden file created by the Mac OS X Finder.
7276 .DS_Store
7277 </programlisting>
7278 </sect1>
7280 <sect1 id="sec:names:case">
7281 <title>Case sensitivity</title>
7283 <para id="x_56a">If you're working in a mixed development environment that
7284 contains both Linux (or other Unix) systems and Macs or Windows
7285 systems, you should keep in the back of your mind the knowledge
7286 that they treat the case (<quote>N</quote> versus
7287 <quote>n</quote>) of file names in incompatible ways. This is
7288 not very likely to affect you, and it's easy to deal with if it
7289 does, but it could surprise you if you don't know about
7290 it.</para>
7292 <para id="x_56b">Operating systems and filesystems differ in the way they
7293 handle the <emphasis>case</emphasis> of characters in file and
7294 directory names. There are three common ways to handle case in
7295 names.</para>
7296 <itemizedlist>
7297 <listitem><para id="x_56c">Completely case insensitive. Uppercase and
7298 lowercase versions of a letter are treated as identical,
7299 both when creating a file and during subsequent accesses.
7300 This is common on older DOS-based systems.</para>
7301 </listitem>
7302 <listitem><para id="x_56d">Case preserving, but insensitive. When a file
7303 or directory is created, the case of its name is stored, and
7304 can be retrieved and displayed by the operating system.
7305 When an existing file is being looked up, its case is
7306 ignored. This is the standard arrangement on Windows and
7307 MacOS. The names <filename moreinfo="none">foo</filename> and
7308 <filename moreinfo="none">FoO</filename> identify the same file. This
7309 treatment of uppercase and lowercase letters as
7310 interchangeable is also referred to as <emphasis>case
7311 folding</emphasis>.</para>
7312 </listitem>
7313 <listitem><para id="x_56e">Case sensitive. The case of a name
7314 is significant at all times. The names
7315 <filename moreinfo="none">foo</filename> and <filename moreinfo="none">FoO</filename>
7316 identify different files. This is the way Linux and Unix
7317 systems normally work.</para>
7318 </listitem></itemizedlist>
7320 <para id="x_56f">On Unix-like systems, it is possible to have any or all of
7321 the above ways of handling case in action at once. For example,
7322 if you use a USB thumb drive formatted with a FAT32 filesystem
7323 on a Linux system, Linux will handle names on that filesystem in
7324 a case preserving, but insensitive, way.</para>
7326 <sect2>
7327 <title>Safe, portable repository storage</title>
7329 <para id="x_570">Mercurial's repository storage mechanism is <emphasis>case
7330 safe</emphasis>. It translates file names so that they can
7331 be safely stored on both case sensitive and case insensitive
7332 filesystems. This means that you can use normal file copying
7333 tools to transfer a Mercurial repository onto, for example, a
7334 USB thumb drive, and safely move that drive and repository
7335 back and forth between a Mac, a PC running Windows, and a
7336 Linux box.</para>
7338 </sect2>
7339 <sect2>
7340 <title>Detecting case conflicts</title>
7342 <para id="x_571">When operating in the working directory, Mercurial honours
7343 the naming policy of the filesystem where the working
7344 directory is located. If the filesystem is case preserving,
7345 but insensitive, Mercurial will treat names that differ only
7346 in case as the same.</para>
7348 <para id="x_572">An important aspect of this approach is that it is
7349 possible to commit a changeset on a case sensitive (typically
7350 Linux or Unix) filesystem that will cause trouble for users on
7351 case insensitive (usually Windows and MacOS) users. If a
7352 Linux user commits changes to two files, one named
7353 <filename moreinfo="none">myfile.c</filename> and the other named
7354 <filename moreinfo="none">MyFile.C</filename>, they will be stored correctly
7355 in the repository. And in the working directories of other
7356 Linux users, they will be correctly represented as separate
7357 files.</para>
7359 <para id="x_573">If a Windows or Mac user pulls this change, they will not
7360 initially have a problem, because Mercurial's repository
7361 storage mechanism is case safe. However, once they try to
7362 <command role="hg-cmd" moreinfo="none">hg update</command> the working
7363 directory to that changeset, or <command role="hg-cmd" moreinfo="none">hg
7364 merge</command> with that changeset, Mercurial will spot the
7365 conflict between the two file names that the filesystem would
7366 treat as the same, and forbid the update or merge from
7367 occurring.</para>
7368 </sect2>
7370 <sect2>
7371 <title>Fixing a case conflict</title>
7373 <para id="x_574">If you are using Windows or a Mac in a mixed environment
7374 where some of your collaborators are using Linux or Unix, and
7375 Mercurial reports a case folding conflict when you try to
7376 <command role="hg-cmd" moreinfo="none">hg update</command> or <command role="hg-cmd" moreinfo="none">hg merge</command>, the procedure to fix the
7377 problem is simple.</para>
7379 <para id="x_575">Just find a nearby Linux or Unix box, clone the problem
7380 repository onto it, and use Mercurial's <command role="hg-cmd" moreinfo="none">hg rename</command> command to change the
7381 names of any offending files or directories so that they will
7382 no longer cause case folding conflicts. Commit this change,
7383 <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
7384 MacOS system, and <command role="hg-cmd" moreinfo="none">hg update</command>
7385 to the revision with the non-conflicting names.</para>
7387 <para id="x_576">The changeset with case-conflicting names will remain in
7388 your project's history, and you still won't be able to
7389 <command role="hg-cmd" moreinfo="none">hg update</command> your working
7390 directory to that changeset on a Windows or MacOS system, but
7391 you can continue development unimpeded.</para>
7392 </sect2>
7393 </sect1>
7394 </chapter>
7396 <!--
7397 local variables:
7398 sgml-parent-document: ("00book.xml" "book" "chapter")
7399 end:
7400 -->
7402 <!-- BEGIN ch08 -->
7403 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
7405 <chapter id="chap:branch">
7406 <?dbhtml filename="managing-releases-and-branchy-development.html"?>
7407 <title>Managing releases and branchy development</title>
7409 <para id="x_369">Mercurial provides several mechanisms for you to manage a
7410 project that is making progress on multiple fronts at once. To
7411 understand these mechanisms, let's first take a brief look at a
7412 fairly normal software project structure.</para>
7414 <para id="x_36a">Many software projects issue periodic <quote>major</quote>
7415 releases that contain substantial new features. In parallel, they
7416 may issue <quote>minor</quote> releases. These are usually
7417 identical to the major releases off which they're based, but with
7418 a few bugs fixed.</para>
7420 <para id="x_36b">In this chapter, we'll start by talking about how to keep
7421 records of project milestones such as releases. We'll then
7422 continue on to talk about the flow of work between different
7423 phases of a project, and how Mercurial can help you to isolate and
7424 manage this work.</para>
7426 <sect1>
7427 <title>Giving a persistent name to a revision</title>
7429 <para id="x_36c">Once you decide that you'd like to call a particular
7430 revision a <quote>release</quote>, it's a good idea to record
7431 the identity of that revision. This will let you reproduce that
7432 release at a later date, for whatever purpose you might need at
7433 the time (reproducing a bug, porting to a new platform, etc).
7434 <!-- BEGIN tag.init -->
7435 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init mytag</userinput>
7436 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd mytag</userinput>
7437 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo hello > myfile</userinput>
7438 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'Initial commit'</userinput>
7439 adding myfile
7440 </screen>
7441 <!-- END tag.init -->
7442 </para>
7444 <para id="x_36d">Mercurial lets you give a permanent name to any revision
7445 using the <command role="hg-cmd" moreinfo="none">hg tag</command> command. Not
7446 surprisingly, these names are called <quote>tags</quote>.</para>
7448 <!-- BEGIN tag.tag -->
7449 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag v1.0</userinput>
7450 </screen>
7451 <!-- END tag.tag -->
7454 <para id="x_36e">A tag is nothing more than a <quote>symbolic name</quote>
7455 for a revision. Tags exist purely for your convenience, so that
7456 you have a handy permanent way to refer to a revision; Mercurial
7457 doesn't interpret the tag names you use in any way. Neither
7458 does Mercurial place any restrictions on the name of a tag,
7459 beyond a few that are necessary to ensure that a tag can be
7460 parsed unambiguously. A tag name cannot contain any of the
7461 following characters:</para>
7462 <itemizedlist>
7463 <listitem><para id="x_36f">Colon (ASCII 58,
7464 <quote><literal moreinfo="none">:</literal></quote>)</para>
7465 </listitem>
7466 <listitem><para id="x_370">Carriage return (ASCII 13,
7467 <quote><literal moreinfo="none">\r</literal></quote>)</para>
7468 </listitem>
7469 <listitem><para id="x_371">Newline (ASCII 10,
7470 <quote><literal moreinfo="none">\n</literal></quote>)</para>
7471 </listitem></itemizedlist>
7473 <para id="x_372">You can use the <command role="hg-cmd" moreinfo="none">hg tags</command>
7474 command to display the tags present in your repository. In the
7475 output, each tagged revision is identified first by its name,
7476 then by revision number, and finally by the unique hash of the
7477 revision.</para>
7479 <!-- BEGIN tag.tags -->
7480 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tags</userinput>
7481 tip 1:f283c2669b38
7482 v1.0 0:0c957785065f
7483 </screen>
7484 <!-- END tag.tags -->
7487 <para id="x_373">Notice that <literal moreinfo="none">tip</literal> is listed in the output
7488 of <command role="hg-cmd" moreinfo="none">hg tags</command>. The
7489 <literal moreinfo="none">tip</literal> tag is a special <quote>floating</quote>
7490 tag, which always identifies the newest revision in the
7491 repository.</para>
7493 <para id="x_374">In the output of the <command role="hg-cmd" moreinfo="none">hg
7494 tags</command> command, tags are listed in reverse order, by
7495 revision number. This usually means that recent tags are listed
7496 before older tags. It also means that <literal moreinfo="none">tip</literal> is
7497 always going to be the first tag listed in the output of
7498 <command role="hg-cmd" moreinfo="none">hg tags</command>.</para>
7500 <para id="x_375">When you run <command role="hg-cmd" moreinfo="none">hg log</command>, if it
7501 displays a revision that has tags associated with it, it will
7502 print those tags.</para>
7504 <!-- BEGIN tag.log -->
7505 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log</userinput>
7506 changeset: 1:f283c2669b38
7507 tag: tip
7508 user: Bryan O'Sullivan <bos@serpentine.com>
7509 date: Sun Aug 16 14:05:16 2009 +0000
7510 summary: Added tag v1.0 for changeset 0c957785065f
7512 changeset: 0:0c957785065f
7513 tag: v1.0
7514 user: Bryan O'Sullivan <bos@serpentine.com>
7515 date: Sun Aug 16 14:05:15 2009 +0000
7516 summary: Initial commit
7518 </screen>
7519 <!-- END tag.log -->
7522 <para id="x_376">Any time you need to provide a revision ID to a Mercurial
7523 command, the command will accept a tag name in its place.
7524 Internally, Mercurial will translate your tag name into the
7525 corresponding revision ID, then use that.</para>
7527 <!-- BEGIN tag.log.v1.0 -->
7528 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo goodbye > myfile2</userinput>
7529 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'Second commit'</userinput>
7530 adding myfile2
7531 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r v1.0</userinput>
7532 changeset: 0:0c957785065f
7533 tag: v1.0
7534 user: Bryan O'Sullivan <bos@serpentine.com>
7535 date: Sun Aug 16 14:05:15 2009 +0000
7536 summary: Initial commit
7538 </screen>
7539 <!-- END tag.log.v1.0 -->
7542 <para id="x_377">There's no limit on the number of tags you can have in a
7543 repository, or on the number of tags that a single revision can
7544 have. As a practical matter, it's not a great idea to have
7545 <quote>too many</quote> (a number which will vary from project
7546 to project), simply because tags are supposed to help you to
7547 find revisions. If you have lots of tags, the ease of using
7548 them to identify revisions diminishes rapidly.</para>
7550 <para id="x_378">For example, if your project has milestones as frequent as
7551 every few days, it's perfectly reasonable to tag each one of
7552 those. But if you have a continuous build system that makes
7553 sure every revision can be built cleanly, you'd be introducing a
7554 lot of noise if you were to tag every clean build. Instead, you
7555 could tag failed builds (on the assumption that they're rare!),
7556 or simply not use tags to track buildability.</para>
7558 <para id="x_379">If you want to remove a tag that you no longer want, use
7559 <command role="hg-cmd" moreinfo="none">hg tag --remove</command>.</para>
7561 <!-- BEGIN tag.remove -->
7562 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag --remove v1.0</userinput>
7563 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tags</userinput>
7564 tip 3:0f446f1d1f7f
7565 </screen>
7566 <!-- END tag.remove -->
7569 <para id="x_37a">You can also modify a tag at any time, so that it identifies
7570 a different revision, by simply issuing a new <command role="hg-cmd" moreinfo="none">hg tag</command> command. You'll have to use the
7571 <option role="hg-opt-tag">-f</option> option to tell Mercurial
7572 that you <emphasis>really</emphasis> want to update the
7573 tag.</para>
7575 <!-- BEGIN tag.replace -->
7576 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag -r 1 v1.1</userinput>
7577 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tags</userinput>
7578 tip 4:12fc7bf92915
7579 v1.1 1:f283c2669b38
7580 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag -r 2 v1.1</userinput>
7581 abort: tag 'v1.1' already exists (use -f to force)
7582 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag -f -r 2 v1.1</userinput>
7583 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tags</userinput>
7584 tip 5:17e25cf010af
7585 v1.1 2:737882b3cc76
7586 </screen>
7587 <!-- END tag.replace -->
7590 <para id="x_37b">There will still be a permanent record of the previous
7591 identity of the tag, but Mercurial will no longer use it.
7592 There's thus no penalty to tagging the wrong revision; all you
7593 have to do is turn around and tag the correct revision once you
7594 discover your error.</para>
7596 <para id="x_37c">Mercurial stores tags in a normal revision-controlled file
7597 in your repository. If you've created any tags, you'll find
7598 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
7599 this file, then automatically commits the change to it. This
7600 means that every time you run <command role="hg-cmd" moreinfo="none">hg
7601 tag</command>, you'll see a corresponding changeset in the
7602 output of <command role="hg-cmd" moreinfo="none">hg log</command>.</para>
7604 <!-- BEGIN tag.tip -->
7605 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
7606 changeset: 5:17e25cf010af
7607 tag: tip
7608 user: Bryan O'Sullivan <bos@serpentine.com>
7609 date: Sun Aug 16 14:05:16 2009 +0000
7610 summary: Added tag v1.1 for changeset 737882b3cc76
7612 </screen>
7613 <!-- END tag.tip -->
7616 <sect2>
7617 <title>Handling tag conflicts during a merge</title>
7619 <para id="x_37d">You won't often need to care about the <filename role="special" moreinfo="none">.hgtags</filename> file, but it sometimes
7620 makes its presence known during a merge. The format of the
7621 file is simple: it consists of a series of lines. Each line
7622 starts with a changeset hash, followed by a space, followed by
7623 the name of a tag.</para>
7625 <para id="x_37e">If you're resolving a conflict in the <filename role="special" moreinfo="none">.hgtags</filename> file during a merge,
7626 there's one twist to modifying the <filename role="special" moreinfo="none">.hgtags</filename> file: when Mercurial is
7627 parsing the tags in a repository, it
7628 <emphasis>never</emphasis> reads the working copy of the
7629 <filename role="special" moreinfo="none">.hgtags</filename> file. Instead, it
7630 reads the <emphasis>most recently committed</emphasis>
7631 revision of the file.</para>
7633 <para id="x_37f">An unfortunate consequence of this design is that you
7634 can't actually verify that your merged <filename role="special" moreinfo="none">.hgtags</filename> file is correct until
7635 <emphasis>after</emphasis> you've committed a change. So if
7636 you find yourself resolving a conflict on <filename role="special" moreinfo="none">.hgtags</filename> during a merge, be sure to
7637 run <command role="hg-cmd" moreinfo="none">hg tags</command> after you commit.
7638 If it finds an error in the <filename role="special" moreinfo="none">.hgtags</filename> file, it will report the
7639 location of the error, which you can then fix and commit. You
7640 should then run <command role="hg-cmd" moreinfo="none">hg tags</command>
7641 again, just to be sure that your fix is correct.</para>
7642 </sect2>
7644 <sect2>
7645 <title>Tags and cloning</title>
7647 <para id="x_380">You may have noticed that the <command role="hg-cmd" moreinfo="none">hg
7648 clone</command> command has a <option role="hg-opt-clone">-r</option> option that lets you clone
7649 an exact copy of the repository as of a particular changeset.
7650 The new clone will not contain any project history that comes
7651 after the revision you specified. This has an interaction
7652 with tags that can surprise the unwary.</para>
7654 <para id="x_381">Recall that a tag is stored as a revision to
7655 the <filename role="special" moreinfo="none">.hgtags</filename> file. When you
7656 create a tag, the changeset in which its recorded refers to an
7657 older changeset. When you run <command role="hg-cmd" moreinfo="none">hg clone
7658 -r foo</command> to clone a repository as of tag
7659 <literal moreinfo="none">foo</literal>, the new clone <emphasis>will not
7660 contain any revision newer than the one the tag refers to,
7661 including the revision where the tag was created</emphasis>.
7662 The result is that you'll get exactly the right subset of the
7663 project's history in the new repository, but
7664 <emphasis>not</emphasis> the tag you might have
7665 expected.</para>
7666 </sect2>
7668 <sect2>
7669 <title>When permanent tags are too much</title>
7671 <para id="x_382">Since Mercurial's tags are revision controlled and carried
7672 around with a project's history, everyone you work with will
7673 see the tags you create. But giving names to revisions has
7674 uses beyond simply noting that revision
7675 <literal moreinfo="none">4237e45506ee</literal> is really
7676 <literal moreinfo="none">v2.0.2</literal>. If you're trying to track down a
7677 subtle bug, you might want a tag to remind you of something
7678 like <quote>Anne saw the symptoms with this
7679 revision</quote>.</para>
7681 <para id="x_383">For cases like this, what you might want to use are
7682 <emphasis>local</emphasis> tags. You can create a local tag
7683 with the <option role="hg-opt-tag">-l</option> option to the
7684 <command role="hg-cmd" moreinfo="none">hg tag</command> command. This will
7685 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
7686 controlled. Any tags you create using <option role="hg-opt-tag">-l</option> remain strictly local to the
7687 repository you're currently working in.</para>
7688 </sect2>
7689 </sect1>
7691 <sect1>
7692 <title>The flow of changes—big picture vs. little</title>
7694 <para id="x_384">To return to the outline I sketched at the
7695 beginning of the chapter, let's think about a project that has
7696 multiple concurrent pieces of work under development at
7697 once.</para>
7699 <para id="x_385">There might be a push for a new <quote>main</quote> release;
7700 a new minor bugfix release to the last main release; and an
7701 unexpected <quote>hot fix</quote> to an old release that is now
7702 in maintenance mode.</para>
7704 <para id="x_386">The usual way people refer to these different concurrent
7705 directions of development is as <quote>branches</quote>.
7706 However, we've already seen numerous times that Mercurial treats
7707 <emphasis>all of history</emphasis> as a series of branches and
7708 merges. Really, what we have here is two ideas that are
7709 peripherally related, but which happen to share a name.</para>
7710 <itemizedlist>
7711 <listitem><para id="x_387"><quote>Big picture</quote> branches represent
7712 the sweep of a project's evolution; people give them names,
7713 and talk about them in conversation.</para>
7714 </listitem>
7715 <listitem><para id="x_388"><quote>Little picture</quote> branches are
7716 artefacts of the day-to-day activity of developing and
7717 merging changes. They expose the narrative of how the code
7718 was developed.</para>
7719 </listitem></itemizedlist>
7720 </sect1>
7722 <sect1>
7723 <title>Managing big-picture branches in repositories</title>
7725 <para id="x_389">The easiest way to isolate a <quote>big picture</quote>
7726 branch in Mercurial is in a dedicated repository. If you have
7727 an existing shared repository—let's call it
7728 <literal moreinfo="none">myproject</literal>—that reaches a
7729 <quote>1.0</quote> milestone, you can start to prepare for
7730 future maintenance releases on top of version 1.0 by tagging the
7731 revision from which you prepared the 1.0 release.</para>
7733 <!-- BEGIN branch-repo.tag -->
7734 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd myproject</userinput>
7735 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tag v1.0</userinput>
7736 </screen>
7737 <!-- END branch-repo.tag -->
7740 <para id="x_38a">You can then clone a new shared
7741 <literal moreinfo="none">myproject-1.0.1</literal> repository as of that
7742 tag.</para>
7744 <!-- BEGIN branch-repo.clone -->
7745 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
7746 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone myproject myproject-1.0.1</userinput>
7747 updating working directory
7748 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
7749 </screen>
7750 <!-- END branch-repo.clone -->
7753 <para id="x_38b">Afterwards, if someone needs to work on a bug fix that ought
7754 to go into an upcoming 1.0.1 minor release, they clone the
7755 <literal moreinfo="none">myproject-1.0.1</literal> repository, make their
7756 changes, and push them back.</para>
7758 <!-- BEGIN branch-repo.bugfix -->
7759 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone myproject-1.0.1 my-1.0.1-bugfix</userinput>
7760 updating working directory
7761 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
7762 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-1.0.1-bugfix</userinput>
7763 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'I fixed a bug using only echo!' >> myfile</userinput>
7764 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Important fix for 1.0.1'</userinput>
7765 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push</userinput>
7766 pushing to /tmp/branch-repo3rVLLS/myproject-1.0.1
7767 searching for changes
7768 adding changesets
7769 adding manifests
7770 adding file changes
7771 added 1 changesets with 1 changes to 1 files
7772 </screen>
7773 <!-- END branch-repo.bugfix -->
7776 <para id="x_38c">Meanwhile, development for
7777 the next major release can continue, isolated and unabated, in
7778 the <literal moreinfo="none">myproject</literal> repository.</para>
7780 <!-- BEGIN branch-repo.new -->
7781 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
7782 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone myproject my-feature</userinput>
7783 updating working directory
7784 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
7785 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd my-feature</userinput>
7786 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'This sure is an exciting new feature!' > mynewfile</userinput>
7787 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'New feature'</userinput>
7788 adding mynewfile
7789 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push</userinput>
7790 pushing to /tmp/branch-repo3rVLLS/myproject
7791 searching for changes
7792 adding changesets
7793 adding manifests
7794 adding file changes
7795 added 1 changesets with 1 changes to 1 files
7796 </screen>
7797 <!-- END branch-repo.new -->
7799 </sect1>
7801 <sect1>
7802 <title>Don't repeat yourself: merging across branches</title>
7804 <para id="x_38d">In many cases, if you have a bug to fix on a maintenance
7805 branch, the chances are good that the bug exists on your
7806 project's main branch (and possibly other maintenance branches,
7807 too). It's a rare developer who wants to fix the same bug
7808 multiple times, so let's look at a few ways that Mercurial can
7809 help you to manage these bugfixes without duplicating your
7810 work.</para>
7812 <para id="x_38e">In the simplest instance, all you need to do is pull changes
7813 from your maintenance branch into your local clone of the target
7814 branch.</para>
7816 <!-- BEGIN branch-repo.pull -->
7817 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
7818 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone myproject myproject-merge</userinput>
7819 updating working directory
7820 3 files updated, 0 files merged, 0 files removed, 0 files unresolved
7821 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd myproject-merge</userinput>
7822 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../myproject-1.0.1</userinput>
7823 pulling from ../myproject-1.0.1
7824 searching for changes
7825 adding changesets
7826 adding manifests
7827 adding file changes
7828 added 1 changesets with 1 changes to 1 files (+1 heads)
7829 (run 'hg heads' to see heads, 'hg merge' to merge)
7830 </screen>
7831 <!-- END branch-repo.pull -->
7834 <para id="x_38f">You'll then need to merge the heads of the two branches, and
7835 push back to the main branch.</para>
7837 <!-- BEGIN branch-repo.merge -->
7838 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
7839 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
7840 (branch merge, don't forget to commit)
7841 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Merge bugfix from 1.0.1 branch'</userinput>
7842 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg push</userinput>
7843 pushing to /tmp/branch-repo3rVLLS/myproject
7844 searching for changes
7845 adding changesets
7846 adding manifests
7847 adding file changes
7848 added 2 changesets with 1 changes to 1 files
7849 </screen>
7850 <!-- END branch-repo.merge -->
7852 </sect1>
7854 <sect1>
7855 <title>Naming branches within one repository</title>
7857 <para id="x_390">In most instances, isolating branches in repositories is the
7858 right approach. Its simplicity makes it easy to understand; and
7859 so it's hard to make mistakes. There's a one-to-one
7860 relationship between branches you're working in and directories
7861 on your system. This lets you use normal (non-Mercurial-aware)
7862 tools to work on files within a branch/repository.</para>
7864 <para id="x_391">If you're more in the <quote>power user</quote> category
7865 (<emphasis>and</emphasis> your collaborators are too), there is
7866 an alternative way of handling branches that you can consider.
7867 I've already mentioned the human-level distinction between
7868 <quote>small picture</quote> and <quote>big picture</quote>
7869 branches. While Mercurial works with multiple <quote>small
7870 picture</quote> branches in a repository all the time (for
7871 example after you pull changes in, but before you merge them),
7872 it can <emphasis>also</emphasis> work with multiple <quote>big
7873 picture</quote> branches.</para>
7875 <para id="x_392">The key to working this way is that Mercurial lets you
7876 assign a persistent <emphasis>name</emphasis> to a branch.
7877 There always exists a branch named <literal moreinfo="none">default</literal>.
7878 Even before you start naming branches yourself, you can find
7879 traces of the <literal moreinfo="none">default</literal> branch if you look for
7880 them.</para>
7882 <para id="x_393">As an example, when you run the <command role="hg-cmd" moreinfo="none">hg
7883 commit</command> command, and it pops up your editor so that
7884 you can enter a commit message, look for a line that contains
7885 the text <quote><literal moreinfo="none">HG: branch default</literal></quote> at
7886 the bottom. This is telling you that your commit will occur on
7887 the branch named <literal moreinfo="none">default</literal>.</para>
7889 <para id="x_394">To start working with named branches, use the <command role="hg-cmd" moreinfo="none">hg branches</command> command. This command
7890 lists the named branches already present in your repository,
7891 telling you which changeset is the tip of each.</para>
7893 <!-- BEGIN branch-named.branches -->
7894 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
7895 changeset: 0:90897f9e54e3
7896 tag: tip
7897 user: Bryan O'Sullivan <bos@serpentine.com>
7898 date: Sun Aug 16 14:04:42 2009 +0000
7899 summary: Initial commit
7901 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branches</userinput>
7902 default 0:90897f9e54e3
7903 </screen>
7904 <!-- END branch-named.branches -->
7907 <para id="x_395">Since you haven't created any named branches yet, the only
7908 one that exists is <literal moreinfo="none">default</literal>.</para>
7910 <para id="x_396">To find out what the <quote>current</quote> branch is, run
7911 the <command role="hg-cmd" moreinfo="none">hg branch</command> command, giving
7912 it no arguments. This tells you what branch the parent of the
7913 current changeset is on.</para>
7915 <!-- BEGIN branch-named.branch -->
7916 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch</userinput>
7917 default
7918 </screen>
7919 <!-- END branch-named.branch -->
7922 <para id="x_397">To create a new branch, run the <command role="hg-cmd" moreinfo="none">hg
7923 branch</command> command again. This time, give it one
7924 argument: the name of the branch you want to create.</para>
7926 <!-- BEGIN branch-named.create -->
7927 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch foo</userinput>
7928 marked working directory as branch foo
7929 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch</userinput>
7930 foo
7931 </screen>
7932 <!-- END branch-named.create -->
7935 <para id="x_398">After you've created a branch, you might wonder what effect
7936 the <command role="hg-cmd" moreinfo="none">hg branch</command> command has had.
7937 What do the <command role="hg-cmd" moreinfo="none">hg status</command> and
7938 <command role="hg-cmd" moreinfo="none">hg tip</command> commands report?</para>
7940 <!-- BEGIN branch-named.status -->
7941 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
7942 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
7943 changeset: 0:90897f9e54e3
7944 tag: tip
7945 user: Bryan O'Sullivan <bos@serpentine.com>
7946 date: Sun Aug 16 14:04:42 2009 +0000
7947 summary: Initial commit
7949 </screen>
7950 <!-- END branch-named.status -->
7953 <para id="x_399">Nothing has changed in the
7954 working directory, and there's been no new history created. As
7955 this suggests, running the <command role="hg-cmd" moreinfo="none">hg
7956 branch</command> command has no permanent effect; it only
7957 tells Mercurial what branch name to use the
7958 <emphasis>next</emphasis> time you commit a changeset.</para>
7960 <para id="x_39a">When you commit a change, Mercurial records the name of the
7961 branch on which you committed. Once you've switched from the
7962 <literal moreinfo="none">default</literal> branch to another and committed,
7963 you'll see the name of the new branch show up in the output of
7964 <command role="hg-cmd" moreinfo="none">hg log</command>, <command role="hg-cmd" moreinfo="none">hg tip</command>, and other commands that
7965 display the same kind of output.</para>
7967 <!-- BEGIN branch-named.commit -->
7968 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'hello again' >> myfile</userinput>
7969 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Second commit'</userinput>
7970 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
7971 changeset: 1:5656f8ffdd49
7972 branch: foo
7973 tag: tip
7974 user: Bryan O'Sullivan <bos@serpentine.com>
7975 date: Sun Aug 16 14:04:42 2009 +0000
7976 summary: Second commit
7978 </screen>
7979 <!-- END branch-named.commit -->
7982 <para id="x_39b">The <command role="hg-cmd" moreinfo="none">hg log</command>-like commands
7983 will print the branch name of every changeset that's not on the
7984 <literal moreinfo="none">default</literal> branch. As a result, if you never
7985 use named branches, you'll never see this information.</para>
7987 <para id="x_39c">Once you've named a branch and committed a change with that
7988 name, every subsequent commit that descends from that change
7989 will inherit the same branch name. You can change the name of a
7990 branch at any time, using the <command role="hg-cmd" moreinfo="none">hg
7991 branch</command> command.</para>
7993 <!-- BEGIN branch-named.rebranch -->
7994 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch</userinput>
7995 foo
7996 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch bar</userinput>
7997 marked working directory as branch bar
7998 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo new file > newfile</userinput>
7999 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'Third commit'</userinput>
8000 adding newfile
8001 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
8002 changeset: 2:c59d680fc2ec
8003 branch: bar
8004 tag: tip
8005 user: Bryan O'Sullivan <bos@serpentine.com>
8006 date: Sun Aug 16 14:04:42 2009 +0000
8007 summary: Third commit
8009 </screen>
8010 <!-- END branch-named.rebranch -->
8013 <para id="x_39d">In practice, this is something you won't do very often, as
8014 branch names tend to have fairly long lifetimes. (This isn't a
8015 rule, just an observation.)</para>
8016 </sect1>
8018 <sect1>
8019 <title>Dealing with multiple named branches in a
8020 repository</title>
8022 <para id="x_39e">If you have more than one named branch in a repository,
8023 Mercurial will remember the branch that your working directory
8024 is on when you start a command like <command role="hg-cmd" moreinfo="none">hg
8025 update</command> or <command role="hg-cmd" moreinfo="none">hg pull
8026 -u</command>. It will update the working directory to the tip
8027 of this branch, no matter what the <quote>repo-wide</quote> tip
8028 is. To update to a revision that's on a different named branch,
8029 you may need to use the <option role="hg-opt-update">-C</option>
8030 option to <command role="hg-cmd" moreinfo="none">hg update</command>.</para>
8032 <para id="x_39f">This behavior is a little subtle, so let's see it in
8033 action. First, let's remind ourselves what branch we're
8034 currently on, and what branches are in our repository.</para>
8036 <!-- BEGIN branch-named.parents -->
8037 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
8038 changeset: 2:c59d680fc2ec
8039 branch: bar
8040 tag: tip
8041 user: Bryan O'Sullivan <bos@serpentine.com>
8042 date: Sun Aug 16 14:04:42 2009 +0000
8043 summary: Third commit
8045 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branches</userinput>
8046 bar 2:c59d680fc2ec
8047 foo 1:5656f8ffdd49 (inactive)
8048 default 0:90897f9e54e3 (inactive)
8049 </screen>
8050 <!-- END branch-named.parents -->
8053 <para id="x_3a0">We're on the <literal moreinfo="none">bar</literal> branch, but there also
8054 exists an older <command role="hg-cmd" moreinfo="none">hg foo</command>
8055 branch.</para>
8057 <para id="x_3a1">We can <command role="hg-cmd" moreinfo="none">hg update</command> back and
8058 forth between the tips of the <literal moreinfo="none">foo</literal> and
8059 <literal moreinfo="none">bar</literal> branches without needing to use the
8060 <option role="hg-opt-update">-C</option> option, because this
8061 only involves going backwards and forwards linearly through our
8062 change history.</para>
8064 <!-- BEGIN branch-named.update-switchy -->
8065 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update foo</userinput>
8066 0 files updated, 0 files merged, 1 files removed, 0 files unresolved
8067 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
8068 changeset: 1:5656f8ffdd49
8069 branch: foo
8070 user: Bryan O'Sullivan <bos@serpentine.com>
8071 date: Sun Aug 16 14:04:42 2009 +0000
8072 summary: Second commit
8074 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update bar</userinput>
8075 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
8076 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
8077 changeset: 2:c59d680fc2ec
8078 branch: bar
8079 tag: tip
8080 user: Bryan O'Sullivan <bos@serpentine.com>
8081 date: Sun Aug 16 14:04:42 2009 +0000
8082 summary: Third commit
8084 </screen>
8085 <!-- END branch-named.update-switchy -->
8088 <para id="x_3a2">If we go back to the <literal moreinfo="none">foo</literal> branch and then
8089 run <command role="hg-cmd" moreinfo="none">hg update</command>, it will keep us
8090 on <literal moreinfo="none">foo</literal>, not move us to the tip of
8091 <literal moreinfo="none">bar</literal>.</para>
8093 <!-- BEGIN branch-named.update-nothing -->
8094 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update foo</userinput>
8095 0 files updated, 0 files merged, 1 files removed, 0 files unresolved
8096 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg update</userinput>
8097 0 files updated, 0 files merged, 0 files removed, 0 files unresolved
8098 </screen>
8099 <!-- END branch-named.update-nothing -->
8102 <para id="x_3a3">Committing a new change on the <literal moreinfo="none">foo</literal> branch
8103 introduces a new head.</para>
8105 <!-- BEGIN branch-named.foo-commit -->
8106 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo something > somefile</userinput>
8107 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'New file'</userinput>
8108 adding somefile
8109 created new head
8110 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg heads</userinput>
8111 changeset: 3:4dd2f7a37288
8112 branch: foo
8113 tag: tip
8114 parent: 1:5656f8ffdd49
8115 user: Bryan O'Sullivan <bos@serpentine.com>
8116 date: Sun Aug 16 14:04:43 2009 +0000
8117 summary: New file
8119 changeset: 2:c59d680fc2ec
8120 branch: bar
8121 user: Bryan O'Sullivan <bos@serpentine.com>
8122 date: Sun Aug 16 14:04:42 2009 +0000
8123 summary: Third commit
8125 </screen>
8126 <!-- END branch-named.foo-commit -->
8128 </sect1>
8130 <sect1>
8131 <title>Branch names and merging</title>
8133 <para id="x_3a4">As you've probably noticed, merges in Mercurial are not
8134 symmetrical. Let's say our repository has two heads, 17 and 23.
8135 If I <command role="hg-cmd" moreinfo="none">hg update</command> to 17 and then
8136 <command role="hg-cmd" moreinfo="none">hg merge</command> with 23, Mercurial
8137 records 17 as the first parent of the merge, and 23 as the
8138 second. Whereas if I <command role="hg-cmd" moreinfo="none">hg update</command>
8139 to 23 and then <command role="hg-cmd" moreinfo="none">hg merge</command> with
8140 17, it records 23 as the first parent, and 17 as the
8141 second.</para>
8143 <para id="x_3a5">This affects Mercurial's choice of branch name when you
8144 merge. After a merge, Mercurial will retain the branch name of
8145 the first parent when you commit the result of the merge. If
8146 your first parent's branch name is <literal moreinfo="none">foo</literal>, and
8147 you merge with <literal moreinfo="none">bar</literal>, the branch name will
8148 still be <literal moreinfo="none">foo</literal> after you merge.</para>
8150 <para id="x_3a6">It's not unusual for a repository to contain multiple heads,
8151 each with the same branch name. Let's say I'm working on the
8152 <literal moreinfo="none">foo</literal> branch, and so are you. We commit
8153 different changes; I pull your changes; I now have two heads,
8154 each claiming to be on the <literal moreinfo="none">foo</literal> branch. The
8155 result of a merge will be a single head on the
8156 <literal moreinfo="none">foo</literal> branch, as you might hope.</para>
8158 <para id="x_3a7">But if I'm working on the <literal moreinfo="none">bar</literal> branch, and
8159 I merge work from the <literal moreinfo="none">foo</literal> branch, the result
8160 will remain on the <literal moreinfo="none">bar</literal> branch.</para>
8162 <!-- BEGIN branch-named.merge -->
8163 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg branch</userinput>
8164 bar
8165 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge foo</userinput>
8166 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
8167 (branch merge, don't forget to commit)
8168 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Merge'</userinput>
8169 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
8170 changeset: 4:9f05d4ef3efe
8171 branch: bar
8172 tag: tip
8173 parent: 2:c59d680fc2ec
8174 parent: 3:4dd2f7a37288
8175 user: Bryan O'Sullivan <bos@serpentine.com>
8176 date: Sun Aug 16 14:04:44 2009 +0000
8177 summary: Merge
8179 </screen>
8180 <!-- END branch-named.merge -->
8183 <para id="x_3a8">To give a more concrete example, if I'm working on the
8184 <literal moreinfo="none">bleeding-edge</literal> branch, and I want to bring in
8185 the latest fixes from the <literal moreinfo="none">stable</literal> branch,
8186 Mercurial will choose the <quote>right</quote>
8187 (<literal moreinfo="none">bleeding-edge</literal>) branch name when I pull and
8188 merge from <literal moreinfo="none">stable</literal>.</para>
8189 </sect1>
8191 <sect1>
8192 <title>Branch naming is generally useful</title>
8194 <para id="x_3a9">You shouldn't think of named branches as applicable only to
8195 situations where you have multiple long-lived branches
8196 cohabiting in a single repository. They're very useful even in
8197 the one-branch-per-repository case.</para>
8199 <para id="x_3aa">In the simplest case, giving a name to each branch gives you
8200 a permanent record of which branch a changeset originated on.
8201 This gives you more context when you're trying to follow the
8202 history of a long-lived branchy project.</para>
8204 <para id="x_3ab">If you're working with shared repositories, you can set up a
8205 <literal role="hook" moreinfo="none">pretxnchangegroup</literal> hook on each
8206 that will block incoming changes that have the
8207 <quote>wrong</quote> branch name. This provides a simple, but
8208 effective, defence against people accidentally pushing changes
8209 from a <quote>bleeding edge</quote> branch to a
8210 <quote>stable</quote> branch. Such a hook might look like this
8211 inside the shared repo's <filename role="special" moreinfo="none">
8212 /.hgrc</filename>.</para>
8213 <programlisting format="linespecific">[hooks]
8214 pretxnchangegroup.branch = hg heads --template '{branches} ' | grep mybranch</programlisting>
8215 </sect1>
8216 </chapter>
8218 <!--
8219 local variables:
8220 sgml-parent-document: ("00book.xml" "book" "chapter")
8221 end:
8222 -->
8224 <!-- BEGIN ch09 -->
8225 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
8227 <chapter id="chap:undo">
8228 <?dbhtml filename="finding-and-fixing-mistakes.html"?>
8229 <title>Finding and fixing mistakes</title>
8231 <para id="x_d2">To err might be human, but to really handle the consequences
8232 well takes a top-notch revision control system. In this chapter,
8233 we'll discuss some of the techniques you can use when you find
8234 that a problem has crept into your project. Mercurial has some
8235 highly capable features that will help you to isolate the sources
8236 of problems, and to handle them appropriately.</para>
8238 <sect1>
8239 <title>Erasing local history</title>
8241 <sect2>
8242 <title>The accidental commit</title>
8244 <para id="x_d3">I have the occasional but persistent problem of typing
8245 rather more quickly than I can think, which sometimes results
8246 in me committing a changeset that is either incomplete or
8247 plain wrong. In my case, the usual kind of incomplete
8248 changeset is one in which I've created a new source file, but
8249 forgotten to <command role="hg-cmd" moreinfo="none">hg add</command> it. A
8250 <quote>plain wrong</quote> changeset is not as common, but no
8251 less annoying.</para>
8253 </sect2>
8254 <sect2 id="sec:undo:rollback">
8255 <title>Rolling back a transaction</title>
8257 <para id="x_d4">In <xref linkend="sec:concepts:txn"/>, I
8258 mentioned that Mercurial treats each modification of a
8259 repository as a <emphasis>transaction</emphasis>. Every time
8260 you commit a changeset or pull changes from another
8261 repository, Mercurial remembers what you did. You can undo,
8262 or <emphasis>roll back</emphasis>, exactly one of these
8263 actions using the <command role="hg-cmd" moreinfo="none">hg rollback</command>
8264 command. (See <xref linkend="sec:undo:rollback-after-push"/>
8265 for an important caveat about the use of this command.)</para>
8267 <para id="x_d5">Here's a mistake that I often find myself making:
8268 committing a change in which I've created a new file, but
8269 forgotten to <command role="hg-cmd" moreinfo="none">hg add</command>
8270 it.</para>
8272 <!-- BEGIN rollback.commit -->
8273 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
8274 M a
8275 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo b > b</userinput>
8276 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Add file b'</userinput>
8277 </screen>
8278 <!-- END rollback.commit -->
8281 <para id="x_d6">Looking at the output of <command role="hg-cmd" moreinfo="none">hg
8282 status</command> after the commit immediately confirms the
8283 error.</para>
8285 <!-- BEGIN rollback.status -->
8286 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
8287 ? b
8288 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
8289 changeset: 1:246e2aada1c5
8290 tag: tip
8291 user: Bryan O'Sullivan <bos@serpentine.com>
8292 date: Sun Aug 16 14:05:14 2009 +0000
8293 summary: Add file b
8295 </screen>
8296 <!-- END rollback.status -->
8299 <para id="x_d7">The commit captured the changes to the file
8300 <filename moreinfo="none">a</filename>, but not the new file
8301 <filename moreinfo="none">b</filename>. If I were to push this changeset to a
8302 repository that I shared with a colleague, the chances are
8303 high that something in <filename moreinfo="none">a</filename> would refer to
8304 <filename moreinfo="none">b</filename>, which would not be present in their
8305 repository when they pulled my changes. I would thus become
8306 the object of some indignation.</para>
8308 <para id="x_d8">However, luck is with me—I've caught my error
8309 before I pushed the changeset. I use the <command role="hg-cmd" moreinfo="none">hg rollback</command> command, and Mercurial
8310 makes that last changeset vanish.</para>
8312 <!-- BEGIN rollback.rollback -->
8313 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rollback</userinput>
8314 rolling back last transaction
8315 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
8316 changeset: 0:c37ce4157509
8317 tag: tip
8318 user: Bryan O'Sullivan <bos@serpentine.com>
8319 date: Sun Aug 16 14:05:14 2009 +0000
8320 summary: First commit
8322 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
8323 M a
8324 ? b
8325 </screen>
8326 <!-- END rollback.rollback -->
8329 <para id="x_d9">Notice that the changeset is no longer present in the
8330 repository's history, and the working directory once again
8331 thinks that the file <filename moreinfo="none">a</filename> is modified. The
8332 commit and rollback have left the working directory exactly as
8333 it was prior to the commit; the changeset has been completely
8334 erased. I can now safely <command role="hg-cmd" moreinfo="none">hg
8335 add</command> the file <filename moreinfo="none">b</filename>, and rerun my
8336 commit.</para>
8338 <!-- BEGIN rollback.add -->
8339 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add b</userinput>
8340 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'Add file b, this time for real'</userinput>
8341 </screen>
8342 <!-- END rollback.add -->
8345 </sect2>
8346 <sect2>
8347 <title>The erroneous pull</title>
8349 <para id="x_da">It's common practice with Mercurial to maintain separate
8350 development branches of a project in different repositories.
8351 Your development team might have one shared repository for
8352 your project's <quote>0.9</quote> release, and another,
8353 containing different changes, for the <quote>1.0</quote>
8354 release.</para>
8356 <para id="x_db">Given this, you can imagine that the consequences could be
8357 messy if you had a local <quote>0.9</quote> repository, and
8358 accidentally pulled changes from the shared <quote>1.0</quote>
8359 repository into it. At worst, you could be paying
8360 insufficient attention, and push those changes into the shared
8361 <quote>0.9</quote> tree, confusing your entire team (but don't
8362 worry, we'll return to this horror scenario later). However,
8363 it's more likely that you'll notice immediately, because
8364 Mercurial will display the URL it's pulling from, or you will
8365 see it pull a suspiciously large number of changes into the
8366 repository.</para>
8368 <para id="x_dc">The <command role="hg-cmd" moreinfo="none">hg rollback</command> command
8369 will work nicely to expunge all of the changesets that you
8370 just pulled. Mercurial groups all changes from one <command role="hg-cmd" moreinfo="none">hg pull</command> into a single transaction,
8371 so one <command role="hg-cmd" moreinfo="none">hg rollback</command> is all you
8372 need to undo this mistake.</para>
8374 </sect2>
8375 <sect2 id="sec:undo:rollback-after-push">
8376 <title>Rolling back is useless once you've pushed</title>
8378 <para id="x_dd">The value of the <command role="hg-cmd" moreinfo="none">hg
8379 rollback</command> command drops to zero once you've pushed
8380 your changes to another repository. Rolling back a change
8381 makes it disappear entirely, but <emphasis>only</emphasis> in
8382 the repository in which you perform the <command role="hg-cmd" moreinfo="none">hg rollback</command>. Because a rollback
8383 eliminates history, there's no way for the disappearance of a
8384 change to propagate between repositories.</para>
8386 <para id="x_de">If you've pushed a change to another
8387 repository—particularly if it's a shared
8388 repository—it has essentially <quote>escaped into the
8389 wild,</quote> and you'll have to recover from your mistake
8390 in a different way. If you push a changeset somewhere, then
8391 roll it back, then pull from the repository you pushed to, the
8392 changeset you thought you'd gotten rid of will simply reappear
8393 in your repository.</para>
8395 <para id="x_df">(If you absolutely know for sure that the change
8396 you want to roll back is the most recent change in the
8397 repository that you pushed to, <emphasis>and</emphasis> you
8398 know that nobody else could have pulled it from that
8399 repository, you can roll back the changeset there, too, but
8400 you really should not expect this to work reliably. Sooner or
8401 later a change really will make it into a repository that you
8402 don't directly control (or have forgotten about), and come
8403 back to bite you.)</para>
8405 </sect2>
8406 <sect2>
8407 <title>You can only roll back once</title>
8409 <para id="x_e0">Mercurial stores exactly one transaction in its
8410 transaction log; that transaction is the most recent one that
8411 occurred in the repository. This means that you can only roll
8412 back one transaction. If you expect to be able to roll back
8413 one transaction, then its predecessor, this is not the
8414 behavior you will get.</para>
8416 <!-- BEGIN rollback.twice -->
8417 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rollback</userinput>
8418 rolling back last transaction
8419 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg rollback</userinput>
8420 no rollback information available
8421 </screen>
8422 <!-- END rollback.twice -->
8425 <para id="x_e1">Once you've rolled back one transaction in a repository,
8426 you can't roll back again in that repository until you perform
8427 another commit or pull.</para>
8429 </sect2>
8430 </sect1>
8431 <sect1>
8432 <title>Reverting the mistaken change</title>
8434 <para id="x_e2">If you make a modification to a file, and decide that you
8435 really didn't want to change the file at all, and you haven't
8436 yet committed your changes, the <command role="hg-cmd" moreinfo="none">hg
8437 revert</command> command is the one you'll need. It looks at
8438 the changeset that's the parent of the working directory, and
8439 restores the contents of the file to their state as of that
8440 changeset. (That's a long-winded way of saying that, in the
8441 normal case, it undoes your modifications.)</para>
8443 <para id="x_e3">Let's illustrate how the <command role="hg-cmd" moreinfo="none">hg
8444 revert</command> command works with yet another small example.
8445 We'll begin by modifying a file that Mercurial is already
8446 tracking.</para>
8448 <!-- BEGIN daily.revert.modify -->
8449 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat file</userinput>
8450 original content
8451 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo unwanted change >> file</userinput>
8452 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff file</userinput>
8453 diff -r 2eacf948d309 file
8454 --- a/file Sun Aug 16 14:05:00 2009 +0000
8455 +++ b/file Sun Aug 16 14:05:00 2009 +0000
8456 @@ -1,1 +1,2 @@
8457 original content
8458 +unwanted change
8459 </screen>
8460 <!-- END daily.revert.modify -->
8463 <para id="x_e4">If we don't
8464 want that change, we can simply <command role="hg-cmd" moreinfo="none">hg
8465 revert</command> the file.</para>
8467 <!-- BEGIN daily.revert.unmodify -->
8468 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
8469 M file
8470 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert file</userinput>
8471 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat file</userinput>
8472 original content
8473 </screen>
8474 <!-- END daily.revert.unmodify -->
8477 <para id="x_e5">The <command role="hg-cmd" moreinfo="none">hg revert</command> command
8478 provides us with an extra degree of safety by saving our
8479 modified file with a <filename moreinfo="none">.orig</filename>
8480 extension.</para>
8482 <!-- BEGIN daily.revert.status -->
8483 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
8484 ? file.orig
8485 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat file.orig</userinput>
8486 original content
8487 unwanted change
8488 </screen>
8489 <!-- END daily.revert.status -->
8492 <tip>
8493 <title>Be careful with <filename moreinfo="none">.orig</filename> files</title>
8495 <para id="x_6b8">It's extremely unlikely that you are either using
8496 Mercurial to manage files with <filename moreinfo="none">.orig</filename>
8497 extensions or that you even care about the contents of such
8498 files. Just in case, though, it's useful to remember that
8499 <command role="hg-cmd" moreinfo="none">hg revert</command> will
8500 unconditionally overwrite an existing file with a
8501 <filename moreinfo="none">.orig</filename> extension. For instance, if you
8502 already have a file named <filename moreinfo="none">foo.orig</filename> when
8503 you revert <filename moreinfo="none">foo</filename>, the contents of
8504 <filename moreinfo="none">foo.orig</filename> will be clobbered.</para>
8505 </tip>
8507 <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
8508 will describe each of these in more detail in the section that
8509 follows.</para>
8510 <itemizedlist>
8511 <listitem><para id="x_e7">If you modify a file, it will restore the file
8512 to its unmodified state.</para>
8513 </listitem>
8514 <listitem><para id="x_e8">If you <command role="hg-cmd" moreinfo="none">hg add</command> a
8515 file, it will undo the <quote>added</quote> state of the
8516 file, but leave the file itself untouched.</para>
8517 </listitem>
8518 <listitem><para id="x_e9">If you delete a file without telling Mercurial,
8519 it will restore the file to its unmodified contents.</para>
8520 </listitem>
8521 <listitem><para id="x_ea">If you use the <command role="hg-cmd" moreinfo="none">hg
8522 remove</command> command to remove a file, it will undo
8523 the <quote>removed</quote> state of the file, and restore
8524 the file to its unmodified contents.</para>
8525 </listitem></itemizedlist>
8527 <sect2 id="sec:undo:mgmt">
8528 <title>File management errors</title>
8530 <para id="x_eb">The <command role="hg-cmd" moreinfo="none">hg revert</command> command is
8531 useful for more than just modified files. It lets you reverse
8532 the results of all of Mercurial's file management
8533 commands—<command role="hg-cmd" moreinfo="none">hg add</command>,
8534 <command role="hg-cmd" moreinfo="none">hg remove</command>, and so on.</para>
8536 <para id="x_ec">If you <command role="hg-cmd" moreinfo="none">hg add</command> a file,
8537 then decide that in fact you don't want Mercurial to track it,
8538 use <command role="hg-cmd" moreinfo="none">hg revert</command> to undo the
8539 add. Don't worry; Mercurial will not modify the file in any
8540 way. It will just <quote>unmark</quote> the file.</para>
8542 <!-- BEGIN daily.revert.add -->
8543 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo oops > oops</userinput>
8544 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add oops</userinput>
8545 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status oops</userinput>
8546 A oops
8547 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert oops</userinput>
8548 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
8549 ? oops
8550 </screen>
8551 <!-- END daily.revert.add -->
8554 <para id="x_ed">Similarly, if you ask Mercurial to <command role="hg-cmd" moreinfo="none">hg remove</command> a file, you can use
8555 <command role="hg-cmd" moreinfo="none">hg revert</command> to restore it to
8556 the contents it had as of the parent of the working directory.
8557 <!-- BEGIN daily.revert.remove -->
8558 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg remove file</userinput>
8559 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
8560 R file
8561 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert file</userinput>
8562 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
8563 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls file</userinput>
8564 file
8565 </screen>
8566 <!-- END daily.revert.remove -->
8567 This works just as
8568 well for a file that you deleted by hand, without telling
8569 Mercurial (recall that in Mercurial terminology, this kind of
8570 file is called <quote>missing</quote>).</para>
8572 <!-- BEGIN daily.revert.missing -->
8573 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">rm file</userinput>
8574 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
8575 ! file
8576 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert file</userinput>
8577 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls file</userinput>
8578 file
8579 </screen>
8580 <!-- END daily.revert.missing -->
8583 <para id="x_ee">If you revert a <command role="hg-cmd" moreinfo="none">hg copy</command>,
8584 the copied-to file remains in your working directory
8585 afterwards, untracked. Since a copy doesn't affect the
8586 copied-from file in any way, Mercurial doesn't do anything
8587 with the copied-from file.</para>
8589 <!-- BEGIN daily.revert.copy -->
8590 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg copy file new-file</userinput>
8591 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg revert new-file</userinput>
8592 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
8593 ? new-file
8594 </screen>
8595 <!-- END daily.revert.copy -->
8597 </sect2>
8598 </sect1>
8600 <sect1>
8601 <title>Dealing with committed changes</title>
8603 <para id="x_f5">Consider a case where you have committed a change
8604 <emphasis>a</emphasis>, and another change
8605 <emphasis>b</emphasis> on top of it; you then realise that
8606 change <emphasis>a</emphasis> was incorrect. Mercurial lets you
8607 <quote>back out</quote> an entire changeset automatically, and
8608 building blocks that let you reverse part of a changeset by
8609 hand.</para>
8611 <para id="x_f6">Before you read this section, here's something to
8612 keep in mind: the <command role="hg-cmd" moreinfo="none">hg backout</command>
8613 command undoes the effect of a change by
8614 <emphasis>adding</emphasis> to your repository's history, not by
8615 modifying or erasing it. It's the right tool to use if you're
8616 fixing bugs, but not if you're trying to undo some change that
8617 has catastrophic consequences. To deal with those, see
8618 <xref linkend="sec:undo:aaaiiieee"/>.</para>
8620 <sect2>
8621 <title>Backing out a changeset</title>
8623 <para id="x_f7">The <command role="hg-cmd" moreinfo="none">hg backout</command> command
8624 lets you <quote>undo</quote> the effects of an entire
8625 changeset in an automated fashion. Because Mercurial's
8626 history is immutable, this command <emphasis>does
8627 not</emphasis> get rid of the changeset you want to undo.
8628 Instead, it creates a new changeset that
8629 <emphasis>reverses</emphasis> the effect of the to-be-undone
8630 changeset.</para>
8632 <para id="x_f8">The operation of the <command role="hg-cmd" moreinfo="none">hg
8633 backout</command> command is a little intricate, so let's
8634 illustrate it with some examples. First, we'll create a
8635 repository with some simple changes.</para>
8637 <!-- BEGIN backout.init -->
8638 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init myrepo</userinput>
8639 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd myrepo</userinput>
8640 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo first change >> myfile</userinput>
8641 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add myfile</userinput>
8642 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'first change'</userinput>
8643 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo second change >> myfile</userinput>
8644 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'second change'</userinput>
8645 </screen>
8646 <!-- END backout.init -->
8649 <para id="x_f9">The <command role="hg-cmd" moreinfo="none">hg backout</command> command
8650 takes a single changeset ID as its argument; this is the
8651 changeset to back out. Normally, <command role="hg-cmd" moreinfo="none">hg
8652 backout</command> will drop you into a text editor to write
8653 a commit message, so you can record why you're backing the
8654 change out. In this example, we provide a commit message on
8655 the command line using the <option role="hg-opt-backout">-m</option> option.</para>
8657 </sect2>
8658 <sect2>
8659 <title>Backing out the tip changeset</title>
8661 <para id="x_fa">We're going to start by backing out the last changeset we
8662 committed.</para>
8664 <!-- BEGIN backout.simple -->
8665 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg backout -m 'back out second change' tip</userinput>
8666 reverting myfile
8667 changeset 2:611a0cae251c backs out changeset 1:43700a9b3ec8
8668 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
8669 first change
8670 </screen>
8671 <!-- END backout.simple -->
8674 <para id="x_fb">You can see that the second line from
8675 <filename moreinfo="none">myfile</filename> is no longer present. Taking a
8676 look at the output of <command role="hg-cmd" moreinfo="none">hg log</command>
8677 gives us an idea of what the <command role="hg-cmd" moreinfo="none">hg
8678 backout</command> command has done.
8679 <!-- BEGIN backout.simple.log -->
8680 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style compact</userinput>
8681 2[tip] 611a0cae251c 2009-08-16 14:04 +0000 bos
8682 back out second change
8684 1 43700a9b3ec8 2009-08-16 14:04 +0000 bos
8685 second change
8687 0 f2ef23d503fd 2009-08-16 14:04 +0000 bos
8688 first change
8690 </screen>
8691 <!-- END backout.simple.log -->
8692 Notice that the new changeset
8693 that <command role="hg-cmd" moreinfo="none">hg backout</command> has created
8694 is a child of the changeset we backed out. It's easier to see
8695 this in <xref linkend="fig:undo:backout"/>, which presents a
8696 graphical view of the change history. As you can see, the
8697 history is nice and linear.</para>
8699 <figure id="fig:undo:backout" float="0">
8700 <title>Backing out a change using the <command role="hg-cmd" moreinfo="none">hg backout</command> command</title>
8701 <mediaobject>
8702 <imageobject><imagedata fileref="figs/undo-simple.png"/></imageobject>
8703 <textobject><phrase>XXX add text</phrase></textobject>
8704 </mediaobject>
8705 </figure>
8707 </sect2>
8708 <sect2>
8709 <title>Backing out a non-tip change</title>
8711 <para id="x_fd">If you want to back out a change other than the last one
8712 you committed, pass the <option role="hg-opt-backout">--merge</option> option to the
8713 <command role="hg-cmd" moreinfo="none">hg backout</command> command.</para>
8715 <!-- BEGIN backout.non-tip.clone -->
8716 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
8717 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone -r1 myrepo non-tip-repo</userinput>
8718 requesting all changes
8719 adding changesets
8720 adding manifests
8721 adding file changes
8722 added 2 changesets with 2 changes to 1 files
8723 updating working directory
8724 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
8725 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd non-tip-repo</userinput>
8726 </screen>
8727 <!-- END backout.non-tip.clone -->
8730 <para id="x_fe">This makes backing out any changeset a
8731 <quote>one-shot</quote> operation that's usually simple and
8732 fast.</para>
8734 <!-- BEGIN backout.non-tip.backout -->
8735 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo third change >> myfile</userinput>
8736 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'third change'</userinput>
8737 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg backout --merge -m 'back out second change' 1</userinput>
8738 reverting myfile
8739 created new head
8740 changeset 3:611a0cae251c backs out changeset 1:43700a9b3ec8
8741 merging with changeset 3:611a0cae251c
8742 merging myfile
8743 0 files updated, 1 files merged, 0 files removed, 0 files unresolved
8744 (branch merge, don't forget to commit)
8745 </screen>
8746 <!-- END backout.non-tip.backout -->
8749 <para id="x_ff">If you take a look at the contents of
8750 <filename moreinfo="none">myfile</filename> after the backout finishes, you'll
8751 see that the first and third changes are present, but not the
8752 second.</para>
8754 <!-- BEGIN backout.non-tip.cat -->
8755 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
8756 first change
8757 third change
8758 </screen>
8759 <!-- END backout.non-tip.cat -->
8762 <para id="x_100">As the graphical history in <xref linkend="fig:undo:backout-non-tip"/> illustrates, Mercurial
8763 still commits one change in this kind of situation (the
8764 box-shaped node is the ones that Mercurial commits
8765 automatically), but the revision graph now looks different.
8766 Before Mercurial begins the backout process, it first
8767 remembers what the current parent of the working directory is.
8768 It then backs out the target changeset, and commits that as a
8769 changeset. Finally, it merges back to the previous parent of
8770 the working directory, but notice that it <emphasis>does not
8771 commit</emphasis> the result of the merge. The repository
8772 now contains two heads, and the working directory is in a
8773 merge state.</para>
8775 <figure id="fig:undo:backout-non-tip" float="0">
8776 <title>Automated backout of a non-tip change using the
8777 <command role="hg-cmd" moreinfo="none">hg backout</command> command</title>
8778 <mediaobject>
8779 <imageobject><imagedata fileref="figs/undo-non-tip.png"/></imageobject>
8780 <textobject><phrase>XXX add text</phrase></textobject>
8781 </mediaobject>
8782 </figure>
8784 <para id="x_103">The result is that you end up <quote>back where you
8785 were</quote>, only with some extra history that undoes the
8786 effect of the changeset you wanted to back out.</para>
8788 <para id="x_6b9">You might wonder why Mercurial does not commit the result
8789 of the merge that it performed. The reason lies in Mercurial
8790 behaving conservatively: a merge naturally has more scope for
8791 error than simply undoing the effect of the tip changeset,
8792 so your work will be safest if you first inspect (and test!)
8793 the result of the merge, <emphasis>then</emphasis> commit
8794 it.</para>
8796 <sect3>
8797 <title>Always use the <option role="hg-opt-backout">--merge</option> option</title>
8799 <para id="x_104">In fact, since the <option role="hg-opt-backout">--merge</option> option will do the
8800 <quote>right thing</quote> whether or not the changeset
8801 you're backing out is the tip (i.e. it won't try to merge if
8802 it's backing out the tip, since there's no need), you should
8803 <emphasis>always</emphasis> use this option when you run the
8804 <command role="hg-cmd" moreinfo="none">hg backout</command> command.</para>
8806 </sect3>
8807 </sect2>
8808 <sect2>
8809 <title>Gaining more control of the backout process</title>
8811 <para id="x_105">While I've recommended that you always use the <option role="hg-opt-backout">--merge</option> option when backing
8812 out a change, the <command role="hg-cmd" moreinfo="none">hg backout</command>
8813 command lets you decide how to merge a backout changeset.
8814 Taking control of the backout process by hand is something you
8815 will rarely need to do, but it can be useful to understand
8816 what the <command role="hg-cmd" moreinfo="none">hg backout</command> command
8817 is doing for you automatically. To illustrate this, let's
8818 clone our first repository, but omit the backout change that
8819 it contains.</para>
8821 <!-- BEGIN backout.manual.clone -->
8822 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
8823 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone -r1 myrepo newrepo</userinput>
8824 requesting all changes
8825 adding changesets
8826 adding manifests
8827 adding file changes
8828 added 2 changesets with 2 changes to 1 files
8829 updating working directory
8830 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
8831 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd newrepo</userinput>
8832 </screen>
8833 <!-- END backout.manual.clone -->
8836 <para id="x_106">As with our
8837 earlier example, We'll commit a third changeset, then back out
8838 its parent, and see what happens.</para>
8840 <!-- BEGIN backout.manual.backout -->
8841 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo third change >> myfile</userinput>
8842 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'third change'</userinput>
8843 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg backout -m 'back out second change' 1</userinput>
8844 reverting myfile
8845 created new head
8846 changeset 3:bf906ee0baae backs out changeset 1:43700a9b3ec8
8847 the backout changeset is a new head - do not forget to merge
8848 (use "backout --merge" if you want to auto-merge)
8849 </screen>
8850 <!-- END backout.manual.backout -->
8853 <para id="x_107">Our new changeset is again a descendant of the changeset
8854 we backout out; it's thus a new head, <emphasis>not</emphasis>
8855 a descendant of the changeset that was the tip. The <command role="hg-cmd" moreinfo="none">hg backout</command> command was quite
8856 explicit in telling us this.</para>
8858 <!-- BEGIN backout.manual.log -->
8859 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style compact</userinput>
8860 3[tip]:1 bf906ee0baae 2009-08-16 14:04 +0000 bos
8861 back out second change
8863 2 2521379001ad 2009-08-16 14:04 +0000 bos
8864 third change
8866 1 43700a9b3ec8 2009-08-16 14:04 +0000 bos
8867 second change
8869 0 f2ef23d503fd 2009-08-16 14:04 +0000 bos
8870 first change
8872 </screen>
8873 <!-- END backout.manual.log -->
8876 <para id="x_108">Again, it's easier to see what has happened by looking at
8877 a graph of the revision history, in <xref linkend="fig:undo:backout-manual"/>. This makes it clear
8878 that when we use <command role="hg-cmd" moreinfo="none">hg backout</command>
8879 to back out a change other than the tip, Mercurial adds a new
8880 head to the repository (the change it committed is
8881 box-shaped).</para>
8883 <figure id="fig:undo:backout-manual" float="0">
8884 <title>Backing out a change using the <command role="hg-cmd" moreinfo="none">hg backout</command> command</title>
8885 <mediaobject>
8886 <imageobject><imagedata fileref="figs/undo-manual.png"/></imageobject>
8887 <textobject><phrase>XXX add text</phrase></textobject>
8888 </mediaobject>
8889 </figure>
8891 <para id="x_10a">After the <command role="hg-cmd" moreinfo="none">hg backout</command>
8892 command has completed, it leaves the new
8893 <quote>backout</quote> changeset as the parent of the working
8894 directory.</para>
8896 <!-- BEGIN backout.manual.parents -->
8897 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg parents</userinput>
8898 changeset: 2:2521379001ad
8899 user: Bryan O'Sullivan <bos@serpentine.com>
8900 date: Sun Aug 16 14:04:37 2009 +0000
8901 summary: third change
8903 </screen>
8904 <!-- END backout.manual.parents -->
8907 <para id="x_10b">Now we have two isolated sets of changes.</para>
8909 <!-- BEGIN backout.manual.heads -->
8910 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg heads</userinput>
8911 changeset: 3:bf906ee0baae
8912 tag: tip
8913 parent: 1:43700a9b3ec8
8914 user: Bryan O'Sullivan <bos@serpentine.com>
8915 date: Sun Aug 16 14:04:37 2009 +0000
8916 summary: back out second change
8918 changeset: 2:2521379001ad
8919 user: Bryan O'Sullivan <bos@serpentine.com>
8920 date: Sun Aug 16 14:04:37 2009 +0000
8921 summary: third change
8923 </screen>
8924 <!-- END backout.manual.heads -->
8927 <para id="x_10c">Let's think about what we expect to see as the contents of
8928 <filename moreinfo="none">myfile</filename> now. The first change should be
8929 present, because we've never backed it out. The second change
8930 should be missing, as that's the change we backed out. Since
8931 the history graph shows the third change as a separate head,
8932 we <emphasis>don't</emphasis> expect to see the third change
8933 present in <filename moreinfo="none">myfile</filename>.</para>
8935 <!-- BEGIN backout.manual.cat -->
8936 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
8937 first change
8938 </screen>
8939 <!-- END backout.manual.cat -->
8942 <para id="x_10d">To get the third change back into the file, we just do a
8943 normal merge of our two heads.</para>
8945 <!-- BEGIN backout.manual.merge -->
8946 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg merge</userinput>
8947 abort: outstanding uncommitted changes
8948 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'merged backout with previous tip'</userinput>
8949 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat myfile</userinput>
8950 first change
8951 </screen>
8952 <!-- END backout.manual.merge -->
8955 <para id="x_10e">Afterwards, the graphical history of our
8956 repository looks like
8957 <xref linkend="fig:undo:backout-manual-merge"/>.</para>
8959 <figure id="fig:undo:backout-manual-merge" float="0">
8960 <title>Manually merging a backout change</title>
8961 <mediaobject>
8962 <imageobject><imagedata fileref="figs/undo-manual-merge.png"/></imageobject>
8963 <textobject><phrase>XXX add text</phrase></textobject>
8964 </mediaobject>
8965 </figure>
8967 </sect2>
8968 <sect2>
8969 <title>Why <command role="hg-cmd" moreinfo="none">hg backout</command> works as
8970 it does</title>
8972 <para id="x_110">Here's a brief description of how the <command role="hg-cmd" moreinfo="none">hg backout</command> command works.</para>
8973 <orderedlist inheritnum="ignore" continuation="restarts">
8974 <listitem><para id="x_111">It ensures that the working directory is
8975 <quote>clean</quote>, i.e. that the output of <command role="hg-cmd" moreinfo="none">hg status</command> would be empty.</para>
8976 </listitem>
8977 <listitem><para id="x_112">It remembers the current parent of the working
8978 directory. Let's call this changeset
8979 <literal moreinfo="none">orig</literal>.</para>
8980 </listitem>
8981 <listitem><para id="x_113">It does the equivalent of a <command role="hg-cmd" moreinfo="none">hg update</command> to sync the working
8982 directory to the changeset you want to back out. Let's
8983 call this changeset <literal moreinfo="none">backout</literal>.</para>
8984 </listitem>
8985 <listitem><para id="x_114">It finds the parent of that changeset. Let's
8986 call that changeset <literal moreinfo="none">parent</literal>.</para>
8987 </listitem>
8988 <listitem><para id="x_115">For each file that the
8989 <literal moreinfo="none">backout</literal> changeset affected, it does the
8990 equivalent of a <command role="hg-cmd" moreinfo="none">hg revert -r
8991 parent</command> on that file, to restore it to the
8992 contents it had before that changeset was
8993 committed.</para>
8994 </listitem>
8995 <listitem><para id="x_116">It commits the result as a new changeset.
8996 This changeset has <literal moreinfo="none">backout</literal> as its
8997 parent.</para>
8998 </listitem>
8999 <listitem><para id="x_117">If you specify <option role="hg-opt-backout">--merge</option> on the command
9000 line, it merges with <literal moreinfo="none">orig</literal>, and commits
9001 the result of the merge.</para>
9002 </listitem></orderedlist>
9004 <para id="x_118">An alternative way to implement the <command role="hg-cmd" moreinfo="none">hg backout</command> command would be to
9005 <command role="hg-cmd" moreinfo="none">hg export</command> the
9006 to-be-backed-out changeset as a diff, then use the <option role="cmd-opt-patch">--reverse</option> option to the
9007 <command moreinfo="none">patch</command> command to reverse the effect of the
9008 change without fiddling with the working directory. This
9009 sounds much simpler, but it would not work nearly as
9010 well.</para>
9012 <para id="x_119">The reason that <command role="hg-cmd" moreinfo="none">hg
9013 backout</command> does an update, a commit, a merge, and
9014 another commit is to give the merge machinery the best chance
9015 to do a good job when dealing with all the changes
9016 <emphasis>between</emphasis> the change you're backing out and
9017 the current tip.</para>
9019 <para id="x_11a">If you're backing out a changeset that's 100 revisions
9020 back in your project's history, the chances that the
9021 <command moreinfo="none">patch</command> command will be able to apply a
9022 reverse diff cleanly are not good, because intervening changes
9023 are likely to have <quote>broken the context</quote> that
9024 <command moreinfo="none">patch</command> uses to determine whether it can
9025 apply a patch (if this sounds like gibberish, see <xref linkend="sec:mq:patch"/> for a
9026 discussion of the <command moreinfo="none">patch</command> command). Also,
9027 Mercurial's merge machinery will handle files and directories
9028 being renamed, permission changes, and modifications to binary
9029 files, none of which <command moreinfo="none">patch</command> can deal
9030 with.</para>
9032 </sect2>
9033 </sect1>
9034 <sect1 id="sec:undo:aaaiiieee">
9035 <title>Changes that should never have been</title>
9037 <para id="x_11b">Most of the time, the <command role="hg-cmd" moreinfo="none">hg
9038 backout</command> command is exactly what you need if you want
9039 to undo the effects of a change. It leaves a permanent record
9040 of exactly what you did, both when committing the original
9041 changeset and when you cleaned up after it.</para>
9043 <para id="x_11c">On rare occasions, though, you may find that you've
9044 committed a change that really should not be present in the
9045 repository at all. For example, it would be very unusual, and
9046 usually considered a mistake, to commit a software project's
9047 object files as well as its source files. Object files have
9048 almost no intrinsic value, and they're <emphasis>big</emphasis>,
9049 so they increase the size of the repository and the amount of
9050 time it takes to clone or pull changes.</para>
9052 <para id="x_11d">Before I discuss the options that you have if you commit a
9053 <quote>brown paper bag</quote> change (the kind that's so bad
9054 that you want to pull a brown paper bag over your head), let me
9055 first discuss some approaches that probably won't work.</para>
9057 <para id="x_11e">Since Mercurial treats history as
9058 accumulative—every change builds on top of all changes
9059 that preceded it—you generally can't just make disastrous
9060 changes disappear. The one exception is when you've just
9061 committed a change, and it hasn't been pushed or pulled into
9062 another repository. That's when you can safely use the <command role="hg-cmd" moreinfo="none">hg rollback</command> command, as I detailed in
9063 <xref linkend="sec:undo:rollback"/>.</para>
9065 <para id="x_11f">After you've pushed a bad change to another repository, you
9066 <emphasis>could</emphasis> still use <command role="hg-cmd" moreinfo="none">hg
9067 rollback</command> to make your local copy of the change
9068 disappear, but it won't have the consequences you want. The
9069 change will still be present in the remote repository, so it
9070 will reappear in your local repository the next time you
9071 pull.</para>
9073 <para id="x_120">If a situation like this arises, and you know which
9074 repositories your bad change has propagated into, you can
9075 <emphasis>try</emphasis> to get rid of the change from
9076 <emphasis>every</emphasis> one of those repositories. This is,
9077 of course, not a satisfactory solution: if you miss even a
9078 single repository while you're expunging, the change is still
9079 <quote>in the wild</quote>, and could propagate further.</para>
9081 <para id="x_121">If you've committed one or more changes
9082 <emphasis>after</emphasis> the change that you'd like to see
9083 disappear, your options are further reduced. Mercurial doesn't
9084 provide a way to <quote>punch a hole</quote> in history, leaving
9085 changesets intact.</para>
9087 <sect2>
9088 <title>Backing out a merge</title>
9090 <para id="x_6ba">Since merges are often complicated, it is not unheard of
9091 for a merge to be mangled badly, but committed erroneously.
9092 Mercurial provides an important safeguard against bad merges
9093 by refusing to commit unresolved files, but human ingenuity
9094 guarantees that it is still possible to mess a merge up and
9095 commit it.</para>
9097 <para id="x_6bb">Given a bad merge that has been committed, usually the
9098 best way to approach it is to simply try to repair the damage
9099 by hand. A complete disaster that cannot be easily fixed up
9100 by hand ought to be very rare, but the <command role="hg-cmd" moreinfo="none">hg backout</command> command may help in
9101 making the cleanup easier. It offers a <option role="hg-opt-backout">--parent</option> option, which lets
9102 you specify which parent to revert to when backing out a
9103 merge.</para>
9105 <figure id="fig:undo:bad-merge-1" float="0">
9106 <title>A bad merge</title>
9107 <mediaobject>
9108 <imageobject><imagedata fileref="figs/bad-merge-1.png"/></imageobject>
9109 <textobject><phrase>XXX add text</phrase></textobject>
9110 </mediaobject>
9111 </figure>
9113 <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
9114 <emphasis>redo</emphasis> the merge of revisions 2 and
9115 3.</para>
9117 <para id="x_6bd">One way to do so would be as follows.</para>
9119 <orderedlist inheritnum="ignore" continuation="restarts">
9120 <listitem>
9121 <para id="x_6be">Call <command role="hg-cmd" moreinfo="none">hg backout --rev=4
9122 --parent=2</command>. This tells <command role="hg-cmd" moreinfo="none">hg backout</command> to back out revision
9123 4, which is the bad merge, and to when deciding which
9124 revision to prefer, to choose parent 2, one of the parents
9125 of the merge. The effect can be seen in <xref linkend="fig:undo:bad-merge-2"/>.</para>
9126 <figure id="fig:undo:bad-merge-2" float="0">
9127 <title>Backing out the merge, favoring one parent</title>
9128 <mediaobject>
9129 <imageobject><imagedata fileref="figs/bad-merge-2.png"/></imageobject>
9130 <textobject><phrase>XXX add text</phrase></textobject>
9131 </mediaobject>
9132 </figure>
9133 </listitem>
9135 <listitem>
9136 <para id="x_6bf">Call <command role="hg-cmd" moreinfo="none">hg backout --rev=4
9137 --parent=3</command>. This tells <command role="hg-cmd" moreinfo="none">hg backout</command> to back out revision
9138 4 again, but this time to choose parent 3, the other
9139 parent of the merge. The result is visible in <xref linkend="fig:undo:bad-merge-3"/>, in which the repository
9140 now contains three heads.</para>
9141 <figure id="fig:undo:bad-merge-3" float="0">
9142 <title>Backing out the merge, favoring the other
9143 parent</title>
9144 <mediaobject>
9145 <imageobject><imagedata fileref="figs/bad-merge-3.png"/></imageobject>
9146 <textobject><phrase>XXX add text</phrase></textobject>
9147 </mediaobject>
9148 </figure>
9149 </listitem>
9151 <listitem>
9152 <para id="x_6c0">Redo the bad merge by merging the two backout heads,
9153 which reduces the number of heads in the repository to
9154 two, as can be seen in <xref linkend="fig:undo:bad-merge-4"/>.</para>
9155 <figure id="fig:undo:bad-merge-4" float="0">
9156 <title>Merging the backouts</title>
9157 <mediaobject>
9158 <imageobject><imagedata fileref="figs/bad-merge-4.png"/></imageobject>
9159 <textobject><phrase>XXX add text</phrase></textobject>
9160 </mediaobject>
9161 </figure>
9162 </listitem>
9164 <listitem>
9165 <para id="x_6c1">Merge with the commit that was made after the bad
9166 merge, as shown in <xref linkend="fig:undo:bad-merge-5"/>.</para>
9167 <figure id="fig:undo:bad-merge-5" float="0">
9168 <title>Merging the backouts</title>
9169 <mediaobject>
9170 <imageobject><imagedata fileref="figs/bad-merge-5.png"/></imageobject>
9171 <textobject><phrase>XXX add text</phrase></textobject>
9172 </mediaobject>
9173 </figure>
9174 </listitem>
9175 </orderedlist>
9176 </sect2>
9178 <sect2>
9179 <title>Protect yourself from <quote>escaped</quote>
9180 changes</title>
9182 <para id="x_123">If you've committed some changes to your local repository
9183 and they've been pushed or pulled somewhere else, this isn't
9184 necessarily a disaster. You can protect yourself ahead of
9185 time against some classes of bad changeset. This is
9186 particularly easy if your team usually pulls changes from a
9187 central repository.</para>
9189 <para id="x_124">By configuring some hooks on that repository to validate
9190 incoming changesets (see chapter <xref linkend="chap:hook"/>),
9191 you can
9192 automatically prevent some kinds of bad changeset from being
9193 pushed to the central repository at all. With such a
9194 configuration in place, some kinds of bad changeset will
9195 naturally tend to <quote>die out</quote> because they can't
9196 propagate into the central repository. Better yet, this
9197 happens without any need for explicit intervention.</para>
9199 <para id="x_125">For instance, an incoming change hook that
9200 verifies that a changeset will actually compile can prevent
9201 people from inadvertently <quote>breaking the
9202 build</quote>.</para>
9203 </sect2>
9205 <sect2>
9206 <title>What to do about sensitive changes that escape</title>
9208 <para id="x_6c2">Even a carefully run project can suffer an unfortunate
9209 event such as the committing and uncontrolled propagation of a
9210 file that contains important passwords.</para>
9212 <para id="x_6c3">If something like this happens to you, and the information
9213 that gets accidentally propagated is truly sensitive, your
9214 first step should be to mitigate the effect of the leak
9215 without trying to control the leak itself. If you are not 100%
9216 certain that you know exactly who could have seen the changes,
9217 you should immediately change passwords, cancel credit cards,
9218 or find some other way to make sure that the information that
9219 has leaked is no longer useful. In other words, assume that
9220 the change has propagated far and wide, and that there's
9221 nothing more you can do.</para>
9223 <para id="x_6c4">You might hope that there would be mechanisms you could
9224 use to either figure out who has seen a change or to erase the
9225 change permanently everywhere, but there are good reasons why
9226 these are not possible.</para>
9228 <para id="x_6c5">Mercurial does not provide an audit trail of who has
9229 pulled changes from a repository, because it is usually either
9230 impossible to record such information or trivial to spoof it.
9231 In a multi-user or networked environment, you should thus be
9232 extremely skeptical of yourself if you think that you have
9233 identified every place that a sensitive changeset has
9234 propagated to. Don't forget that people can and will send
9235 bundles by email, have their backup software save data
9236 offsite, carry repositories on USB sticks, and find other
9237 completely innocent ways to confound your attempts to track
9238 down every copy of a problematic change.</para>
9240 <para id="x_6c6">Mercurial also does not provide a way to make a file or
9241 changeset completely disappear from history, because there is
9242 no way to enforce its disappearance; someone could easily
9243 modify their copy of Mercurial to ignore such directives. In
9244 addition, even if Mercurial provided such a capability,
9245 someone who simply hadn't pulled a <quote>make this file
9246 disappear</quote> changeset wouldn't be affected by it, nor
9247 would web crawlers visiting at the wrong time, disk backups,
9248 or other mechanisms. Indeed, no distributed revision control
9249 system can make data reliably vanish. Providing the illusion
9250 of such control could easily give a false sense of security,
9251 and be worse than not providing it at all.</para>
9252 </sect2>
9253 </sect1>
9255 <sect1 id="sec:undo:bisect">
9256 <title>Finding the source of a bug</title>
9258 <para id="x_126">While it's all very well to be able to back out a changeset
9259 that introduced a bug, this requires that you know which
9260 changeset to back out. Mercurial provides an invaluable
9261 command, called <command role="hg-cmd" moreinfo="none">hg bisect</command>, that
9262 helps you to automate this process and accomplish it very
9263 efficiently.</para>
9265 <para id="x_127">The idea behind the <command role="hg-cmd" moreinfo="none">hg
9266 bisect</command> command is that a changeset has introduced
9267 some change of behavior that you can identify with a simple
9268 pass/fail test. You don't know which piece of code introduced the
9269 change, but you know how to test for the presence of the bug.
9270 The <command role="hg-cmd" moreinfo="none">hg bisect</command> command uses your
9271 test to direct its search for the changeset that introduced the
9272 code that caused the bug.</para>
9274 <para id="x_128">Here are a few scenarios to help you understand how you
9275 might apply this command.</para>
9276 <itemizedlist>
9277 <listitem><para id="x_129">The most recent version of your software has a
9278 bug that you remember wasn't present a few weeks ago, but
9279 you don't know when it was introduced. Here, your binary
9280 test checks for the presence of that bug.</para>
9281 </listitem>
9282 <listitem><para id="x_12a">You fixed a bug in a rush, and now it's time to
9283 close the entry in your team's bug database. The bug
9284 database requires a changeset ID when you close an entry,
9285 but you don't remember which changeset you fixed the bug in.
9286 Once again, your binary test checks for the presence of the
9287 bug.</para>
9288 </listitem>
9289 <listitem><para id="x_12b">Your software works correctly, but runs 15%
9290 slower than the last time you measured it. You want to know
9291 which changeset introduced the performance regression. In
9292 this case, your binary test measures the performance of your
9293 software, to see whether it's <quote>fast</quote> or
9294 <quote>slow</quote>.</para>
9295 </listitem>
9296 <listitem><para id="x_12c">The sizes of the components of your project that
9297 you ship exploded recently, and you suspect that something
9298 changed in the way you build your project.</para>
9299 </listitem></itemizedlist>
9301 <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
9302 for finding the sources of bugs. You can use it to find any
9303 <quote>emergent property</quote> of a repository (anything that
9304 you can't find from a simple text search of the files in the
9305 tree) for which you can write a binary test.</para>
9307 <para id="x_12e">We'll introduce a little bit of terminology here, just to
9308 make it clear which parts of the search process are your
9309 responsibility, and which are Mercurial's. A
9310 <emphasis>test</emphasis> is something that
9311 <emphasis>you</emphasis> run when <command role="hg-cmd" moreinfo="none">hg
9312 bisect</command> chooses a changeset. A
9313 <emphasis>probe</emphasis> is what <command role="hg-cmd" moreinfo="none">hg
9314 bisect</command> runs to tell whether a revision is good.
9315 Finally, we'll use the word <quote>bisect</quote>, as both a
9316 noun and a verb, to stand in for the phrase <quote>search using
9317 the <command role="hg-cmd" moreinfo="none">hg bisect</command>
9318 command</quote>.</para>
9320 <para id="x_12f">One simple way to automate the searching process would be
9321 simply to probe every changeset. However, this scales poorly.
9322 If it took ten minutes to test a single changeset, and you had
9323 10,000 changesets in your repository, the exhaustive approach
9324 would take on average 35 <emphasis>days</emphasis> to find the
9325 changeset that introduced a bug. Even if you knew that the bug
9326 was introduced by one of the last 500 changesets, and limited
9327 your search to those, you'd still be looking at over 40 hours to
9328 find the changeset that introduced your bug.</para>
9330 <para id="x_130">What the <command role="hg-cmd" moreinfo="none">hg bisect</command> command
9331 does is use its knowledge of the <quote>shape</quote> of your
9332 project's revision history to perform a search in time
9333 proportional to the <emphasis>logarithm</emphasis> of the number
9334 of changesets to check (the kind of search it performs is called
9335 a dichotomic search). With this approach, searching through
9336 10,000 changesets will take less than three hours, even at ten
9337 minutes per test (the search will require about 14 tests).
9338 Limit your search to the last hundred changesets, and it will
9339 take only about an hour (roughly seven tests).</para>
9341 <para id="x_131">The <command role="hg-cmd" moreinfo="none">hg bisect</command> command is
9342 aware of the <quote>branchy</quote> nature of a Mercurial
9343 project's revision history, so it has no problems dealing with
9344 branches, merges, or multiple heads in a repository. It can
9345 prune entire branches of history with a single probe, which is
9346 how it operates so efficiently.</para>
9348 <sect2>
9349 <title>Using the <command role="hg-cmd" moreinfo="none">hg bisect</command>
9350 command</title>
9352 <para id="x_132">Here's an example of <command role="hg-cmd" moreinfo="none">hg
9353 bisect</command> in action.</para>
9355 <note>
9356 <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:
9357 it was distributed with Mercurial as an extension. This
9358 section describes the built-in command, not the old
9359 extension.</para>
9360 </note>
9362 <para id="x_134">Now let's create a repository, so that we can try out the
9363 <command role="hg-cmd" moreinfo="none">hg bisect</command> command in
9364 isolation.</para>
9366 <!-- BEGIN bisect.init -->
9367 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init mybug</userinput>
9368 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd mybug</userinput>
9369 </screen>
9370 <!-- END bisect.init -->
9373 <para id="x_135">We'll simulate a project that has a bug in it in a
9374 simple-minded way: create trivial changes in a loop, and
9375 nominate one specific change that will have the
9376 <quote>bug</quote>. This loop creates 35 changesets, each
9377 adding a single file to the repository. We'll represent our
9378 <quote>bug</quote> with a file that contains the text <quote>i
9379 have a gub</quote>.</para>
9381 <!-- BEGIN bisect.commits -->
9382 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">buggy_change=22</userinput>
9383 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">for (( i = 0; i < 35; i++ )); do</userinput>
9384 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> if [[ $i = $buggy_change ]]; then</userinput>
9385 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> echo 'i have a gub' > myfile$i</userinput>
9386 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> hg commit -q -A -m 'buggy changeset'</userinput>
9387 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> else</userinput>
9388 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> echo 'nothing to see here, move along' > myfile$i</userinput>
9389 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> hg commit -q -A -m 'normal changeset'</userinput>
9390 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> fi</userinput>
9391 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">done</userinput>
9392 </screen>
9393 <!-- END bisect.commits -->
9396 <para id="x_136">The next thing that we'd like to do is figure out how to
9397 use the <command role="hg-cmd" moreinfo="none">hg bisect</command> command.
9398 We can use Mercurial's normal built-in help mechanism for
9399 this.</para>
9401 <!-- BEGIN bisect.help -->
9402 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg help bisect</userinput>
9403 hg bisect [-gbsr] [-c CMD] [REV]
9405 subdivision search of changesets
9407 This command helps to find changesets which introduce problems.
9408 To use, mark the earliest changeset you know exhibits the problem
9409 as bad, then mark the latest changeset which is free from the
9410 problem as good. Bisect will update your working directory to a
9411 revision for testing (unless the --noupdate option is specified).
9412 Once you have performed tests, mark the working directory as bad
9413 or good and bisect will either update to another candidate changeset
9414 or announce that it has found the bad revision.
9416 As a shortcut, you can also use the revision argument to mark a
9417 revision as good or bad without checking it out first.
9419 If you supply a command it will be used for automatic bisection. Its exit
9420 status will be used as flag to mark revision as bad or good. In case exit
9421 status is 0 the revision is marked as good, 125 - skipped, 127 (command not
9422 found) - bisection will be aborted; any other status bigger than 0 will
9423 mark revision as bad.
9425 options:
9427 -r --reset reset bisect state
9428 -g --good mark changeset good
9429 -b --bad mark changeset bad
9430 -s --skip skip testing changeset
9431 -c --command use command to check changeset state
9432 -U --noupdate do not update to target
9434 use "hg -v help bisect" to show global options
9435 </screen>
9436 <!-- END bisect.help -->
9439 <para id="x_137">The <command role="hg-cmd" moreinfo="none">hg bisect</command> command
9440 works in steps. Each step proceeds as follows.</para>
9441 <orderedlist inheritnum="ignore" continuation="restarts">
9442 <listitem><para id="x_138">You run your binary test.</para>
9443 <itemizedlist>
9444 <listitem><para id="x_139">If the test succeeded, you tell <command role="hg-cmd" moreinfo="none">hg bisect</command> by running the
9445 <command role="hg-cmd" moreinfo="none">hg bisect --good</command>
9446 command.</para>
9447 </listitem>
9448 <listitem><para id="x_13a">If it failed, run the <command role="hg-cmd" moreinfo="none">hg bisect --bad</command>
9449 command.</para></listitem></itemizedlist>
9450 </listitem>
9451 <listitem><para id="x_13b">The command uses your information to decide
9452 which changeset to test next.</para>
9453 </listitem>
9454 <listitem><para id="x_13c">It updates the working directory to that
9455 changeset, and the process begins again.</para>
9456 </listitem></orderedlist>
9457 <para id="x_13d">The process ends when <command role="hg-cmd" moreinfo="none">hg
9458 bisect</command> identifies a unique changeset that marks
9459 the point where your test transitioned from
9460 <quote>succeeding</quote> to <quote>failing</quote>.</para>
9462 <para id="x_13e">To start the search, we must run the <command role="hg-cmd" moreinfo="none">hg bisect --reset</command> command.</para>
9464 <!-- BEGIN bisect.search.init -->
9465 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg bisect --reset</userinput>
9466 </screen>
9467 <!-- END bisect.search.init -->
9470 <para id="x_13f">In our case, the binary test we use is simple: we check to
9471 see if any file in the repository contains the string <quote>i
9472 have a gub</quote>. If it does, this changeset contains the
9473 change that <quote>caused the bug</quote>. By convention, a
9474 changeset that has the property we're searching for is
9475 <quote>bad</quote>, while one that doesn't is
9476 <quote>good</quote>.</para>
9478 <para id="x_140">Most of the time, the revision to which the working
9479 directory is synced (usually the tip) already exhibits the
9480 problem introduced by the buggy change, so we'll mark it as
9481 <quote>bad</quote>.</para>
9483 <!-- BEGIN bisect.search.bad-init -->
9484 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg bisect --bad</userinput>
9485 </screen>
9486 <!-- END bisect.search.bad-init -->
9489 <para id="x_141">Our next task is to nominate a changeset that we know
9490 <emphasis>doesn't</emphasis> have the bug; the <command role="hg-cmd" moreinfo="none">hg bisect</command> command will
9491 <quote>bracket</quote> its search between the first pair of
9492 good and bad changesets. In our case, we know that revision
9493 10 didn't have the bug. (I'll have more words about choosing
9494 the first <quote>good</quote> changeset later.)</para>
9496 <!-- BEGIN bisect.search.good-init -->
9497 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg bisect --good 10</userinput>
9498 Testing changeset 22:69f52b967ab8 (24 changesets remaining, ~4 tests)
9499 0 files updated, 0 files merged, 12 files removed, 0 files unresolved
9500 </screen>
9501 <!-- END bisect.search.good-init -->
9504 <para id="x_142">Notice that this command printed some output.</para>
9505 <itemizedlist>
9506 <listitem><para id="x_143">It told us how many changesets it must
9507 consider before it can identify the one that introduced
9508 the bug, and how many tests that will require.</para>
9509 </listitem>
9510 <listitem><para id="x_144">It updated the working directory to the next
9511 changeset to test, and told us which changeset it's
9512 testing.</para>
9513 </listitem></itemizedlist>
9515 <para id="x_145">We now run our test in the working directory. We use the
9516 <command moreinfo="none">grep</command> command to see if our
9517 <quote>bad</quote> file is present in the working directory.
9518 If it is, this revision is bad; if not, this revision is good.
9519 <!-- BEGIN bisect.search.step1 -->
9520 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">if grep -q 'i have a gub' *</userinput>
9521 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">then</userinput>
9522 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> result=bad</userinput>
9523 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">else</userinput>
9524 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> result=good</userinput>
9525 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">fi</userinput>
9526 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo this revision is $result</userinput>
9527 this revision is bad
9528 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg bisect --$result</userinput>
9529 Testing changeset 16:f1dd8bc690ae (12 changesets remaining, ~3 tests)
9530 0 files updated, 0 files merged, 6 files removed, 0 files unresolved
9531 </screen>
9532 <!-- END bisect.search.step1 -->
9533 </para>
9535 <para id="x_146">This test looks like a perfect candidate for automation,
9536 so let's turn it into a shell function.</para>
9537 <!-- BEGIN bisect.search.mytest -->
9538 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mytest() {</userinput>
9539 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> if grep -q 'i have a gub' *</userinput>
9540 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> then</userinput>
9541 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> result=bad</userinput>
9542 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> else</userinput>
9543 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> result=good</userinput>
9544 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> fi</userinput>
9545 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> echo this revision is $result</userinput>
9546 <prompt moreinfo="none">></prompt> <userinput moreinfo="none"> hg bisect --$result</userinput>
9547 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">}</userinput>
9548 </screen>
9549 <!-- END bisect.search.mytest -->
9552 <para id="x_147">We can now run an entire test step with a single command,
9553 <literal moreinfo="none">mytest</literal>.</para>
9555 <!-- BEGIN bisect.search.step2 -->
9556 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mytest</userinput>
9557 this revision is good
9558 Testing changeset 19:88d99d97058a (6 changesets remaining, ~2 tests)
9559 3 files updated, 0 files merged, 0 files removed, 0 files unresolved
9560 </screen>
9561 <!-- END bisect.search.step2 -->
9564 <para id="x_148">A few more invocations of our canned test step command,
9565 and we're done.</para>
9567 <!-- BEGIN bisect.search.rest -->
9568 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mytest</userinput>
9569 this revision is good
9570 Testing changeset 20:32a195a31d51 (3 changesets remaining, ~1 tests)
9571 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
9572 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mytest</userinput>
9573 this revision is good
9574 Testing changeset 21:a2efe8e4f624 (2 changesets remaining, ~1 tests)
9575 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
9576 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">mytest</userinput>
9577 this revision is good
9578 The first bad revision is:
9579 changeset: 22:69f52b967ab8
9580 user: Bryan O'Sullivan <bos@serpentine.com>
9581 date: Sun Aug 16 14:04:39 2009 +0000
9582 summary: buggy changeset
9584 </screen>
9585 <!-- END bisect.search.rest -->
9588 <para id="x_149">Even though we had 40 changesets to search through, the
9589 <command role="hg-cmd" moreinfo="none">hg bisect</command> command let us find
9590 the changeset that introduced our <quote>bug</quote> with only
9591 five tests. Because the number of tests that the <command role="hg-cmd" moreinfo="none">hg bisect</command> command performs grows
9592 logarithmically with the number of changesets to search, the
9593 advantage that it has over the <quote>brute force</quote>
9594 search approach increases with every changeset you add.</para>
9596 </sect2>
9597 <sect2>
9598 <title>Cleaning up after your search</title>
9600 <para id="x_14a">When you're finished using the <command role="hg-cmd" moreinfo="none">hg
9601 bisect</command> command in a repository, you can use the
9602 <command role="hg-cmd" moreinfo="none">hg bisect --reset</command> command to
9603 drop the information it was using to drive your search. The
9604 command doesn't use much space, so it doesn't matter if you
9605 forget to run this command. However, <command role="hg-cmd" moreinfo="none">hg bisect</command> won't let you start a new
9606 search in that repository until you do a <command role="hg-cmd" moreinfo="none">hg bisect --reset</command>.</para>
9608 <!-- BEGIN bisect.search.reset -->
9609 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg bisect --reset</userinput>
9610 </screen>
9611 <!-- END bisect.search.reset -->
9614 </sect2>
9615 </sect1>
9616 <sect1>
9617 <title>Tips for finding bugs effectively</title>
9619 <sect2>
9620 <title>Give consistent input</title>
9622 <para id="x_14b">The <command role="hg-cmd" moreinfo="none">hg bisect</command> command
9623 requires that you correctly report the result of every test
9624 you perform. If you tell it that a test failed when it really
9625 succeeded, it <emphasis>might</emphasis> be able to detect the
9626 inconsistency. If it can identify an inconsistency in your
9627 reports, it will tell you that a particular changeset is both
9628 good and bad. However, it can't do this perfectly; it's about
9629 as likely to report the wrong changeset as the source of the
9630 bug.</para>
9632 </sect2>
9633 <sect2>
9634 <title>Automate as much as possible</title>
9636 <para id="x_14c">When I started using the <command role="hg-cmd" moreinfo="none">hg
9637 bisect</command> command, I tried a few times to run my
9638 tests by hand, on the command line. This is an approach that
9639 I, at least, am not suited to. After a few tries, I found
9640 that I was making enough mistakes that I was having to restart
9641 my searches several times before finally getting correct
9642 results.</para>
9644 <para id="x_14d">My initial problems with driving the <command role="hg-cmd" moreinfo="none">hg bisect</command> command by hand occurred
9645 even with simple searches on small repositories; if the
9646 problem you're looking for is more subtle, or the number of
9647 tests that <command role="hg-cmd" moreinfo="none">hg bisect</command> must
9648 perform increases, the likelihood of operator error ruining
9649 the search is much higher. Once I started automating my
9650 tests, I had much better results.</para>
9652 <para id="x_14e">The key to automated testing is twofold:</para>
9653 <itemizedlist>
9654 <listitem><para id="x_14f">always test for the same symptom, and</para>
9655 </listitem>
9656 <listitem><para id="x_150">always feed consistent input to the <command role="hg-cmd" moreinfo="none">hg bisect</command> command.</para>
9657 </listitem></itemizedlist>
9658 <para id="x_151">In my tutorial example above, the <command moreinfo="none">grep</command>
9659 command tests for the symptom, and the <literal moreinfo="none">if</literal>
9660 statement takes the result of this check and ensures that we
9661 always feed the same input to the <command role="hg-cmd" moreinfo="none">hg
9662 bisect</command> command. The <literal moreinfo="none">mytest</literal>
9663 function marries these together in a reproducible way, so that
9664 every test is uniform and consistent.</para>
9666 </sect2>
9667 <sect2>
9668 <title>Check your results</title>
9670 <para id="x_152">Because the output of a <command role="hg-cmd" moreinfo="none">hg
9671 bisect</command> search is only as good as the input you
9672 give it, don't take the changeset it reports as the absolute
9673 truth. A simple way to cross-check its report is to manually
9674 run your test at each of the following changesets:</para>
9675 <itemizedlist>
9676 <listitem><para id="x_153">The changeset that it reports as the first bad
9677 revision. Your test should still report this as
9678 bad.</para>
9679 </listitem>
9680 <listitem><para id="x_154">The parent of that changeset (either parent,
9681 if it's a merge). Your test should report this changeset
9682 as good.</para>
9683 </listitem>
9684 <listitem><para id="x_155">A child of that changeset. Your test should
9685 report this changeset as bad.</para>
9686 </listitem></itemizedlist>
9688 </sect2>
9689 <sect2>
9690 <title>Beware interference between bugs</title>
9692 <para id="x_156">It's possible that your search for one bug could be
9693 disrupted by the presence of another. For example, let's say
9694 your software crashes at revision 100, and worked correctly at
9695 revision 50. Unknown to you, someone else introduced a
9696 different crashing bug at revision 60, and fixed it at
9697 revision 80. This could distort your results in one of
9698 several ways.</para>
9700 <para id="x_157">It is possible that this other bug completely
9701 <quote>masks</quote> yours, which is to say that it occurs
9702 before your bug has a chance to manifest itself. If you can't
9703 avoid that other bug (for example, it prevents your project
9704 from building), and so can't tell whether your bug is present
9705 in a particular changeset, the <command role="hg-cmd" moreinfo="none">hg
9706 bisect</command> command cannot help you directly. Instead,
9707 you can mark a changeset as untested by running <command role="hg-cmd" moreinfo="none">hg bisect --skip</command>.</para>
9709 <para id="x_158">A different problem could arise if your test for a bug's
9710 presence is not specific enough. If you check for <quote>my
9711 program crashes</quote>, then both your crashing bug and an
9712 unrelated crashing bug that masks it will look like the same
9713 thing, and mislead <command role="hg-cmd" moreinfo="none">hg
9714 bisect</command>.</para>
9716 <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
9717 test a revision because your project was in a broken and hence
9718 untestable state at that revision, perhaps because someone
9719 checked in a change that prevented the project from
9720 building.</para>
9722 </sect2>
9723 <sect2>
9724 <title>Bracket your search lazily</title>
9726 <para id="x_15a">Choosing the first <quote>good</quote> and
9727 <quote>bad</quote> changesets that will mark the end points of
9728 your search is often easy, but it bears a little discussion
9729 nevertheless. From the perspective of <command role="hg-cmd" moreinfo="none">hg bisect</command>, the <quote>newest</quote>
9730 changeset is conventionally <quote>bad</quote>, and the older
9731 changeset is <quote>good</quote>.</para>
9733 <para id="x_15b">If you're having trouble remembering when a suitable
9734 <quote>good</quote> change was, so that you can tell <command role="hg-cmd" moreinfo="none">hg bisect</command>, you could do worse than
9735 testing changesets at random. Just remember to eliminate
9736 contenders that can't possibly exhibit the bug (perhaps
9737 because the feature with the bug isn't present yet) and those
9738 where another problem masks the bug (as I discussed
9739 above).</para>
9741 <para id="x_15c">Even if you end up <quote>early</quote> by thousands of
9742 changesets or months of history, you will only add a handful
9743 of tests to the total number that <command role="hg-cmd" moreinfo="none">hg
9744 bisect</command> must perform, thanks to its logarithmic
9745 behavior.</para>
9747 </sect2>
9748 </sect1>
9749 </chapter>
9751 <!--
9752 local variables:
9753 sgml-parent-document: ("00book.xml" "book" "chapter")
9754 end:
9755 -->
9757 <!-- BEGIN ch10 -->
9758 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
9760 <chapter id="chap:hook">
9761 <?dbhtml filename="handling-repository-events-with-hooks.html"?>
9762 <title>Handling repository events with hooks</title>
9764 <para id="x_1e6">Mercurial offers a powerful mechanism to let you perform
9765 automated actions in response to events that occur in a
9766 repository. In some cases, you can even control Mercurial's
9767 response to those events.</para>
9769 <para id="x_1e7">The name Mercurial uses for one of these actions is a
9770 <emphasis>hook</emphasis>. Hooks are called
9771 <quote>triggers</quote> in some revision control systems, but the
9772 two names refer to the same idea.</para>
9774 <sect1>
9775 <title>An overview of hooks in Mercurial</title>
9777 <para id="x_1e8">Here is a brief list of the hooks that Mercurial
9778 supports. We will revisit each of these hooks in more detail
9779 later, in <xref linkend="sec:hook:ref"/>.</para>
9781 <para id="x_1f6">Each of the hooks whose description begins with the word
9782 <quote>Controlling</quote> has the ability to determine whether
9783 an activity can proceed. If the hook succeeds, the activity may
9784 proceed; if it fails, the activity is either not permitted or
9785 undone, depending on the hook.</para>
9787 <itemizedlist>
9788 <listitem><para id="x_1e9"><literal role="hook" moreinfo="none">changegroup</literal>: This
9789 is run after a group of changesets has been brought into the
9790 repository from elsewhere.</para>
9791 </listitem>
9792 <listitem><para id="x_1ea"><literal role="hook" moreinfo="none">commit</literal>: This is
9793 run after a new changeset has been created in the local
9794 repository.</para>
9795 </listitem>
9796 <listitem><para id="x_1eb"><literal role="hook" moreinfo="none">incoming</literal>: This is
9797 run once for each new changeset that is brought into the
9798 repository from elsewhere. Notice the difference from
9799 <literal role="hook" moreinfo="none">changegroup</literal>, which is run
9800 once per <emphasis>group</emphasis> of changesets brought
9801 in.</para>
9802 </listitem>
9803 <listitem><para id="x_1ec"><literal role="hook" moreinfo="none">outgoing</literal>: This is
9804 run after a group of changesets has been transmitted from
9805 this repository.</para>
9806 </listitem>
9807 <listitem><para id="x_1ed"><literal role="hook" moreinfo="none">prechangegroup</literal>:
9808 This is run before starting to bring a group of changesets
9809 into the repository.
9810 </para>
9811 </listitem>
9812 <listitem><para id="x_1ee"><literal role="hook" moreinfo="none">precommit</literal>:
9813 Controlling. This is run before starting a commit.
9814 </para>
9815 </listitem>
9816 <listitem><para id="x_1ef"><literal role="hook" moreinfo="none">preoutgoing</literal>:
9817 Controlling. This is run before starting to transmit a group
9818 of changesets from this repository.
9819 </para>
9820 </listitem>
9821 <listitem><para id="x_1f0"><literal role="hook" moreinfo="none">pretag</literal>:
9822 Controlling. This is run before creating a tag.
9823 </para>
9824 </listitem>
9825 <listitem><para id="x_1f1"><literal role="hook" moreinfo="none">pretxnchangegroup</literal>: Controlling. This
9826 is run after a group of changesets has been brought into the
9827 local repository from another, but before the transaction
9828 completes that will make the changes permanent in the
9829 repository.
9830 </para>
9831 </listitem>
9832 <listitem><para id="x_1f2"><literal role="hook" moreinfo="none">pretxncommit</literal>:
9833 Controlling. This is run after a new changeset has been
9834 created in the local repository, but before the transaction
9835 completes that will make it permanent.
9836 </para>
9837 </listitem>
9838 <listitem><para id="x_1f3"><literal role="hook" moreinfo="none">preupdate</literal>:
9839 Controlling. This is run before starting an update or merge
9840 of the working directory.
9841 </para>
9842 </listitem>
9843 <listitem><para id="x_1f4"><literal role="hook" moreinfo="none">tag</literal>: This is run
9844 after a tag is created.
9845 </para>
9846 </listitem>
9847 <listitem><para id="x_1f5"><literal role="hook" moreinfo="none">update</literal>: This is
9848 run after an update or merge of the working directory has
9849 finished.
9850 </para>
9851 </listitem></itemizedlist>
9853 </sect1>
9854 <sect1>
9855 <title>Hooks and security</title>
9857 <sect2>
9858 <title>Hooks are run with your privileges</title>
9860 <para id="x_1f7">When you run a Mercurial command in a repository, and the
9861 command causes a hook to run, that hook runs on
9862 <emphasis>your</emphasis> system, under
9863 <emphasis>your</emphasis> user account, with
9864 <emphasis>your</emphasis> privilege level. Since hooks are
9865 arbitrary pieces of executable code, you should treat them
9866 with an appropriate level of suspicion. Do not install a hook
9867 unless you are confident that you know who created it and what
9868 it does.
9869 </para>
9871 <para id="x_1f8">In some cases, you may be exposed to hooks that you did
9872 not install yourself. If you work with Mercurial on an
9873 unfamiliar system, Mercurial will run hooks defined in that
9874 system's global <filename role="special" moreinfo="none">~/.hgrc</filename>
9875 file.
9876 </para>
9878 <para id="x_1f9">If you are working with a repository owned by another
9879 user, Mercurial can run hooks defined in that user's
9880 repository, but it will still run them as <quote>you</quote>.
9881 For example, if you <command role="hg-cmd" moreinfo="none">hg pull</command>
9882 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
9883 under your user account, even though you don't own that
9884 repository.
9885 </para>
9887 <note>
9888 <para id="x_1fa"> This only applies if you are pulling from a repository
9889 on a local or network filesystem. If you're pulling over
9890 http or ssh, any <literal role="hook" moreinfo="none">outgoing</literal>
9891 hook will run under whatever account is executing the server
9892 process, on the server.
9893 </para>
9894 </note>
9896 <para id="x_1fb">To see what hooks are defined in a repository,
9897 use the <command role="hg-cmd" moreinfo="none">hg showconfig hooks</command>
9898 command. If you are working in one repository, but talking to
9899 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
9900 incoming</command>), remember that it is the other
9901 repository's hooks you should be checking, not your own.
9902 </para>
9903 </sect2>
9905 <sect2>
9906 <title>Hooks do not propagate</title>
9908 <para id="x_1fc">In Mercurial, hooks are not revision controlled, and do
9909 not propagate when you clone, or pull from, a repository. The
9910 reason for this is simple: a hook is a completely arbitrary
9911 piece of executable code. It runs under your user identity,
9912 with your privilege level, on your machine.
9913 </para>
9915 <para id="x_1fd">It would be extremely reckless for any distributed
9916 revision control system to implement revision-controlled
9917 hooks, as this would offer an easily exploitable way to
9918 subvert the accounts of users of the revision control system.
9919 </para>
9921 <para id="x_1fe">Since Mercurial does not propagate hooks, if you are
9922 collaborating with other people on a common project, you
9923 should not assume that they are using the same Mercurial hooks
9924 as you are, or that theirs are correctly configured. You
9925 should document the hooks you expect people to use.
9926 </para>
9928 <para id="x_1ff">In a corporate intranet, this is somewhat easier to
9929 control, as you can for example provide a
9930 <quote>standard</quote> installation of Mercurial on an NFS
9931 filesystem, and use a site-wide <filename role="special" moreinfo="none">~/.hgrc</filename> file to define hooks that all users will
9932 see. However, this too has its limits; see below.
9933 </para>
9934 </sect2>
9936 <sect2>
9937 <title>Hooks can be overridden</title>
9939 <para id="x_200">Mercurial allows you to override a hook definition by
9940 redefining the hook. You can disable it by setting its value
9941 to the empty string, or change its behavior as you wish.
9942 </para>
9944 <para id="x_201">If you deploy a system- or site-wide <filename role="special" moreinfo="none">~/.hgrc</filename> file that defines some
9945 hooks, you should thus understand that your users can disable
9946 or override those hooks.
9947 </para>
9948 </sect2>
9950 <sect2>
9951 <title>Ensuring that critical hooks are run</title>
9953 <para id="x_202">Sometimes you may want to enforce a policy that you do not
9954 want others to be able to work around. For example, you may
9955 have a requirement that every changeset must pass a rigorous
9956 set of tests. Defining this requirement via a hook in a
9957 site-wide <filename role="special" moreinfo="none">~/.hgrc</filename> won't
9958 work for remote users on laptops, and of course local users
9959 can subvert it at will by overriding the hook.
9960 </para>
9962 <para id="x_203">Instead, you can set up your policies for use of Mercurial
9963 so that people are expected to propagate changes through a
9964 well-known <quote>canonical</quote> server that you have
9965 locked down and configured appropriately.
9966 </para>
9968 <para id="x_204">One way to do this is via a combination of social
9969 engineering and technology. Set up a restricted-access
9970 account; users can push changes over the network to
9971 repositories managed by this account, but they cannot log into
9972 the account and run normal shell commands. In this scenario,
9973 a user can commit a changeset that contains any old garbage
9974 they want.
9975 </para>
9977 <para id="x_205">When someone pushes a changeset to the server that
9978 everyone pulls from, the server will test the changeset before
9979 it accepts it as permanent, and reject it if it fails to pass
9980 the test suite. If people only pull changes from this
9981 filtering server, it will serve to ensure that all changes
9982 that people pull have been automatically vetted.
9983 </para>
9985 </sect2>
9986 </sect1>
9988 <sect1 id="sec:hook:simple">
9989 <title>A short tutorial on using hooks</title>
9991 <para id="x_212">It is easy to write a Mercurial hook. Let's start with a
9992 hook that runs when you finish a <command role="hg-cmd" moreinfo="none">hg
9993 commit</command>, and simply prints the hash of the changeset
9994 you just created. The hook is called <literal role="hook" moreinfo="none">commit</literal>.
9995 </para>
9997 <para id="x_213">All hooks follow the pattern in this example.</para>
9999 <!-- BEGIN hook.simple.init -->
10000 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init hook-test</userinput>
10001 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd hook-test</userinput>
10002 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo '[hooks]' >> .hg/hgrc</userinput>
10003 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'commit = echo committed $HG_NODE' >> .hg/hgrc</userinput>
10004 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/hgrc</userinput>
10005 [hooks]
10006 commit = echo committed $HG_NODE
10007 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a > a</userinput>
10008 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a</userinput>
10009 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'testing commit hook'</userinput>
10010 committed 13a334d1e5ca83fea465aa779110eec3c5ddd6b1
10011 </screen>
10012 <!-- END hook.simple.init -->
10015 <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
10016 the event to trigger on; on the right is the action to take. As
10017 you can see, you can run an arbitrary shell command in a hook.
10018 Mercurial passes extra information to the hook using environment
10019 variables (look for <envar>HG_NODE</envar> in the example).
10020 </para>
10022 <sect2>
10023 <title>Performing multiple actions per event</title>
10025 <para id="x_215">Quite often, you will want to define more than one hook
10026 for a particular kind of event, as shown below.</para>
10028 <!-- BEGIN hook.simple.ext -->
10029 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'commit.when = echo -n "date of commit: "; date' >> .hg/hgrc</userinput>
10030 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a >> a</userinput>
10031 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'i have two hooks'</userinput>
10032 committed 3be6e2778fb853cbc7e5138d0b9c29386504670b
10033 date of commit: Sun Aug 16 14:05:05 GMT 2009
10034 </screen>
10035 <!-- END hook.simple.ext -->
10038 <para id="x_216">Mercurial lets you do this by adding an
10039 <emphasis>extension</emphasis> to the end of a hook's name.
10040 You extend a hook's name by giving the name of the hook,
10041 followed by a full stop (the
10042 <quote><literal moreinfo="none">.</literal></quote> character), followed by
10043 some more text of your choosing. For example, Mercurial will
10044 run both <literal moreinfo="none">commit.foo</literal> and
10045 <literal moreinfo="none">commit.bar</literal> when the
10046 <literal moreinfo="none">commit</literal> event occurs.
10047 </para>
10049 <para id="x_217">To give a well-defined order of execution when there are
10050 multiple hooks defined for an event, Mercurial sorts hooks by
10051 extension, and executes the hook commands in this sorted
10052 order. In the above example, it will execute
10053 <literal moreinfo="none">commit.bar</literal> before
10054 <literal moreinfo="none">commit.foo</literal>, and <literal moreinfo="none">commit</literal>
10055 before both.
10056 </para>
10058 <para id="x_218">It is a good idea to use a somewhat descriptive
10059 extension when you define a new hook. This will help you to
10060 remember what the hook was for. If the hook fails, you'll get
10061 an error message that contains the hook name and extension, so
10062 using a descriptive extension could give you an immediate hint
10063 as to why the hook failed (see <xref linkend="sec:hook:perm"/> for an example).
10064 </para>
10066 </sect2>
10067 <sect2 id="sec:hook:perm">
10068 <title>Controlling whether an activity can proceed</title>
10070 <para id="x_219">In our earlier examples, we used the <literal role="hook" moreinfo="none">commit</literal> hook, which is run after a
10071 commit has completed. This is one of several Mercurial hooks
10072 that run after an activity finishes. Such hooks have no way
10073 of influencing the activity itself.
10074 </para>
10076 <para id="x_21a">Mercurial defines a number of events that occur before an
10077 activity starts; or after it starts, but before it finishes.
10078 Hooks that trigger on these events have the added ability to
10079 choose whether the activity can continue, or will abort.
10080 </para>
10082 <para id="x_21b">The <literal role="hook" moreinfo="none">pretxncommit</literal> hook runs
10083 after a commit has all but completed. In other words, the
10084 metadata representing the changeset has been written out to
10085 disk, but the transaction has not yet been allowed to
10086 complete. The <literal role="hook" moreinfo="none">pretxncommit</literal>
10087 hook has the ability to decide whether the transaction can
10088 complete, or must be rolled back.
10089 </para>
10091 <para id="x_21c">If the <literal role="hook" moreinfo="none">pretxncommit</literal> hook
10092 exits with a status code of zero, the transaction is allowed
10093 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
10094 non-zero status code, the transaction is rolled back; the
10095 metadata representing the changeset is erased; and the
10096 <literal role="hook" moreinfo="none">commit</literal> hook is not run.
10097 </para>
10099 <!-- BEGIN hook.simple.pretxncommit -->
10100 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat check_bug_id</userinput>
10101 #!/bin/sh
10102 # check that a commit comment mentions a numeric bug id
10103 hg log -r $1 --template {desc} | grep -q "\<bug *[0-9]"
10104 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'pretxncommit.bug_id_required = ./check_bug_id $HG_NODE' >> .hg/hgrc</userinput>
10105 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a >> a</userinput>
10106 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'i am not mentioning a bug id'</userinput>
10107 transaction abort!
10108 rollback completed
10109 abort: pretxncommit.bug_id_required hook exited with status 1
10110 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m 'i refer you to bug 666'</userinput>
10111 committed 1a52be73a1ca4fa05e269f99003ed00912e8e836
10112 date of commit: Sun Aug 16 14:05:05 GMT 2009
10113 </screen>
10114 <!-- END hook.simple.pretxncommit -->
10117 <para id="x_21d">The hook in the example above checks that a commit comment
10118 contains a bug ID. If it does, the commit can complete. If
10119 not, the commit is rolled back.
10120 </para>
10122 </sect2>
10123 </sect1>
10124 <sect1>
10125 <title>Writing your own hooks</title>
10127 <para id="x_21e">When you are writing a hook, you might find it useful to run
10128 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
10129 <quote>true</quote>. When you do so, Mercurial will print a
10130 message before it calls each hook.
10131 </para>
10133 <sect2 id="sec:hook:lang">
10134 <title>Choosing how your hook should run</title>
10136 <para id="x_21f">You can write a hook either as a normal
10137 program—typically a shell script—or as a Python
10138 function that is executed within the Mercurial process.
10139 </para>
10141 <para id="x_220">Writing a hook as an external program has the advantage
10142 that it requires no knowledge of Mercurial's internals. You
10143 can call normal Mercurial commands to get any added
10144 information you need. The trade-off is that external hooks
10145 are slower than in-process hooks.
10146 </para>
10148 <para id="x_221">An in-process Python hook has complete access to the
10149 Mercurial API, and does not <quote>shell out</quote> to
10150 another process, so it is inherently faster than an external
10151 hook. It is also easier to obtain much of the information
10152 that a hook requires by using the Mercurial API than by
10153 running Mercurial commands.
10154 </para>
10156 <para id="x_222">If you are comfortable with Python, or require high
10157 performance, writing your hooks in Python may be a good
10158 choice. However, when you have a straightforward hook to
10159 write and you don't need to care about performance (probably
10160 the majority of hooks), a shell script is perfectly fine.
10161 </para>
10163 </sect2>
10164 <sect2 id="sec:hook:param">
10165 <title>Hook parameters</title>
10167 <para id="x_223">Mercurial calls each hook with a set of well-defined
10168 parameters. In Python, a parameter is passed as a keyword
10169 argument to your hook function. For an external program, a
10170 parameter is passed as an environment variable.
10171 </para>
10173 <para id="x_224">Whether your hook is written in Python or as a shell
10174 script, the hook-specific parameter names and values will be
10175 the same. A boolean parameter will be represented as a
10176 boolean value in Python, but as the number 1 (for
10177 <quote>true</quote>) or 0 (for <quote>false</quote>) as an
10178 environment variable for an external hook. If a hook
10179 parameter is named <literal moreinfo="none">foo</literal>, the keyword
10180 argument for a Python hook will also be named
10181 <literal moreinfo="none">foo</literal>, while the environment variable for an
10182 external hook will be named <literal moreinfo="none">HG_FOO</literal>.
10183 </para>
10184 </sect2>
10186 <sect2>
10187 <title>Hook return values and activity control</title>
10189 <para id="x_225">A hook that executes successfully must exit with a status
10190 of zero if external, or return boolean <quote>false</quote> if
10191 in-process. Failure is indicated with a non-zero exit status
10192 from an external hook, or an in-process hook returning boolean
10193 <quote>true</quote>. If an in-process hook raises an
10194 exception, the hook is considered to have failed.
10195 </para>
10197 <para id="x_226">For a hook that controls whether an activity can proceed,
10198 zero/false means <quote>allow</quote>, while
10199 non-zero/true/exception means <quote>deny</quote>.
10200 </para>
10201 </sect2>
10203 <sect2>
10204 <title>Writing an external hook</title>
10206 <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
10207 value is passed to your shell, which interprets it. This
10208 means that you can use normal shell constructs in the body of
10209 the hook.
10210 </para>
10212 <para id="x_228">An executable hook is always run with its current
10213 directory set to a repository's root directory.
10214 </para>
10216 <para id="x_229">Each hook parameter is passed in as an environment
10217 variable; the name is upper-cased, and prefixed with the
10218 string <quote><literal moreinfo="none">HG_</literal></quote>.
10219 </para>
10221 <para id="x_22a">With the exception of hook parameters, Mercurial does not
10222 set or modify any environment variables when running a hook.
10223 This is useful to remember if you are writing a site-wide hook
10224 that may be run by a number of different users with differing
10225 environment variables set. In multi-user situations, you
10226 should not rely on environment variables being set to the
10227 values you have in your environment when testing the hook.
10228 </para>
10229 </sect2>
10231 <sect2>
10232 <title>Telling Mercurial to use an in-process hook</title>
10234 <para id="x_22b">The <filename role="special" moreinfo="none">~/.hgrc</filename> syntax
10235 for defining an in-process hook is slightly different than for
10236 an executable hook. The value of the hook must start with the
10237 text <quote><literal moreinfo="none">python:</literal></quote>, and continue
10238 with the fully-qualified name of a callable object to use as
10239 the hook's value.
10240 </para>
10242 <para id="x_22c">The module in which a hook lives is automatically imported
10243 when a hook is run. So long as you have the module name and
10244 <envar>PYTHONPATH</envar> right, it should <quote>just
10245 work</quote>.
10246 </para>
10248 <para id="x_22d">The following <filename role="special" moreinfo="none">~/.hgrc</filename>
10249 example snippet illustrates the syntax and meaning of the
10250 notions we just described.
10251 </para>
10252 <programlisting format="linespecific">[hooks]
10253 commit.example = python:mymodule.submodule.myhook</programlisting>
10254 <para id="x_22e">When Mercurial runs the <literal moreinfo="none">commit.example</literal>
10255 hook, it imports <literal moreinfo="none">mymodule.submodule</literal>, looks
10256 for the callable object named <literal moreinfo="none">myhook</literal>, and
10257 calls it.
10258 </para>
10259 </sect2>
10261 <sect2>
10262 <title>Writing an in-process hook</title>
10264 <para id="x_22f">The simplest in-process hook does nothing, but illustrates
10265 the basic shape of the hook API:
10266 </para>
10267 <programlisting format="linespecific">def myhook(ui, repo, **kwargs):
10268 pass</programlisting>
10269 <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
10270 is a repository object; at the moment, it is always an
10271 instance of <literal role="py-mod-mercurial.localrepo" moreinfo="none">localrepository</literal>.
10272 Following these two arguments are other keyword arguments.
10273 Which ones are passed in depends on the hook being called, but
10274 a hook can ignore arguments it doesn't care about by dropping
10275 them into a keyword argument dict, as with
10276 <literal moreinfo="none">**kwargs</literal> above.
10277 </para>
10279 </sect2>
10280 </sect1>
10281 <sect1>
10282 <title>Some hook examples</title>
10284 <sect2>
10285 <title>Writing meaningful commit messages</title>
10287 <para id="x_231">It's hard to imagine a useful commit message being very
10288 short. The simple <literal role="hook" moreinfo="none">pretxncommit</literal>
10289 hook of the example below will prevent you from committing a
10290 changeset with a message that is less than ten bytes long.
10291 </para>
10293 <!-- BEGIN hook.msglen.go -->
10294 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/hgrc</userinput>
10295 [hooks]
10296 pretxncommit.msglen = test `hg tip --template {desc} | wc -c` -ge 10
10297 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a > a</userinput>
10298 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a</userinput>
10299 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'too short'</userinput>
10300 transaction abort!
10301 rollback completed
10302 abort: pretxncommit.msglen hook exited with status 1
10303 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'long enough'</userinput>
10304 </screen>
10305 <!-- END hook.msglen.go -->
10307 </sect2>
10309 <sect2>
10310 <title>Checking for trailing whitespace</title>
10312 <para id="x_232">An interesting use of a commit-related hook is to help you
10313 to write cleaner code. A simple example of <quote>cleaner
10314 code</quote> is the dictum that a change should not add any
10315 new lines of text that contain <quote>trailing
10316 whitespace</quote>. Trailing whitespace is a series of
10317 space and tab characters at the end of a line of text. In
10318 most cases, trailing whitespace is unnecessary, invisible
10319 noise, but it is occasionally problematic, and people often
10320 prefer to get rid of it.
10321 </para>
10323 <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
10324 have a trailing whitespace problem. If you use the <literal role="hook" moreinfo="none">precommit</literal> hook, the hook will not know
10325 which files you are committing, so it will have to check every
10326 modified file in the repository for trailing white space. If
10327 you want to commit a change to just the file
10328 <filename moreinfo="none">foo</filename>, but the file
10329 <filename moreinfo="none">bar</filename> contains trailing whitespace, doing a
10330 check in the <literal role="hook" moreinfo="none">precommit</literal> hook
10331 will prevent you from committing <filename moreinfo="none">foo</filename> due
10332 to the problem with <filename moreinfo="none">bar</filename>. This doesn't
10333 seem right.
10334 </para>
10336 <para id="x_234">Should you choose the <literal role="hook" moreinfo="none">pretxncommit</literal> hook, the check won't
10337 occur until just before the transaction for the commit
10338 completes. This will allow you to check for problems only the
10339 exact files that are being committed. However, if you entered
10340 the commit message interactively and the hook fails, the
10341 transaction will roll back; you'll have to re-enter the commit
10342 message after you fix the trailing whitespace and run <command role="hg-cmd" moreinfo="none">hg commit</command> again.
10343 </para>
10345 <!-- BEGIN ch09/hook.ws.simple -->
10346 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/hgrc</userinput>
10347 [hooks]
10348 pretxncommit.whitespace = hg export tip | (! egrep -q '^\+.*[ \t]$')
10349 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'a ' > a</userinput>
10350 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'test with trailing whitespace'</userinput>
10351 adding a
10352 transaction abort!
10353 rollback completed
10354 abort: pretxncommit.whitespace hook exited with status 1
10355 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'a' > a</userinput>
10356 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'drop trailing whitespace and try again'</userinput>
10357 </screen>
10358 <!-- END ch09/hook.ws.simple -->
10361 <para id="x_235">In this example, we introduce a simple <literal role="hook" moreinfo="none">pretxncommit</literal> hook that checks for
10362 trailing whitespace. This hook is short, but not very
10363 helpful. It exits with an error status if a change adds a
10364 line with trailing whitespace to any file, but does not print
10365 any information that might help us to identify the offending
10366 file or line. It also has the nice property of not paying
10367 attention to unmodified lines; only lines that introduce new
10368 trailing whitespace cause problems.
10369 </para>
10371 <!-- BEGIN ch09/check_whitespace.py.lst -->
10372 <programlisting format="linespecific">#!/usr/bin/env python
10373 #
10374 # save as .hg/check_whitespace.py and make executable
10376 import re
10378 def trailing_whitespace(difflines):
10379 #
10380 linenum, header = 0, False
10382 for line in difflines:
10383 if header:
10384 # remember the name of the file that this diff affects
10385 m = re.match(r'(?:---|\+\+\+) ([^\t]+)', line)
10386 if m and m.group(1) != '/dev/null':
10387 filename = m.group(1).split('/', 1)[-1]
10388 if line.startswith('+++ '):
10389 header = False
10390 continue
10391 if line.startswith('diff '):
10392 header = True
10393 continue
10394 # hunk header - save the line number
10395 m = re.match(r'@@ -\d+,\d+ \+(\d+),', line)
10396 if m:
10397 linenum = int(m.group(1))
10398 continue
10399 # hunk body - check for an added line with trailing whitespace
10400 m = re.match(r'\+.*\s$', line)
10401 if m:
10402 yield filename, linenum
10403 if line and line[0] in ' +':
10404 linenum += 1
10406 if __name__ == '__main__':
10407 import os, sys
10409 added = 0
10410 for filename, linenum in trailing_whitespace(os.popen('hg export tip')):
10411 print >> sys.stderr, ('%s, line %d: trailing whitespace added' %
10412 (filename, linenum))
10413 added += 1
10414 if added:
10415 # save the commit message so we don't need to retype it
10416 os.system('hg tip --template "{desc}" > .hg/commit.save')
10417 print >> sys.stderr, 'commit message saved to .hg/commit.save'
10418 sys.exit(1)</programlisting>
10419 <!-- END ch09/check_whitespace.py.lst -->
10422 <para id="x_236">The above version is much more complex, but also more
10423 useful. It parses a unified diff to see if any lines add
10424 trailing whitespace, and prints the name of the file and the
10425 line number of each such occurrence. Even better, if the
10426 change adds trailing whitespace, this hook saves the commit
10427 comment and prints the name of the save file before exiting
10428 and telling Mercurial to roll the transaction back, so you can
10429 use the <option role="hg-opt-commit">-l filename</option>
10430 option to <command role="hg-cmd" moreinfo="none">hg commit</command> to reuse
10431 the saved commit message once you've corrected the problem.
10432 </para>
10434 <!-- BEGIN ch09/hook.ws.better -->
10435 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/hgrc</userinput>
10436 [hooks]
10437 pretxncommit.whitespace = .hg/check_whitespace.py
10438 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'a ' >> a</userinput>
10439 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'add new line with trailing whitespace'</userinput>
10440 a, line 2: trailing whitespace added
10441 commit message saved to .hg/commit.save
10442 transaction abort!
10443 rollback completed
10444 abort: pretxncommit.whitespace hook exited with status 1
10445 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">sed -i 's, *$,,' a</userinput>
10446 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -A -m 'trimmed trailing whitespace'</userinput>
10447 a, line 2: trailing whitespace added
10448 commit message saved to .hg/commit.save
10449 transaction abort!
10450 rollback completed
10451 abort: pretxncommit.whitespace hook exited with status 1
10452 </screen>
10453 <!-- END ch09/hook.ws.better -->
10456 <para id="x_237">As a final aside, note in the example above the
10457 use of <command moreinfo="none">sed</command>'s in-place editing feature to
10458 get rid of trailing whitespace from a file. This is concise
10459 and useful enough that I will reproduce it here (using
10460 <command moreinfo="none">perl</command> for good measure).</para>
10461 <programlisting format="linespecific">perl -pi -e 's,\s+$,,' filename</programlisting>
10463 </sect2>
10464 </sect1>
10465 <sect1>
10466 <title>Bundled hooks</title>
10468 <para id="x_238">Mercurial ships with several bundled hooks. You can find
10469 them in the <filename class="directory" moreinfo="none">hgext</filename>
10470 directory of a Mercurial source tree. If you are using a
10471 Mercurial binary package, the hooks will be located in the
10472 <filename class="directory" moreinfo="none">hgext</filename> directory of
10473 wherever your package installer put Mercurial.
10474 </para>
10476 <sect2>
10477 <title><literal role="hg-ext" moreinfo="none">acl</literal>—access
10478 control for parts of a repository</title>
10480 <para id="x_239">The <literal role="hg-ext" moreinfo="none">acl</literal> extension lets
10481 you control which remote users are allowed to push changesets
10482 to a networked server. You can protect any portion of a
10483 repository (including the entire repo), so that a specific
10484 remote user can push changes that do not affect the protected
10485 portion.
10486 </para>
10488 <para id="x_23a">This extension implements access control based on the
10489 identity of the user performing a push,
10490 <emphasis>not</emphasis> on who committed the changesets
10491 they're pushing. It makes sense to use this hook only if you
10492 have a locked-down server environment that authenticates
10493 remote users, and you want to be sure that only specific users
10494 are allowed to push changes to that server.
10495 </para>
10497 <sect3>
10498 <title>Configuring the <literal role="hook" moreinfo="none">acl</literal>
10499 hook</title>
10501 <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
10502 <literal role="hook" moreinfo="none">pretxnchangegroup</literal> hook. This
10503 lets it see which files are modified by each incoming
10504 changeset, and roll back a group of changesets if they
10505 modify <quote>forbidden</quote> files. Example:
10506 </para>
10507 <programlisting format="linespecific">[hooks]
10508 pretxnchangegroup.acl = python:hgext.acl.hook</programlisting>
10510 <para id="x_23c">The <literal role="hg-ext" moreinfo="none">acl</literal> extension is
10511 configured using three sections.
10512 </para>
10514 <para id="x_23d">The <literal role="rc-acl" moreinfo="none">acl</literal> section has
10515 only one entry, <envar role="rc-item-acl">sources</envar>,
10516 which lists the sources of incoming changesets that the hook
10517 should pay attention to. You don't normally need to
10518 configure this section.
10519 </para>
10520 <itemizedlist>
10521 <listitem><para id="x_23e"><envar role="rc-item-acl">serve</envar>:
10522 Control incoming changesets that are arriving from a
10523 remote repository over http or ssh. This is the default
10524 value of <envar role="rc-item-acl">sources</envar>, and
10525 usually the only setting you'll need for this
10526 configuration item.
10527 </para>
10528 </listitem>
10529 <listitem><para id="x_23f"><envar role="rc-item-acl">pull</envar>:
10530 Control incoming changesets that are arriving via a pull
10531 from a local repository.
10532 </para>
10533 </listitem>
10534 <listitem><para id="x_240"><envar role="rc-item-acl">push</envar>:
10535 Control incoming changesets that are arriving via a push
10536 from a local repository.
10537 </para>
10538 </listitem>
10539 <listitem><para id="x_241"><envar role="rc-item-acl">bundle</envar>:
10540 Control incoming changesets that are arriving from
10541 another repository via a bundle.
10542 </para>
10543 </listitem></itemizedlist>
10545 <para id="x_242">The <literal role="rc-acl.allow" moreinfo="none">acl.allow</literal>
10546 section controls the users that are allowed to add
10547 changesets to the repository. If this section is not
10548 present, all users that are not explicitly denied are
10549 allowed. If this section is present, all users that are not
10550 explicitly allowed are denied (so an empty section means
10551 that all users are denied).
10552 </para>
10554 <para id="x_243">The <literal role="rc-acl.deny" moreinfo="none">acl.deny</literal>
10555 section determines which users are denied from adding
10556 changesets to the repository. If this section is not
10557 present or is empty, no users are denied.
10558 </para>
10560 <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
10561 identical. On the left of each entry is a glob pattern that
10562 matches files or directories, relative to the root of the
10563 repository; on the right, a user name.
10564 </para>
10566 <para id="x_245">In the following example, the user
10567 <literal moreinfo="none">docwriter</literal> can only push changes to the
10568 <filename class="directory" moreinfo="none">docs</filename> subtree of the
10569 repository, while <literal moreinfo="none">intern</literal> can push changes
10570 to any file or directory except <filename class="directory" moreinfo="none">source/sensitive</filename>.
10571 </para>
10572 <programlisting format="linespecific">[acl.allow]
10573 docs/** = docwriter
10574 [acl.deny]
10575 source/sensitive/** = intern</programlisting>
10577 </sect3>
10578 <sect3>
10579 <title>Testing and troubleshooting</title>
10581 <para id="x_246">If you want to test the <literal role="hg-ext" moreinfo="none">acl</literal> hook, run it with Mercurial's
10582 debugging output enabled. Since you'll probably be running
10583 it on a server where it's not convenient (or sometimes
10584 possible) to pass in the <option role="hg-opt-global">--debug</option> option, don't forget
10585 that you can enable debugging output in your <filename role="special" moreinfo="none">~/.hgrc</filename>:
10586 </para>
10587 <programlisting format="linespecific">[ui]
10588 debug = true</programlisting>
10589 <para id="x_247">With this enabled, the <literal role="hg-ext" moreinfo="none">acl</literal> hook will print enough
10590 information to let you figure out why it is allowing or
10591 forbidding pushes from specific users.
10592 </para>
10594 </sect3> </sect2>
10596 <sect2>
10597 <title><literal role="hg-ext" moreinfo="none">bugzilla</literal>—integration with
10598 Bugzilla</title>
10600 <para id="x_248">The <literal role="hg-ext" moreinfo="none">bugzilla</literal> extension
10601 adds a comment to a Bugzilla bug whenever it finds a reference
10602 to that bug ID in a commit comment. You can install this hook
10603 on a shared server, so that any time a remote user pushes
10604 changes to this server, the hook gets run.
10605 </para>
10607 <para id="x_249">It adds a comment to the bug that looks like this (you can
10608 configure the contents of the comment—see below):
10609 </para>
10610 <programlisting format="linespecific">Changeset aad8b264143a, made by Joe User
10611 <joe.user@domain.com> in the frobnitz repository, refers
10612 to this bug. For complete details, see
10613 http://hg.domain.com/frobnitz?cmd=changeset;node=aad8b264143a
10614 Changeset description: Fix bug 10483 by guarding against some
10615 NULL pointers</programlisting>
10616 <para id="x_24a">The value of this hook is that it automates the process of
10617 updating a bug any time a changeset refers to it. If you
10618 configure the hook properly, it makes it easy for people to
10619 browse straight from a Bugzilla bug to a changeset that refers
10620 to that bug.
10621 </para>
10623 <para id="x_24b">You can use the code in this hook as a starting point for
10624 some more exotic Bugzilla integration recipes. Here are a few
10625 possibilities:
10626 </para>
10627 <itemizedlist>
10628 <listitem><para id="x_24c">Require that every changeset pushed to the
10629 server have a valid bug ID in its commit comment. In this
10630 case, you'd want to configure the hook as a <literal role="hook" moreinfo="none">pretxncommit</literal> hook. This would
10631 allow the hook to reject changes that didn't contain bug
10632 IDs.
10633 </para>
10634 </listitem>
10635 <listitem><para id="x_24d">Allow incoming changesets to automatically
10636 modify the <emphasis>state</emphasis> of a bug, as well as
10637 simply adding a comment. For example, the hook could
10638 recognise the string <quote>fixed bug 31337</quote> as
10639 indicating that it should update the state of bug 31337 to
10640 <quote>requires testing</quote>.
10641 </para>
10642 </listitem></itemizedlist>
10644 <sect3 id="sec:hook:bugzilla:config">
10645 <title>Configuring the <literal role="hook" moreinfo="none">bugzilla</literal>
10646 hook</title>
10648 <para id="x_24e">You should configure this hook in your server's
10649 <filename role="special" moreinfo="none">~/.hgrc</filename> as an <literal role="hook" moreinfo="none">incoming</literal> hook, for example as
10650 follows:
10651 </para>
10652 <programlisting format="linespecific">[hooks]
10653 incoming.bugzilla = python:hgext.bugzilla.hook</programlisting>
10655 <para id="x_24f">Because of the specialised nature of this hook, and
10656 because Bugzilla was not written with this kind of
10657 integration in mind, configuring this hook is a somewhat
10658 involved process.
10659 </para>
10661 <para id="x_250">Before you begin, you must install the MySQL bindings
10662 for Python on the host(s) where you'll be running the hook.
10663 If this is not available as a binary package for your
10664 system, you can download it from
10665 <citation>web:mysql-python</citation>.
10666 </para>
10668 <para id="x_251">Configuration information for this hook lives in the
10669 <literal role="rc-bugzilla" moreinfo="none">bugzilla</literal> section of
10670 your <filename role="special" moreinfo="none">~/.hgrc</filename>.
10671 </para>
10672 <itemizedlist>
10673 <listitem><para id="x_252"><envar role="rc-item-bugzilla">version</envar>: The version
10674 of Bugzilla installed on the server. The database
10675 schema that Bugzilla uses changes occasionally, so this
10676 hook has to know exactly which schema to use.</para>
10677 </listitem>
10678 <listitem><para id="x_253"><envar role="rc-item-bugzilla">host</envar>:
10679 The hostname of the MySQL server that stores your
10680 Bugzilla data. The database must be configured to allow
10681 connections from whatever host you are running the
10682 <literal role="hook" moreinfo="none">bugzilla</literal> hook on.
10683 </para>
10684 </listitem>
10685 <listitem><para id="x_254"><envar role="rc-item-bugzilla">user</envar>:
10686 The username with which to connect to the MySQL server.
10687 The database must be configured to allow this user to
10688 connect from whatever host you are running the <literal role="hook" moreinfo="none">bugzilla</literal> hook on. This user
10689 must be able to access and modify Bugzilla tables. The
10690 default value of this item is <literal moreinfo="none">bugs</literal>,
10691 which is the standard name of the Bugzilla user in a
10692 MySQL database.
10693 </para>
10694 </listitem>
10695 <listitem><para id="x_255"><envar role="rc-item-bugzilla">password</envar>: The MySQL
10696 password for the user you configured above. This is
10697 stored as plain text, so you should make sure that
10698 unauthorised users cannot read the <filename role="special" moreinfo="none">~/.hgrc</filename> file where you
10699 store this information.
10700 </para>
10701 </listitem>
10702 <listitem><para id="x_256"><envar role="rc-item-bugzilla">db</envar>:
10703 The name of the Bugzilla database on the MySQL server.
10704 The default value of this item is
10705 <literal moreinfo="none">bugs</literal>, which is the standard name of
10706 the MySQL database where Bugzilla stores its data.
10707 </para>
10708 </listitem>
10709 <listitem><para id="x_257"><envar role="rc-item-bugzilla">notify</envar>: If you want
10710 Bugzilla to send out a notification email to subscribers
10711 after this hook has added a comment to a bug, you will
10712 need this hook to run a command whenever it updates the
10713 database. The command to run depends on where you have
10714 installed Bugzilla, but it will typically look something
10715 like this, if you have Bugzilla installed in <filename class="directory" moreinfo="none">/var/www/html/bugzilla</filename>:
10716 </para>
10717 <programlisting format="linespecific">cd /var/www/html/bugzilla &&
10718 ./processmail %s nobody@nowhere.com</programlisting>
10719 </listitem>
10720 <listitem><para id="x_258"> The Bugzilla
10721 <literal moreinfo="none">processmail</literal> program expects to be
10722 given a bug ID (the hook replaces
10723 <quote><literal moreinfo="none">%s</literal></quote> with the bug ID)
10724 and an email address. It also expects to be able to
10725 write to some files in the directory that it runs in.
10726 If Bugzilla and this hook are not installed on the same
10727 machine, you will need to find a way to run
10728 <literal moreinfo="none">processmail</literal> on the server where
10729 Bugzilla is installed.
10730 </para>
10731 </listitem></itemizedlist>
10733 </sect3>
10734 <sect3>
10735 <title>Mapping committer names to Bugzilla user names</title>
10737 <para id="x_259">By default, the <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook tries to use the
10738 email address of a changeset's committer as the Bugzilla
10739 user name with which to update a bug. If this does not suit
10740 your needs, you can map committer email addresses to
10741 Bugzilla user names using a <literal role="rc-usermap" moreinfo="none">usermap</literal> section.
10742 </para>
10744 <para id="x_25a">Each item in the <literal role="rc-usermap" moreinfo="none">usermap</literal> section contains an
10745 email address on the left, and a Bugzilla user name on the
10746 right.
10747 </para>
10748 <programlisting format="linespecific">[usermap]
10749 jane.user@example.com = jane</programlisting>
10750 <para id="x_25b">You can either keep the <literal role="rc-usermap" moreinfo="none">usermap</literal> data in a normal
10751 <filename role="special" moreinfo="none">~/.hgrc</filename>, or tell the
10752 <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook to read the
10753 information from an external <filename moreinfo="none">usermap</filename>
10754 file. In the latter case, you can store
10755 <filename moreinfo="none">usermap</filename> data by itself in (for example)
10756 a user-modifiable repository. This makes it possible to let
10757 your users maintain their own <envar role="rc-item-bugzilla">usermap</envar> entries. The main
10758 <filename role="special" moreinfo="none">~/.hgrc</filename> file might look
10759 like this:
10760 </para>
10761 <programlisting format="linespecific"># regular hgrc file refers to external usermap file
10762 [bugzilla]
10763 usermap = /home/hg/repos/userdata/bugzilla-usermap.conf</programlisting>
10764 <para id="x_25c">While the <filename moreinfo="none">usermap</filename> file that it
10765 refers to might look like this:
10766 </para>
10767 <programlisting format="linespecific"># bugzilla-usermap.conf - inside a hg repository
10768 [usermap] stephanie@example.com = steph</programlisting>
10770 </sect3>
10771 <sect3>
10772 <title>Configuring the text that gets added to a bug</title>
10774 <para id="x_25d">You can configure the text that this hook adds as a
10775 comment; you specify it in the form of a Mercurial template.
10776 Several <filename role="special" moreinfo="none">~/.hgrc</filename> entries
10777 (still in the <literal role="rc-bugzilla" moreinfo="none">bugzilla</literal>
10778 section) control this behavior.
10779 </para>
10780 <itemizedlist>
10781 <listitem><para id="x_25e"><literal moreinfo="none">strip</literal>: The number of
10782 leading path elements to strip from a repository's path
10783 name to construct a partial path for a URL. For example,
10784 if the repositories on your server live under <filename class="directory" moreinfo="none">/home/hg/repos</filename>, and you
10785 have a repository whose path is <filename class="directory" moreinfo="none">/home/hg/repos/app/tests</filename>,
10786 then setting <literal moreinfo="none">strip</literal> to
10787 <literal moreinfo="none">4</literal> will give a partial path of
10788 <filename class="directory" moreinfo="none">app/tests</filename>. The
10789 hook will make this partial path available when
10790 expanding a template, as <literal moreinfo="none">webroot</literal>.
10791 </para>
10792 </listitem>
10793 <listitem><para id="x_25f"><literal moreinfo="none">template</literal>: The text of the
10794 template to use. In addition to the usual
10795 changeset-related variables, this template can use
10796 <literal moreinfo="none">hgweb</literal> (the value of the
10797 <literal moreinfo="none">hgweb</literal> configuration item above) and
10798 <literal moreinfo="none">webroot</literal> (the path constructed using
10799 <literal moreinfo="none">strip</literal> above).
10800 </para>
10801 </listitem></itemizedlist>
10803 <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
10804 available when expanding a template, as the base string to
10805 use when constructing a URL that will let users browse from
10806 a Bugzilla comment to view a changeset. Example:
10807 </para>
10808 <programlisting format="linespecific">[web]
10809 baseurl = http://hg.domain.com/</programlisting>
10811 <para id="x_261">Here is an example set of <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook config information.
10812 </para>
10814 <!-- BEGIN ch10/bugzilla-config.lst -->
10815 <programlisting format="linespecific">[bugzilla]
10816 host = bugzilla.example.com
10817 password = mypassword version = 2.16
10818 # server-side repos live in /home/hg/repos, so strip 4 leading
10819 # separators
10820 strip = 4
10821 hgweb = http://hg.example.com/
10822 usermap = /home/hg/repos/notify/bugzilla.conf
10823 template = Changeset {node|short}, made by {author} in the {webroot}
10824 repo, refers to this bug.\n
10825 For complete details, see
10826 {hgweb}{webroot}?cmd=changeset;node={node|short}\n
10827 Changeset description:\n
10828 \t{desc|tabindent}</programlisting>
10829 <!-- END ch10/bugzilla-config.lst -->
10832 </sect3>
10833 <sect3>
10834 <title>Testing and troubleshooting</title>
10836 <para id="x_262">The most common problems with configuring the <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook relate to running
10837 Bugzilla's <filename moreinfo="none">processmail</filename> script and
10838 mapping committer names to user names.
10839 </para>
10841 <para id="x_263">Recall from <xref linkend="sec:hook:bugzilla:config"/> above that the user
10842 that runs the Mercurial process on the server is also the
10843 one that will run the <filename moreinfo="none">processmail</filename>
10844 script. The <filename moreinfo="none">processmail</filename> script
10845 sometimes causes Bugzilla to write to files in its
10846 configuration directory, and Bugzilla's configuration files
10847 are usually owned by the user that your web server runs
10848 under.
10849 </para>
10851 <para id="x_264">You can cause <filename moreinfo="none">processmail</filename> to be run
10852 with the suitable user's identity using the
10853 <command moreinfo="none">sudo</command> command. Here is an example entry
10854 for a <filename moreinfo="none">sudoers</filename> file.
10855 </para>
10856 <programlisting format="linespecific">hg_user = (httpd_user)
10857 NOPASSWD: /var/www/html/bugzilla/processmail-wrapper %s</programlisting>
10858 <para id="x_265">This allows the <literal moreinfo="none">hg_user</literal> user to run a
10859 <filename moreinfo="none">processmail-wrapper</filename> program under the
10860 identity of <literal moreinfo="none">httpd_user</literal>.
10861 </para>
10863 <para id="x_266">This indirection through a wrapper script is necessary,
10864 because <filename moreinfo="none">processmail</filename> expects to be run
10865 with its current directory set to wherever you installed
10866 Bugzilla; you can't specify that kind of constraint in a
10867 <filename moreinfo="none">sudoers</filename> file. The contents of the
10868 wrapper script are simple:
10869 </para>
10870 <programlisting format="linespecific">#!/bin/sh
10871 cd `dirname $0` && ./processmail "$1" nobody@example.com</programlisting>
10872 <para id="x_267">It doesn't seem to matter what email address you pass to
10873 <filename moreinfo="none">processmail</filename>.
10874 </para>
10876 <para id="x_268">If your <literal role="rc-usermap" moreinfo="none">usermap</literal> is
10877 not set up correctly, users will see an error message from
10878 the <literal role="hg-ext" moreinfo="none">bugzilla</literal> hook when they
10879 push changes to the server. The error message will look
10880 like this:
10881 </para>
10882 <programlisting format="linespecific">cannot find bugzilla user id for john.q.public@example.com</programlisting>
10883 <para id="x_269">What this means is that the committer's address,
10884 <literal moreinfo="none">john.q.public@example.com</literal>, is not a valid
10885 Bugzilla user name, nor does it have an entry in your
10886 <literal role="rc-usermap" moreinfo="none">usermap</literal> that maps it to
10887 a valid Bugzilla user name.
10888 </para>
10890 </sect3> </sect2>
10892 <sect2>
10893 <title><literal role="hg-ext" moreinfo="none">notify</literal>—send email
10894 notifications</title>
10896 <para id="x_26a">Although Mercurial's built-in web server provides RSS
10897 feeds of changes in every repository, many people prefer to
10898 receive change notifications via email. The <literal role="hg-ext" moreinfo="none">notify</literal> hook lets you send out
10899 notifications to a set of email addresses whenever changesets
10900 arrive that those subscribers are interested in.
10901 </para>
10903 <para id="x_26b">As with the <literal role="hg-ext" moreinfo="none">bugzilla</literal>
10904 hook, the <literal role="hg-ext" moreinfo="none">notify</literal> hook is
10905 template-driven, so you can customise the contents of the
10906 notification messages that it sends.
10907 </para>
10909 <para id="x_26c">By default, the <literal role="hg-ext" moreinfo="none">notify</literal>
10910 hook includes a diff of every changeset that it sends out; you
10911 can limit the size of the diff, or turn this feature off
10912 entirely. It is useful for letting subscribers review changes
10913 immediately, rather than clicking to follow a URL.
10914 </para>
10916 <sect3>
10917 <title>Configuring the <literal role="hg-ext" moreinfo="none">notify</literal>
10918 hook</title>
10920 <para id="x_26d">You can set up the <literal role="hg-ext" moreinfo="none">notify</literal> hook to send one email
10921 message per incoming changeset, or one per incoming group of
10922 changesets (all those that arrived in a single pull or
10923 push).
10924 </para>
10925 <programlisting format="linespecific">[hooks]
10926 # send one email per group of changes
10927 changegroup.notify = python:hgext.notify.hook
10928 # send one email per change
10929 incoming.notify = python:hgext.notify.hook</programlisting>
10931 <para id="x_26e">Configuration information for this hook lives in the
10932 <literal role="rc-notify" moreinfo="none">notify</literal> section of a
10933 <filename role="special" moreinfo="none">~/.hgrc</filename> file.
10934 </para>
10935 <itemizedlist>
10936 <listitem><para id="x_26f"><envar role="rc-item-notify">test</envar>:
10937 By default, this hook does not send out email at all;
10938 instead, it prints the message that it
10939 <emphasis>would</emphasis> send. Set this item to
10940 <literal moreinfo="none">false</literal> to allow email to be sent. The
10941 reason that sending of email is turned off by default is
10942 that it takes several tries to configure this extension
10943 exactly as you would like, and it would be bad form to
10944 spam subscribers with a number of <quote>broken</quote>
10945 notifications while you debug your configuration.
10946 </para>
10947 </listitem>
10948 <listitem><para id="x_270"><envar role="rc-item-notify">config</envar>:
10949 The path to a configuration file that contains
10950 subscription information. This is kept separate from
10951 the main <filename role="special" moreinfo="none">~/.hgrc</filename> so
10952 that you can maintain it in a repository of its own.
10953 People can then clone that repository, update their
10954 subscriptions, and push the changes back to your server.
10955 </para>
10956 </listitem>
10957 <listitem><para id="x_271"><envar role="rc-item-notify">strip</envar>:
10958 The number of leading path separator characters to strip
10959 from a repository's path, when deciding whether a
10960 repository has subscribers. For example, if the
10961 repositories on your server live in <filename class="directory" moreinfo="none">/home/hg/repos</filename>, and
10962 <literal role="hg-ext" moreinfo="none">notify</literal> is considering a
10963 repository named <filename class="directory" moreinfo="none">/home/hg/repos/shared/test</filename>,
10964 setting <envar role="rc-item-notify">strip</envar> to
10965 <literal moreinfo="none">4</literal> will cause <literal role="hg-ext" moreinfo="none">notify</literal> to trim the path it
10966 considers down to <filename class="directory" moreinfo="none">shared/test</filename>, and it will
10967 match subscribers against that.
10968 </para>
10969 </listitem>
10970 <listitem><para id="x_272"><envar role="rc-item-notify">template</envar>: The template
10971 text to use when sending messages. This specifies both
10972 the contents of the message header and its body.
10973 </para>
10974 </listitem>
10975 <listitem><para id="x_273"><envar role="rc-item-notify">maxdiff</envar>: The maximum
10976 number of lines of diff data to append to the end of a
10977 message. If a diff is longer than this, it is
10978 truncated. By default, this is set to 300. Set this to
10979 <literal moreinfo="none">0</literal> to omit diffs from notification
10980 emails.
10981 </para>
10982 </listitem>
10983 <listitem><para id="x_274"><envar role="rc-item-notify">sources</envar>: A list of
10984 sources of changesets to consider. This lets you limit
10985 <literal role="hg-ext" moreinfo="none">notify</literal> to only sending
10986 out email about changes that remote users pushed into
10987 this repository via a server, for example. See
10988 <xref linkend="sec:hook:sources"/> for the sources you
10989 can specify here.
10990 </para>
10991 </listitem></itemizedlist>
10993 <para id="x_275">If you set the <envar role="rc-item-web">baseurl</envar>
10994 item in the <literal role="rc-web" moreinfo="none">web</literal> section,
10995 you can use it in a template; it will be available as
10996 <literal moreinfo="none">webroot</literal>.
10997 </para>
10999 <para id="x_276">Here is an example set of <literal role="hg-ext" moreinfo="none">notify</literal> configuration information.
11000 </para>
11002 <!-- BEGIN ch10/notify-config.lst -->
11003 <programlisting format="linespecific">[notify]
11004 # really send email
11005 test = false
11006 # subscriber data lives in the notify repo
11007 config = /home/hg/repos/notify/notify.conf
11008 # repos live in /home/hg/repos on server, so strip 4 "/" chars
11009 strip = 4
11010 template = X-Hg-Repo: {webroot}\n
11011 Subject: {webroot}: {desc|firstline|strip}\n
11012 From: {author}
11013 \n\n
11014 changeset {node|short} in {root}
11015 \n\ndetails:
11016 {baseurl}{webroot}?cmd=changeset;node={node|short}
11017 description: {desc|tabindent|strip}
11019 [web]
11020 baseurl =
11021 http://hg.example.com/</programlisting>
11022 <!-- END ch10/notify-config.lst -->
11025 <para id="x_277">This will produce a message that looks like the
11026 following:
11027 </para>
11029 <!-- BEGIN ch10/notify-config-mail.lst -->
11030 <programlisting format="linespecific">X-Hg-Repo: tests/slave
11031 Subject: tests/slave: Handle error case when slave has no buffers
11032 Date: Wed, 2 Aug 2006 15:25:46 -0700 (PDT)
11034 changeset 3cba9bfe74b5 in /home/hg/repos/tests/slave
11036 details:
11037 http://hg.example.com/tests/slave?cmd=changeset;node=3cba9bfe74b5
11039 description: Handle error case when slave has no buffers
11041 diffs (54 lines):
11042 diff -r 9d95df7cf2ad -r 3cba9bfe74b5 include/tests.h
11043 --- a/include/tests.h Wed Aug 02 15:19:52 2006 -0700
11044 +++ b/include/tests.h Wed Aug 02 15:25:26 2006 -0700
11045 @@ -212,6 +212,15 @@ static __inline__
11046 void test_headers(void *h)
11047 [...snip...]</programlisting>
11048 <!-- END ch10/notify-config-mail.lst -->
11051 </sect3>
11052 <sect3>
11053 <title>Testing and troubleshooting</title>
11055 <para id="x_278">Do not forget that by default, the <literal role="hg-ext" moreinfo="none">notify</literal> extension <emphasis>will not
11056 send any mail</emphasis> until you explicitly configure it to do so,
11057 by setting <envar role="rc-item-notify">test</envar> to
11058 <literal moreinfo="none">false</literal>. Until you do that, it simply
11059 prints the message it <emphasis>would</emphasis> send.
11060 </para>
11062 </sect3>
11063 </sect2>
11064 </sect1>
11065 <sect1 id="sec:hook:ref">
11066 <title>Information for writers of hooks</title>
11068 <sect2>
11069 <title>In-process hook execution</title>
11071 <para id="x_279">An in-process hook is called with arguments of the
11072 following form:
11073 </para>
11074 <programlisting format="linespecific">def myhook(ui, repo, **kwargs): pass</programlisting>
11075 <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
11076 <literal moreinfo="none">repo</literal> parameter is a <literal role="py-mod-mercurial.localrepo" moreinfo="none">localrepository</literal>
11077 object. The names and values of the
11078 <literal moreinfo="none">**kwargs</literal> parameters depend on the hook
11079 being invoked, with the following common features:
11080 </para>
11081 <itemizedlist>
11082 <listitem><para id="x_27b">If a parameter is named
11083 <literal moreinfo="none">node</literal> or <literal moreinfo="none">parentN</literal>, it
11084 will contain a hexadecimal changeset ID. The empty string
11085 is used to represent <quote>null changeset ID</quote>
11086 instead of a string of zeroes.
11087 </para>
11088 </listitem>
11089 <listitem><para id="x_27c">If a parameter is named
11090 <literal moreinfo="none">url</literal>, it will contain the URL of a
11091 remote repository, if that can be determined.
11092 </para>
11093 </listitem>
11094 <listitem><para id="x_27d">Boolean-valued parameters are represented as
11095 Python <literal moreinfo="none">bool</literal> objects.
11096 </para>
11097 </listitem></itemizedlist>
11099 <para id="x_27e">An in-process hook is called without a change to the
11100 process's working directory (unlike external hooks, which are
11101 run in the root of the repository). It must not change the
11102 process's working directory, or it will cause any calls it
11103 makes into the Mercurial API to fail.
11104 </para>
11106 <para id="x_27f">If a hook returns a boolean <quote>false</quote> value, it
11107 is considered to have succeeded. If it returns a boolean
11108 <quote>true</quote> value or raises an exception, it is
11109 considered to have failed. A useful way to think of the
11110 calling convention is <quote>tell me if you fail</quote>.
11111 </para>
11113 <para id="x_280">Note that changeset IDs are passed into Python hooks as
11114 hexadecimal strings, not the binary hashes that Mercurial's
11115 APIs normally use. To convert a hash from hex to binary, use
11116 the <literal moreinfo="none">bin</literal> function.
11117 </para>
11118 </sect2>
11120 <sect2>
11121 <title>External hook execution</title>
11123 <para id="x_281">An external hook is passed to the shell of the user
11124 running Mercurial. Features of that shell, such as variable
11125 substitution and command redirection, are available. The hook
11126 is run in the root directory of the repository (unlike
11127 in-process hooks, which are run in the same directory that
11128 Mercurial was run in).
11129 </para>
11131 <para id="x_282">Hook parameters are passed to the hook as environment
11132 variables. Each environment variable's name is converted in
11133 upper case and prefixed with the string
11134 <quote><literal moreinfo="none">HG_</literal></quote>. For example, if the
11135 name of a parameter is <quote><literal moreinfo="none">node</literal></quote>,
11136 the name of the environment variable representing that
11137 parameter will be <quote><literal moreinfo="none">HG_NODE</literal></quote>.
11138 </para>
11140 <para id="x_283">A boolean parameter is represented as the string
11141 <quote><literal moreinfo="none">1</literal></quote> for <quote>true</quote>,
11142 <quote><literal moreinfo="none">0</literal></quote> for <quote>false</quote>.
11143 If an environment variable is named <envar>HG_NODE</envar>,
11144 <envar>HG_PARENT1</envar> or <envar>HG_PARENT2</envar>, it
11145 contains a changeset ID represented as a hexadecimal string.
11146 The empty string is used to represent <quote>null changeset
11147 ID</quote> instead of a string of zeroes. If an environment
11148 variable is named <envar>HG_URL</envar>, it will contain the
11149 URL of a remote repository, if that can be determined.
11150 </para>
11152 <para id="x_284">If a hook exits with a status of zero, it is considered to
11153 have succeeded. If it exits with a non-zero status, it is
11154 considered to have failed.
11155 </para>
11156 </sect2>
11158 <sect2>
11159 <title>Finding out where changesets come from</title>
11161 <para id="x_285">A hook that involves the transfer of changesets between a
11162 local repository and another may be able to find out
11163 information about the <quote>far side</quote>. Mercurial
11164 knows <emphasis>how</emphasis> changes are being transferred,
11165 and in many cases <emphasis>where</emphasis> they are being
11166 transferred to or from.
11167 </para>
11169 <sect3 id="sec:hook:sources">
11170 <title>Sources of changesets</title>
11172 <para id="x_286">Mercurial will tell a hook what means are, or were, used
11173 to transfer changesets between repositories. This is
11174 provided by Mercurial in a Python parameter named
11175 <literal moreinfo="none">source</literal>, or an environment variable named
11176 <envar>HG_SOURCE</envar>.
11177 </para>
11179 <itemizedlist>
11180 <listitem><para id="x_287"><literal moreinfo="none">serve</literal>: Changesets are
11181 transferred to or from a remote repository over http or
11182 ssh.
11183 </para>
11184 </listitem>
11185 <listitem><para id="x_288"><literal moreinfo="none">pull</literal>: Changesets are
11186 being transferred via a pull from one repository into
11187 another.
11188 </para>
11189 </listitem>
11190 <listitem><para id="x_289"><literal moreinfo="none">push</literal>: Changesets are
11191 being transferred via a push from one repository into
11192 another.
11193 </para>
11194 </listitem>
11195 <listitem><para id="x_28a"><literal moreinfo="none">bundle</literal>: Changesets are
11196 being transferred to or from a bundle.
11197 </para>
11198 </listitem></itemizedlist>
11199 </sect3>
11201 <sect3 id="sec:hook:url">
11202 <title>Where changes are going—remote repository
11203 URLs</title>
11205 <para id="x_28b">When possible, Mercurial will tell a hook the location
11206 of the <quote>far side</quote> of an activity that transfers
11207 changeset data between repositories. This is provided by
11208 Mercurial in a Python parameter named
11209 <literal moreinfo="none">url</literal>, or an environment variable named
11210 <envar>HG_URL</envar>.
11211 </para>
11213 <para id="x_28c">This information is not always known. If a hook is
11214 invoked in a repository that is being served via http or
11215 ssh, Mercurial cannot tell where the remote repository is,
11216 but it may know where the client is connecting from. In
11217 such cases, the URL will take one of the following forms:
11218 </para>
11219 <itemizedlist>
11220 <listitem><para id="x_28d"><literal moreinfo="none">remote:ssh:1.2.3.4</literal>—remote
11221 ssh client, at the IP address
11222 <literal moreinfo="none">1.2.3.4</literal>.
11223 </para>
11224 </listitem>
11225 <listitem><para id="x_28e"><literal moreinfo="none">remote:http:1.2.3.4</literal>—remote
11226 http client, at the IP address
11227 <literal moreinfo="none">1.2.3.4</literal>. If the client is using SSL,
11228 this will be of the form
11229 <literal moreinfo="none">remote:https:1.2.3.4</literal>.
11230 </para>
11231 </listitem>
11232 <listitem><para id="x_28f">Empty—no information could be
11233 discovered about the remote client.
11234 </para>
11235 </listitem></itemizedlist>
11236 </sect3>
11237 </sect2>
11238 </sect1>
11239 <sect1>
11240 <title>Hook reference</title>
11242 <sect2 id="sec:hook:changegroup">
11243 <title><literal role="hook" moreinfo="none">changegroup</literal>—after
11244 remote changesets added</title>
11246 <para id="x_290">This hook is run after a group of pre-existing changesets
11247 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
11248 unbundle</command>. This hook is run once per operation
11249 that added one or more changesets. This is in contrast to the
11250 <literal role="hook" moreinfo="none">incoming</literal> hook, which is run
11251 once per changeset, regardless of whether the changesets
11252 arrive in a group.
11253 </para>
11255 <para id="x_291">Some possible uses for this hook include kicking off an
11256 automated build or test of the added changesets, updating a
11257 bug database, or notifying subscribers that a repository
11258 contains new changes.
11259 </para>
11261 <para id="x_292">Parameters to this hook:
11262 </para>
11263 <itemizedlist>
11264 <listitem><para id="x_293"><literal moreinfo="none">node</literal>: A changeset ID. The
11265 changeset ID of the first changeset in the group that was
11266 added. All changesets between this and
11267 <literal role="tag" moreinfo="none">tip</literal>, inclusive, were added by a single
11268 <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>.
11269 </para>
11270 </listitem>
11271 <listitem><para id="x_294"><literal moreinfo="none">source</literal>: A
11272 string. The source of these changes. See <xref linkend="sec:hook:sources"/> for details.
11273 </para>
11274 </listitem>
11275 <listitem><para id="x_295"><literal moreinfo="none">url</literal>: A URL. The
11276 location of the remote repository, if known. See <xref linkend="sec:hook:url"/> for more information.
11277 </para>
11278 </listitem></itemizedlist>
11280 <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"/>)
11281 </para>
11282 </sect2>
11284 <sect2 id="sec:hook:commit">
11285 <title><literal role="hook" moreinfo="none">commit</literal>—after a new
11286 changeset is created</title>
11288 <para id="x_297">This hook is run after a new changeset has been created.
11289 </para>
11291 <para id="x_298">Parameters to this hook:
11292 </para>
11293 <itemizedlist>
11294 <listitem><para id="x_299"><literal moreinfo="none">node</literal>: A changeset ID. The
11295 changeset ID of the newly committed changeset.
11296 </para>
11297 </listitem>
11298 <listitem><para id="x_29a"><literal moreinfo="none">parent1</literal>: A changeset ID.
11299 The changeset ID of the first parent of the newly
11300 committed changeset.
11301 </para>
11302 </listitem>
11303 <listitem><para id="x_29b"><literal moreinfo="none">parent2</literal>: A changeset ID.
11304 The changeset ID of the second parent of the newly
11305 committed changeset.
11306 </para>
11307 </listitem></itemizedlist>
11309 <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"/>)
11310 </para>
11311 </sect2>
11313 <sect2 id="sec:hook:incoming">
11314 <title><literal role="hook" moreinfo="none">incoming</literal>—after one
11315 remote changeset is added</title>
11317 <para id="x_29d">This hook is run after a pre-existing changeset has been
11318 added to the repository, for example via a <command role="hg-cmd" moreinfo="none">hg push</command>. If a group of changesets
11319 was added in a single operation, this hook is called once for
11320 each added changeset.
11321 </para>
11323 <para id="x_29e">You can use this hook for the same purposes as
11324 the <literal role="hook" moreinfo="none">changegroup</literal> hook (<xref linkend="sec:hook:changegroup"/>); it's simply more
11325 convenient sometimes to run a hook once per group of
11326 changesets, while other times it's handier once per changeset.
11327 </para>
11329 <para id="x_29f">Parameters to this hook:
11330 </para>
11331 <itemizedlist>
11332 <listitem><para id="x_2a0"><literal moreinfo="none">node</literal>: A changeset ID. The
11333 ID of the newly added changeset.
11334 </para>
11335 </listitem>
11336 <listitem><para id="x_2a1"><literal moreinfo="none">source</literal>: A
11337 string. The source of these changes. See <xref linkend="sec:hook:sources"/> for details.
11338 </para>
11339 </listitem>
11340 <listitem><para id="x_2a2"><literal moreinfo="none">url</literal>: A URL. The
11341 location of the remote repository, if known. See <xref linkend="sec:hook:url"/> for more information.
11342 </para>
11343 </listitem></itemizedlist>
11345 <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"/>)
11346 </para>
11347 </sect2>
11349 <sect2 id="sec:hook:outgoing">
11350 <title><literal role="hook" moreinfo="none">outgoing</literal>—after
11351 changesets are propagated</title>
11353 <para id="x_2a4">This hook is run after a group of changesets has been
11354 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
11355 bundle</command> command.
11356 </para>
11358 <para id="x_2a5">One possible use for this hook is to notify administrators
11359 that changes have been pulled.
11360 </para>
11362 <para id="x_2a6">Parameters to this hook:
11363 </para>
11364 <itemizedlist>
11365 <listitem><para id="x_2a7"><literal moreinfo="none">node</literal>: A changeset ID. The
11366 changeset ID of the first changeset of the group that was
11367 sent.
11368 </para>
11369 </listitem>
11370 <listitem><para id="x_2a8"><literal moreinfo="none">source</literal>: A string. The
11371 source of the of the operation (see <xref linkend="sec:hook:sources"/>). If a remote
11372 client pulled changes from this repository,
11373 <literal moreinfo="none">source</literal> will be
11374 <literal moreinfo="none">serve</literal>. If the client that obtained
11375 changes from this repository was local,
11376 <literal moreinfo="none">source</literal> will be
11377 <literal moreinfo="none">bundle</literal>, <literal moreinfo="none">pull</literal>, or
11378 <literal moreinfo="none">push</literal>, depending on the operation the
11379 client performed.
11380 </para>
11381 </listitem>
11382 <listitem><para id="x_2a9"><literal moreinfo="none">url</literal>: A URL. The
11383 location of the remote repository, if known. See <xref linkend="sec:hook:url"/> for more information.
11384 </para>
11385 </listitem></itemizedlist>
11387 <para id="x_2aa">See also: <literal role="hook" moreinfo="none">preoutgoing</literal> (<xref linkend="sec:hook:preoutgoing"/>)
11388 </para>
11389 </sect2>
11391 <sect2 id="sec:hook:prechangegroup">
11392 <title><literal role="hook" moreinfo="none">prechangegroup</literal>—before starting
11393 to add remote changesets</title>
11395 <para id="x_2ab">This controlling hook is run before Mercurial begins to
11396 add a group of changesets from another repository.
11397 </para>
11399 <para id="x_2ac">This hook does not have any information about the
11400 changesets to be added, because it is run before transmission
11401 of those changesets is allowed to begin. If this hook fails,
11402 the changesets will not be transmitted.
11403 </para>
11405 <para id="x_2ad">One use for this hook is to prevent external changes from
11406 being added to a repository. For example, you could use this
11407 to <quote>freeze</quote> a server-hosted branch temporarily or
11408 permanently so that users cannot push to it, while still
11409 allowing a local administrator to modify the repository.
11410 </para>
11412 <para id="x_2ae">Parameters to this hook:
11413 </para>
11414 <itemizedlist>
11415 <listitem><para id="x_2af"><literal moreinfo="none">source</literal>: A string. The
11416 source of these changes. See <xref linkend="sec:hook:sources"/> for details.
11417 </para>
11418 </listitem>
11419 <listitem><para id="x_2b0"><literal moreinfo="none">url</literal>: A URL. The
11420 location of the remote repository, if known. See <xref linkend="sec:hook:url"/> for more information.
11421 </para>
11422 </listitem></itemizedlist>
11424 <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"/>)
11425 </para>
11426 </sect2>
11428 <sect2 id="sec:hook:precommit">
11429 <title><literal role="hook" moreinfo="none">precommit</literal>—before
11430 starting to commit a changeset</title>
11432 <para id="x_2b2">This hook is run before Mercurial begins to commit a new
11433 changeset. It is run before Mercurial has any of the metadata
11434 for the commit, such as the files to be committed, the commit
11435 message, or the commit date.
11436 </para>
11438 <para id="x_2b3">One use for this hook is to disable the ability to commit
11439 new changesets, while still allowing incoming changesets.
11440 Another is to run a build or test, and only allow the commit
11441 to begin if the build or test succeeds.
11442 </para>
11444 <para id="x_2b4">Parameters to this hook:
11445 </para>
11446 <itemizedlist>
11447 <listitem><para id="x_2b5"><literal moreinfo="none">parent1</literal>: A changeset ID.
11448 The changeset ID of the first parent of the working
11449 directory.
11450 </para>
11451 </listitem>
11452 <listitem><para id="x_2b6"><literal moreinfo="none">parent2</literal>: A changeset ID.
11453 The changeset ID of the second parent of the working
11454 directory.
11455 </para>
11456 </listitem></itemizedlist>
11457 <para id="x_2b7">If the commit proceeds, the parents of the working
11458 directory will become the parents of the new changeset.
11459 </para>
11461 <para id="x_2b8">See also: <literal role="hook" moreinfo="none">commit</literal>
11462 (<xref linkend="sec:hook:commit"/>), <literal role="hook" moreinfo="none">pretxncommit</literal> (<xref linkend="sec:hook:pretxncommit"/>)
11463 </para>
11464 </sect2>
11466 <sect2 id="sec:hook:preoutgoing">
11467 <title><literal role="hook" moreinfo="none">preoutgoing</literal>—before
11468 starting to propagate changesets</title>
11470 <para id="x_2b9">This hook is invoked before Mercurial knows the identities
11471 of the changesets to be transmitted.
11472 </para>
11474 <para id="x_2ba">One use for this hook is to prevent changes from being
11475 transmitted to another repository.
11476 </para>
11478 <para id="x_2bb">Parameters to this hook:
11479 </para>
11480 <itemizedlist>
11481 <listitem><para id="x_2bc"><literal moreinfo="none">source</literal>: A
11482 string. The source of the operation that is attempting to
11483 obtain changes from this repository (see <xref linkend="sec:hook:sources"/>). See the documentation
11484 for the <literal moreinfo="none">source</literal> parameter to the
11485 <literal role="hook" moreinfo="none">outgoing</literal> hook, in
11486 <xref linkend="sec:hook:outgoing"/>, for possible values
11487 of this parameter.
11488 </para>
11489 </listitem>
11490 <listitem><para id="x_2bd"><literal moreinfo="none">url</literal>: A URL. The
11491 location of the remote repository, if known. See <xref linkend="sec:hook:url"/> for more information.
11492 </para>
11493 </listitem></itemizedlist>
11495 <para id="x_2be">See also: <literal role="hook" moreinfo="none">outgoing</literal> (<xref linkend="sec:hook:outgoing"/>)
11496 </para>
11497 </sect2>
11499 <sect2 id="sec:hook:pretag">
11500 <title><literal role="hook" moreinfo="none">pretag</literal>—before
11501 tagging a changeset</title>
11503 <para id="x_2bf">This controlling hook is run before a tag is created. If
11504 the hook succeeds, creation of the tag proceeds. If the hook
11505 fails, the tag is not created.
11506 </para>
11508 <para id="x_2c0">Parameters to this hook:
11509 </para>
11510 <itemizedlist>
11511 <listitem><para id="x_2c1"><literal moreinfo="none">local</literal>: A boolean. Whether
11512 the tag is local to this repository instance (i.e. stored
11513 in <filename role="special" moreinfo="none">.hg/localtags</filename>) or
11514 managed by Mercurial (stored in <filename role="special" moreinfo="none">.hgtags</filename>).
11515 </para>
11516 </listitem>
11517 <listitem><para id="x_2c2"><literal moreinfo="none">node</literal>: A changeset ID. The
11518 ID of the changeset to be tagged.
11519 </para>
11520 </listitem>
11521 <listitem><para id="x_2c3"><literal moreinfo="none">tag</literal>: A string. The name of
11522 the tag to be created.
11523 </para>
11524 </listitem></itemizedlist>
11526 <para id="x_2c4">If the tag to be created is
11527 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.
11528 </para>
11530 <para id="x_2c5">See also: <literal role="hook" moreinfo="none">tag</literal>
11531 (<xref linkend="sec:hook:tag"/>)
11532 </para>
11533 </sect2>
11535 <sect2 id="sec:hook:pretxnchangegroup">
11536 <title><literal role="hook" moreinfo="none">pretxnchangegroup</literal>—before
11537 completing addition of remote changesets</title>
11539 <para id="x_2c6">This controlling hook is run before a
11540 transaction—that manages the addition of a group of new
11541 changesets from outside the repository—completes. If
11542 the hook succeeds, the transaction completes, and all of the
11543 changesets become permanent within this repository. If the
11544 hook fails, the transaction is rolled back, and the data for
11545 the changesets is erased.
11546 </para>
11548 <para id="x_2c7">This hook can access the metadata associated with the
11549 almost-added changesets, but it should not do anything
11550 permanent with this data. It must also not modify the working
11551 directory.
11552 </para>
11554 <para id="x_2c8">While this hook is running, if other Mercurial processes
11555 access this repository, they will be able to see the
11556 almost-added changesets as if they are permanent. This may
11557 lead to race conditions if you do not take steps to avoid
11558 them.
11559 </para>
11561 <para id="x_2c9">This hook can be used to automatically vet a group of
11562 changesets. If the hook fails, all of the changesets are
11563 <quote>rejected</quote> when the transaction rolls back.
11564 </para>
11566 <para id="x_2ca">Parameters to this hook:
11567 </para>
11568 <itemizedlist>
11569 <listitem><para id="x_2cb"><literal moreinfo="none">node</literal>: A changeset ID. The
11570 changeset ID of the first changeset in the group that was
11571 added. All changesets between this and
11572 <literal role="tag" moreinfo="none">tip</literal>,
11573 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>.
11574 </para>
11575 </listitem>
11576 <listitem><para id="x_2cc"><literal moreinfo="none">source</literal>: A
11577 string. The source of these changes. See <xref linkend="sec:hook:sources"/> for details.
11578 </para>
11579 </listitem>
11580 <listitem><para id="x_2cd"><literal moreinfo="none">url</literal>: A URL. The
11581 location of the remote repository, if known. See <xref linkend="sec:hook:url"/> for more information.
11582 </para>
11583 </listitem></itemizedlist>
11585 <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"/>)
11586 </para>
11587 </sect2>
11589 <sect2 id="sec:hook:pretxncommit">
11590 <title><literal role="hook" moreinfo="none">pretxncommit</literal>—before
11591 completing commit of new changeset</title>
11593 <para id="x_2cf">This controlling hook is run before a
11594 transaction—that manages a new commit—completes.
11595 If the hook succeeds, the transaction completes and the
11596 changeset becomes permanent within this repository. If the
11597 hook fails, the transaction is rolled back, and the commit
11598 data is erased.
11599 </para>
11601 <para id="x_2d0">This hook can access the metadata associated with the
11602 almost-new changeset, but it should not do anything permanent
11603 with this data. It must also not modify the working
11604 directory.
11605 </para>
11607 <para id="x_2d1">While this hook is running, if other Mercurial processes
11608 access this repository, they will be able to see the
11609 almost-new changeset as if it is permanent. This may lead to
11610 race conditions if you do not take steps to avoid them.
11611 </para>
11613 <para id="x_2d2">Parameters to this hook:</para>
11615 <itemizedlist>
11616 <listitem><para id="x_2d3"><literal moreinfo="none">node</literal>: A changeset ID. The
11617 changeset ID of the newly committed changeset.
11618 </para>
11619 </listitem>
11620 <listitem><para id="x_2d4"><literal moreinfo="none">parent1</literal>: A changeset ID.
11621 The changeset ID of the first parent of the newly
11622 committed changeset.
11623 </para>
11624 </listitem>
11625 <listitem><para id="x_2d5"><literal moreinfo="none">parent2</literal>: A changeset ID.
11626 The changeset ID of the second parent of the newly
11627 committed changeset.
11628 </para>
11629 </listitem></itemizedlist>
11631 <para id="x_2d6">See also: <literal role="hook" moreinfo="none">precommit</literal> (<xref linkend="sec:hook:precommit"/>)
11632 </para>
11633 </sect2>
11635 <sect2 id="sec:hook:preupdate">
11636 <title><literal role="hook" moreinfo="none">preupdate</literal>—before
11637 updating or merging working directory</title>
11639 <para id="x_2d7">This controlling hook is run before an update
11640 or merge of the working directory begins. It is run only if
11641 Mercurial's normal pre-update checks determine that the update
11642 or merge can proceed. If the hook succeeds, the update or
11643 merge may proceed; if it fails, the update or merge does not
11644 start.
11645 </para>
11647 <para id="x_2d8">Parameters to this hook:
11648 </para>
11649 <itemizedlist>
11650 <listitem><para id="x_2d9"><literal moreinfo="none">parent1</literal>: A
11651 changeset ID. The ID of the parent that the working
11652 directory is to be updated to. If the working directory
11653 is being merged, it will not change this parent.
11654 </para>
11655 </listitem>
11656 <listitem><para id="x_2da"><literal moreinfo="none">parent2</literal>: A
11657 changeset ID. Only set if the working directory is being
11658 merged. The ID of the revision that the working directory
11659 is being merged with.
11660 </para>
11661 </listitem></itemizedlist>
11663 <para id="x_2db">See also: <literal role="hook" moreinfo="none">update</literal>
11664 (<xref linkend="sec:hook:update"/>)</para>
11665 </sect2>
11667 <sect2 id="sec:hook:tag">
11668 <title><literal role="hook" moreinfo="none">tag</literal>—after tagging a
11669 changeset</title>
11671 <para id="x_2dc">This hook is run after a tag has been created.
11672 </para>
11674 <para id="x_2dd">Parameters to this hook:
11675 </para>
11676 <itemizedlist>
11677 <listitem><para id="x_2de"><literal moreinfo="none">local</literal>: A boolean. Whether
11678 the new tag is local to this repository instance (i.e.
11679 stored in <filename role="special" moreinfo="none">.hg/localtags</filename>) or managed by
11680 Mercurial (stored in <filename role="special" moreinfo="none">.hgtags</filename>).
11681 </para>
11682 </listitem>
11683 <listitem><para id="x_2df"><literal moreinfo="none">node</literal>: A changeset ID. The
11684 ID of the changeset that was tagged.
11685 </para>
11686 </listitem>
11687 <listitem><para id="x_2e0"><literal moreinfo="none">tag</literal>: A string. The name of
11688 the tag that was created.
11689 </para>
11690 </listitem></itemizedlist>
11692 <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.
11693 </para>
11695 <para id="x_2e2">See also: <literal role="hook" moreinfo="none">pretag</literal>
11696 (<xref linkend="sec:hook:pretag"/>)
11697 </para>
11698 </sect2>
11700 <sect2 id="sec:hook:update">
11701 <title><literal role="hook" moreinfo="none">update</literal>—after
11702 updating or merging working directory</title>
11704 <para id="x_2e3">This hook is run after an update or merge of the working
11705 directory completes. Since a merge can fail (if the external
11706 <command moreinfo="none">hgmerge</command> command fails to resolve conflicts
11707 in a file), this hook communicates whether the update or merge
11708 completed cleanly.
11709 </para>
11711 <itemizedlist>
11712 <listitem><para id="x_2e4"><literal moreinfo="none">error</literal>: A boolean.
11713 Indicates whether the update or merge completed
11714 successfully.
11715 </para>
11716 </listitem>
11717 <listitem><para id="x_2e5"><literal moreinfo="none">parent1</literal>: A changeset ID.
11718 The ID of the parent that the working directory was
11719 updated to. If the working directory was merged, it will
11720 not have changed this parent.
11721 </para>
11722 </listitem>
11723 <listitem><para id="x_2e6"><literal moreinfo="none">parent2</literal>: A changeset ID.
11724 Only set if the working directory was merged. The ID of
11725 the revision that the working directory was merged with.
11726 </para>
11727 </listitem></itemizedlist>
11729 <para id="x_2e7">See also: <literal role="hook" moreinfo="none">preupdate</literal>
11730 (<xref linkend="sec:hook:preupdate"/>)
11731 </para>
11733 </sect2>
11734 </sect1>
11735 </chapter>
11737 <!--
11738 local variables:
11739 sgml-parent-document: ("00book.xml" "book" "chapter")
11740 end:
11741 -->
11743 <!-- BEGIN ch11 -->
11744 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
11746 <chapter id="chap:template">
11747 <?dbhtml filename="customizing-the-output-of-mercurial.html"?>
11748 <title>Customizing the output of Mercurial</title>
11750 <para id="x_578">Mercurial provides a powerful mechanism to let you control how
11751 it displays information. The mechanism is based on templates.
11752 You can use templates to generate specific output for a single
11753 command, or to customize the entire appearance of the built-in web
11754 interface.</para>
11756 <sect1 id="sec:style">
11757 <title>Using precanned output styles</title>
11759 <para id="x_579">Packaged with Mercurial are some output styles that you can
11760 use immediately. A style is simply a precanned template that
11761 someone wrote and installed somewhere that Mercurial can
11762 find.</para>
11764 <para id="x_57a">Before we take a look at Mercurial's bundled styles, let's
11765 review its normal output.</para>
11767 <!-- BEGIN template.simple.normal -->
11768 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1</userinput>
11769 changeset: 1:e3d2468ca47c
11770 tag: mytag
11771 user: Bryan O'Sullivan <bos@serpentine.com>
11772 date: Sun Aug 16 14:05:17 2009 +0000
11773 summary: added line to end of <<hello>> file.
11775 </screen>
11776 <!-- END template.simple.normal -->
11779 <para id="x_57b">This is somewhat informative, but it takes up a lot of
11780 space—five lines of output per changeset. The
11781 <literal moreinfo="none">compact</literal> style reduces this to three lines,
11782 presented in a sparse manner.</para>
11784 <!-- BEGIN template.simple.compact -->
11785 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style compact</userinput>
11786 3[tip] d3cc7424d32c 2009-08-16 14:05 +0000 bos
11787 Added tag v0.1 for changeset a5dd5392119b
11789 2[v0.1] a5dd5392119b 2009-08-16 14:05 +0000 bos
11790 Added tag mytag for changeset e3d2468ca47c
11792 1[mytag] e3d2468ca47c 2009-08-16 14:05 +0000 bos
11793 added line to end of <<hello>> file.
11795 0 1cf727e9fc61 2009-08-16 14:05 +0000 bos
11796 added hello
11798 </screen>
11799 <!-- END template.simple.compact -->
11802 <para id="x_57c">The <literal moreinfo="none">changelog</literal> style hints at the
11803 expressive power of Mercurial's templating engine. This style
11804 attempts to follow the GNU Project's changelog
11805 guidelines<citation>web:changelog</citation>.</para>
11807 <!-- BEGIN template.simple.changelog -->
11808 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style changelog</userinput>
11809 2009-08-16 Bryan O'Sullivan <bos@serpentine.com>
11811 * .hgtags:
11812 Added tag v0.1 for changeset a5dd5392119b
11813 [d3cc7424d32c] [tip]
11815 * .hgtags:
11816 Added tag mytag for changeset e3d2468ca47c
11817 [a5dd5392119b] [v0.1]
11819 * goodbye, hello:
11820 added line to end of <<hello>> file.
11822 in addition, added a file with the helpful name (at least i hope
11823 that some might consider it so) of goodbye.
11824 [e3d2468ca47c] [mytag]
11826 * hello:
11827 added hello
11828 [1cf727e9fc61]
11830 </screen>
11831 <!-- END template.simple.changelog -->
11834 <para id="x_57d">You will not be shocked to learn that Mercurial's default
11835 output style is named <literal moreinfo="none">default</literal>.</para>
11837 <sect2>
11838 <title>Setting a default style</title>
11840 <para id="x_57e">You can modify the output style that Mercurial will use
11841 for every command by editing your <filename role="special" moreinfo="none">~/.hgrc</filename> file, naming the style
11842 you would prefer to use.</para>
11844 <programlisting format="linespecific">[ui]
11845 style = compact</programlisting>
11847 <para id="x_57f">If you write a style of your own, you can use it by either
11848 providing the path to your style file, or copying your style
11849 file into a location where Mercurial can find it (typically
11850 the <literal moreinfo="none">templates</literal> subdirectory of your
11851 Mercurial install directory).</para>
11852 </sect2>
11853 </sect1>
11855 <sect1>
11856 <title>Commands that support styles and templates</title>
11858 <para id="x_580">All of Mercurial's
11859 <quote><literal moreinfo="none">log</literal>-like</quote> commands let you use
11860 styles and templates: <command role="hg-cmd" moreinfo="none">hg
11861 incoming</command>, <command role="hg-cmd" moreinfo="none">hg log</command>,
11862 <command role="hg-cmd" moreinfo="none">hg outgoing</command>, and <command role="hg-cmd" moreinfo="none">hg tip</command>.</para>
11864 <para id="x_581">As I write this manual, these are so far the only commands
11865 that support styles and templates. Since these are the most
11866 important commands that need customizable output, there has been
11867 little pressure from the Mercurial user community to add style
11868 and template support to other commands.</para>
11869 </sect1>
11871 <sect1>
11872 <title>The basics of templating</title>
11874 <para id="x_582">At its simplest, a Mercurial template is a piece of text.
11875 Some of the text never changes, while other parts are
11876 <emphasis>expanded</emphasis>, or replaced with new text, when
11877 necessary.</para>
11879 <para id="x_583">Before we continue, let's look again at a simple example of
11880 Mercurial's normal output.</para>
11882 <!-- BEGIN template.simple.normal -->
11883 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1</userinput>
11884 changeset: 1:e3d2468ca47c
11885 tag: mytag
11886 user: Bryan O'Sullivan <bos@serpentine.com>
11887 date: Sun Aug 16 14:05:17 2009 +0000
11888 summary: added line to end of <<hello>> file.
11890 </screen>
11891 <!-- END template.simple.normal -->
11894 <para id="x_584">Now, let's run the same command, but using a template to
11895 change its output.</para>
11897 <!-- BEGIN template.simple.simplest -->
11898 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'i saw a changeset\n'</userinput>
11899 i saw a changeset
11900 </screen>
11901 <!-- END template.simple.simplest -->
11904 <para id="x_585">The example above illustrates the simplest possible
11905 template; it's just a piece of static text, printed once for
11906 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
11907 the given text as the template when printing each
11908 changeset.</para>
11910 <para id="x_586">Notice that the template string above ends with the text
11911 <quote><literal moreinfo="none">\n</literal></quote>. This is an
11912 <emphasis>escape sequence</emphasis>, telling Mercurial to print
11913 a newline at the end of each template item. If you omit this
11914 newline, Mercurial will run each piece of output together. See
11915 <xref linkend="sec:template:escape"/> for more details
11916 of escape sequences.</para>
11918 <para id="x_587">A template that prints a fixed string of text all the time
11919 isn't very useful; let's try something a bit more
11920 complex.</para>
11922 <!-- BEGIN template.simple.simplesub -->
11923 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --template 'i saw a changeset: {desc}\n'</userinput>
11924 i saw a changeset: Added tag v0.1 for changeset a5dd5392119b
11925 i saw a changeset: Added tag mytag for changeset e3d2468ca47c
11926 i saw a changeset: added line to end of <<hello>> file.
11928 in addition, added a file with the helpful name (at least i hope that some might consider it so) of goodbye.
11929 i saw a changeset: added hello
11930 </screen>
11931 <!-- END template.simple.simplesub -->
11934 <para id="x_588">As you can see, the string
11935 <quote><literal moreinfo="none">{desc}</literal></quote> in the template has
11936 been replaced in the output with the description of each
11937 changeset. Every time Mercurial finds text enclosed in curly
11938 braces (<quote><literal moreinfo="none">{</literal></quote> and
11939 <quote><literal moreinfo="none">}</literal></quote>), it will try to replace the
11940 braces and text with the expansion of whatever is inside. To
11941 print a literal curly brace, you must escape it, as described in
11942 <xref linkend="sec:template:escape"/>.</para>
11943 </sect1>
11945 <sect1 id="sec:template:keyword">
11946 <title>Common template keywords</title>
11948 <para id="x_589">You can start writing simple templates immediately using the
11949 keywords below.</para>
11951 <itemizedlist>
11952 <listitem><para id="x_58a"><literal role="template-keyword" moreinfo="none">author</literal>: String. The
11953 unmodified author of the changeset.</para>
11954 </listitem>
11955 <listitem><para id="x_58b"><literal role="template-keyword" moreinfo="none">branches</literal>: String. The
11956 name of the branch on which the changeset was committed.
11957 Will be empty if the branch name was
11958 <literal moreinfo="none">default</literal>.</para>
11959 </listitem>
11960 <listitem><para id="x_58c"><literal role="template-keyword" moreinfo="none">date</literal>:
11961 Date information. The date when the changeset was
11962 committed. This is <emphasis>not</emphasis> human-readable;
11963 you must pass it through a filter that will render it
11964 appropriately. See <xref linkend="sec:template:filter"/> for more information
11965 on filters. The date is expressed as a pair of numbers. The
11966 first number is a Unix UTC timestamp (seconds since January
11967 1, 1970); the second is the offset of the committer's
11968 timezone from UTC, in seconds.</para>
11969 </listitem>
11970 <listitem><para id="x_58d"><literal role="template-keyword" moreinfo="none">desc</literal>:
11971 String. The text of the changeset description.</para>
11972 </listitem>
11973 <listitem><para id="x_58e"><literal role="template-keyword" moreinfo="none">files</literal>: List of strings.
11974 All files modified, added, or removed by this
11975 changeset.</para>
11976 </listitem>
11977 <listitem><para id="x_58f"><literal role="template-keyword" moreinfo="none">file_adds</literal>: List of
11978 strings. Files added by this changeset.</para>
11979 </listitem>
11980 <listitem><para id="x_590"><literal role="template-keyword" moreinfo="none">file_dels</literal>: List of
11981 strings. Files removed by this changeset.</para>
11982 </listitem>
11983 <listitem><para id="x_591"><literal role="template-keyword" moreinfo="none">node</literal>:
11984 String. The changeset identification hash, as a
11985 40-character hexadecimal string.</para>
11986 </listitem>
11987 <listitem><para id="x_592"><literal role="template-keyword" moreinfo="none">parents</literal>: List of
11988 strings. The parents of the changeset.</para>
11989 </listitem>
11990 <listitem><para id="x_593"><literal role="template-keyword" moreinfo="none">rev</literal>:
11991 Integer. The repository-local changeset revision
11992 number.</para>
11993 </listitem>
11994 <listitem><para id="x_594"><literal role="template-keyword" moreinfo="none">tags</literal>:
11995 List of strings. Any tags associated with the
11996 changeset.</para>
11997 </listitem>
11998 </itemizedlist>
12000 <para id="x_595">A few simple experiments will show us what to expect when we
12001 use these keywords; you can see the results below.</para>
12003 <!-- BEGIN template.simple.keywords -->
12004 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'author: {author}\n'</userinput>
12005 author: Bryan O'Sullivan <bos@serpentine.com>
12006 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'desc:\n{desc}\n'</userinput>
12007 desc:
12008 added line to end of <<hello>> file.
12010 in addition, added a file with the helpful name (at least i hope that some might consider it so) of goodbye.
12011 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'files: {files}\n'</userinput>
12012 files: goodbye hello
12013 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'file_adds: {file_adds}\n'</userinput>
12014 file_adds: goodbye
12015 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'file_dels: {file_dels}\n'</userinput>
12016 file_dels:
12017 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'node: {node}\n'</userinput>
12018 node: e3d2468ca47c10bdfbbb41b367a0c84509862197
12019 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'parents: {parents}\n'</userinput>
12020 parents:
12021 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'rev: {rev}\n'</userinput>
12022 rev: 1
12023 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'tags: {tags}\n'</userinput>
12024 tags: mytag
12025 </screen>
12026 <!-- END template.simple.keywords -->
12029 <para id="x_596">As we noted above, the date keyword does not produce
12030 human-readable output, so we must treat it specially. This
12031 involves using a <emphasis>filter</emphasis>, about which more
12032 in <xref linkend="sec:template:filter"/>.</para>
12034 <!-- BEGIN template.simple.datekeyword -->
12035 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'date: {date}\n'</userinput>
12036 date: 1250431517.00
12037 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'date: {date|isodate}\n'</userinput>
12038 date: 2009-08-16 14:05 +0000
12039 </screen>
12040 <!-- END template.simple.datekeyword -->
12042 </sect1>
12044 <sect1 id="sec:template:escape">
12045 <title>Escape sequences</title>
12047 <para id="x_597">Mercurial's templating engine recognises the most commonly
12048 used escape sequences in strings. When it sees a backslash
12049 (<quote><literal moreinfo="none">\</literal></quote>) character, it looks at the
12050 following character and substitutes the two characters with a
12051 single replacement, as described below.</para>
12053 <itemizedlist>
12054 <listitem><para id="x_598"><literal moreinfo="none">\</literal>:
12055 Backslash, <quote><literal moreinfo="none">\</literal></quote>, ASCII
12056 134.</para>
12057 </listitem>
12058 <listitem><para id="x_599"><literal moreinfo="none">\n</literal>: Newline,
12059 ASCII 12.</para>
12060 </listitem>
12061 <listitem><para id="x_59a"><literal moreinfo="none">\r</literal>: Carriage
12062 return, ASCII 15.</para>
12063 </listitem>
12064 <listitem><para id="x_59b"><literal moreinfo="none">\t</literal>: Tab, ASCII
12065 11.</para>
12066 </listitem>
12067 <listitem><para id="x_59c"><literal moreinfo="none">\v</literal>: Vertical
12068 tab, ASCII 13.</para>
12069 </listitem>
12070 <listitem><para id="x_59d"><literal moreinfo="none">\{</literal>: Open curly
12071 brace, <quote><literal moreinfo="none">{</literal></quote>, ASCII
12072 173.</para>
12073 </listitem>
12074 <listitem><para id="x_59e"><literal moreinfo="none">\}</literal>: Close curly
12075 brace, <quote><literal moreinfo="none">}</literal></quote>, ASCII
12076 175.</para>
12077 </listitem></itemizedlist>
12079 <para id="x_59f">As indicated above, if you want the expansion of a template
12080 to contain a literal <quote><literal moreinfo="none">\</literal></quote>,
12081 <quote><literal moreinfo="none">{</literal></quote>, or
12082 <quote><literal moreinfo="none">{</literal></quote> character, you must escape
12083 it.</para>
12084 </sect1>
12086 <sect1 id="sec:template:filter">
12087 <title>Filtering keywords to change their results</title>
12089 <para id="x_5a0">Some of the results of template expansion are not
12090 immediately easy to use. Mercurial lets you specify an optional
12091 chain of <emphasis>filters</emphasis> to modify the result of
12092 expanding a keyword. You have already seen a common filter,
12093 <literal role="template-kw-filt-date" moreinfo="none">isodate</literal>, in
12094 action above, to make a date readable.</para>
12096 <para id="x_5a1">Below is a list of the most commonly used filters that
12097 Mercurial supports. While some filters can be applied to any
12098 text, others can only be used in specific circumstances. The
12099 name of each filter is followed first by an indication of where
12100 it can be used, then a description of its effect.</para>
12102 <itemizedlist>
12103 <listitem><para id="x_5a2"><literal role="template-filter" moreinfo="none">addbreaks</literal>: Any text. Add
12104 an XHTML <quote><literal moreinfo="none"><br/></literal></quote> tag
12105 before the end of every line except the last. For example,
12106 <quote><literal moreinfo="none">foo\nbar</literal></quote> becomes
12107 <quote><literal moreinfo="none">foo<br/>\nbar</literal></quote>.</para>
12108 </listitem>
12109 <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
12110 the age of the date, relative to the current time. Yields a
12111 string like <quote><literal moreinfo="none">10
12112 minutes</literal></quote>.</para>
12113 </listitem>
12114 <listitem><para id="x_5a4"><literal role="template-filter" moreinfo="none">basename</literal>: Any text, but
12115 most useful for the <literal role="template-keyword" moreinfo="none">files</literal> keyword and its
12116 relatives. Treat the text as a path, and return the
12117 basename. For example,
12118 <quote><literal moreinfo="none">foo/bar/baz</literal></quote> becomes
12119 <quote><literal moreinfo="none">baz</literal></quote>.</para>
12120 </listitem>
12121 <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
12122 date in a similar format to the Unix <literal role="template-keyword" moreinfo="none">date</literal> command, but with
12123 timezone included. Yields a string like <quote><literal moreinfo="none">Mon
12124 Sep 04 15:13:13 2006 -0700</literal></quote>.</para>
12125 </listitem>
12126 <listitem><para id="x_5a6"><literal role="template-kw-filt-author" moreinfo="none">domain</literal>: Any text,
12127 but most useful for the <literal role="template-keyword" moreinfo="none">author</literal> keyword. Finds
12128 the first string that looks like an email address, and
12129 extract just the domain component. For example,
12130 <quote><literal moreinfo="none">Bryan O'Sullivan
12131 <bos@serpentine.com></literal></quote> becomes
12132 <quote><literal moreinfo="none">serpentine.com</literal></quote>.</para>
12133 </listitem>
12134 <listitem><para id="x_5a7"><literal role="template-kw-filt-author" moreinfo="none">email</literal>: Any text,
12135 but most useful for the <literal role="template-keyword" moreinfo="none">author</literal> keyword. Extract
12136 the first string that looks like an email address. For
12137 example, <quote><literal moreinfo="none">Bryan O'Sullivan
12138 <bos@serpentine.com></literal></quote> becomes
12139 <quote><literal moreinfo="none">bos@serpentine.com</literal></quote>.</para>
12140 </listitem>
12141 <listitem><para id="x_5a8"><literal role="template-filter" moreinfo="none">escape</literal>: Any text.
12142 Replace the special XML/XHTML characters
12143 <quote><literal moreinfo="none">&</literal></quote>,
12144 <quote><literal moreinfo="none"><</literal></quote> and
12145 <quote><literal moreinfo="none">></literal></quote> with XML
12146 entities.</para>
12147 </listitem>
12148 <listitem><para id="x_5a9"><literal role="template-filter" moreinfo="none">fill68</literal>: Any text. Wrap
12149 the text to fit in 68 columns. This is useful before you
12150 pass text through the <literal role="template-filter" moreinfo="none">tabindent</literal> filter, and
12151 still want it to fit in an 80-column fixed-font
12152 window.</para>
12153 </listitem>
12154 <listitem><para id="x_5aa"><literal role="template-filter" moreinfo="none">fill76</literal>: Any text. Wrap
12155 the text to fit in 76 columns.</para>
12156 </listitem>
12157 <listitem><para id="x_5ab"><literal role="template-filter" moreinfo="none">firstline</literal>: Any text.
12158 Yield the first line of text, without any trailing
12159 newlines.</para>
12160 </listitem>
12161 <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
12162 the date as a pair of readable numbers. Yields a string
12163 like <quote><literal moreinfo="none">1157407993
12164 25200</literal></quote>.</para>
12165 </listitem>
12166 <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
12167 the date as a text string in ISO 8601 format. Yields a
12168 string like <quote><literal moreinfo="none">2006-09-04 15:13:13
12169 -0700</literal></quote>.</para>
12170 </listitem>
12171 <listitem><para id="x_5ae"><literal role="template-filter" moreinfo="none">obfuscate</literal>: Any text, but
12172 most useful for the <literal role="template-keyword" moreinfo="none">author</literal> keyword. Yield
12173 the input text rendered as a sequence of XML entities. This
12174 helps to defeat some particularly stupid screen-scraping
12175 email harvesting spambots.</para>
12176 </listitem>
12177 <listitem><para id="x_5af"><literal role="template-kw-filt-author" moreinfo="none">person</literal>: Any text,
12178 but most useful for the <literal role="template-keyword" moreinfo="none">author</literal> keyword. Yield
12179 the text before an email address. For example,
12180 <quote><literal moreinfo="none">Bryan O'Sullivan
12181 <bos@serpentine.com></literal></quote> becomes
12182 <quote><literal moreinfo="none">Bryan O'Sullivan</literal></quote>.</para>
12183 </listitem>
12184 <listitem><para id="x_5b0"><literal role="template-kw-filt-date" moreinfo="none">rfc822date</literal>:
12185 <literal role="template-keyword" moreinfo="none">date</literal> keyword.
12186 Render a date using the same format used in email headers.
12187 Yields a string like <quote><literal moreinfo="none">Mon, 04 Sep 2006
12188 15:13:13 -0700</literal></quote>.</para>
12189 </listitem>
12190 <listitem><para id="x_5b1"><literal role="template-kw-filt-node" moreinfo="none">short</literal>: Changeset
12191 hash. Yield the short form of a changeset hash, i.e. a
12192 12-character hexadecimal string.</para>
12193 </listitem>
12194 <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
12195 the year, month, and day of the date. Yields a string like
12196 <quote><literal moreinfo="none">2006-09-04</literal></quote>.</para>
12197 </listitem>
12198 <listitem><para id="x_5b3"><literal role="template-filter" moreinfo="none">strip</literal>:
12199 Any text. Strip all leading and trailing whitespace from
12200 the string.</para>
12201 </listitem>
12202 <listitem><para id="x_5b4"><literal role="template-filter" moreinfo="none">tabindent</literal>: Any text.
12203 Yield the text, with every line except the first starting
12204 with a tab character.</para>
12205 </listitem>
12206 <listitem><para id="x_5b5"><literal role="template-filter" moreinfo="none">urlescape</literal>: Any text.
12207 Escape all characters that are considered
12208 <quote>special</quote> by URL parsers. For example,
12209 <literal moreinfo="none">foo bar</literal> becomes
12210 <literal moreinfo="none">foo%20bar</literal>.</para>
12211 </listitem>
12212 <listitem><para id="x_5b6"><literal role="template-kw-filt-author" moreinfo="none">user</literal>: Any text,
12213 but most useful for the <literal role="template-keyword" moreinfo="none">author</literal> keyword. Return
12214 the <quote>user</quote> portion of an email address. For
12215 example, <quote><literal moreinfo="none">Bryan O'Sullivan
12216 <bos@serpentine.com></literal></quote> becomes
12217 <quote><literal moreinfo="none">bos</literal></quote>.</para>
12218 </listitem>
12219 </itemizedlist>
12221 <!-- BEGIN template.simple.manyfilters -->
12222 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author}\n'</userinput>
12223 Bryan O'Sullivan <bos@serpentine.com>
12224 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author|domain}\n'</userinput>
12225 serpentine.com
12226 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author|email}\n'</userinput>
12227 bos@serpentine.com
12228 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author|obfuscate}\n' | cut -c-76</userinput>
12229 &#66;&#114;&#121;&#97;&#110;&#32;&#79;&#39;&#83;&#117;&#108;&#108;&#105;&#11
12230 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author|person}\n'</userinput>
12231 Bryan O'Sullivan
12232 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{author|user}\n'</userinput>
12233 bos
12234 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'looks almost right, but actually garbage: {date}\n'</userinput>
12235 looks almost right, but actually garbage: 1250431517.00
12236 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|age}\n'</userinput>
12237 3 seconds
12238 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|date}\n'</userinput>
12239 Sun Aug 16 14:05:17 2009 +0000
12240 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|hgdate}\n'</userinput>
12241 1250431517 0
12242 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|isodate}\n'</userinput>
12243 2009-08-16 14:05 +0000
12244 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|rfc822date}\n'</userinput>
12245 Sun, 16 Aug 2009 14:05:17 +0000
12246 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{date|shortdate}\n'</userinput>
12247 2009-08-16
12248 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc}\n' | cut -c-76</userinput>
12249 added line to end of <<hello>> file.
12251 in addition, added a file with the helpful name (at least i hope that some m
12252 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|addbreaks}\n' | cut -c-76</userinput>
12253 added line to end of <<hello>> file.<br/>
12254 <br/>
12255 in addition, added a file with the helpful name (at least i hope that some m
12256 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|escape}\n' | cut -c-76</userinput>
12257 added line to end of &lt;&lt;hello&gt;&gt; file.
12259 in addition, added a file with the helpful name (at least i hope that some m
12260 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|fill68}\n'</userinput>
12261 added line to end of <<hello>> file.
12263 in addition, added a file with the helpful name (at least i hope
12264 that some might consider it so) of goodbye.
12265 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|fill76}\n'</userinput>
12266 added line to end of <<hello>> file.
12268 in addition, added a file with the helpful name (at least i hope that some
12269 might consider it so) of goodbye.
12270 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|firstline}\n'</userinput>
12271 added line to end of <<hello>> file.
12272 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|strip}\n' | cut -c-76</userinput>
12273 added line to end of <<hello>> file.
12275 in addition, added a file with the helpful name (at least i hope that some m
12276 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{desc|tabindent}\n' | expand | cut -c-76</userinput>
12277 added line to end of <<hello>> file.
12279 in addition, added a file with the helpful name (at least i hope tha
12280 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{node}\n'</userinput>
12281 e3d2468ca47c10bdfbbb41b367a0c84509862197
12282 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template '{node|short}\n'</userinput>
12283 e3d2468ca47c
12284 </screen>
12285 <!-- END template.simple.manyfilters -->
12288 <note>
12289 <para id="x_5b7"> If you try to apply a filter to a piece of data that it
12290 cannot process, Mercurial will fail and print a Python
12291 exception. For example, trying to run the output of the
12292 <literal role="template-keyword" moreinfo="none">desc</literal> keyword into
12293 the <literal role="template-kw-filt-date" moreinfo="none">isodate</literal>
12294 filter is not a good idea.</para>
12295 </note>
12297 <sect2>
12298 <title>Combining filters</title>
12300 <para id="x_5b8">It is easy to combine filters to yield output in the form
12301 you would like. The following chain of filters tidies up a
12302 description, then makes sure that it fits cleanly into 68
12303 columns, then indents it by a further 8 characters (at least
12304 on Unix-like systems, where a tab is conventionally 8
12305 characters wide).</para>
12307 <!-- BEGIN template.simple.combine -->
12308 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --template 'description:\n\t{desc|strip|fill68|tabindent}\n'</userinput>
12309 description:
12310 added line to end of <<hello>> file.
12312 in addition, added a file with the helpful name (at least i hope
12313 that some might consider it so) of goodbye.
12314 </screen>
12315 <!-- END template.simple.combine -->
12318 <para id="x_5b9">Note the use of <quote><literal moreinfo="none">\t</literal></quote> (a
12319 tab character) in the template to force the first line to be
12320 indented; this is necessary since <literal role="template-keyword" moreinfo="none">tabindent</literal> indents all
12321 lines <emphasis>except</emphasis> the first.</para>
12323 <para id="x_5ba">Keep in mind that the order of filters in a chain is
12324 significant. The first filter is applied to the result of the
12325 keyword; the second to the result of the first filter; and so
12326 on. For example, using <literal moreinfo="none">fill68|tabindent</literal>
12327 gives very different results from
12328 <literal moreinfo="none">tabindent|fill68</literal>.</para>
12329 </sect2>
12330 </sect1>
12332 <sect1>
12333 <title>From templates to styles</title>
12335 <para id="x_5bb">A command line template provides a quick and simple way to
12336 format some output. Templates can become verbose, though, and
12337 it's useful to be able to give a template a name. A style file
12338 is a template with a name, stored in a file.</para>
12340 <para id="x_5bc">More than that, using a style file unlocks the power of
12341 Mercurial's templating engine in ways that are not possible
12342 using the command line <option role="hg-opt-log">--template</option> option.</para>
12344 <sect2>
12345 <title>The simplest of style files</title>
12347 <para id="x_5bd">Our simple style file contains just one line:</para>
12349 <!-- BEGIN template.simple.rev -->
12350 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'changeset = "rev: {rev}\n"' > rev</userinput>
12351 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -l1 --style ./rev</userinput>
12352 rev: 3
12353 </screen>
12354 <!-- END template.simple.rev -->
12357 <para id="x_5be">This tells Mercurial, <quote>if you're printing a
12358 changeset, use the text on the right as the
12359 template</quote>.</para>
12360 </sect2>
12362 <sect2>
12363 <title>Style file syntax</title>
12365 <para id="x_5bf">The syntax rules for a style file are simple.</para>
12367 <itemizedlist>
12368 <listitem><para id="x_5c0">The file is processed one line at a
12369 time.</para>
12370 </listitem>
12371 <listitem><para id="x_5c1">Leading and trailing white space are
12372 ignored.</para>
12373 </listitem>
12374 <listitem><para id="x_5c2">Empty lines are skipped.</para>
12375 </listitem>
12376 <listitem><para id="x_5c3">If a line starts with either of the characters
12377 <quote><literal moreinfo="none">#</literal></quote> or
12378 <quote><literal moreinfo="none">;</literal></quote>, the entire line is
12379 treated as a comment, and skipped as if empty.</para>
12380 </listitem>
12381 <listitem><para id="x_5c4">A line starts with a keyword. This must start
12382 with an alphabetic character or underscore, and can
12383 subsequently contain any alphanumeric character or
12384 underscore. (In regexp notation, a keyword must match
12385 <literal moreinfo="none">[A-Za-z_][A-Za-z0-9_]*</literal>.)</para>
12386 </listitem>
12387 <listitem><para id="x_5c5">The next element must be an
12388 <quote><literal moreinfo="none">=</literal></quote> character, which can
12389 be preceded or followed by an arbitrary amount of white
12390 space.</para>
12391 </listitem>
12392 <listitem><para id="x_5c6">If the rest of the line starts and ends with
12393 matching quote characters (either single or double quote),
12394 it is treated as a template body.</para>
12395 </listitem>
12396 <listitem><para id="x_5c7">If the rest of the line <emphasis>does
12397 not</emphasis> start with a quote character, it is
12398 treated as the name of a file; the contents of this file
12399 will be read and used as a template body.</para>
12400 </listitem></itemizedlist>
12401 </sect2>
12402 </sect1>
12404 <sect1>
12405 <title>Style files by example</title>
12407 <para id="x_5c8">To illustrate how to write a style file, we will construct a
12408 few by example. Rather than provide a complete style file and
12409 walk through it, we'll mirror the usual process of developing a
12410 style file by starting with something very simple, and walking
12411 through a series of successively more complete examples.</para>
12413 <sect2>
12414 <title>Identifying mistakes in style files</title>
12416 <para id="x_5c9">If Mercurial encounters a problem in a style file you are
12417 working on, it prints a terse error message that, once you
12418 figure out what it means, is actually quite useful.</para>
12420 <!-- BEGIN template.svnstyle.syntax.input -->
12421 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat broken.style</userinput>
12422 changeset =
12423 </screen>
12424 <!-- END template.svnstyle.syntax.input -->
12427 <para id="x_5ca">Notice that <filename moreinfo="none">broken.style</filename> attempts to
12428 define a <literal moreinfo="none">changeset</literal> keyword, but forgets to
12429 give any content for it. When instructed to use this style
12430 file, Mercurial promptly complains.</para>
12432 <!-- BEGIN template.svnstyle.syntax.error -->
12433 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r1 --style broken.style</userinput>
12434 abort: broken.style:1: parse error
12435 </screen>
12436 <!-- END template.svnstyle.syntax.error -->
12439 <para id="x_5cb">This error message looks intimidating, but it is not too
12440 hard to follow.</para>
12442 <itemizedlist>
12443 <listitem><para id="x_5cc">The first component is simply Mercurial's way
12444 of saying <quote>I am giving up</quote>.</para>
12445 <programlisting format="linespecific">___abort___: broken.style:1: parse error</programlisting>
12446 </listitem>
12447 <listitem><para id="x_5cd">Next comes the name of the style file that
12448 contains the error.</para>
12449 <programlisting format="linespecific">abort: ___broken.style___:1: parse error</programlisting>
12450 </listitem>
12451 <listitem><para id="x_5ce">Following the file name is the line number
12452 where the error was encountered.</para>
12453 <programlisting format="linespecific">abort: broken.style:___1___: parse error</programlisting>
12454 </listitem>
12455 <listitem><para id="x_5cf">Finally, a description of what went
12456 wrong.</para>
12457 <programlisting format="linespecific">abort: broken.style:1: ___parse error___</programlisting>
12458 </listitem>
12459 <listitem><para id="x_5d0">The description of the problem is not always
12460 clear (as in this case), but even when it is cryptic, it
12461 is almost always trivial to visually inspect the offending
12462 line in the style file and see what is wrong.</para>
12463 </listitem>
12464 </itemizedlist>
12465 </sect2>
12467 <sect2>
12468 <title>Uniquely identifying a repository</title>
12470 <para id="x_5d1">If you would like to be able to identify a Mercurial
12471 repository <quote>fairly uniquely</quote> using a short string
12472 as an identifier, you can use the first revision in the
12473 repository.</para>
12475 <!-- BEGIN template.svnstyle.id -->
12476 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r0 --template '{node}'</userinput>
12477 02b4f9d8a52a6da645e20fa7df0accc8aa33b650</screen>
12478 <!-- END template.svnstyle.id -->
12481 <para id="x_5d2">This is likely to be unique, and so it is
12482 useful in many cases. There are a few caveats.</para>
12483 <itemizedlist>
12484 <listitem><para id="x_5d3">It will not work in a completely empty
12485 repository, because such a repository does not have a
12486 revision zero.</para>
12487 </listitem>
12488 <listitem><para id="x_5d4">Neither will it work in the (extremely rare)
12489 case where a repository is a merge of two or more formerly
12490 independent repositories, and you still have those
12491 repositories around.</para>
12492 </listitem></itemizedlist>
12493 <para id="x_5d5">Here are some uses to which you could put this
12494 identifier:</para>
12495 <itemizedlist>
12496 <listitem><para id="x_5d6">As a key into a table for a database that
12497 manages repositories on a server.</para>
12498 </listitem>
12499 <listitem><para id="x_5d7">As half of a {<emphasis>repository
12500 ID</emphasis>, <emphasis>revision ID</emphasis>} tuple.
12501 Save this information away when you run an automated build
12502 or other activity, so that you can <quote>replay</quote>
12503 the build later if necessary.</para>
12504 </listitem>
12505 </itemizedlist>
12506 </sect2>
12508 <sect2>
12509 <title>Listing files on multiple lines</title>
12511 <para id="x_714">Suppose we want to list the files changed by a changeset,
12512 one per line, with a little indentation before each file
12513 name.</para>
12515 <!-- BEGIN ch10/multiline.go -->
12516 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat > multiline << EOF</userinput>
12517 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">changeset = "Changed in {node|short}:\n{files}"</userinput>
12518 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">file = " {file}\n"</userinput>
12519 <prompt moreinfo="none">></prompt> <userinput moreinfo="none">EOF</userinput>
12520 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style multiline</userinput>
12521 Changed in badb58085712:
12522 .bashrc
12523 .hgrc
12524 test.c
12525 </screen>
12526 <!-- END ch10/multiline.go -->
12528 </sect2>
12530 <sect2>
12531 <title>Mimicking Subversion's output</title>
12533 <para id="x_5d8">Let's try to emulate the default output format used by
12534 another revision control tool, Subversion.</para>
12536 <!-- BEGIN template.svnstyle.short -->
12537 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">svn log -r9653</userinput>
12538 ------------------------------------------------------------------------
12539 r9653 | sean.hefty | 2006-09-27 14:39:55 -0700 (Wed, 27 Sep 2006) | 5 lines
12541 On reporting a route error, also include the status for the error,
12542 rather than indicating a status of 0 when an error has occurred.
12544 Signed-off-by: Sean Hefty <sean.hefty@intel.com>
12546 ------------------------------------------------------------------------
12547 </screen>
12548 <!-- END template.svnstyle.short -->
12551 <para id="x_5d9">Since Subversion's output style is fairly simple, it is
12552 easy to copy-and-paste a hunk of its output into a file, and
12553 replace the text produced above by Subversion with the
12554 template values we'd like to see expanded.</para>
12556 <!-- BEGIN template.svnstyle.template -->
12557 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat svn.template</userinput>
12558 r{rev} | {author|user} | {date|isodate} ({date|rfc822date})
12560 {desc|strip|fill76}
12562 ------------------------------------------------------------------------
12563 </screen>
12564 <!-- END template.svnstyle.template -->
12567 <para id="x_5da">There are a few small ways in which this template deviates
12568 from the output produced by Subversion.</para>
12569 <itemizedlist>
12570 <listitem><para id="x_5db">Subversion prints a <quote>readable</quote>
12571 date (the <quote><literal moreinfo="none">Wed, 27 Sep 2006</literal></quote> in the
12572 example output above) in parentheses. Mercurial's
12573 templating engine does not provide a way to display a date
12574 in this format without also printing the time and time
12575 zone.</para>
12576 </listitem>
12577 <listitem><para id="x_5dc">We emulate Subversion's printing of
12578 <quote>separator</quote> lines full of
12579 <quote><literal moreinfo="none">-</literal></quote> characters by ending
12580 the template with such a line. We use the templating
12581 engine's <literal role="template-keyword" moreinfo="none">header</literal>
12582 keyword to print a separator line as the first line of
12583 output (see below), thus achieving similar output to
12584 Subversion.</para>
12585 </listitem>
12586 <listitem><para id="x_5dd">Subversion's output includes a count in the
12587 header of the number of lines in the commit message. We
12588 cannot replicate this in Mercurial; the templating engine
12589 does not currently provide a filter that counts the number
12590 of lines the template generates.</para>
12591 </listitem></itemizedlist>
12592 <para id="x_5de">It took me no more than a minute or two of work to replace
12593 literal text from an example of Subversion's output with some
12594 keywords and filters to give the template above. The style
12595 file simply refers to the template.</para>
12597 <!-- BEGIN template.svnstyle.style -->
12598 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat svn.style</userinput>
12599 header = '------------------------------------------------------------------------\n\n'
12600 changeset = svn.template
12601 </screen>
12602 <!-- END template.svnstyle.style -->
12605 <para id="x_5df">We could have included the text of the template file
12606 directly in the style file by enclosing it in quotes and
12607 replacing the newlines with
12608 <quote><literal moreinfo="none">\n</literal></quote> sequences, but it would
12609 have made the style file too difficult to read. Readability
12610 is a good guide when you're trying to decide whether some text
12611 belongs in a style file, or in a template file that the style
12612 file points to. If the style file will look too big or
12613 cluttered if you insert a literal piece of text, drop it into
12614 a template instead.</para>
12615 </sect2>
12616 </sect1>
12617 </chapter>
12619 <!--
12620 local variables:
12621 sgml-parent-document: ("00book.xml" "book" "chapter")
12622 end:
12623 -->
12625 <!-- BEGIN ch12 -->
12626 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
12628 <chapter id="chap:mq">
12629 <?dbhtml filename="managing-change-with-mercurial-queues.html"?>
12630 <title>Managing change with Mercurial Queues</title>
12632 <sect1 id="sec:mq:patch-mgmt">
12633 <title>The patch management problem</title>
12635 <para id="x_3ac">Here is a common scenario: you need to install a software
12636 package from source, but you find a bug that you must fix in the
12637 source before you can start using the package. You make your
12638 changes, forget about the package for a while, and a few months
12639 later you need to upgrade to a newer version of the package. If
12640 the newer version of the package still has the bug, you must
12641 extract your fix from the older source tree and apply it against
12642 the newer version. This is a tedious task, and it's easy to
12643 make mistakes.</para>
12645 <para id="x_3ad">This is a simple case of the <quote>patch management</quote>
12646 problem. You have an <quote>upstream</quote> source tree that
12647 you can't change; you need to make some local changes on top of
12648 the upstream tree; and you'd like to be able to keep those
12649 changes separate, so that you can apply them to newer versions
12650 of the upstream source.</para>
12652 <para id="x_3ae">The patch management problem arises in many situations.
12653 Probably the most visible is that a user of an open source
12654 software project will contribute a bug fix or new feature to the
12655 project's maintainers in the form of a patch.</para>
12657 <para id="x_3af">Distributors of operating systems that include open source
12658 software often need to make changes to the packages they
12659 distribute so that they will build properly in their
12660 environments.</para>
12662 <para id="x_3b0">When you have few changes to maintain, it is easy to manage
12663 a single patch using the standard <command moreinfo="none">diff</command> and
12664 <command moreinfo="none">patch</command> programs (see <xref linkend="sec:mq:patch"/> for a discussion of these
12665 tools). Once the number of changes grows, it starts to make
12666 sense to maintain patches as discrete <quote>chunks of
12667 work,</quote> so that for example a single patch will contain
12668 only one bug fix (the patch might modify several files, but it's
12669 doing <quote>only one thing</quote>), and you may have a number
12670 of such patches for different bugs you need fixed and local
12671 changes you require. In this situation, if you submit a bug fix
12672 patch to the upstream maintainers of a package and they include
12673 your fix in a subsequent release, you can simply drop that
12674 single patch when you're updating to the newer release.</para>
12676 <para id="x_3b1">Maintaining a single patch against an upstream tree is a
12677 little tedious and error-prone, but not difficult. However, the
12678 complexity of the problem grows rapidly as the number of patches
12679 you have to maintain increases. With more than a tiny number of
12680 patches in hand, understanding which ones you have applied and
12681 maintaining them moves from messy to overwhelming.</para>
12683 <para id="x_3b2">Fortunately, Mercurial includes a powerful extension,
12684 Mercurial Queues (or simply <quote>MQ</quote>), that massively
12685 simplifies the patch management problem.</para>
12687 </sect1>
12688 <sect1 id="sec:mq:history">
12689 <title>The prehistory of Mercurial Queues</title>
12691 <para id="x_3b3">During the late 1990s, several Linux kernel developers
12692 started to maintain <quote>patch series</quote> that modified
12693 the behavior of the Linux kernel. Some of these series were
12694 focused on stability, some on feature coverage, and others were
12695 more speculative.</para>
12697 <para id="x_3b4">The sizes of these patch series grew rapidly. In 2002,
12698 Andrew Morton published some shell scripts he had been using to
12699 automate the task of managing his patch queues. Andrew was
12700 successfully using these scripts to manage hundreds (sometimes
12701 thousands) of patches on top of the Linux kernel.</para>
12703 <sect2 id="sec:mq:quilt">
12704 <title>A patchwork quilt</title>
12706 <para id="x_3b5">In early 2003, Andreas Gruenbacher and Martin Quinson
12707 borrowed the approach of Andrew's scripts and published a tool
12708 called <quote>patchwork quilt</quote>
12709 <citation>web:quilt</citation>, or simply <quote>quilt</quote>
12710 (see <citation>gruenbacher:2005</citation> for a paper
12711 describing it). Because quilt substantially automated patch
12712 management, it rapidly gained a large following among open
12713 source software developers.</para>
12715 <para id="x_3b6">Quilt manages a <emphasis>stack of patches</emphasis> on
12716 top of a directory tree. To begin, you tell quilt to manage a
12717 directory tree, and tell it which files you want to manage; it
12718 stores away the names and contents of those files. To fix a
12719 bug, you create a new patch (using a single command), edit the
12720 files you need to fix, then <quote>refresh</quote> the
12721 patch.</para>
12723 <para id="x_3b7">The refresh step causes quilt to scan the directory tree;
12724 it updates the patch with all of the changes you have made.
12725 You can create another patch on top of the first, which will
12726 track the changes required to modify the tree from <quote>tree
12727 with one patch applied</quote> to <quote>tree with two
12728 patches applied</quote>.</para>
12730 <para id="x_3b8">You can <emphasis>change</emphasis> which patches are
12731 applied to the tree. If you <quote>pop</quote> a patch, the
12732 changes made by that patch will vanish from the directory
12733 tree. Quilt remembers which patches you have popped, though,
12734 so you can <quote>push</quote> a popped patch again, and the
12735 directory tree will be restored to contain the modifications
12736 in the patch. Most importantly, you can run the
12737 <quote>refresh</quote> command at any time, and the topmost
12738 applied patch will be updated. This means that you can, at
12739 any time, change both which patches are applied and what
12740 modifications those patches make.</para>
12742 <para id="x_3b9">Quilt knows nothing about revision control tools, so it
12743 works equally well on top of an unpacked tarball or a
12744 Subversion working copy.</para>
12745 </sect2>
12747 <sect2 id="sec:mq:quilt-mq">
12748 <title>From patchwork quilt to Mercurial Queues</title>
12750 <para id="x_3ba">In mid-2005, Chris Mason took the features of quilt and
12751 wrote an extension that he called Mercurial Queues, which
12752 added quilt-like behavior to Mercurial.</para>
12754 <para id="x_3bb">The key difference between quilt and MQ is that quilt
12755 knows nothing about revision control systems, while MQ is
12756 <emphasis>integrated</emphasis> into Mercurial. Each patch
12757 that you push is represented as a Mercurial changeset. Pop a
12758 patch, and the changeset goes away.</para>
12760 <para id="x_3bc">Because quilt does not care about revision control tools,
12761 it is still a tremendously useful piece of software to know
12762 about for situations where you cannot use Mercurial and
12763 MQ.</para>
12765 </sect2>
12766 </sect1>
12767 <sect1>
12768 <title>The huge advantage of MQ</title>
12770 <para id="x_3bd">I cannot overstate the value that MQ offers through the
12771 unification of patches and revision control.</para>
12773 <para id="x_3be">A major reason that patches have persisted in the free
12774 software and open source world—in spite of the
12775 availability of increasingly capable revision control tools over
12776 the years—is the <emphasis>agility</emphasis> they
12777 offer.</para>
12779 <para id="x_3bf">Traditional revision control tools make a permanent,
12780 irreversible record of everything that you do. While this has
12781 great value, it's also somewhat stifling. If you want to
12782 perform a wild-eyed experiment, you have to be careful in how
12783 you go about it, or you risk leaving unneeded—or worse,
12784 misleading or destabilising—traces of your missteps and
12785 errors in the permanent revision record.</para>
12787 <para id="x_3c0">By contrast, MQ's marriage of distributed revision control
12788 with patches makes it much easier to isolate your work. Your
12789 patches live on top of normal revision history, and you can make
12790 them disappear or reappear at will. If you don't like a patch,
12791 you can drop it. If a patch isn't quite as you want it to be,
12792 simply fix it—as many times as you need to, until you
12793 have refined it into the form you desire.</para>
12795 <para id="x_3c1">As an example, the integration of patches with revision
12796 control makes understanding patches and debugging their
12797 effects—and their interplay with the code they're based
12798 on—<emphasis>enormously</emphasis> easier. Since every
12799 applied patch has an associated changeset, you can give <command role="hg-cmd" moreinfo="none">hg log</command> a file name to see which
12800 changesets and patches affected the file. You can use the
12801 <command role="hg-cmd" moreinfo="none">hg bisect</command> command to
12802 binary-search through all changesets and applied patches to see
12803 where a bug got introduced or fixed. You can use the <command role="hg-cmd" moreinfo="none">hg annotate</command> command to see which
12804 changeset or patch modified a particular line of a source file.
12805 And so on.</para>
12806 </sect1>
12808 <sect1 id="sec:mq:patch">
12809 <title>Understanding patches</title>
12811 <para id="x_3c2">Because MQ doesn't hide its patch-oriented nature, it is
12812 helpful to understand what patches are, and a little about the
12813 tools that work with them.</para>
12815 <para id="x_3c3">The traditional Unix <command moreinfo="none">diff</command> command
12816 compares two files, and prints a list of differences between
12817 them. The <command moreinfo="none">patch</command> command understands these
12818 differences as <emphasis>modifications</emphasis> to make to a
12819 file. Take a look below for a simple example of these commands
12820 in action.</para>
12822 <!-- BEGIN mq.dodiff.diff -->
12823 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'this is my original thought' > oldfile</userinput>
12824 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'i have changed my mind' > newfile</userinput>
12825 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">diff -u oldfile newfile > tiny.patch</userinput>
12826 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat tiny.patch</userinput>
12827 --- oldfile 2009-08-16 14:05:06.000000000 +0000
12828 +++ newfile 2009-08-16 14:05:06.000000000 +0000
12829 @@ -1 +1 @@
12830 -this is my original thought
12831 +i have changed my mind
12832 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">patch < tiny.patch</userinput>
12833 patching file oldfile
12834 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat oldfile</userinput>
12835 i have changed my mind
12836 </screen>
12837 <!-- END mq.dodiff.diff -->
12840 <para id="x_3c4">The type of file that <command moreinfo="none">diff</command> generates (and
12841 <command moreinfo="none">patch</command> takes as input) is called a
12842 <quote>patch</quote> or a <quote>diff</quote>; there is no
12843 difference between a patch and a diff. (We'll use the term
12844 <quote>patch</quote>, since it's more commonly used.)</para>
12846 <para id="x_3c5">A patch file can start with arbitrary text; the
12847 <command moreinfo="none">patch</command> command ignores this text, but MQ uses
12848 it as the commit message when creating changesets. To find the
12849 beginning of the patch content, <command moreinfo="none">patch</command>
12850 searches for the first line that starts with the string
12851 <quote><literal moreinfo="none">diff -</literal></quote>.</para>
12853 <para id="x_3c6">MQ works with <emphasis>unified</emphasis> diffs
12854 (<command moreinfo="none">patch</command> can accept several other diff formats,
12855 but MQ doesn't). A unified diff contains two kinds of header.
12856 The <emphasis>file header</emphasis> describes the file being
12857 modified; it contains the name of the file to modify. When
12858 <command moreinfo="none">patch</command> sees a new file header, it looks for a
12859 file with that name to start modifying.</para>
12861 <para id="x_3c7">After the file header comes a series of
12862 <emphasis>hunks</emphasis>. Each hunk starts with a header;
12863 this identifies the range of line numbers within the file that
12864 the hunk should modify. Following the header, a hunk starts and
12865 ends with a few (usually three) lines of text from the
12866 unmodified file; these are called the
12867 <emphasis>context</emphasis> for the hunk. If there's only a
12868 small amount of context between successive hunks,
12869 <command moreinfo="none">diff</command> doesn't print a new hunk header; it just
12870 runs the hunks together, with a few lines of context between
12871 modifications.</para>
12873 <para id="x_3c8">Each line of context begins with a space character. Within
12874 the hunk, a line that begins with
12875 <quote><literal moreinfo="none">-</literal></quote> means <quote>remove this
12876 line,</quote> while a line that begins with
12877 <quote><literal moreinfo="none">+</literal></quote> means <quote>insert this
12878 line.</quote> For example, a line that is modified is
12879 represented by one deletion and one insertion.</para>
12881 <para id="x_3c9">We will return to some of the more subtle aspects of patches
12882 later (in <xref linkend="sec:mq:adv-patch"/>), but you
12883 should have
12884 enough information now to use MQ.</para>
12885 </sect1>
12887 <sect1 id="sec:mq:start">
12888 <title>Getting started with Mercurial Queues</title>
12890 <para id="x_3ca">Because MQ is implemented as an extension, you must
12891 explicitly enable before you can use it. (You don't need to
12892 download anything; MQ ships with the standard Mercurial
12893 distribution.) To enable MQ, edit your <filename role="home" moreinfo="none">~/.hgrc</filename> file, and add the lines
12894 below.</para>
12896 <programlisting format="linespecific">[extensions]
12897 hgext.mq =</programlisting>
12899 <para id="x_3cb">Once the extension is enabled, it will make a number of new
12900 commands available. To verify that the extension is working,
12901 you can use <command role="hg-cmd" moreinfo="none">hg help</command> to see if
12902 the <command role="hg-ext-mq" moreinfo="none">qinit</command> command is now
12903 available.</para>
12905 <!-- BEGIN mq.qinit-help.help -->
12906 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg help qinit</userinput>
12907 hg qinit [-c]
12909 init a new queue repository
12911 The queue repository is unversioned by default. If -c is
12912 specified, qinit will create a separate nested repository
12913 for patches (qinit -c may also be run later to convert
12914 an unversioned patch repository into a versioned one).
12915 You can use qcommit to commit changes to this queue repository.
12917 options:
12919 -c --create-repo create queue repository
12921 use "hg -v help qinit" to show global options
12922 </screen>
12923 <!-- END mq.qinit-help.help -->
12926 <para id="x_3cc">You can use MQ with <emphasis>any</emphasis> Mercurial
12927 repository, and its commands only operate within that
12928 repository. To get started, simply prepare the repository using
12929 the <command role="hg-ext-mq" moreinfo="none">qinit</command> command.</para>
12931 <!-- BEGIN mq.tutorial.qinit -->
12932 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init mq-sandbox</userinput>
12933 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd mq-sandbox</userinput>
12934 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'line 1' > file1</userinput>
12935 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'another line 1' > file2</userinput>
12936 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add file1 file2</userinput>
12937 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -m'first change'</userinput>
12938 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qinit</userinput>
12939 </screen>
12940 <!-- END mq.tutorial.qinit -->
12943 <para id="x_3cd">This command creates an empty directory called <filename role="special" class="directory" moreinfo="none">.hg/patches</filename>, where
12944 MQ will keep its metadata. As with many Mercurial commands, the
12945 <command role="hg-ext-mq" moreinfo="none">qinit</command> command prints nothing
12946 if it succeeds.</para>
12948 <sect2>
12949 <title>Creating a new patch</title>
12951 <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
12952 one argument, the name of the patch to create.</para>
12954 <para id="x_3cf">MQ will use this as the name of an actual file in the
12955 <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory, as you
12956 can see below.</para>
12958 <!-- BEGIN mq.tutorial.qnew -->
12959 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
12960 changeset: 0:5d84c303994b
12961 tag: tip
12962 user: Bryan O'Sullivan <bos@serpentine.com>
12963 date: Sun Aug 16 14:05:11 2009 +0000
12964 summary: first change
12966 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew first.patch</userinput>
12967 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip</userinput>
12968 changeset: 1:ba4d7a3f2149
12969 tag: qtip
12970 tag: first.patch
12971 tag: tip
12972 tag: qbase
12973 user: Bryan O'Sullivan <bos@serpentine.com>
12974 date: Sun Aug 16 14:05:11 2009 +0000
12975 summary: [mq]: first.patch
12977 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">ls .hg/patches</userinput>
12978 first.patch series status
12979 </screen>
12980 <!-- END mq.tutorial.qnew -->
12983 <para id="x_3d0">Also newly present in the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory are two
12984 other files, <filename role="special" moreinfo="none">series</filename> and
12985 <filename role="special" moreinfo="none">status</filename>. The <filename role="special" moreinfo="none">series</filename> file lists all of the
12986 patches that MQ knows about for this repository, with one
12987 patch per line. Mercurial uses the <filename role="special" moreinfo="none">status</filename> file for internal
12988 book-keeping; it tracks all of the patches that MQ has
12989 <emphasis>applied</emphasis> in this repository.</para>
12991 <note>
12992 <para id="x_3d1"> You may sometimes want to edit the <filename role="special" moreinfo="none">series</filename> file by hand; for
12993 example, to change the sequence in which some patches are
12994 applied. However, manually editing the <filename role="special" moreinfo="none">status</filename> file is almost always a
12995 bad idea, as it's easy to corrupt MQ's idea of what is
12996 happening.</para>
12997 </note>
12999 <para id="x_3d2">Once you have created your new patch, you can edit files
13000 in the working directory as you usually would. All of the
13001 normal Mercurial commands, such as <command role="hg-cmd" moreinfo="none">hg
13002 diff</command> and <command role="hg-cmd" moreinfo="none">hg
13003 annotate</command>, work exactly as they did before.</para>
13004 </sect2>
13006 <sect2>
13007 <title>Refreshing a patch</title>
13009 <para id="x_3d3">When you reach a point where you want to save your work,
13010 use the <command role="hg-ext-mq" moreinfo="none">qrefresh</command> command
13011 to update the patch you are working on.</para>
13013 <!-- BEGIN mq.tutorial.qrefresh -->
13014 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'line 2' >> file1</userinput>
13015 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
13016 diff -r ba4d7a3f2149 file1
13017 --- a/file1 Sun Aug 16 14:05:11 2009 +0000
13018 +++ b/file1 Sun Aug 16 14:05:11 2009 +0000
13019 @@ -1,1 +1,2 @@
13020 line 1
13021 +line 2
13022 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
13023 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
13024 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip --style=compact --patch</userinput>
13025 1[qtip,first.patch,tip,qbase] 1aa236e17e55 2009-08-16 14:05 +0000 bos
13026 [mq]: first.patch
13028 diff -r 5d84c303994b -r 1aa236e17e55 file1
13029 --- a/file1 Sun Aug 16 14:05:11 2009 +0000
13030 +++ b/file1 Sun Aug 16 14:05:11 2009 +0000
13031 @@ -1,1 +1,2 @@
13032 line 1
13033 +line 2
13035 </screen>
13036 <!-- END mq.tutorial.qrefresh -->
13039 <para id="x_3d4">This command folds the changes you have made in the
13040 working directory into your patch, and updates its
13041 corresponding changeset to contain those changes.</para>
13043 <para id="x_3d5">You can run <command role="hg-ext-mq" moreinfo="none">qrefresh</command>
13044 as often as you like, so it's a good way to
13045 <quote>checkpoint</quote> your work. Refresh your patch at an
13046 opportune time; try an experiment; and if the experiment
13047 doesn't work out, <command role="hg-cmd" moreinfo="none">hg revert</command>
13048 your modifications back to the last time you refreshed.</para>
13050 <!-- BEGIN mq.tutorial.qrefresh2 -->
13051 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'line 3' >> file1</userinput>
13052 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status</userinput>
13053 M file1
13054 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
13055 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip --style=compact --patch</userinput>
13056 1[qtip,first.patch,tip,qbase] ebec7ce95e11 2009-08-16 14:05 +0000 bos
13057 [mq]: first.patch
13059 diff -r 5d84c303994b -r ebec7ce95e11 file1
13060 --- a/file1 Sun Aug 16 14:05:11 2009 +0000
13061 +++ b/file1 Sun Aug 16 14:05:12 2009 +0000
13062 @@ -1,1 +1,3 @@
13063 line 1
13064 +line 2
13065 +line 3
13067 </screen>
13068 <!-- END mq.tutorial.qrefresh2 -->
13070 </sect2>
13072 <sect2>
13073 <title>Stacking and tracking patches</title>
13075 <para id="x_3d6">Once you have finished working on a patch, or need to work
13076 on another, you can use the <command role="hg-ext-mq" moreinfo="none">qnew</command> command again to create a
13077 new patch. Mercurial will apply this patch on top of your
13078 existing patch.</para>
13080 <!-- BEGIN mq.tutorial.qnew2 -->
13081 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew second.patch</userinput>
13082 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log --style=compact --limit=2</userinput>
13083 2[qtip,second.patch,tip] dffbc4265523 2009-08-16 14:05 +0000 bos
13084 [mq]: second.patch
13086 1[first.patch,qbase] ebec7ce95e11 2009-08-16 14:05 +0000 bos
13087 [mq]: first.patch
13089 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'line 4' >> file1</userinput>
13090 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
13091 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip --style=compact --patch</userinput>
13092 2[qtip,second.patch,tip] fdacb9b232ac 2009-08-16 14:05 +0000 bos
13093 [mq]: second.patch
13095 diff -r ebec7ce95e11 -r fdacb9b232ac file1
13096 --- a/file1 Sun Aug 16 14:05:12 2009 +0000
13097 +++ b/file1 Sun Aug 16 14:05:12 2009 +0000
13098 @@ -1,3 +1,4 @@
13099 line 1
13100 line 2
13101 line 3
13102 +line 4
13104 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg annotate file1</userinput>
13105 0: line 1
13106 1: line 2
13107 1: line 3
13108 2: line 4
13109 </screen>
13110 <!-- END mq.tutorial.qnew2 -->
13113 <para id="x_3d7">Notice that the patch contains the changes in our prior
13114 patch as part of its context (you can see this more clearly in
13115 the output of <command role="hg-cmd" moreinfo="none">hg
13116 annotate</command>).</para>
13118 <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
13119 only use regular Mercurial commands. However, MQ provides
13120 many commands that are easier to use when you are thinking
13121 about patches, as illustrated below.</para>
13123 <!-- BEGIN mq.tutorial.qseries -->
13124 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qseries</userinput>
13125 first.patch
13126 second.patch
13127 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
13128 first.patch
13129 second.patch
13130 </screen>
13131 <!-- END mq.tutorial.qseries -->
13134 <itemizedlist>
13135 <listitem><para id="x_3d9">The <command role="hg-ext-mq" moreinfo="none">qseries</command> command lists every
13136 patch that MQ knows about in this repository, from oldest
13137 to newest (most recently
13138 <emphasis>created</emphasis>).</para>
13139 </listitem>
13140 <listitem><para id="x_3da">The <command role="hg-ext-mq" moreinfo="none">qapplied</command> command lists every
13141 patch that MQ has <emphasis>applied</emphasis> in this
13142 repository, again from oldest to newest (most recently
13143 applied).</para>
13144 </listitem></itemizedlist>
13145 </sect2>
13147 <sect2>
13148 <title>Manipulating the patch stack</title>
13150 <para id="x_3db">The previous discussion implied that there must be a
13151 difference between <quote>known</quote> and
13152 <quote>applied</quote> patches, and there is. MQ can manage a
13153 patch without it being applied in the repository.</para>
13155 <para id="x_3dc">An <emphasis>applied</emphasis> patch has a corresponding
13156 changeset in the repository, and the effects of the patch and
13157 changeset are visible in the working directory. You can undo
13158 the application of a patch using the <command role="hg-ext-mq" moreinfo="none">qpop</command> command. MQ still
13159 <emphasis>knows about</emphasis>, or manages, a popped patch,
13160 but the patch no longer has a corresponding changeset in the
13161 repository, and the working directory does not contain the
13162 changes made by the patch. <xref linkend="fig:mq:stack"/> illustrates
13163 the difference between applied and tracked patches.</para>
13165 <figure id="fig:mq:stack" float="0">
13166 <title>Applied and unapplied patches in the MQ patch
13167 stack</title>
13168 <mediaobject>
13169 <imageobject><imagedata fileref="figs/mq-stack.png"/></imageobject>
13170 <textobject><phrase>XXX add text</phrase></textobject>
13171 </mediaobject>
13172 </figure>
13174 <para id="x_3de">You can reapply an unapplied, or popped, patch using the
13175 <command role="hg-ext-mq" moreinfo="none">qpush</command> command. This
13176 creates a new changeset to correspond to the patch, and the
13177 patch's changes once again become present in the working
13178 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>
13180 <!-- BEGIN mq.tutorial.qpop -->
13181 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
13182 first.patch
13183 second.patch
13184 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop</userinput>
13185 now at: first.patch
13186 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qseries</userinput>
13187 first.patch
13188 second.patch
13189 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
13190 first.patch
13191 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat file1</userinput>
13192 line 1
13193 line 2
13194 line 3
13195 </screen>
13196 <!-- END mq.tutorial.qpop -->
13199 <para id="x_3df">Notice that once we have popped a patch or two patches,
13200 the output of <command role="hg-ext-mq" moreinfo="none">qseries</command>
13201 remains the same, while that of <command role="hg-ext-mq" moreinfo="none">qapplied</command> has changed.</para>
13203 </sect2>
13205 <sect2>
13206 <title>Pushing and popping many patches</title>
13208 <para id="x_3e0">While <command role="hg-ext-mq" moreinfo="none">qpush</command> and
13209 <command role="hg-ext-mq" moreinfo="none">qpop</command> each operate on a
13210 single patch at a time by default, you can push and pop many
13211 patches in one go. The <option role="hg-ext-mq-cmd-qpush-opt">hg -a</option> option to
13212 <command role="hg-ext-mq" moreinfo="none">qpush</command> causes it to push
13213 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
13214 patches. (For some more ways to push and pop many patches,
13215 see <xref linkend="sec:mq:perf"/> below.)</para>
13217 <!-- BEGIN mq.tutorial.qpush-a -->
13218 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpush -a</userinput>
13219 applying second.patch
13220 now at: second.patch
13221 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat file1</userinput>
13222 line 1
13223 line 2
13224 line 3
13225 line 4
13226 </screen>
13227 <!-- END mq.tutorial.qpush-a -->
13229 </sect2>
13231 <sect2>
13232 <title>Safety checks, and overriding them</title>
13234 <para id="x_3e1">Several MQ commands check the working directory before
13235 they do anything, and fail if they find any modifications.
13236 They do this to ensure that you won't lose any changes that
13237 you have made, but not yet incorporated into a patch. The
13238 example below illustrates this; the <command role="hg-ext-mq" moreinfo="none">qnew</command> command will not create a
13239 new patch if there are outstanding changes, caused in this
13240 case by the <command role="hg-cmd" moreinfo="none">hg add</command> of
13241 <filename moreinfo="none">file3</filename>.</para>
13243 <!-- BEGIN mq.tutorial.add -->
13244 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo 'file 3, line 1' >> file3</userinput>
13245 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew add-file3.patch</userinput>
13246 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew -f add-file3.patch</userinput>
13247 abort: patch "add-file3.patch" already exists
13248 </screen>
13249 <!-- END mq.tutorial.add -->
13252 <para id="x_3e2">Commands that check the working directory all take an
13253 <quote>I know what I'm doing</quote> option, which is always
13254 named <option>-f</option>. The exact meaning of
13255 <option>-f</option> depends on the command. For example,
13256 <command role="hg-cmd" moreinfo="none">hg qnew <option role="hg-ext-mq-cmd-qnew-opt">hg -f</option></command>
13257 will incorporate any outstanding changes into the new patch it
13258 creates, but <command role="hg-cmd" moreinfo="none">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">hg -f</option></command>
13259 will revert modifications to any files affected by the patch
13260 that it is popping. Be sure to read the documentation for a
13261 command's <option>-f</option> option before you use it!</para>
13262 </sect2>
13264 <sect2>
13265 <title>Working on several patches at once</title>
13267 <para id="x_3e3">The <command role="hg-ext-mq" moreinfo="none">qrefresh</command> command
13268 always refreshes the <emphasis>topmost</emphasis> applied
13269 patch. This means that you can suspend work on one patch (by
13270 refreshing it), pop or push to make a different patch the top,
13271 and work on <emphasis>that</emphasis> patch for a
13272 while.</para>
13274 <para id="x_3e4">Here's an example that illustrates how you can use this
13275 ability. Let's say you're developing a new feature as two
13276 patches. The first is a change to the core of your software,
13277 and the second—layered on top of the
13278 first—changes the user interface to use the code you
13279 just added to the core. If you notice a bug in the core while
13280 you're working on the UI patch, it's easy to fix the core.
13281 Simply <command role="hg-ext-mq" moreinfo="none">qrefresh</command> the UI
13282 patch to save your in-progress changes, and <command role="hg-ext-mq" moreinfo="none">qpop</command> down to the core patch. Fix
13283 the core bug, <command role="hg-ext-mq" moreinfo="none">qrefresh</command> the
13284 core patch, and <command role="hg-ext-mq" moreinfo="none">qpush</command> back
13285 to the UI patch to continue where you left off.</para>
13286 </sect2>
13287 </sect1>
13289 <sect1 id="sec:mq:adv-patch">
13290 <title>More about patches</title>
13292 <para id="x_3e5">MQ uses the GNU <command moreinfo="none">patch</command> command to apply
13293 patches, so it's helpful to know a few more detailed aspects of
13294 how <command moreinfo="none">patch</command> works, and about patches
13295 themselves.</para>
13297 <sect2>
13298 <title>The strip count</title>
13300 <para id="x_3e6">If you look at the file headers in a patch, you will
13301 notice that the pathnames usually have an extra component on
13302 the front that isn't present in the actual path name. This is
13303 a holdover from the way that people used to generate patches
13304 (people still do this, but it's somewhat rare with modern
13305 revision control tools).</para>
13307 <para id="x_3e7">Alice would unpack a tarball, edit her files, then decide
13308 that she wanted to create a patch. So she'd rename her
13309 working directory, unpack the tarball again (hence the need
13310 for the rename), and use the <option role="cmd-opt-diff">-r</option> and <option role="cmd-opt-diff">-N</option> options to
13311 <command moreinfo="none">diff</command> to recursively generate a patch
13312 between the unmodified directory and the modified one. The
13313 result would be that the name of the unmodified directory
13314 would be at the front of the left-hand path in every file
13315 header, and the name of the modified directory would be at the
13316 front of the right-hand path.</para>
13318 <para id="x_3e8">Since someone receiving a patch from the Alices of the net
13319 would be unlikely to have unmodified and modified directories
13320 with exactly the same names, the <command moreinfo="none">patch</command>
13321 command has a <option role="cmd-opt-patch">-p</option> option
13322 that indicates the number of leading path name components to
13323 strip when trying to apply a patch. This number is called the
13324 <emphasis>strip count</emphasis>.</para>
13326 <para id="x_3e9">An option of <quote><literal moreinfo="none">-p1</literal></quote> means
13327 <quote>use a strip count of one</quote>. If
13328 <command moreinfo="none">patch</command> sees a file name
13329 <filename moreinfo="none">foo/bar/baz</filename> in a file header, it will
13330 strip <filename moreinfo="none">foo</filename> and try to patch a file named
13331 <filename moreinfo="none">bar/baz</filename>. (Strictly speaking, the strip
13332 count refers to the number of <emphasis>path
13333 separators</emphasis> (and the components that go with them
13334 ) to strip. A strip count of one will turn
13335 <filename moreinfo="none">foo/bar</filename> into <filename moreinfo="none">bar</filename>,
13336 but <filename moreinfo="none">/foo/bar</filename> (notice the extra leading
13337 slash) into <filename moreinfo="none">foo/bar</filename>.)</para>
13339 <para id="x_3ea">The <quote>standard</quote> strip count for patches is
13340 one; almost all patches contain one leading path name
13341 component that needs to be stripped. Mercurial's <command role="hg-cmd" moreinfo="none">hg diff</command> command generates path names
13342 in this form, and the <command role="hg-cmd" moreinfo="none">hg
13343 import</command> command and MQ expect patches to have a
13344 strip count of one.</para>
13346 <para id="x_3eb">If you receive a patch from someone that you want to add
13347 to your patch queue, and the patch needs a strip count other
13348 than one, you cannot just <command role="hg-ext-mq" moreinfo="none">qimport</command> the patch, because
13349 <command role="hg-ext-mq" moreinfo="none">qimport</command> does not yet have
13350 a <literal moreinfo="none">-p</literal> option (see <ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue311">issue
13351 311</ulink>). Your best bet is to <command role="hg-ext-mq" moreinfo="none">qnew</command> a patch of your own, then
13352 use <command moreinfo="none">patch -pN</command> to apply their patch,
13353 followed by <command role="hg-cmd" moreinfo="none">hg addremove</command> to
13354 pick up any files added or removed by the patch, followed by
13355 <command role="hg-ext-mq" moreinfo="none">hg qrefresh</command>. This
13356 complexity may become unnecessary; see <ulink role="hg-bug" url="http://www.selenic.com/mercurial/bts/issue311">issue
13357 311</ulink> for details.
13358 </para>
13359 </sect2>
13361 <sect2>
13362 <title>Strategies for applying a patch</title>
13364 <para id="x_3ec">When <command moreinfo="none">patch</command> applies a hunk, it tries a
13365 handful of successively less accurate strategies to try to
13366 make the hunk apply. This falling-back technique often makes
13367 it possible to take a patch that was generated against an old
13368 version of a file, and apply it against a newer version of
13369 that file.</para>
13371 <para id="x_3ed">First, <command moreinfo="none">patch</command> tries an exact match,
13372 where the line numbers, the context, and the text to be
13373 modified must apply exactly. If it cannot make an exact
13374 match, it tries to find an exact match for the context,
13375 without honouring the line numbering information. If this
13376 succeeds, it prints a line of output saying that the hunk was
13377 applied, but at some <emphasis>offset</emphasis> from the
13378 original line number.</para>
13380 <para id="x_3ee">If a context-only match fails, <command moreinfo="none">patch</command>
13381 removes the first and last lines of the context, and tries a
13382 <emphasis>reduced</emphasis> context-only match. If the hunk
13383 with reduced context succeeds, it prints a message saying that
13384 it applied the hunk with a <emphasis>fuzz factor</emphasis>
13385 (the number after the fuzz factor indicates how many lines of
13386 context <command moreinfo="none">patch</command> had to trim before the patch
13387 applied).</para>
13389 <para id="x_3ef">When neither of these techniques works,
13390 <command moreinfo="none">patch</command> prints a message saying that the hunk
13391 in question was rejected. It saves rejected hunks (also
13392 simply called <quote>rejects</quote>) to a file with the same
13393 name, and an added <filename role="special" moreinfo="none">.rej</filename>
13394 extension. It also saves an unmodified copy of the file with
13395 a <filename role="special" moreinfo="none">.orig</filename> extension; the
13396 copy of the file without any extensions will contain any
13397 changes made by hunks that <emphasis>did</emphasis> apply
13398 cleanly. If you have a patch that modifies
13399 <filename moreinfo="none">foo</filename> with six hunks, and one of them fails
13400 to apply, you will have: an unmodified
13401 <filename moreinfo="none">foo.orig</filename>, a <filename moreinfo="none">foo.rej</filename>
13402 containing one hunk, and <filename moreinfo="none">foo</filename>, containing
13403 the changes made by the five successful hunks.</para>
13404 </sect2>
13406 <sect2>
13407 <title>Some quirks of patch representation</title>
13409 <para id="x_3f0">There are a few useful things to know about how
13410 <command moreinfo="none">patch</command> works with files.</para>
13411 <itemizedlist>
13412 <listitem><para id="x_3f1">This should already be obvious, but
13413 <command moreinfo="none">patch</command> cannot handle binary
13414 files.</para>
13415 </listitem>
13416 <listitem><para id="x_3f2">Neither does it care about the executable bit;
13417 it creates new files as readable, but not
13418 executable.</para>
13419 </listitem>
13420 <listitem><para id="x_3f3"><command moreinfo="none">patch</command> treats the removal of
13421 a file as a diff between the file to be removed and the
13422 empty file. So your idea of <quote>I deleted this
13423 file</quote> looks like <quote>every line of this file
13424 was deleted</quote> in a patch.</para>
13425 </listitem>
13426 <listitem><para id="x_3f4">It treats the addition of a file as a diff
13427 between the empty file and the file to be added. So in a
13428 patch, your idea of <quote>I added this file</quote> looks
13429 like <quote>every line of this file was
13430 added</quote>.</para>
13431 </listitem>
13432 <listitem><para id="x_3f5">It treats a renamed file as the removal of the
13433 old name, and the addition of the new name. This means
13434 that renamed files have a big footprint in patches. (Note
13435 also that Mercurial does not currently try to infer when
13436 files have been renamed or copied in a patch.)</para>
13437 </listitem>
13438 <listitem><para id="x_3f6"><command moreinfo="none">patch</command> cannot represent
13439 empty files, so you cannot use a patch to represent the
13440 notion <quote>I added this empty file to the
13441 tree</quote>.</para>
13442 </listitem></itemizedlist>
13443 </sect2>
13445 <sect2>
13446 <title>Beware the fuzz</title>
13448 <para id="x_3f7">While applying a hunk at an offset, or with a fuzz factor,
13449 will often be completely successful, these inexact techniques
13450 naturally leave open the possibility of corrupting the patched
13451 file. The most common cases typically involve applying a
13452 patch twice, or at an incorrect location in the file. If
13453 <command moreinfo="none">patch</command> or <command role="hg-ext-mq" moreinfo="none">qpush</command> ever mentions an offset or
13454 fuzz factor, you should make sure that the modified files are
13455 correct afterwards.</para>
13457 <para id="x_3f8">It's often a good idea to refresh a patch that has applied
13458 with an offset or fuzz factor; refreshing the patch generates
13459 new context information that will make it apply cleanly. I
13460 say <quote>often,</quote> not <quote>always,</quote> because
13461 sometimes refreshing a patch will make it fail to apply
13462 against a different revision of the underlying files. In some
13463 cases, such as when you're maintaining a patch that must sit
13464 on top of multiple versions of a source tree, it's acceptable
13465 to have a patch apply with some fuzz, provided you've verified
13466 the results of the patching process in such cases.</para>
13467 </sect2>
13469 <sect2>
13470 <title>Handling rejection</title>
13472 <para id="x_3f9">If <command role="hg-ext-mq" moreinfo="none">qpush</command> fails to
13473 apply a patch, it will print an error message and exit. If it
13474 has left <filename role="special" moreinfo="none">.rej</filename> files
13475 behind, it is usually best to fix up the rejected hunks before
13476 you push more patches or do any further work.</para>
13478 <para id="x_3fa">If your patch <emphasis>used to</emphasis> apply cleanly,
13479 and no longer does because you've changed the underlying code
13480 that your patches are based on, Mercurial Queues can help; see
13481 <xref linkend="sec:mq:merge"/> for details.</para>
13483 <para id="x_3fb">Unfortunately, there aren't any great techniques for
13484 dealing with rejected hunks. Most often, you'll need to view
13485 the <filename role="special" moreinfo="none">.rej</filename> file and edit the
13486 target file, applying the rejected hunks by hand.</para>
13488 <para id="x_3fd">A Linux kernel hacker, Chris Mason (the author
13489 of Mercurial Queues), wrote a tool called
13490 <command moreinfo="none">mpatch</command> (<ulink url="http://oss.oracle.com/~mason/mpatch/">http://oss.oracle.com/~mason/mpatch/</ulink>),
13491 which takes a simple approach to automating the application of
13492 hunks rejected by <command moreinfo="none">patch</command>. The
13493 <command moreinfo="none">mpatch</command> command can help with four common
13494 reasons that a hunk may be rejected:</para>
13496 <itemizedlist>
13497 <listitem><para id="x_3fe">The context in the middle of a hunk has
13498 changed.</para>
13499 </listitem>
13500 <listitem><para id="x_3ff">A hunk is missing some context at the
13501 beginning or end.</para>
13502 </listitem>
13503 <listitem><para id="x_400">A large hunk might apply better—either
13504 entirely or in part—if it was broken up into
13505 smaller hunks.</para>
13506 </listitem>
13507 <listitem><para id="x_401">A hunk removes lines with slightly different
13508 content than those currently present in the file.</para>
13509 </listitem></itemizedlist>
13511 <para id="x_402">If you use <command moreinfo="none">mpatch</command>, you
13512 should be doubly careful to check your results when you're
13513 done. In fact, <command moreinfo="none">mpatch</command> enforces this method
13514 of double-checking the tool's output, by automatically
13515 dropping you into a merge program when it has done its job, so
13516 that you can verify its work and finish off any remaining
13517 merges.</para>
13518 </sect2>
13519 </sect1>
13521 <sect1>
13522 <title>More on patch management</title>
13524 <para id="x_6db">As you grow familiar with MQ, you will find yourself wanting
13525 to perform other kinds of patch management operations.</para>
13527 <sect2>
13528 <title>Deleting unwanted patches</title>
13530 <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
13531 patch file and remove its entry from the patch series. If you
13532 try to delete a patch that is still applied, <command role="hg-ext-mq" moreinfo="none">hg qdelete</command> will refuse.</para>
13534 <!-- BEGIN ch11/qdelete.go -->
13535 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init myrepo</userinput>
13536 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd myrepo</userinput>
13537 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qinit</userinput>
13538 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew bad.patch</userinput>
13539 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a > a</userinput>
13540 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a</userinput>
13541 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
13542 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qdelete bad.patch</userinput>
13543 abort: cannot delete applied patch bad.patch
13544 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop</userinput>
13545 patch queue now empty
13546 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qdelete bad.patch</userinput>
13547 </screen>
13548 <!-- END ch11/qdelete.go -->
13550 </sect2>
13552 <sect2>
13553 <title>Converting to and from permanent revisions</title>
13555 <para id="x_6dd">Once you're done working on a patch and want to
13556 turn it into a permanent changeset, use the <command role="hg-ext-mq" moreinfo="none">hg qfinish</command> command. Pass a revision
13557 to the command to identify the patch that you want to turn into
13558 a regular changeset; this patch must already be applied.</para>
13560 <!-- BEGIN ch11/qdelete.convert -->
13561 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew good.patch</userinput>
13562 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo a > a</userinput>
13563 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add a</userinput>
13564 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh -m 'Good change'</userinput>
13565 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qfinish tip</userinput>
13566 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
13567 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip --style=compact</userinput>
13568 0[tip] 32fc5ce6b092 2009-08-16 14:04 +0000 bos
13569 Good change
13571 </screen>
13572 <!-- END ch11/qdelete.convert -->
13575 <para id="x_6e0">The <command role="hg-ext-mq" moreinfo="none">hg qfinish</command> command
13576 accepts an <option>--all</option> or <option>-a</option>
13577 option, which turns all applied patches into regular
13578 changesets.</para>
13580 <para id="x_6de">It is also possible to turn an existing changeset into a
13581 patch, by passing the <option>-r</option> option to <command role="hg-ext-mq" moreinfo="none">hg qimport</command>.</para>
13583 <!-- BEGIN ch11/qdelete.import -->
13584 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qimport -r tip</userinput>
13585 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
13586 0.diff
13587 </screen>
13588 <!-- END ch11/qdelete.import -->
13591 <para id="x_6df">Note that it only makes sense to convert a changeset into
13592 a patch if you have not propagated that changeset into any
13593 other repositories. The imported changeset's ID will change
13594 every time you refresh the patch, which will make Mercurial
13595 treat it as unrelated to the original changeset if you have
13596 pushed it somewhere else.</para>
13597 </sect2>
13598 </sect1>
13600 <sect1 id="sec:mq:perf">
13601 <title>Getting the best performance out of MQ</title>
13603 <para id="x_403">MQ is very efficient at handling a large number
13604 of patches. I ran some performance experiments in mid-2006 for a
13605 talk that I gave at the 2006 EuroPython conference (on modern
13606 hardware, you should expect better performance than you'll see
13607 below). I used as my data set the Linux 2.6.17-mm1 patch
13608 series, which consists of 1,738 patches. I applied these on top
13609 of a Linux kernel repository containing all 27,472 revisions
13610 between Linux 2.6.12-rc2 and Linux 2.6.17.</para>
13612 <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
13613 1,738 patches in 3.5 minutes, and <command role="hg-cmd" moreinfo="none">hg qpop
13614 <option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command>
13615 them all in 30 seconds. (On a newer laptop, the time to push
13616 all patches dropped to two minutes.) I could <command role="hg-ext-mq" moreinfo="none">qrefresh</command> one of the biggest patches
13617 (which made 22,779 lines of changes to 287 files) in 6.6
13618 seconds.</para>
13620 <para id="x_405">Clearly, MQ is well suited to working in large trees, but
13621 there are a few tricks you can use to get the best performance
13622 of it.</para>
13624 <para id="x_406">First of all, try to <quote>batch</quote> operations
13625 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
13626 working directory once to make sure you haven't made some
13627 changes and then forgotten to run <command role="hg-ext-mq" moreinfo="none">qrefresh</command>. On a small tree, the
13628 time that this scan takes is unnoticeable. However, on a
13629 medium-sized tree (containing tens of thousands of files), it
13630 can take a second or more.</para>
13632 <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
13633 pop multiple patches at a time. You can identify the
13634 <quote>destination patch</quote> that you want to end up at.
13635 When you <command role="hg-ext-mq" moreinfo="none">qpush</command> with a
13636 destination specified, it will push patches until that patch is
13637 at the top of the applied stack. When you <command role="hg-ext-mq" moreinfo="none">qpop</command> to a destination, MQ will pop
13638 patches until the destination patch is at the top.</para>
13640 <para id="x_408">You can identify a destination patch using either the name
13641 of the patch, or by number. If you use numeric addressing,
13642 patches are counted from zero; this means that the first patch
13643 is zero, the second is one, and so on.</para>
13644 </sect1>
13646 <sect1 id="sec:mq:merge">
13647 <title>Updating your patches when the underlying code
13648 changes</title>
13650 <para id="x_409">It's common to have a stack of patches on top of an
13651 underlying repository that you don't modify directly. If you're
13652 working on changes to third-party code, or on a feature that is
13653 taking longer to develop than the rate of change of the code
13654 beneath, you will often need to sync up with the underlying
13655 code, and fix up any hunks in your patches that no longer apply.
13656 This is called <emphasis>rebasing</emphasis> your patch
13657 series.</para>
13659 <para id="x_40a">The simplest way to do this is to <command role="hg-cmd" moreinfo="none">hg
13660 qpop <option role="hg-ext-mq-cmd-qpop-opt">hg
13661 -a</option></command> your patches, then <command role="hg-cmd" moreinfo="none">hg pull</command> changes into the underlying
13662 repository, and finally <command role="hg-cmd" moreinfo="none">hg qpush <option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> your
13663 patches again. MQ will stop pushing any time it runs across a
13664 patch that fails to apply during conflicts, allowing you to fix
13665 your conflicts, <command role="hg-ext-mq" moreinfo="none">qrefresh</command> the
13666 affected patch, and continue pushing until you have fixed your
13667 entire stack.</para>
13669 <para id="x_40b">This approach is easy to use and works well if you don't
13670 expect changes to the underlying code to affect how well your
13671 patches apply. If your patch stack touches code that is modified
13672 frequently or invasively in the underlying repository, however,
13673 fixing up rejected hunks by hand quickly becomes
13674 tiresome.</para>
13676 <para id="x_40c">It's possible to partially automate the rebasing process.
13677 If your patches apply cleanly against some revision of the
13678 underlying repo, MQ can use this information to help you to
13679 resolve conflicts between your patches and a different
13680 revision.</para>
13682 <para id="x_40d">The process is a little involved.</para>
13683 <orderedlist inheritnum="ignore" continuation="restarts">
13684 <listitem><para id="x_40e">To begin, <command role="hg-cmd" moreinfo="none">hg qpush
13685 -a</command> all of your patches on top of the revision
13686 where you know that they apply cleanly.</para>
13687 </listitem>
13688 <listitem><para id="x_40f">Save a backup copy of your patch directory using
13689 <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>.
13690 This prints the name of the directory that it has saved the
13691 patches in. It will save the patches to a directory called
13692 <filename role="special" class="directory" moreinfo="none">.hg/patches.N</filename>, where
13693 <literal moreinfo="none">N</literal> is a small integer. It also commits a
13694 <quote>save changeset</quote> on top of your applied
13695 patches; this is for internal book-keeping, and records the
13696 states of the <filename role="special" moreinfo="none">series</filename> and
13697 <filename role="special" moreinfo="none">status</filename> files.</para>
13698 </listitem>
13699 <listitem><para id="x_410">Use <command role="hg-cmd" moreinfo="none">hg pull</command> to
13700 bring new changes into the underlying repository. (Don't
13701 run <command role="hg-cmd" moreinfo="none">hg pull -u</command>; see below
13702 for why.)</para>
13703 </listitem>
13704 <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
13705 the patches you have pushed.</para>
13706 </listitem>
13707 <listitem><para id="x_412">Merge all patches using <command moreinfo="none">hg qpush -m
13708 -a</command>. The <option role="hg-ext-mq-cmd-qpush-opt">-m</option> option to
13709 <command role="hg-ext-mq" moreinfo="none">qpush</command> tells MQ to
13710 perform a three-way merge if the patch fails to
13711 apply.</para>
13712 </listitem></orderedlist>
13714 <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>,
13715 each patch in the <filename role="special" moreinfo="none">series</filename>
13716 file is applied normally. If a patch applies with fuzz or
13717 rejects, MQ looks at the queue you <command role="hg-ext-mq" moreinfo="none">qsave</command>d, and performs a three-way
13718 merge with the corresponding changeset. This merge uses
13719 Mercurial's normal merge machinery, so it may pop up a GUI merge
13720 tool to help you to resolve problems.</para>
13722 <para id="x_414">When you finish resolving the effects of a patch, MQ
13723 refreshes your patch based on the result of the merge.</para>
13725 <para id="x_415">At the end of this process, your repository will have one
13726 extra head from the old patch queue, and a copy of the old patch
13727 queue will be in <filename role="special" class="directory" moreinfo="none">.hg/patches.N</filename>. You can remove the
13728 extra head using <command role="hg-cmd" moreinfo="none">hg qpop -a -n
13729 patches.N</command> or <command role="hg-cmd" moreinfo="none">hg
13730 strip</command>. You can delete <filename role="special" class="directory" moreinfo="none">.hg/patches.N</filename> once you are sure
13731 that you no longer need it as a backup.</para>
13732 </sect1>
13734 <sect1>
13735 <title>Identifying patches</title>
13737 <para id="x_416">MQ commands that work with patches let you refer to a patch
13738 either by using its name or by a number. By name is obvious
13739 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
13740 push patches until <filename moreinfo="none">foo.patch</filename> is
13741 applied.</para>
13743 <para id="x_417">As a shortcut, you can refer to a patch using both a name
13744 and a numeric offset; <literal moreinfo="none">foo.patch-2</literal> means
13745 <quote>two patches before <literal moreinfo="none">foo.patch</literal></quote>,
13746 while <literal moreinfo="none">bar.patch+4</literal> means <quote>four patches
13747 after <literal moreinfo="none">bar.patch</literal></quote>.</para>
13749 <para id="x_418">Referring to a patch by index isn't much different. The
13750 first patch printed in the output of <command role="hg-ext-mq" moreinfo="none">qseries</command> is patch zero (yes, it's
13751 one of those start-at-zero counting systems); the second is
13752 patch one; and so on.</para>
13754 <para id="x_419">MQ also makes it easy to work with patches when you are
13755 using normal Mercurial commands. Every command that accepts a
13756 changeset ID will also accept the name of an applied patch. MQ
13757 augments the tags normally in the repository with an eponymous
13758 one for each applied patch. In addition, the special tags
13759 <literal role="tag" moreinfo="none">qbase</literal> and
13760 <literal role="tag" moreinfo="none">qtip</literal> identify
13761 the <quote>bottom-most</quote> and topmost applied patches,
13762 respectively.</para>
13764 <para id="x_41a">These additions to Mercurial's normal tagging capabilities
13765 make dealing with patches even more of a breeze.</para>
13766 <itemizedlist>
13767 <listitem><para id="x_41b">Want to patchbomb a mailing list with your
13768 latest series of changes?</para>
13769 <programlisting format="linespecific">hg email qbase:qtip</programlisting>
13770 <para id="x_41c"> (Don't know what <quote>patchbombing</quote> is? See
13771 <xref linkend="sec:hgext:patchbomb"/>.)</para>
13772 </listitem>
13773 <listitem><para id="x_41d">Need to see all of the patches since
13774 <literal moreinfo="none">foo.patch</literal> that have touched files in a
13775 subdirectory of your tree?</para>
13776 <programlisting format="linespecific">hg log -r foo.patch:qtip subdir</programlisting>
13777 </listitem>
13778 </itemizedlist>
13780 <para id="x_41e">Because MQ makes the names of patches available to the rest
13781 of Mercurial through its normal internal tag machinery, you
13782 don't need to type in the entire name of a patch when you want
13783 to identify it by name.</para>
13785 <para id="x_41f">Another nice consequence of representing patch names as tags
13786 is that when you run the <command role="hg-cmd" moreinfo="none">hg log</command>
13787 command, it will display a patch's name as a tag, simply as part
13788 of its normal output. This makes it easy to visually
13789 distinguish applied patches from underlying
13790 <quote>normal</quote> revisions. The following example shows a
13791 few normal Mercurial commands in use with applied
13792 patches.</para>
13794 <!-- BEGIN mq.id.output -->
13795 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qapplied</userinput>
13796 first.patch
13797 second.patch
13798 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg log -r qbase:qtip</userinput>
13799 changeset: 1:c3bcf3b7335a
13800 tag: first.patch
13801 tag: qbase
13802 user: Bryan O'Sullivan <bos@serpentine.com>
13803 date: Sun Aug 16 14:05:08 2009 +0000
13804 summary: [mq]: first.patch
13806 changeset: 2:d189ba63b5f7
13807 tag: qtip
13808 tag: second.patch
13809 tag: tip
13810 user: Bryan O'Sullivan <bos@serpentine.com>
13811 date: Sun Aug 16 14:05:09 2009 +0000
13812 summary: [mq]: second.patch
13814 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg export second.patch</userinput>
13815 # HG changeset patch
13816 # User Bryan O'Sullivan <bos@serpentine.com>
13817 # Date 1250431509 0
13818 # Node ID d189ba63b5f7427f9644663c01fc16fe80399c65
13819 # Parent c3bcf3b7335afc0a250e85c51a1266d35d43a545
13820 [mq]: second.patch
13822 diff -r c3bcf3b7335a -r d189ba63b5f7 other.c
13823 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
13824 +++ b/other.c Sun Aug 16 14:05:09 2009 +0000
13825 @@ -0,0 +1,1 @@
13826 +double u;
13827 </screen>
13828 <!-- END mq.id.output -->
13830 </sect1>
13832 <sect1>
13833 <title>Useful things to know about</title>
13835 <para id="x_420">There are a number of aspects of MQ usage that don't fit
13836 tidily into sections of their own, but that are good to know.
13837 Here they are, in one place.</para>
13839 <itemizedlist>
13840 <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
13841 that represents the patch after the pop/push will have a
13842 <emphasis>different identity</emphasis> than the changeset
13843 that represented the hash beforehand. See <xref linkend="sec:mqref:cmd:qpush"/> for
13844 information as to why this is.</para>
13845 </listitem>
13846 <listitem><para id="x_422">It's not a good idea to <command role="hg-cmd" moreinfo="none">hg merge</command> changes from another
13847 branch with a patch changeset, at least if you want to
13848 maintain the <quote>patchiness</quote> of that changeset and
13849 changesets below it on the patch stack. If you try to do
13850 this, it will appear to succeed, but MQ will become
13851 confused.</para>
13852 </listitem></itemizedlist>
13853 </sect1>
13855 <sect1 id="sec:mq:repo">
13856 <title>Managing patches in a repository</title>
13858 <para id="x_423">Because MQ's <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory resides
13859 outside a Mercurial repository's working directory, the
13860 <quote>underlying</quote> Mercurial repository knows nothing
13861 about the management or presence of patches.</para>
13863 <para id="x_424">This presents the interesting possibility of managing the
13864 contents of the patch directory as a Mercurial repository in its
13865 own right. This can be a useful way to work. For example, you
13866 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
13867 patch. This lets you <quote>roll back</quote> to that version
13868 of the patch later on.</para>
13870 <para id="x_425">You can then share different versions of the same patch
13871 stack among multiple underlying repositories. I use this when I
13872 am developing a Linux kernel feature. I have a pristine copy of
13873 my kernel sources for each of several CPU architectures, and a
13874 cloned repository under each that contains the patches I am
13875 working on. When I want to test a change on a different
13876 architecture, I push my current patches to the patch repository
13877 associated with that kernel tree, pop and push all of my
13878 patches, and build and test that kernel.</para>
13880 <para id="x_426">Managing patches in a repository makes it possible for
13881 multiple developers to work on the same patch series without
13882 colliding with each other, all on top of an underlying source
13883 base that they may or may not control.</para>
13885 <sect2>
13886 <title>MQ support for patch repositories</title>
13888 <para id="x_427">MQ helps you to work with the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory as a
13889 repository; when you prepare a repository for working with
13890 patches using <command role="hg-ext-mq" moreinfo="none">qinit</command>, you
13891 can pass the <option role="hg-ext-mq-cmd-qinit-opt">hg
13892 -c</option> option to create the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory as a
13893 Mercurial repository.</para>
13895 <note>
13896 <para id="x_428"> If you forget to use the <option role="hg-ext-mq-cmd-qinit-opt">hg -c</option> option, you
13897 can simply go into the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory at any
13898 time and run <command role="hg-cmd" moreinfo="none">hg init</command>.
13899 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>
13901 <para id="x_429"> (<command role="hg-cmd" moreinfo="none">hg qinit <option role="hg-ext-mq-cmd-qinit-opt">hg -c</option></command>
13902 does this for you automatically); you
13903 <emphasis>really</emphasis> don't want to manage the
13904 <filename role="special" moreinfo="none">status</filename> file.</para>
13905 </note>
13907 <para id="x_42a">As a convenience, if MQ notices that the <filename class="directory" moreinfo="none">.hg/patches</filename> directory is a
13908 repository, it will automatically <command role="hg-cmd" moreinfo="none">hg
13909 add</command> every patch that you create and import.</para>
13911 <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>
13912 directory. This saves some bothersome typing.</para>
13914 <para id="x_42c">Finally, as a convenience to manage the patch directory,
13915 you can define the alias <command moreinfo="none">mq</command> on Unix
13916 systems. For example, on Linux systems using the
13917 <command moreinfo="none">bash</command> shell, you can include the following
13918 snippet in your <filename role="home" moreinfo="none">~/.bashrc</filename>.</para>
13920 <programlisting format="linespecific">alias mq=`hg -R $(hg root)/.hg/patches'</programlisting>
13922 <para id="x_42d">You can then issue commands of the form <command moreinfo="none">mq
13923 pull</command> from the main repository.</para>
13924 </sect2>
13926 <sect2>
13927 <title>A few things to watch out for</title>
13929 <para id="x_42e">MQ's support for working with a repository full of patches
13930 is limited in a few small respects.</para>
13932 <para id="x_42f">MQ cannot automatically detect changes that you make to
13933 the patch directory. If you <command role="hg-cmd" moreinfo="none">hg
13934 pull</command>, manually edit, or <command role="hg-cmd" moreinfo="none">hg
13935 update</command> changes to patches or the <filename role="special" moreinfo="none">series</filename> file, you will have to
13936 <command role="hg-cmd" moreinfo="none">hg qpop <option role="hg-ext-mq-cmd-qpop-opt">hg -a</option></command> and
13937 then <command role="hg-cmd" moreinfo="none">hg qpush <option role="hg-ext-mq-cmd-qpush-opt">hg -a</option></command> in
13938 the underlying repository to see those changes show up there.
13939 If you forget to do this, you can confuse MQ's idea of which
13940 patches are applied.</para>
13942 </sect2>
13943 </sect1>
13944 <sect1 id="sec:mq:tools">
13945 <title>Third party tools for working with patches</title>
13947 <para id="x_430">Once you've been working with patches for a while, you'll
13948 find yourself hungry for tools that will help you to understand
13949 and manipulate the patches you're dealing with.</para>
13951 <para id="x_431">The <command moreinfo="none">diffstat</command> command
13952 <citation>web:diffstat</citation> generates a histogram of the
13953 modifications made to each file in a patch. It provides a good
13954 way to <quote>get a sense of</quote> a patch—which files
13955 it affects, and how much change it introduces to each file and
13956 as a whole. (I find that it's a good idea to use
13957 <command moreinfo="none">diffstat</command>'s <option role="cmd-opt-diffstat">-p</option> option as a matter of
13958 course, as otherwise it will try to do clever things with
13959 prefixes of file names that inevitably confuse at least
13960 me.)</para>
13962 <!-- BEGIN mq.tools.tools -->
13963 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">diffstat -p1 remove-redundant-null-checks.patch</userinput>
13964 drivers/char/agp/sgi-agp.c | 5 ++---
13965 drivers/char/hvcs.c | 11 +++++------
13966 drivers/message/fusion/mptfc.c | 6 ++----
13967 drivers/message/fusion/mptsas.c | 3 +--
13968 drivers/net/fs_enet/fs_enet-mii.c | 3 +--
13969 drivers/net/wireless/ipw2200.c | 22 ++++++----------------
13970 drivers/scsi/libata-scsi.c | 4 +---
13971 drivers/video/au1100fb.c | 3 +--
13972 8 files changed, 19 insertions(+), 38 deletions(-)
13973 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">filterdiff -i '*/video/*' remove-redundant-null-checks.patch</userinput>
13974 --- a/drivers/video/au1100fb.c~remove-redundant-null-checks-before-free-in-drivers
13975 +++ a/drivers/video/au1100fb.c
13976 @@ -743,8 +743,7 @@ void __exit au1100fb_cleanup(void)
13977 {
13978 driver_unregister(&au1100fb_driver);
13980 - if (drv_info.opt_mode)
13981 - kfree(drv_info.opt_mode);
13982 + kfree(drv_info.opt_mode);
13983 }
13985 module_init(au1100fb_init);
13986 </screen>
13987 <!-- END mq.tools.tools -->
13990 <para id="x_432">The <literal role="package" moreinfo="none">patchutils</literal> package
13991 <citation>web:patchutils</citation> is invaluable. It provides a
13992 set of small utilities that follow the <quote>Unix
13993 philosophy;</quote> each does one useful thing with a patch.
13994 The <literal role="package" moreinfo="none">patchutils</literal> command I use
13995 most is <command moreinfo="none">filterdiff</command>, which extracts subsets
13996 from a patch file. For example, given a patch that modifies
13997 hundreds of files across dozens of directories, a single
13998 invocation of <command moreinfo="none">filterdiff</command> can generate a
13999 smaller patch that only touches files whose names match a
14000 particular glob pattern. See <xref linkend="mq-collab:tips:interdiff"/> for another
14001 example.</para>
14003 </sect1>
14004 <sect1>
14005 <title>Good ways to work with patches</title>
14007 <para id="x_433">Whether you are working on a patch series to submit to a
14008 free software or open source project, or a series that you
14009 intend to treat as a sequence of regular changesets when you're
14010 done, you can use some simple techniques to keep your work well
14011 organized.</para>
14013 <para id="x_434">Give your patches descriptive names. A good name for a
14014 patch might be <filename moreinfo="none">rework-device-alloc.patch</filename>,
14015 because it will immediately give you a hint what the purpose of
14016 the patch is. Long names shouldn't be a problem; you won't be
14017 typing the names often, but you <emphasis>will</emphasis> be
14018 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
14019 becomes especially important when you have a number of patches
14020 to work with, or if you are juggling a number of different tasks
14021 and your patches only get a fraction of your attention.</para>
14023 <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
14024 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
14025 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
14026 one I intended, and it's often tricky to migrate changes into
14027 the right patch after making them in the wrong one.</para>
14029 <para id="x_436">For this reason, it is very much worth investing a little
14030 time to learn how to use some of the third-party tools I
14031 described in <xref linkend="sec:mq:tools"/>,
14032 particularly
14033 <command moreinfo="none">diffstat</command> and <command moreinfo="none">filterdiff</command>.
14034 The former will give you a quick idea of what changes your patch
14035 is making, while the latter makes it easy to splice hunks
14036 selectively out of one patch and into another.</para>
14038 </sect1>
14039 <sect1>
14040 <title>MQ cookbook</title>
14042 <sect2>
14043 <title>Manage <quote>trivial</quote> patches</title>
14045 <para id="x_437">Because the overhead of dropping files into a new
14046 Mercurial repository is so low, it makes a lot of sense to
14047 manage patches this way even if you simply want to make a few
14048 changes to a source tarball that you downloaded.</para>
14050 <para id="x_438">Begin by downloading and unpacking the source tarball, and
14051 turning it into a Mercurial repository.</para>
14053 <!-- BEGIN mq.tarball.download -->
14054 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">download netplug-1.2.5.tar.bz2</userinput>
14055 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">tar jxf netplug-1.2.5.tar.bz2</userinput>
14056 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd netplug-1.2.5</userinput>
14057 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg init</userinput>
14058 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit -q --addremove --message netplug-1.2.5</userinput>
14059 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
14060 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone netplug-1.2.5 netplug</userinput>
14061 updating working directory
14062 18 files updated, 0 files merged, 0 files removed, 0 files unresolved
14063 </screen>
14064 <!-- END mq.tarball.download -->
14067 <para id="x_439">Continue by creating a patch stack and making your
14068 changes.</para>
14070 <!-- BEGIN mq.tarball.qinit -->
14071 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd netplug</userinput>
14072 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qinit</userinput>
14073 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew -m 'fix build problem with gcc 4' build-fix.patch</userinput>
14074 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">perl -pi -e 's/int addr_len/socklen_t addr_len/' netlink.c</userinput>
14075 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
14076 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg tip -p</userinput>
14077 changeset: 1:eeab56666c54
14078 tag: qtip
14079 tag: build-fix.patch
14080 tag: tip
14081 tag: qbase
14082 user: Bryan O'Sullivan <bos@serpentine.com>
14083 date: Sun Aug 16 14:05:10 2009 +0000
14084 summary: fix build problem with gcc 4
14086 diff -r 1f6afe9a2d68 -r eeab56666c54 netlink.c
14087 --- a/netlink.c Sun Aug 16 14:05:09 2009 +0000
14088 +++ b/netlink.c Sun Aug 16 14:05:10 2009 +0000
14089 @@ -275,7 +275,7 @@
14090 exit(1);
14091 }
14093 - int addr_len = sizeof(addr);
14094 + socklen_t addr_len = sizeof(addr);
14096 if (getsockname(fd, (struct sockaddr *) &addr, &addr_len) == -1) {
14097 do_log(LOG_ERR, "Could not get socket details: %m");
14099 </screen>
14100 <!-- END mq.tarball.qinit -->
14103 <para id="x_43a">Let's say a few weeks or months pass, and your package
14104 author releases a new version. First, bring their changes
14105 into the repository.</para>
14107 <!-- BEGIN mq.tarball.newsource -->
14108 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop -a</userinput>
14109 patch queue now empty
14110 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
14111 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">download netplug-1.2.8.tar.bz2</userinput>
14112 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg clone netplug-1.2.5 netplug-1.2.8</userinput>
14113 updating working directory
14114 18 files updated, 0 files merged, 0 files removed, 0 files unresolved
14115 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd netplug-1.2.8</userinput>
14116 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg locate -0 | xargs -0 rm</userinput>
14117 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ..</userinput>
14118 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">tar jxf netplug-1.2.8.tar.bz2</userinput>
14119 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd netplug-1.2.8</userinput>
14120 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg commit --addremove --message netplug-1.2.8</userinput>
14121 </screen>
14122 <!-- END mq.tarball.newsource -->
14125 <para id="x_43b">The pipeline starting with <command role="hg-cmd" moreinfo="none">hg
14126 locate</command> above deletes all files in the working
14127 directory, so that <command role="hg-cmd" moreinfo="none">hg
14128 commit</command>'s <option role="hg-opt-commit">--addremove</option> option can
14129 actually tell which files have really been removed in the
14130 newer version of the source.</para>
14132 <para id="x_43c">Finally, you can apply your patches on top of the new
14133 tree.</para>
14135 <!-- BEGIN mq.tarball.repush -->
14136 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cd ../netplug</userinput>
14137 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg pull ../netplug-1.2.8</userinput>
14138 pulling from ../netplug-1.2.8
14139 searching for changes
14140 adding changesets
14141 adding manifests
14142 adding file changes
14143 added 1 changesets with 12 changes to 12 files
14144 (run 'hg update' to get a working copy)
14145 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpush -a</userinput>
14146 (working directory not at tip)
14147 applying build-fix.patch
14148 now at: build-fix.patch
14149 </screen>
14150 <!-- END mq.tarball.repush -->
14152 </sect2>
14154 <sect2 id="sec:mq:combine">
14155 <title>Combining entire patches</title>
14157 <para id="x_43d">MQ provides a command, <command role="hg-ext-mq" moreinfo="none">qfold</command> that lets you combine
14158 entire patches. This <quote>folds</quote> the patches you
14159 name, in the order you name them, into the topmost applied
14160 patch, and concatenates their descriptions onto the end of its
14161 description. The patches that you fold must be unapplied
14162 before you fold them.</para>
14164 <para id="x_43e">The order in which you fold patches matters. If your
14165 topmost applied patch is <literal moreinfo="none">foo</literal>, and you
14166 <command role="hg-ext-mq" moreinfo="none">qfold</command>
14167 <literal moreinfo="none">bar</literal> and <literal moreinfo="none">quux</literal> into it,
14168 you will end up with a patch that has the same effect as if
14169 you applied first <literal moreinfo="none">foo</literal>, then
14170 <literal moreinfo="none">bar</literal>, followed by
14171 <literal moreinfo="none">quux</literal>.</para>
14172 </sect2>
14174 <sect2>
14175 <title>Merging part of one patch into another</title>
14177 <para id="x_43f">Merging <emphasis>part</emphasis> of one patch into
14178 another is more difficult than combining entire
14179 patches.</para>
14181 <para id="x_440">If you want to move changes to entire files, you can use
14182 <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
14183 modifications to snip out of one patch, concatenating its
14184 output onto the end of the patch you want to merge into. You
14185 usually won't need to modify the patch you've merged the
14186 changes from. Instead, MQ will report some rejected hunks
14187 when you <command role="hg-ext-mq" moreinfo="none">qpush</command> it (from
14188 the hunks you moved into the other patch), and you can simply
14189 <command role="hg-ext-mq" moreinfo="none">qrefresh</command> the patch to drop
14190 the duplicate hunks.</para>
14192 <para id="x_441">If you have a patch that has multiple hunks modifying a
14193 file, and you only want to move a few of those hunks, the job
14194 becomes more messy, but you can still partly automate it. Use
14195 <command moreinfo="none">lsdiff -nvv</command> to print some metadata about
14196 the patch.</para>
14198 <!-- BEGIN mq.tools.lsdiff -->
14199 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">lsdiff -nvv remove-redundant-null-checks.patch</userinput>
14200 22 File #1 a/drivers/char/agp/sgi-agp.c
14201 24 Hunk #1 static int __devinit agp_sgi_init(void)
14202 37 File #2 a/drivers/char/hvcs.c
14203 39 Hunk #1 static struct tty_operations hvcs_ops =
14204 53 Hunk #2 static int hvcs_alloc_index_list(int n)
14205 69 File #3 a/drivers/message/fusion/mptfc.c
14206 71 Hunk #1 mptfc_GetFcDevPage0(MPT_ADAPTER *ioc, in
14207 85 File #4 a/drivers/message/fusion/mptsas.c
14208 87 Hunk #1 mptsas_probe_hba_phys(MPT_ADAPTER *ioc)
14209 98 File #5 a/drivers/net/fs_enet/fs_enet-mii.c
14210 100 Hunk #1 static struct fs_enet_mii_bus *create_bu
14211 111 File #6 a/drivers/net/wireless/ipw2200.c
14212 113 Hunk #1 static struct ipw_fw_error *ipw_alloc_er
14213 126 Hunk #2 static ssize_t clear_error(struct device
14214 140 Hunk #3 static void ipw_irq_tasklet(struct ipw_p
14215 150 Hunk #4 static void ipw_pci_remove(struct pci_de
14216 164 File #7 a/drivers/scsi/libata-scsi.c
14217 166 Hunk #1 int ata_cmd_ioctl(struct scsi_device *sc
14218 178 File #8 a/drivers/video/au1100fb.c
14219 180 Hunk #1 void __exit au1100fb_cleanup(void)
14220 </screen>
14221 <!-- END mq.tools.lsdiff -->
14224 <para id="x_442">This command prints three different kinds of
14225 number:</para>
14226 <itemizedlist>
14227 <listitem><para id="x_443">(in the first column) a <emphasis>file
14228 number</emphasis> to identify each file modified in the
14229 patch;</para>
14230 </listitem>
14231 <listitem><para id="x_444">(on the next line, indented) the line number
14232 within a modified file where a hunk starts; and</para>
14233 </listitem>
14234 <listitem><para id="x_445">(on the same line) a <emphasis>hunk
14235 number</emphasis> to identify that hunk.</para>
14236 </listitem></itemizedlist>
14238 <para id="x_446">You'll have to use some visual inspection, and reading of
14239 the patch, to identify the file and hunk numbers you'll want,
14240 but you can then pass them to to
14241 <command moreinfo="none">filterdiff</command>'s <option role="cmd-opt-filterdiff">--files</option> and <option role="cmd-opt-filterdiff">--hunks</option> options, to
14242 select exactly the file and hunk you want to extract.</para>
14244 <para id="x_447">Once you have this hunk, you can concatenate it onto the
14245 end of your destination patch and continue with the remainder
14246 of <xref linkend="sec:mq:combine"/>.</para>
14248 </sect2>
14249 </sect1>
14250 <sect1>
14251 <title>Differences between quilt and MQ</title>
14253 <para id="x_448">If you are already familiar with quilt, MQ provides a
14254 similar command set. There are a few differences in the way
14255 that it works.</para>
14257 <para id="x_449">You will already have noticed that most quilt commands have
14258 MQ counterparts that simply begin with a
14259 <quote><literal moreinfo="none">q</literal></quote>. The exceptions are quilt's
14260 <literal moreinfo="none">add</literal> and <literal moreinfo="none">remove</literal> commands,
14261 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
14262 remove</command> commands. There is no MQ equivalent of the
14263 quilt <literal moreinfo="none">edit</literal> command.</para>
14265 </sect1>
14266 </chapter>
14268 <!--
14269 local variables:
14270 sgml-parent-document: ("00book.xml" "book" "chapter")
14271 end:
14272 -->
14274 <!-- BEGIN ch13 -->
14275 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
14277 <chapter id="chap:mq-collab">
14278 <?dbhtml filename="advanced-uses-of-mercurial-queues.html"?>
14279 <title>Advanced uses of Mercurial Queues</title>
14281 <para id="x_15d">While it's easy to pick up straightforward uses of Mercurial
14282 Queues, use of a little discipline and some of MQ's less
14283 frequently used capabilities makes it possible to work in
14284 complicated development environments.</para>
14286 <para id="x_15e">In this chapter, I will use as an example a technique I have
14287 used to manage the development of an Infiniband device driver for
14288 the Linux kernel. The driver in question is large (at least as
14289 drivers go), with 25,000 lines of code spread across 35 source
14290 files. It is maintained by a small team of developers.</para>
14292 <para id="x_15f">While much of the material in this chapter is specific to
14293 Linux, the same principles apply to any code base for which you're
14294 not the primary owner, and upon which you need to do a lot of
14295 development.</para>
14297 <sect1>
14298 <title>The problem of many targets</title>
14300 <para id="x_160">The Linux kernel changes rapidly, and has never been
14301 internally stable; developers frequently make drastic changes
14302 between releases. This means that a version of the driver that
14303 works well with a particular released version of the kernel will
14304 not even <emphasis>compile</emphasis> correctly against,
14305 typically, any other version.</para>
14307 <para id="x_161">To maintain a driver, we have to keep a number of distinct
14308 versions of Linux in mind.</para>
14309 <itemizedlist>
14310 <listitem><para id="x_162">One target is the main Linux kernel development
14311 tree. Maintenance of the code is in this case partly shared
14312 by other developers in the kernel community, who make
14313 <quote>drive-by</quote> modifications to the driver as they
14314 develop and refine kernel subsystems.</para>
14315 </listitem>
14316 <listitem><para id="x_163">We also maintain a number of
14317 <quote>backports</quote> to older versions of the Linux
14318 kernel, to support the needs of customers who are running
14319 older Linux distributions that do not incorporate our
14320 drivers. (To <emphasis>backport</emphasis> a piece of code
14321 is to modify it to work in an older version of its target
14322 environment than the version it was developed for.)</para>
14323 </listitem>
14324 <listitem><para id="x_164">Finally, we make software releases on a schedule
14325 that is necessarily not aligned with those used by Linux
14326 distributors and kernel developers, so that we can deliver
14327 new features to customers without forcing them to upgrade
14328 their entire kernels or distributions.</para>
14329 </listitem></itemizedlist>
14331 <sect2>
14332 <title>Tempting approaches that don't work well</title>
14334 <para id="x_165">There are two <quote>standard</quote> ways to maintain a
14335 piece of software that has to target many different
14336 environments.</para>
14338 <para id="x_166">The first is to maintain a number of branches, each
14339 intended for a single target. The trouble with this approach
14340 is that you must maintain iron discipline in the flow of
14341 changes between repositories. A new feature or bug fix must
14342 start life in a <quote>pristine</quote> repository, then
14343 percolate out to every backport repository. Backport changes
14344 are more limited in the branches they should propagate to; a
14345 backport change that is applied to a branch where it doesn't
14346 belong will probably stop the driver from compiling.</para>
14348 <para id="x_167">The second is to maintain a single source tree filled with
14349 conditional statements that turn chunks of code on or off
14350 depending on the intended target. Because these
14351 <quote>ifdefs</quote> are not allowed in the Linux kernel
14352 tree, a manual or automatic process must be followed to strip
14353 them out and yield a clean tree. A code base maintained in
14354 this fashion rapidly becomes a rat's nest of conditional
14355 blocks that are difficult to understand and maintain.</para>
14357 <para id="x_168">Neither of these approaches is well suited to a situation
14358 where you don't <quote>own</quote> the canonical copy of a
14359 source tree. In the case of a Linux driver that is
14360 distributed with the standard kernel, Linus's tree contains
14361 the copy of the code that will be treated by the world as
14362 canonical. The upstream version of <quote>my</quote> driver
14363 can be modified by people I don't know, without me even
14364 finding out about it until after the changes show up in
14365 Linus's tree.</para>
14367 <para id="x_169">These approaches have the added weakness of making it
14368 difficult to generate well-formed patches to submit
14369 upstream.</para>
14371 <para id="x_16a">In principle, Mercurial Queues seems like a good candidate
14372 to manage a development scenario such as the above. While
14373 this is indeed the case, MQ contains a few added features that
14374 make the job more pleasant.</para>
14376 </sect2>
14377 </sect1>
14378 <sect1>
14379 <title>Conditionally applying patches with guards</title>
14381 <para id="x_16b">Perhaps the best way to maintain sanity with so many targets
14382 is to be able to choose specific patches to apply for a given
14383 situation. MQ provides a feature called <quote>guards</quote>
14384 (which originates with quilt's <literal moreinfo="none">guards</literal>
14385 command) that does just this. To start off, let's create a
14386 simple repository for experimenting in.</para>
14388 <!-- BEGIN mq.guards.init -->
14389 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qinit</userinput>
14390 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew hello.patch</userinput>
14391 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo hello > hello</userinput>
14392 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add hello</userinput>
14393 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
14394 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qnew goodbye.patch</userinput>
14395 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo goodbye > goodbye</userinput>
14396 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg add goodbye</userinput>
14397 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qrefresh</userinput>
14398 </screen>
14399 <!-- END mq.guards.init -->
14402 <para id="x_16c">This gives us a tiny repository that contains two patches
14403 that don't have any dependencies on each other, because they
14404 touch different files.</para>
14406 <para id="x_16d">The idea behind conditional application is that you can
14407 <quote>tag</quote> a patch with a <emphasis>guard</emphasis>,
14408 which is simply a text string of your choosing, then tell MQ to
14409 select specific guards to use when applying patches. MQ will
14410 then either apply, or skip over, a guarded patch, depending on
14411 the guards that you have selected.</para>
14413 <para id="x_16e">A patch can have an arbitrary number of guards; each one is
14414 <emphasis>positive</emphasis> (<quote>apply this patch if this
14415 guard is selected</quote>) or <emphasis>negative</emphasis>
14416 (<quote>skip this patch if this guard is selected</quote>). A
14417 patch with no guards is always applied.</para>
14419 </sect1>
14420 <sect1>
14421 <title>Controlling the guards on a patch</title>
14423 <para id="x_16f">The <command role="hg-ext-mq" moreinfo="none">qguard</command> command lets
14424 you determine which guards should apply to a patch, or display
14425 the guards that are already in effect. Without any arguments, it
14426 displays the guards on the current topmost patch.</para>
14428 <!-- BEGIN mq.guards.qguard -->
14429 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qguard</userinput>
14430 goodbye.patch: unguarded
14431 </screen>
14432 <!-- END mq.guards.qguard -->
14435 <para id="x_170">To set a positive guard on a patch, prefix the name of the
14436 guard with a <quote><literal moreinfo="none">+</literal></quote>.</para>
14438 <!-- BEGIN mq.guards.qguard.pos -->
14439 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qguard +foo</userinput>
14440 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qguard</userinput>
14441 goodbye.patch: +foo
14442 </screen>
14443 <!-- END mq.guards.qguard.pos -->
14446 <para id="x_171">To set a negative guard
14447 on a patch, prefix the name of the guard with a
14448 <quote><literal moreinfo="none">-</literal></quote>.</para>
14450 <!-- BEGIN mq.guards.qguard.neg -->
14451 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qguard -- hello.patch -quux</userinput>
14452 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qguard hello.patch</userinput>
14453 hello.patch: -quux
14454 </screen>
14455 <!-- END mq.guards.qguard.neg -->
14458 <para id="x_74a">Notice that we prefixed the arguments to the <command moreinfo="none">hg
14459 qguard</command> command with a <literal moreinfo="none">--</literal> here, so
14460 that Mercurial would not interpret the text
14461 <literal moreinfo="none">-quux</literal> as an option.</para>
14463 <note>
14464 <title>Setting vs. modifying</title>
14466 <para id="x_172"> The <command role="hg-ext-mq" moreinfo="none">qguard</command> command
14467 <emphasis>sets</emphasis> the guards on a patch; it doesn't
14468 <emphasis>modify</emphasis> them. What this means is that if
14469 you run <command role="hg-cmd" moreinfo="none">hg qguard +a +b</command> on a
14470 patch, then <command role="hg-cmd" moreinfo="none">hg qguard +c</command> on
14471 the same patch, the <emphasis>only</emphasis> guard that will
14472 be set on it afterwards is <literal moreinfo="none">+c</literal>.</para>
14473 </note>
14475 <para id="x_173">Mercurial stores guards in the <filename role="special" moreinfo="none">series</filename> file; the form in which they
14476 are stored is easy both to understand and to edit by hand. (In
14477 other words, you don't have to use the <command role="hg-ext-mq" moreinfo="none">qguard</command> command if you don't want
14478 to; it's okay to simply edit the <filename role="special" moreinfo="none">series</filename> file.)</para>
14480 <!-- BEGIN mq.guards.series -->
14481 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/patches/series</userinput>
14482 hello.patch #-quux
14483 goodbye.patch #+foo
14484 </screen>
14485 <!-- END mq.guards.series -->
14488 </sect1>
14489 <sect1>
14490 <title>Selecting the guards to use</title>
14492 <para id="x_174">The <command role="hg-ext-mq" moreinfo="none">qselect</command> command
14493 determines which guards are active at a given time. The effect
14494 of this is to determine which patches MQ will apply the next
14495 time you run <command role="hg-ext-mq" moreinfo="none">qpush</command>. It has
14496 no other effect; in particular, it doesn't do anything to
14497 patches that are already applied.</para>
14499 <para id="x_175">With no arguments, the <command role="hg-ext-mq" moreinfo="none">qselect</command> command lists the guards
14500 currently in effect, one per line of output. Each argument is
14501 treated as the name of a guard to apply.</para>
14503 <!-- BEGIN mq.guards.qselect.foo -->
14504 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop -a</userinput>
14505 patch queue now empty
14506 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect</userinput>
14507 no active guards
14508 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect foo</userinput>
14509 number of unguarded, unapplied patches has changed from 1 to 2
14510 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect</userinput>
14511 foo
14512 </screen>
14513 <!-- END mq.guards.qselect.foo -->
14516 <para id="x_176">In case you're interested, the currently selected guards are
14517 stored in the <filename role="special" moreinfo="none">guards</filename> file.</para>
14519 <!-- BEGIN mq.guards.qselect.cat -->
14520 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">cat .hg/patches/guards</userinput>
14521 foo
14522 </screen>
14523 <!-- END mq.guards.qselect.cat -->
14526 <para id="x_177">We can see the effect the selected guards have when we run
14527 <command role="hg-ext-mq" moreinfo="none">qpush</command>.</para>
14529 <!-- BEGIN mq.guards.qselect.qpush -->
14530 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpush -a</userinput>
14531 applying hello.patch
14532 applying goodbye.patch
14533 now at: goodbye.patch
14534 </screen>
14535 <!-- END mq.guards.qselect.qpush -->
14538 <para id="x_178">A guard cannot start with a
14539 <quote><literal moreinfo="none">+</literal></quote> or
14540 <quote><literal moreinfo="none">-</literal></quote> character. The name of a
14541 guard must not contain white space, but most other characters
14542 are acceptable. If you try to use a guard with an invalid name,
14543 MQ will complain:</para>
14545 <!-- BEGIN mq.guards.qselect.error -->
14546 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect +foo</userinput>
14547 abort: guard '+foo' starts with invalid character: '+'
14548 </screen>
14549 <!-- END mq.guards.qselect.error -->
14552 <para id="x_179">Changing the selected guards changes the patches that are
14553 applied.</para>
14555 <!-- BEGIN mq.guards.qselect.quux -->
14556 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect quux</userinput>
14557 number of guarded, applied patches has changed from 0 to 2
14558 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop -a</userinput>
14559 patch queue now empty
14560 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpush -a</userinput>
14561 patch series already fully applied
14562 </screen>
14563 <!-- END mq.guards.qselect.quux -->
14566 <para id="x_17a">You can see in the example below that negative guards take
14567 precedence over positive guards.</para>
14569 <!-- BEGIN mq.guards.qselect.foobar -->
14570 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qselect foo bar</userinput>
14571 number of unguarded, unapplied patches has changed from 0 to 2
14572 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpop -a</userinput>
14573 no patches applied
14574 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg qpush -a</userinput>
14575 applying hello.patch
14576 applying goodbye.patch
14577 now at: goodbye.patch
14578 </screen>
14579 <!-- END mq.guards.qselect.foobar -->
14582 </sect1>
14583 <sect1>
14584 <title>MQ's rules for applying patches</title>
14586 <para id="x_17b">The rules that MQ uses when deciding whether to apply a
14587 patch are as follows.</para>
14588 <itemizedlist>
14589 <listitem><para id="x_17c">A patch that has no guards is always
14590 applied.</para>
14591 </listitem>
14592 <listitem><para id="x_17d">If the patch has any negative guard that matches
14593 any currently selected guard, the patch is skipped.</para>
14594 </listitem>
14595 <listitem><para id="x_17e">If the patch has any positive guard that matches
14596 any currently selected guard, the patch is applied.</para>
14597 </listitem>
14598 <listitem><para id="x_17f">If the patch has positive or negative guards,
14599 but none matches any currently selected guard, the patch is
14600 skipped.</para>
14601 </listitem></itemizedlist>
14603 </sect1>
14604 <sect1>
14605 <title>Trimming the work environment</title>
14607 <para id="x_180">In working on the device driver I mentioned earlier, I don't
14608 apply the patches to a normal Linux kernel tree. Instead, I use
14609 a repository that contains only a snapshot of the source files
14610 and headers that are relevant to Infiniband development. This
14611 repository is 1% the size of a kernel repository, so it's easier
14612 to work with.</para>
14614 <para id="x_181">I then choose a <quote>base</quote> version on top of which
14615 the patches are applied. This is a snapshot of the Linux kernel
14616 tree as of a revision of my choosing. When I take the snapshot,
14617 I record the changeset ID from the kernel repository in the
14618 commit message. Since the snapshot preserves the
14619 <quote>shape</quote> and content of the relevant parts of the
14620 kernel tree, I can apply my patches on top of either my tiny
14621 repository or a normal kernel tree.</para>
14623 <para id="x_182">Normally, the base tree atop which the patches apply should
14624 be a snapshot of a very recent upstream tree. This best
14625 facilitates the development of patches that can easily be
14626 submitted upstream with few or no modifications.</para>
14628 </sect1>
14629 <sect1>
14630 <title>Dividing up the <filename role="special" moreinfo="none">series</filename>
14631 file</title>
14633 <para id="x_183">I categorise the patches in the <filename role="special" moreinfo="none">series</filename> file into a number of logical
14634 groups. Each section of like patches begins with a block of
14635 comments that describes the purpose of the patches that
14636 follow.</para>
14638 <para id="x_184">The sequence of patch groups that I maintain follows. The
14639 ordering of these groups is important; I'll describe why after I
14640 introduce the groups.</para>
14641 <itemizedlist>
14642 <listitem><para id="x_185">The <quote>accepted</quote> group. Patches that
14643 the development team has submitted to the maintainer of the
14644 Infiniband subsystem, and which he has accepted, but which
14645 are not present in the snapshot that the tiny repository is
14646 based on. These are <quote>read only</quote> patches,
14647 present only to transform the tree into a similar state as
14648 it is in the upstream maintainer's repository.</para>
14649 </listitem>
14650 <listitem><para id="x_186">The <quote>rework</quote> group. Patches that I
14651 have submitted, but that the upstream maintainer has
14652 requested modifications to before he will accept
14653 them.</para>
14654 </listitem>
14655 <listitem><para id="x_187">The <quote>pending</quote> group. Patches that
14656 I have not yet submitted to the upstream maintainer, but
14657 which we have finished working on. These will be <quote>read
14658 only</quote> for a while. If the upstream maintainer
14659 accepts them upon submission, I'll move them to the end of
14660 the <quote>accepted</quote> group. If he requests that I
14661 modify any, I'll move them to the beginning of the
14662 <quote>rework</quote> group.</para>
14663 </listitem>
14664 <listitem><para id="x_188">The <quote>in progress</quote> group. Patches
14665 that are actively being developed, and should not be
14666 submitted anywhere yet.</para>
14667 </listitem>
14668 <listitem><para id="x_189">The <quote>backport</quote> group. Patches that
14669 adapt the source tree to older versions of the kernel
14670 tree.</para>
14671 </listitem>
14672 <listitem><para id="x_18a">The <quote>do not ship</quote> group. Patches
14673 that for some reason should never be submitted upstream.
14674 For example, one such patch might change embedded driver
14675 identification strings to make it easier to distinguish, in
14676 the field, between an out-of-tree version of the driver and
14677 a version shipped by a distribution vendor.</para>
14678 </listitem></itemizedlist>
14680 <para id="x_18b">Now to return to the reasons for ordering groups of patches
14681 in this way. We would like the lowest patches in the stack to
14682 be as stable as possible, so that we will not need to rework
14683 higher patches due to changes in context. Putting patches that
14684 will never be changed first in the <filename role="special" moreinfo="none">series</filename> file serves this
14685 purpose.</para>
14687 <para id="x_18c">We would also like the patches that we know we'll need to
14688 modify to be applied on top of a source tree that resembles the
14689 upstream tree as closely as possible. This is why we keep
14690 accepted patches around for a while.</para>
14692 <para id="x_18d">The <quote>backport</quote> and <quote>do not ship</quote>
14693 patches float at the end of the <filename role="special" moreinfo="none">series</filename> file. The backport patches
14694 must be applied on top of all other patches, and the <quote>do
14695 not ship</quote> patches might as well stay out of harm's
14696 way.</para>
14698 </sect1>
14699 <sect1>
14700 <title>Maintaining the patch series</title>
14702 <para id="x_18e">In my work, I use a number of guards to control which
14703 patches are to be applied.</para>
14705 <itemizedlist>
14706 <listitem><para id="x_18f"><quote>Accepted</quote> patches are guarded with
14707 <literal moreinfo="none">accepted</literal>. I enable this guard most of
14708 the time. When I'm applying the patches on top of a tree
14709 where the patches are already present, I can turn this patch
14710 off, and the patches that follow it will apply
14711 cleanly.</para>
14712 </listitem>
14713 <listitem><para id="x_190">Patches that are <quote>finished</quote>, but
14714 not yet submitted, have no guards. If I'm applying the
14715 patch stack to a copy of the upstream tree, I don't need to
14716 enable any guards in order to get a reasonably safe source
14717 tree.</para>
14718 </listitem>
14719 <listitem><para id="x_191">Those patches that need reworking before being
14720 resubmitted are guarded with
14721 <literal moreinfo="none">rework</literal>.</para>
14722 </listitem>
14723 <listitem><para id="x_192">For those patches that are still under
14724 development, I use <literal moreinfo="none">devel</literal>.</para>
14725 </listitem>
14726 <listitem><para id="x_193">A backport patch may have several guards, one
14727 for each version of the kernel to which it applies. For
14728 example, a patch that backports a piece of code to 2.6.9
14729 will have a <literal moreinfo="none">2.6.9</literal> guard.</para>
14730 </listitem></itemizedlist>
14731 <para id="x_194">This variety of guards gives me considerable flexibility in
14732 determining what kind of source tree I want to end up with. For
14733 most situations, the selection of appropriate guards is
14734 automated during the build process, but I can manually tune the
14735 guards to use for less common circumstances.</para>
14737 <sect2>
14738 <title>The art of writing backport patches</title>
14740 <para id="x_195">Using MQ, writing a backport patch is a simple process.
14741 All such a patch has to do is modify a piece of code that uses
14742 a kernel feature not present in the older version of the
14743 kernel, so that the driver continues to work correctly under
14744 that older version.</para>
14746 <para id="x_196">A useful goal when writing a good backport patch is to
14747 make your code look as if it was written for the older version
14748 of the kernel you're targeting. The less obtrusive the patch,
14749 the easier it will be to understand and maintain. If you're
14750 writing a collection of backport patches to avoid the
14751 <quote>rat's nest</quote> effect of lots of
14752 <literal moreinfo="none">#ifdef</literal>s (hunks of source code that are only
14753 used conditionally) in your code, don't introduce
14754 version-dependent <literal moreinfo="none">#ifdef</literal>s into the patches.
14755 Instead, write several patches, each of which makes
14756 unconditional changes, and control their application using
14757 guards.</para>
14759 <para id="x_197">There are two reasons to divide backport patches into a
14760 distinct group, away from the <quote>regular</quote> patches
14761 whose effects they modify. The first is that intermingling the
14762 two makes it more difficult to use a tool like the <literal role="hg-ext" moreinfo="none">patchbomb</literal> extension to automate the
14763 process of submitting the patches to an upstream maintainer.
14764 The second is that a backport patch could perturb the context
14765 in which a subsequent regular patch is applied, making it
14766 impossible to apply the regular patch cleanly
14767 <emphasis>without</emphasis> the earlier backport patch
14768 already being applied.</para>
14770 </sect2>
14771 </sect1>
14772 <sect1>
14773 <title>Useful tips for developing with MQ</title>
14775 <sect2>
14776 <title>Organising patches in directories</title>
14778 <para id="x_198">If you're working on a substantial project with MQ, it's
14779 not difficult to accumulate a large number of patches. For
14780 example, I have one patch repository that contains over 250
14781 patches.</para>
14783 <para id="x_199">If you can group these patches into separate logical
14784 categories, you can if you like store them in different
14785 directories; MQ has no problems with patch names that contain
14786 path separators.</para>
14788 </sect2>
14789 <sect2 id="mq-collab:tips:interdiff">
14790 <title>Viewing the history of a patch</title>
14792 <para id="x_19a">If you're developing a set of patches over a long time,
14793 it's a good idea to maintain them in a repository, as
14794 discussed in <xref linkend="sec:mq:repo"/>. If you do
14795 so, you'll quickly
14796 discover that using the <command role="hg-cmd" moreinfo="none">hg
14797 diff</command> command to look at the history of changes to
14798 a patch is unworkable. This is in part because you're looking
14799 at the second derivative of the real code (a diff of a diff),
14800 but also because MQ adds noise to the process by modifying
14801 time stamps and directory names when it updates a
14802 patch.</para>
14804 <para id="x_19b">However, you can use the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension, which is bundled
14805 with Mercurial, to turn a diff of two versions of a patch into
14806 something readable. To do this, you will need a third-party
14807 package called <literal role="package" moreinfo="none">patchutils</literal>
14808 <citation>web:patchutils</citation>. This provides a command
14809 named <command moreinfo="none">interdiff</command>, which shows the
14810 differences between two diffs as a diff. Used on two versions
14811 of the same diff, it generates a diff that represents the diff
14812 from the first to the second version.</para>
14814 <para id="x_19c">You can enable the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension in the usual way,
14815 by adding a line to the <literal role="rc-extensions" moreinfo="none">extensions</literal> section of your
14816 <filename role="special" moreinfo="none">~/.hgrc</filename>.</para>
14817 <programlisting format="linespecific">[extensions]
14818 extdiff =</programlisting>
14819 <para id="x_19d">The <command moreinfo="none">interdiff</command> command expects to be
14820 passed the names of two files, but the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension passes the program
14821 it runs a pair of directories, each of which can contain an
14822 arbitrary number of files. We thus need a small program that
14823 will run <command moreinfo="none">interdiff</command> on each pair of files in
14824 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
14825 source code repository that accompanies this book. <!--
14826 &example.hg-interdiff; --></para>
14828 <para id="x_19e">With the <filename role="special" moreinfo="none">hg-interdiff</filename>
14829 program in your shell's search path, you can run it as
14830 follows, from inside an MQ patch directory:</para>
14831 <programlisting format="linespecific">hg extdiff -p hg-interdiff -r A:B my-change.patch</programlisting>
14832 <para id="x_19f">Since you'll probably want to use this long-winded command
14833 a lot, you can get <literal role="hg-ext" moreinfo="none">hgext</literal> to
14834 make it available as a normal Mercurial command, again by
14835 editing your <filename role="special" moreinfo="none">~/.hgrc</filename>.</para>
14836 <programlisting format="linespecific">[extdiff]
14837 cmd.interdiff = hg-interdiff</programlisting>
14838 <para id="x_1a0">This directs <literal role="hg-ext" moreinfo="none">hgext</literal> to
14839 make an <literal moreinfo="none">interdiff</literal> command available, so you
14840 can now shorten the previous invocation of <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> to something a
14841 little more wieldy.</para>
14842 <programlisting format="linespecific">hg interdiff -r A:B my-change.patch</programlisting>
14844 <note>
14845 <para id="x_1a1"> The <command moreinfo="none">interdiff</command> command works well
14846 only if the underlying files against which versions of a
14847 patch are generated remain the same. If you create a patch,
14848 modify the underlying files, and then regenerate the patch,
14849 <command moreinfo="none">interdiff</command> may not produce useful
14850 output.</para>
14851 </note>
14853 <para id="x_1a2">The <literal role="hg-ext" moreinfo="none">extdiff</literal> extension is
14854 useful for more than merely improving the presentation of MQ
14855 patches. To read more about it, go to <xref linkend="sec:hgext:extdiff"/>.</para>
14857 </sect2>
14858 </sect1>
14859 </chapter>
14861 <!--
14862 local variables:
14863 sgml-parent-document: ("00book.xml" "book" "chapter")
14864 end:
14865 -->
14867 <!-- BEGIN ch14 -->
14868 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
14870 <chapter id="chap:hgext">
14871 <?dbhtml filename="adding-functionality-with-extensions.html"?>
14872 <title>Adding functionality with extensions</title>
14874 <para id="x_4fe">While the core of Mercurial is quite complete from a
14875 functionality standpoint, it's deliberately shorn of fancy
14876 features. This approach of preserving simplicity keeps the
14877 software easy to deal with for both maintainers and users.</para>
14879 <para id="x_4ff">However, Mercurial doesn't box you in with an inflexible
14880 command set: you can add features to it as
14881 <emphasis>extensions</emphasis> (sometimes known as
14882 <emphasis>plugins</emphasis>). We've already discussed a few of
14883 these extensions in earlier chapters.</para>
14884 <itemizedlist>
14885 <listitem><para id="x_500"><xref linkend="sec:tour-merge:fetch"/>
14886 covers the <literal role="hg-ext" moreinfo="none">fetch</literal> extension;
14887 this combines pulling new changes and merging them with local
14888 changes into a single command, <command role="hg-ext-fetch" moreinfo="none">fetch</command>.</para>
14889 </listitem>
14890 <listitem><para id="x_501">In <xref linkend="chap:hook"/>, we covered
14891 several extensions that are useful for hook-related
14892 functionality: <literal role="hg-ext" moreinfo="none">acl</literal> adds
14893 access control lists; <literal role="hg-ext" moreinfo="none">bugzilla</literal> adds integration with the
14894 Bugzilla bug tracking system; and <literal role="hg-ext" moreinfo="none">notify</literal> sends notification emails on
14895 new changes.</para>
14896 </listitem>
14897 <listitem><para id="x_502">The Mercurial Queues patch management extension is
14898 so invaluable that it merits two chapters and an appendix all
14899 to itself. <xref linkend="chap:mq"/> covers the
14900 basics; <xref linkend="chap:mq-collab"/> discusses advanced topics;
14901 and <xref linkend="chap:mqref"/> goes into detail on
14902 each
14903 command.</para>
14904 </listitem></itemizedlist>
14906 <para id="x_503">In this chapter, we'll cover some of the other extensions that
14907 are available for Mercurial, and briefly touch on some of the
14908 machinery you'll need to know about if you want to write an
14909 extension of your own.</para>
14910 <itemizedlist>
14911 <listitem><para id="x_504">In <xref linkend="sec:hgext:inotify"/>,
14912 we'll discuss the possibility of <emphasis>huge</emphasis>
14913 performance improvements using the <literal role="hg-ext" moreinfo="none">inotify</literal> extension.</para>
14914 </listitem></itemizedlist>
14916 <sect1 id="sec:hgext:inotify">
14917 <title>Improve performance with the <literal role="hg-ext" moreinfo="none">inotify</literal> extension</title>
14919 <para id="x_505">Are you interested in having some of the most common
14920 Mercurial operations run as much as a hundred times faster?
14921 Read on!</para>
14923 <para id="x_506">Mercurial has great performance under normal circumstances.
14924 For example, when you run the <command role="hg-cmd" moreinfo="none">hg
14925 status</command> command, Mercurial has to scan almost every
14926 directory and file in your repository so that it can display
14927 file status. Many other Mercurial commands need to do the same
14928 work behind the scenes; for example, the <command role="hg-cmd" moreinfo="none">hg diff</command> command uses the status
14929 machinery to avoid doing an expensive comparison operation on
14930 files that obviously haven't changed.</para>
14932 <para id="x_507">Because obtaining file status is crucial to good
14933 performance, the authors of Mercurial have optimised this code
14934 to within an inch of its life. However, there's no avoiding the
14935 fact that when you run <command role="hg-cmd" moreinfo="none">hg
14936 status</command>, Mercurial is going to have to perform at
14937 least one expensive system call for each managed file to
14938 determine whether it's changed since the last time Mercurial
14939 checked. For a sufficiently large repository, this can take a
14940 long time.</para>
14942 <para id="x_508">To put a number on the magnitude of this effect, I created a
14943 repository containing 150,000 managed files. I timed <command role="hg-cmd" moreinfo="none">hg status</command> as taking ten seconds to
14944 run, even when <emphasis>none</emphasis> of those files had been
14945 modified.</para>
14947 <para id="x_509">Many modern operating systems contain a file notification
14948 facility. If a program signs up to an appropriate service, the
14949 operating system will notify it every time a file of interest is
14950 created, modified, or deleted. On Linux systems, the kernel
14951 component that does this is called
14952 <literal moreinfo="none">inotify</literal>.</para>
14954 <para id="x_50a">Mercurial's <literal role="hg-ext" moreinfo="none">inotify</literal>
14955 extension talks to the kernel's <literal moreinfo="none">inotify</literal>
14956 component to optimise <command role="hg-cmd" moreinfo="none">hg status</command>
14957 commands. The extension has two components. A daemon sits in
14958 the background and receives notifications from the
14959 <literal moreinfo="none">inotify</literal> subsystem. It also listens for
14960 connections from a regular Mercurial command. The extension
14961 modifies Mercurial's behavior so that instead of scanning the
14962 filesystem, it queries the daemon. Since the daemon has perfect
14963 information about the state of the repository, it can respond
14964 with a result instantaneously, avoiding the need to scan every
14965 directory and file in the repository.</para>
14967 <para id="x_50b">Recall the ten seconds that I measured plain Mercurial as
14968 taking to run <command role="hg-cmd" moreinfo="none">hg status</command> on a
14969 150,000 file repository. With the <literal role="hg-ext" moreinfo="none">inotify</literal> extension enabled, the time
14970 dropped to 0.1 seconds, a factor of <emphasis>one
14971 hundred</emphasis> faster.</para>
14973 <para id="x_50c">Before we continue, please pay attention to some
14974 caveats.</para>
14975 <itemizedlist>
14976 <listitem><para id="x_50d">The <literal role="hg-ext" moreinfo="none">inotify</literal>
14977 extension is Linux-specific. Because it interfaces directly
14978 to the Linux kernel's <literal moreinfo="none">inotify</literal> subsystem,
14979 it does not work on other operating systems.</para>
14980 </listitem>
14981 <listitem><para id="x_50e">It should work on any Linux distribution that
14982 was released after early 2005. Older distributions are
14983 likely to have a kernel that lacks
14984 <literal moreinfo="none">inotify</literal>, or a version of
14985 <literal moreinfo="none">glibc</literal> that does not have the necessary
14986 interfacing support.</para>
14987 </listitem>
14988 <listitem><para id="x_50f">Not all filesystems are suitable for use with
14989 the <literal role="hg-ext" moreinfo="none">inotify</literal> extension.
14990 Network filesystems such as NFS are a non-starter, for
14991 example, particularly if you're running Mercurial on several
14992 systems, all mounting the same network filesystem. The
14993 kernel's <literal moreinfo="none">inotify</literal> system has no way of
14994 knowing about changes made on another system. Most local
14995 filesystems (e.g. ext3, XFS, ReiserFS) should work
14996 fine.</para>
14997 </listitem></itemizedlist>
14999 <para id="x_510">The <literal role="hg-ext" moreinfo="none">inotify</literal> extension is
15000 not yet shipped with Mercurial as of May 2007, so it's a little
15001 more involved to set up than other extensions. But the
15002 performance improvement is worth it!</para>
15004 <para id="x_511">The extension currently comes in two parts: a set of patches
15005 to the Mercurial source code, and a library of Python bindings
15006 to the <literal moreinfo="none">inotify</literal> subsystem.</para>
15007 <note>
15008 <para id="x_512"> There are <emphasis>two</emphasis> Python
15009 <literal moreinfo="none">inotify</literal> binding libraries. One of them is
15010 called <literal moreinfo="none">pyinotify</literal>, and is packaged by some
15011 Linux distributions as <literal moreinfo="none">python-inotify</literal>.
15012 This is <emphasis>not</emphasis> the one you'll need, as it is
15013 too buggy and inefficient to be practical.</para>
15014 </note>
15015 <para id="x_513">To get going, it's best to already have a functioning copy
15016 of Mercurial installed.</para>
15017 <note>
15018 <para id="x_514"> If you follow the instructions below, you'll be
15019 <emphasis>replacing</emphasis> and overwriting any existing
15020 installation of Mercurial that you might already have, using
15021 the latest <quote>bleeding edge</quote> Mercurial code. Don't
15022 say you weren't warned!</para>
15023 </note>
15024 <orderedlist inheritnum="ignore" continuation="restarts">
15025 <listitem><para id="x_515">Clone the Python <literal moreinfo="none">inotify</literal>
15026 binding repository. Build and install it.</para>
15027 <programlisting format="linespecific">hg clone http://hg.kublai.com/python/inotify
15028 cd inotify
15029 python setup.py build --force
15030 sudo python setup.py install --skip-build</programlisting>
15031 </listitem>
15032 <listitem><para id="x_516">Clone the <filename class="directory" moreinfo="none">crew</filename> Mercurial repository.
15033 Clone the <literal role="hg-ext" moreinfo="none">inotify</literal> patch
15034 repository so that Mercurial Queues will be able to apply
15035 patches to your cope of the <filename class="directory" moreinfo="none">crew</filename> repository.</para>
15036 <programlisting format="linespecific">hg clone http://hg.intevation.org/mercurial/crew
15037 hg clone crew inotify
15038 hg clone http://hg.kublai.com/mercurial/patches/inotify inotify/.hg/patches</programlisting>
15039 </listitem>
15040 <listitem><para id="x_517">Make sure that you have the Mercurial Queues
15041 extension, <literal role="hg-ext" moreinfo="none">mq</literal>, enabled. If
15042 you've never used MQ, read <xref linkend="sec:mq:start"/> to get started
15043 quickly.</para>
15044 </listitem>
15045 <listitem><para id="x_518">Go into the <filename class="directory" moreinfo="none">inotify</filename> repo, and apply all
15046 of the <literal role="hg-ext" moreinfo="none">inotify</literal> patches
15047 using the <option role="hg-ext-mq-cmd-qpush-opt">hg
15048 -a</option> option to the <command role="hg-ext-mq" moreinfo="none">qpush</command> command.</para>
15049 <programlisting format="linespecific">cd inotify
15050 hg qpush -a</programlisting>
15051 </listitem>
15052 <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.
15053 Instead, ask for help.</para>
15054 </listitem>
15055 <listitem><para id="x_51a">Build and install the patched version of
15056 Mercurial.</para>
15057 <programlisting format="linespecific">python setup.py build --force
15058 sudo python setup.py install --skip-build</programlisting>
15059 </listitem>
15060 </orderedlist>
15061 <para id="x_51b">Once you've build a suitably patched version of Mercurial,
15062 all you need to do to enable the <literal role="hg-ext" moreinfo="none">inotify</literal> extension is add an entry to
15063 your <filename role="special" moreinfo="none">~/.hgrc</filename>.</para>
15064 <programlisting format="linespecific">[extensions] inotify =</programlisting>
15065 <para id="x_51c">When the <literal role="hg-ext" moreinfo="none">inotify</literal> extension
15066 is enabled, Mercurial will automatically and transparently start
15067 the status daemon the first time you run a command that needs
15068 status in a repository. It runs one status daemon per
15069 repository.</para>
15071 <para id="x_51d">The status daemon is started silently, and runs in the
15072 background. If you look at a list of running processes after
15073 you've enabled the <literal role="hg-ext" moreinfo="none">inotify</literal>
15074 extension and run a few commands in different repositories,
15075 you'll thus see a few <literal moreinfo="none">hg</literal> processes sitting
15076 around, waiting for updates from the kernel and queries from
15077 Mercurial.</para>
15079 <para id="x_51e">The first time you run a Mercurial command in a repository
15080 when you have the <literal role="hg-ext" moreinfo="none">inotify</literal>
15081 extension enabled, it will run with about the same performance
15082 as a normal Mercurial command. This is because the status
15083 daemon needs to perform a normal status scan so that it has a
15084 baseline against which to apply later updates from the kernel.
15085 However, <emphasis>every</emphasis> subsequent command that does
15086 any kind of status check should be noticeably faster on
15087 repositories of even fairly modest size. Better yet, the bigger
15088 your repository is, the greater a performance advantage you'll
15089 see. The <literal role="hg-ext" moreinfo="none">inotify</literal> daemon makes
15090 status operations almost instantaneous on repositories of all
15091 sizes!</para>
15093 <para id="x_51f">If you like, you can manually start a status daemon using
15094 the <command role="hg-ext-inotify" moreinfo="none">inserve</command> command.
15095 This gives you slightly finer control over how the daemon ought
15096 to run. This command will of course only be available when the
15097 <literal role="hg-ext" moreinfo="none">inotify</literal> extension is
15098 enabled.</para>
15100 <para id="x_520">When you're using the <literal role="hg-ext" moreinfo="none">inotify</literal> extension, you should notice
15101 <emphasis>no difference at all</emphasis> in Mercurial's
15102 behavior, with the sole exception of status-related commands
15103 running a whole lot faster than they used to. You should
15104 specifically expect that commands will not print different
15105 output; neither should they give different results. If either of
15106 these situations occurs, please report a bug.</para>
15108 </sect1>
15109 <sect1 id="sec:hgext:extdiff">
15110 <title>Flexible diff support with the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension</title>
15112 <para id="x_521">Mercurial's built-in <command role="hg-cmd" moreinfo="none">hg
15113 diff</command> command outputs plaintext unified diffs.</para>
15115 <!-- BEGIN extdiff.diff -->
15116 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg diff</userinput>
15117 diff -r 801b35c37d8b myfile
15118 --- a/myfile Sun Aug 16 14:05:02 2009 +0000
15119 +++ b/myfile Sun Aug 16 14:05:02 2009 +0000
15120 @@ -1,1 +1,2 @@
15121 The first line.
15122 +The second line.
15123 </screen>
15124 <!-- END extdiff.diff -->
15127 <para id="x_522">If you would like to use an external tool to display
15128 modifications, you'll want to use the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension. This will let you
15129 use, for example, a graphical diff tool.</para>
15131 <para id="x_523">The <literal role="hg-ext" moreinfo="none">extdiff</literal> extension is
15132 bundled with Mercurial, so it's easy to set up. In the <literal role="rc-extensions" moreinfo="none">extensions</literal> section of your
15133 <filename role="special" moreinfo="none">~/.hgrc</filename>, simply add a
15134 one-line entry to enable the extension.</para>
15135 <programlisting format="linespecific">[extensions]
15136 extdiff =</programlisting>
15137 <para id="x_524">This introduces a command named <command role="hg-ext-extdiff" moreinfo="none">extdiff</command>, which by default uses
15138 your system's <command moreinfo="none">diff</command> command to generate a
15139 unified diff in the same form as the built-in <command role="hg-cmd" moreinfo="none">hg diff</command> command.</para>
15141 <!-- BEGIN extdiff.extdiff -->
15142 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg extdiff</userinput>
15143 --- a.801b35c37d8b/myfile 2009-08-16 14:05:02.000000000 +0000
15144 +++ /tmp/extdiffl1y_s9/a/myfile 2009-08-16 14:05:02.000000000 +0000
15145 @@ -1 +1,2 @@
15146 The first line.
15147 +The second line.
15148 </screen>
15149 <!-- END extdiff.extdiff -->
15152 <para id="x_525">The result won't be exactly the same as with the built-in
15153 <command role="hg-cmd" moreinfo="none">hg diff</command> variations, because the
15154 output of <command moreinfo="none">diff</command> varies from one system to
15155 another, even when passed the same options.</para>
15157 <para id="x_526">As the <quote><literal moreinfo="none">making snapshot</literal></quote>
15158 lines of output above imply, the <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> command works by
15159 creating two snapshots of your source tree. The first snapshot
15160 is of the source revision; the second, of the target revision or
15161 working directory. The <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> command generates
15162 these snapshots in a temporary directory, passes the name of
15163 each directory to an external diff viewer, then deletes the
15164 temporary directory. For efficiency, it only snapshots the
15165 directories and files that have changed between the two
15166 revisions.</para>
15168 <para id="x_527">Snapshot directory names have the same base name as your
15169 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
15170 snapshot directory. Each snapshot directory name has its
15171 changeset ID appended, if appropriate. If a snapshot is of
15172 revision <literal moreinfo="none">a631aca1083f</literal>, the directory will be
15173 named <filename class="directory" moreinfo="none">foo.a631aca1083f</filename>.
15174 A snapshot of the working directory won't have a changeset ID
15175 appended, so it would just be <filename class="directory" moreinfo="none">foo</filename> in this example. To see what
15176 this looks like in practice, look again at the <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> example above. Notice
15177 that the diff has the snapshot directory names embedded in its
15178 header.</para>
15180 <para id="x_528">The <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> command
15181 accepts two important options. The <option role="hg-ext-extdiff-cmd-extdiff-opt">hg -p</option> option
15182 lets you choose a program to view differences with, instead of
15183 <command moreinfo="none">diff</command>. With the <option role="hg-ext-extdiff-cmd-extdiff-opt">hg -o</option> option,
15184 you can change the options that <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> passes to the program
15185 (by default, these options are
15186 <quote><literal moreinfo="none">-Npru</literal></quote>, which only make sense
15187 if you're running <command moreinfo="none">diff</command>). In other respects,
15188 the <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> command
15189 acts similarly to the built-in <command role="hg-cmd" moreinfo="none">hg
15190 diff</command> command: you use the same option names, syntax,
15191 and arguments to specify the revisions you want, the files you
15192 want, and so on.</para>
15194 <para id="x_529">As an example, here's how to run the normal system
15195 <command moreinfo="none">diff</command> command, getting it to generate context
15196 diffs (using the <option role="cmd-opt-diff">-c</option> option)
15197 instead of unified diffs, and five lines of context instead of
15198 the default three (passing <literal moreinfo="none">5</literal> as the argument
15199 to the <option role="cmd-opt-diff">-C</option> option).</para>
15201 <!-- BEGIN extdiff.extdiff-ctx -->
15202 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg extdiff -o -NprcC5</userinput>
15203 *** a.801b35c37d8b/myfile Sun Aug 16 14:05:02 2009
15204 --- /tmp/extdiffl1y_s9/a/myfile Sun Aug 16 14:05:02 2009
15205 ***************
15206 *** 1 ****
15207 --- 1,2 ----
15208 The first line.
15209 + The second line.
15210 </screen>
15211 <!-- END extdiff.extdiff-ctx -->
15214 <para id="x_52a">Launching a visual diff tool is just as easy. Here's how to
15215 launch the <command moreinfo="none">kdiff3</command> viewer.</para>
15216 <programlisting format="linespecific">hg extdiff -p kdiff3 -o</programlisting>
15218 <para id="x_52b">If your diff viewing command can't deal with directories,
15219 you can easily work around this with a little scripting. For an
15220 example of such scripting in action with the <literal role="hg-ext" moreinfo="none">mq</literal> extension and the
15221 <command moreinfo="none">interdiff</command> command, see <xref linkend="mq-collab:tips:interdiff"/>.</para>
15223 <sect2>
15224 <title>Defining command aliases</title>
15226 <para id="x_52c">It can be cumbersome to remember the options to both the
15227 <command role="hg-ext-extdiff" moreinfo="none">extdiff</command> command and
15228 the diff viewer you want to use, so the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension lets you define
15229 <emphasis>new</emphasis> commands that will invoke your diff
15230 viewer with exactly the right options.</para>
15232 <para id="x_52d">All you need to do is edit your <filename role="special" moreinfo="none">~/.hgrc</filename>, and add a section named
15233 <literal role="rc-extdiff" moreinfo="none">extdiff</literal>. Inside this
15234 section, you can define multiple commands. Here's how to add
15235 a <literal moreinfo="none">kdiff3</literal> command. Once you've defined
15236 this, you can type <quote><literal moreinfo="none">hg kdiff3</literal></quote>
15237 and the <literal role="hg-ext" moreinfo="none">extdiff</literal> extension
15238 will run <command moreinfo="none">kdiff3</command> for you.</para>
15239 <programlisting format="linespecific">[extdiff]
15240 cmd.kdiff3 =</programlisting>
15241 <para id="x_52e">If you leave the right hand side of the definition empty,
15242 as above, the <literal role="hg-ext" moreinfo="none">extdiff</literal>
15243 extension uses the name of the command you defined as the name
15244 of the external program to run. But these names don't have to
15245 be the same. Here, we define a command named
15246 <quote><literal moreinfo="none">hg wibble</literal></quote>, which runs
15247 <command moreinfo="none">kdiff3</command>.</para>
15248 <programlisting format="linespecific">[extdiff]
15249 cmd.wibble = kdiff3</programlisting>
15251 <para id="x_52f">You can also specify the default options that you want to
15252 invoke your diff viewing program with. The prefix to use is
15253 <quote><literal moreinfo="none">opts.</literal></quote>, followed by the name
15254 of the command to which the options apply. This example
15255 defines a <quote><literal moreinfo="none">hg vimdiff</literal></quote> command
15256 that runs the <command moreinfo="none">vim</command> editor's
15257 <literal moreinfo="none">DirDiff</literal> extension.</para>
15258 <programlisting format="linespecific">[extdiff]
15259 cmd.vimdiff = vim
15260 opts.vimdiff = -f '+next' '+execute "DirDiff" argv(0) argv(1)'</programlisting>
15262 </sect2>
15263 </sect1>
15264 <sect1 id="sec:hgext:transplant">
15265 <title>Cherrypicking changes with the <literal role="hg-ext" moreinfo="none">transplant</literal> extension</title>
15267 <para id="x_530">Need to have a long chat with Brendan about this.</para>
15269 </sect1>
15270 <sect1 id="sec:hgext:patchbomb">
15271 <title>Send changes via email with the <literal role="hg-ext" moreinfo="none">patchbomb</literal> extension</title>
15273 <para id="x_531">Many projects have a culture of <quote>change
15274 review</quote>, in which people send their modifications to a
15275 mailing list for others to read and comment on before they
15276 commit the final version to a shared repository. Some projects
15277 have people who act as gatekeepers; they apply changes from
15278 other people to a repository to which those others don't have
15279 access.</para>
15281 <para id="x_532">Mercurial makes it easy to send changes over email for
15282 review or application, via its <literal role="hg-ext" moreinfo="none">patchbomb</literal> extension. The extension is
15283 so named because changes are formatted as patches, and it's usual
15284 to send one changeset per email message. Sending a long series
15285 of changes by email is thus much like <quote>bombing</quote> the
15286 recipient's inbox, hence <quote>patchbomb</quote>.</para>
15288 <para id="x_533">As usual, the basic configuration of the <literal role="hg-ext" moreinfo="none">patchbomb</literal> extension takes just one or
15289 two lines in your <filename role="special" moreinfo="none">
15290 /.hgrc</filename>.</para>
15291 <programlisting format="linespecific">[extensions]
15292 patchbomb =</programlisting>
15293 <para id="x_534">Once you've enabled the extension, you will have a new
15294 command available, named <command role="hg-ext-patchbomb" moreinfo="none">email</command>.</para>
15296 <para id="x_535">The safest and best way to invoke the <command role="hg-ext-patchbomb" moreinfo="none">email</command> command is to
15297 <emphasis>always</emphasis> run it first with the <option role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option.
15298 This will show you what the command <emphasis>would</emphasis>
15299 send, without actually sending anything. Once you've had a
15300 quick glance over the changes and verified that you are sending
15301 the right ones, you can rerun the same command, with the <option role="hg-ext-patchbomb-cmd-email-opt">hg -n</option> option
15302 removed.</para>
15304 <para id="x_536">The <command role="hg-ext-patchbomb" moreinfo="none">email</command> command
15305 accepts the same kind of revision syntax as every other
15306 Mercurial command. For example, this command will send every
15307 revision between 7 and <literal moreinfo="none">tip</literal>, inclusive.</para>
15308 <programlisting format="linespecific">hg email -n 7:tip</programlisting>
15309 <para id="x_537">You can also specify a <emphasis>repository</emphasis> to
15310 compare with. If you provide a repository but no revisions, the
15311 <command role="hg-ext-patchbomb" moreinfo="none">email</command> command will
15312 send all revisions in the local repository that are not present
15313 in the remote repository. If you additionally specify revisions
15314 or a branch name (the latter using the <option role="hg-ext-patchbomb-cmd-email-opt">hg -b</option> option),
15315 this will constrain the revisions sent.</para>
15317 <para id="x_538">It's perfectly safe to run the <command role="hg-ext-patchbomb" moreinfo="none">email</command> command without the
15318 names of the people you want to send to: if you do this, it will
15319 just prompt you for those values interactively. (If you're
15320 using a Linux or Unix-like system, you should have enhanced
15321 <literal moreinfo="none">readline</literal>-style editing capabilities when
15322 entering those headers, too, which is useful.)</para>
15324 <para id="x_539">When you are sending just one revision, the <command role="hg-ext-patchbomb" moreinfo="none">email</command> command will by
15325 default use the first line of the changeset description as the
15326 subject of the single email message it sends.</para>
15328 <para id="x_53a">If you send multiple revisions, the <command role="hg-ext-patchbomb" moreinfo="none">email</command> command will usually
15329 send one message per changeset. It will preface the series with
15330 an introductory message, in which you should describe the
15331 purpose of the series of changes you're sending.</para>
15333 <sect2>
15334 <title>Changing the behavior of patchbombs</title>
15336 <para id="x_53b">Not every project has exactly the same conventions for
15337 sending changes in email; the <literal role="hg-ext" moreinfo="none">patchbomb</literal> extension tries to
15338 accommodate a number of variations through command line
15339 options.</para>
15340 <itemizedlist>
15341 <listitem><para id="x_53c">You can write a subject for the introductory
15342 message on the command line using the <option role="hg-ext-patchbomb-cmd-email-opt">hg -s</option>
15343 option. This takes one argument, the text of the subject
15344 to use.</para>
15345 </listitem>
15346 <listitem><para id="x_53d">To change the email address from which the
15347 messages originate, use the <option role="hg-ext-patchbomb-cmd-email-opt">hg -f</option>
15348 option. This takes one argument, the email address to
15349 use.</para>
15350 </listitem>
15351 <listitem><para id="x_53e">The default behavior is to send unified diffs
15352 (see <xref linkend="sec:mq:patch"/> for a
15353 description of the
15354 format), one per message. You can send a binary bundle
15355 instead with the <option role="hg-ext-patchbomb-cmd-email-opt">hg -b</option>
15356 option.</para>
15357 </listitem>
15358 <listitem><para id="x_53f">Unified diffs are normally prefaced with a
15359 metadata header. You can omit this, and send unadorned
15360 diffs, with the <option role="hg-ext-patchbomb-cmd-email-opt">hg
15361 --plain</option> option.</para>
15362 </listitem>
15363 <listitem><para id="x_540">Diffs are normally sent <quote>inline</quote>,
15364 in the same body part as the description of a patch. This
15365 makes it easiest for the largest number of readers to
15366 quote and respond to parts of a diff, as some mail clients
15367 will only quote the first MIME body part in a message. If
15368 you'd prefer to send the description and the diff in
15369 separate body parts, use the <option role="hg-ext-patchbomb-cmd-email-opt">hg -a</option>
15370 option.</para>
15371 </listitem>
15372 <listitem><para id="x_541">Instead of sending mail messages, you can
15373 write them to an <literal moreinfo="none">mbox</literal>-format mail
15374 folder using the <option role="hg-ext-patchbomb-cmd-email-opt">hg -m</option>
15375 option. That option takes one argument, the name of the
15376 file to write to.</para>
15377 </listitem>
15378 <listitem><para id="x_542">If you would like to add a
15379 <command moreinfo="none">diffstat</command>-format summary to each patch,
15380 and one to the introductory message, use the <option role="hg-ext-patchbomb-cmd-email-opt">hg -d</option>
15381 option. The <command moreinfo="none">diffstat</command> command displays
15382 a table containing the name of each file patched, the
15383 number of lines affected, and a histogram showing how much
15384 each file is modified. This gives readers a qualitative
15385 glance at how complex a patch is.</para>
15386 </listitem></itemizedlist>
15388 </sect2>
15389 </sect1>
15390 </chapter>
15392 <!--
15393 local variables:
15394 sgml-parent-document: ("00book.xml" "book" "chapter")
15395 end:
15396 -->
15398 <!-- BEGIN appA -->
15401 <appendix id="svn">
15402 <?dbhtml filename="migrating-to-mercurial.html"?>
15403 <title>Migrer vers Mercurial</title>
15405 <para id="x_6e1">Une manière courante de s'essayer à un nouveau
15406 gestionnaire de révisions est d'expérimenter en migrant un
15407 projet existant, plutôt que le faire avec un nouveau projet.
15408 </para>
15410 <para id="x_6e2">Dans cette annexe, nous discuterons comment importer
15411 l'historique d'un projet dans Mercurial, et à quoi faire attention
15412 si vous êtes habitués à un autre outil de gestion de révisions.
15413 </para>
15415 <sect1>
15416 <title>Importer l'historique depuis un autre système</title>
15418 <para id="x_6e3">Mercurial est livré avec une extension nommée
15419 <literal moreinfo="none">convert</literal>, qui permet d'importer un historique
15420 depuis les gestionnaire de révisions les plus courants. Au moment de
15421 l'écriture de ce livre, il pouvait importer l'historique depuis:
15422 </para>
15423 <itemizedlist>
15424 <listitem>
15425 <para id="x_6e4">Subversion</para>
15426 </listitem>
15427 <listitem>
15428 <para id="x_6e5">CVS</para>
15429 </listitem>
15430 <listitem>
15431 <para id="x_6e6">git</para>
15432 </listitem>
15433 <listitem>
15434 <para id="x_6e7">Darcs</para>
15435 </listitem>
15436 <listitem>
15437 <para id="x_6e8">Bazaar</para>
15438 </listitem>
15439 <listitem>
15440 <para id="x_6e9">Monotone</para>
15441 </listitem>
15442 <listitem>
15443 <para id="x_6ea">GNU Arch</para>
15444 </listitem>
15445 <listitem>
15446 <para id="x_6eb">Mercurial</para>
15447 </listitem>
15448 </itemizedlist>
15450 <para id="x_6ec">(Pour savoir pourquoi Mercurial lui même est supporté
15451 comme source, voir <xref linkend="svn.filemap"/>.)</para>
15453 <para id="x_6ed">Vous pouvez activer l'extension de la manière
15454 habituelle, en éditant votre fichier <filename moreinfo="none">~/.hgrc</filename></para>
15456 <programlisting format="linespecific">[extensions]
15457 convert =</programlisting>
15459 <para id="x_6ee">Ceci rendra la commande <command moreinfo="none">hg convert</command>
15460 disponible. La commande est facile à utiliser. Par exemple, la
15461 commande suivante va importer l'historique Subversion du <emphasis remap="it">framework</emphasis> de test <quote>Nose Unit</quote> dans Mercurial.
15462 </para>
15464 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen>
15466 <para id="x_6ef">L'extension <literal moreinfo="none">convert</literal> opère de
15467 manière incrémentale. En d'autres mots, après une première exécution de
15468 la commande <command moreinfo="none">hg convert</command>, les exécutions ultérieures
15469 importeront les révisions ultérieures à l'exécution précédente.
15470 La conversion incrémentale ne réussira que si
15471 vous exécutez <command moreinfo="none">hg convert</command> dans le même dépôt que vous
15472 aviez utilisé à l'origine, ceci parce que l'extension <literal moreinfo="none">convert</literal>
15473 sauvegarde un certain nombre de méta-données privées dans le fichier
15474 <filename moreinfo="none">.hg/shamap</filename> (non versioné) au sein du dépôt cible.
15475 </para>
15477 <para id="x_707">Lorsque vous voulez faire des modifications en utilisant
15478 Mercurial, le mieux est de faire un clone de l'ensemble de l'arborescence
15479 que vous souhaitez convertir, et de laisser l'arborescence d'origine pour
15480 de futures conversions incrémentales. C'est la manière la plus sûre pour vous laisser
15481 récupérer et fusionner les modifications futures depuis l'outil de gestion
15482 de révisions dans votre nouveau dépôt Mercurial.</para>
15484 <sect2>
15485 <title>Convertir plusieurs branches</title>
15487 <para id="x_708">La commande <command moreinfo="none">hg convert</command> citée
15488 ci-dessus convertit seulement l'historique de la <literal moreinfo="none">branche
15489 principale (trunk)</literal> du dépôt Subversion. Si nous utilisons
15490 à la place l'URL <literal moreinfo="none">http://python-nose.googlecode.com/svn</literal>,
15491 Mercurial va automatiquement détecter la
15492 <literal moreinfo="none">branche principale (trunk)</literal>, les <literal moreinfo="none">étiquettes
15493 (tags)</literal>, et les <literal moreinfo="none">branches</literal> que les dépôts
15494 Subversion utilisent généralement, et les importera chacun dans
15495 une branche Mercurial distincte.</para>
15497 <para id="x_709">Par défaut, chaque branche Subversion importée
15498 dans Mercurial se voit attribuer un nom de branche. Une fois la
15499 conversion achevée, vous pouvez obtenir la liste des noms des branches
15500 actives dans le dépôt Mercurial en utilisant la commande
15501 <command moreinfo="none">hg branches -a</command>. Si vous préférez importer les
15502 branches Subversion sans noms, ajoutez l'option <option>--config
15503 convert.hg.usebranches=false</option> à la commande
15504 <command moreinfo="none">hg convert</command>.</para>
15506 <para id="x_70a">Une fois votre arborescence convertie,
15507 si vous souhaitez travailler selon la pratique habituelle sous Mercurial
15508 avec une arborescence qui ne contient qu'une seule branche, vous pouvez cloner
15509 cette seule branche en utilisant
15510 <command moreinfo="none">hg clone -r nomdemabranche</command>.</para>
15511 </sect2>
15513 <sect2>
15514 <title>Associer les noms d'utilisateurs</title>
15516 <para id="x_6f0">Certains outils de gestion de révisions
15517 ne sauvegardent, avec les modifications, que les noms
15518 d'utilisateurs raccourcis. Ceux-ci peuvent être difficiles à
15519 interpréter. La norme avec Mercurial est de sauvegarder le
15520 nom du <emphasis remap="it">committeur</emphasis> et son adresse
15521 mail, ce qui est beaucoup plus utile pour discuter avec lui
15522 par la suite.</para>
15524 <para id="x_6f1">Si vous convertissez une arborescence depuis
15525 un gestionnaire de révisions qui utilise seulement les noms
15526 raccourcis, vous pouvez associer ces noms à des équivalents
15527 plus détaillés en passant l'option <option>--authors</option>
15528 à la commande <command moreinfo="none">hg convert</command>. Cette option
15529 attend un fichier qui contient des entrées sous la forme suivante:
15530 </para>
15532 <programlisting format="linespecific">arist = Aristotle <aristotle@phil.example.gr>
15533 soc = Socrates <socrates@phil.example.gr></programlisting>
15535 <para id="x_6f2">Quand <literal moreinfo="none">convert</literal> trouve une
15536 modification associée au nom <literal moreinfo="none">arist</literal> dans le
15537 dépôt de source, il va utiliser le nom <literal moreinfo="none">Aristotle
15538 <aristotle@phil.example.gr></literal> dans les révisions
15539 Mercurial. Si aucune correspondance n'est trouvé, il utilise
15540 le nom tel quel.</para>
15541 </sect2>
15543 <sect2 id="svn.filemap">
15544 <title>Nettoyer l'arboresence</title>
15546 <para id="x_6f3">Tous les projets n'ont pas un historique parfait.
15547 Il peut y avoir des répertoires qui n'auraient jamais dû être ajoutés,
15548 un fichier qui est trop volumineux, ou même une partie de la
15549 hiérarchie qui devrait être réorganisée.</para>
15551 <para id="x_6f4">L'extension <literal moreinfo="none">convert</literal> permet
15552 d'utiliser un <quote>fichier d'association</quote> qui peut
15553 réorganiser les fichiers et les répertoires dans un projet lors de
15554 l'importation de son historique. Ceci est utile non seulement quand vous
15555 importez l'historique d'un autre gestionnaire de révisions, mais
15556 aussi pour nettoyer ou réorganiser l'arborescence d'un projet
15557 Mercurial.</para>
15559 <para id="x_6f5">Pour indiquer le fichier d'association, on utilise
15560 l'option <option>--filemap</option> en lui fournissant un nom de
15561 fichier. Le fichier d'association contient des lignes de la forme
15562 suivante :</para>
15564 <programlisting format="linespecific"># Ceci est un commentaire.
15565 # Les lignes vides sont ignorées.
15567 include path/to/file
15569 exclude path/to/file
15571 rename from/some/path to/some/other/place
15572 </programlisting>
15574 <para id="x_6f6">La directive <literal moreinfo="none">include</literal> inclut un
15575 fichier, ou l'ensemble des fichiers d'un répertoire, dans le dépôt
15576 de destination. La directive <literal moreinfo="none">exclude</literal> omet les
15577 fichiers ou répertoires du dépôt. Ceci inclut aussi les autres
15578 fichiers et répertoires qui ne sont pas explicitement inclus.
15579 La directive <literal moreinfo="none">exclude</literal> entraine l'omission
15580 des fichiers ou répertoires, et autres fichiers qui ne sont pas
15581 explicitement inclus.</para>
15583 <para id="x_6f7">Pour déplacer un fichier ou un répertoire d'un
15584 emplacement à un autre, utilisez la directive
15585 <literal moreinfo="none">rename</literal>. Si vous avez besoin de déplacer un
15586 fichier ou un répertoire depuis un sous répertoire dans la racine
15587 du dépôt, utilisez <literal moreinfo="none">.</literal> comme second argument de
15588 la directive <literal moreinfo="none">rename</literal>.</para>
15589 </sect2>
15591 <sect2>
15592 <title>Améliorer les performances de la conversion Subversion</title>
15594 <para id="x_70b">Vous aurez souvent besoin de plusieurs essais
15595 avant d'arriver à la parfaite combinaison de fichier d'association de fichiers,
15596 de fichier d'association de noms d'utilisateurs et des autres paramètres. Or,
15597 convertir un dépôt Mercurial via un protocole comme <literal moreinfo="none">ssh</literal>
15598 ou <literal moreinfo="none">http</literal> peut être des milliers de fois plus long
15599 que ce dont le système d'exploitation est en fait capable de faire,
15600 à cause des latence réseau. Ceci peut rendre la conception de cette
15601 combinaison parfaite très douloureuse.</para>
15603 <para id="x_70c">La commande <ulink url="http://svn.collab.net/repos/svn/trunk/notes/svnsync.txt"><command moreinfo="none">svnsync</command></ulink>
15604 peut grandement améliorer la vitesse de conversion d'un dépôt
15605 Subversion. Il s'agit d'un programme de miroir de dépôt Subversion
15606 en lecture seule. L'idée est de créer un miroir local d'une
15607 arborescence Subversion, puis de convertir ce miroir en dépôt
15608 Mercurial.</para>
15610 <para id="x_70d">Supposez que nous voulions convertir le dépôt
15611 Subversion du populaire projet Memcached en une arborescence Mercurial.
15612 Tout d'abord, nous créons un dépôt Subversion local.</para>
15614 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">svnadmin create memcached-mirror</userinput></screen>
15616 <para id="x_70e">Puis, nous allons mettre en place un <quote>hook</quote> Subversion
15617 dont <command moreinfo="none">svnsync</command> a besoin.</para>
15619 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">echo '#!/bin/sh' > memcached-mirror/hooks/pre-revprop-change</userinput>
15620 <prompt moreinfo="none">$</prompt> <userinput moreinfo="none">chmod +x memcached-mirror/hooks/pre-revprop-change</userinput></screen>
15622 <para id="x_70f">Nous initialisons ensuite <command moreinfo="none">svnsync</command> dans ce
15623 dépôt.</para>
15625 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">svnsync --init file://`pwd`/memcached-mirror \
15626 http://code.sixapart.com/svn/memcached</userinput></screen>
15628 <para id="x_710">La prochaine étape est de commencer le processus de
15629 mirroring de <command moreinfo="none">svnsync</command>.</para>
15631 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">svnsync sync file://`pwd`/memcached-mirror</userinput></screen>
15633 <para id="x_711">Enfin, nous importons l'historique de notre dépôt
15634 local Subversion dans Mercurial.</para>
15636 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg convert memcached-mirror</userinput></screen>
15638 <para id="x_712">Nous pouvons utiliser ce processus de manière
15639 incrémentale, si le dépôt Subversion est toujours en activité.
15640 Il suffit d'exécuter de nouveau <command moreinfo="none">svnsync</command> pour
15641 récupérer les récentes modifications dans notre miroir, puis <command moreinfo="none">hg
15642 convert</command>
15643 les importe dans notre arborescence Mercurial.</para>
15645 <para id="x_713">Il y a deux avantages à utiliser un import à deux
15646 étages comme avec <command moreinfo="none">svnsync</command>. Le premier
15647 est qu'il utilise du code de synchronisation réseau de Subversion
15648 plus efficace que la commande <command moreinfo="none">hg convert</command>,
15649 et donc transfère moins de données par le réseau. Le deuxième
15650 est que l'import depuis un dépôt Subversion local est si rapide que
15651 vous pouvez peaufiner et réitérer les paramètres de conversion de
15652 ce dernier sans souffrir de la qualité de la connexion réseau.</para>
15653 </sect2>
15654 </sect1>
15656 <sect1>
15657 <title>Migrer depuis Subversion</title>
15659 <para id="x_6f8">Subversion est le système de gestion de versions
15660 open source le plus populaire aujourd'hui. Bien qu'il y ait des
15661 différences entre Mercurial et Subversion, faire la transition de
15662 l'un à l'autre n'est pas très difficile. Les deux disposent en effet
15663 de jeux de commandes similaires et d'interfaces similaires.</para>
15665 <sect2>
15666 <title>Différences philosophiques</title>
15668 <para id="x_6f9">La différence fondamentale entre Subversion et
15669 Mercurial est bien évidement que Subversion est centralisé, alors
15670 que Mercurial est distribué. Puisque que Mercurial enregistre tout
15671 l'historique d'un projet sur votre disque dur local, il n'a besoin
15672 d'effectuer des accès au réseau que lorsque vous voulez
15673 explicitement communiquer avec un autre dépôt. Subversion, par contre,
15674 ne conserve que peu d'informations localement, et le client
15675 doit donc communiquer avec le serveur central pour la
15676 plupart des opérations communes.</para>
15678 <para id="x_6fa">Subversion s'en tire plus ou moins bien sans notion
15679 de branche réellement bien définie : quelle portion de l'espace de nommage
15680 du serveur est une branche est une simple question de convention, le
15681 logiciel n'imposant rien à ce sujet. Mercurial considère
15682 un dépôt comme un élément de la gestion des branches.</para>
15684 <sect3>
15685 <title>Portée des commandes</title>
15687 <para id="x_6fb">Puisque que Subversion ne sait pas réellement
15688 quelle partie de son espace de nommage est en fait une branche, il
15689 traite la plupart des commandes comme des requêtes à exécuter sur le
15690 répertoire où vous vous situez, et ses sous répertoires. Par exemple,
15691 si vous exécutez <command moreinfo="none">svn log</command>, vous verrez l'historique
15692 de la partie de l'arborescence où vous vous situez, et non de la
15693 hiérarchie entière.</para>
15695 <para id="x_6fc">Les commandes de Mercurial ont un comportement
15696 différent : toutes les commandes s'appliquent à l'ensemble de l'arborescence
15697 du dépôt. Exécutez la commande <command moreinfo="none">hg log</command> et elle vous
15698 donnera l'historique de l'ensemble de l'arborescence, quel que soit le
15699 sous-répertoire où vous vous situez. Si
15700 vous souhaitez obtenir l'historique d'un répertoire ou seulement d'un
15701 fichier, ajouter simplement le nom de celui-ci à la commande, par
15702 exemple <command moreinfo="none">hg log src</command>.</para>
15704 <para id="x_6fd">De ma propre expérience, cette différence dans leur
15705 comportement par défaut est probablement ce qui risque de vous
15706 surprendre le plus si vous passez régulièrement d'un outil à l'autre.</para>
15707 </sect3>
15709 <sect3>
15710 <title>Opération multi utilisateur et sécurité</title>
15712 <para id="x_6fe">Avec Subversion, il est normal (bien que légèrement
15713 désapprouvé) que différentes personnes collaborent sur une seule
15714 branche. Si Alice et Bob travaillent ensemble, et Alice ajoute ses
15715 modifications à leur branche partagée, Bob doit alors mettre à jour
15716 sa vue de la branche avant de pouvoir appliquer un commit.
15717 Puisqu'il n'a, à ce moment, pas effectué de commit
15718 des modifications qu'il a faites, il se peut qu'il ne corrompe
15719 ou ne perde
15720 ses modifications pendant ou après la mise à jour.</para>
15722 <para id="x_6ff">Mercurial encourage, à l'inverse, un modèle
15723 "commit-puis-merge". Avant de récupérer des modifications depuis le
15724 serveur, ou avant d'y envoyer les siennes, Bob enregistre ses
15725 modifications de manière locale en appliquant un commit. C'est à dire
15726 que si Alice avait envoyé ses modifications sur le serveur avant
15727 que Bob n'envoie les siennes, ce dernier ne pourra le faire
15728 qu'après avoir récupéré et fusionné celles d'Alice avec les siennes.
15729 Si Bob fait alors une
15730 erreur lors de la fusion, il pourra toujours restaurer sa version, pour
15731 laquelle il avait appliqué le commit.</para>
15733 <para id="x_700">Il est important de souligner qu'il s'agit de la
15734 manière habituelle de travailler avec ces outils. Subversion propose
15735 une manière plus sûre de "travailler-dans-votre-propre-branche", mais elle
15736 est assez complexe pour que, en pratique, elle ne soit que rarement utilisé.
15737 Mercurial propose de son côté un mode un peu moins sûr, permettant de
15738 récupérer des modifications par dessus des modifications non
15739 committées, qui reste toutefois très peu répandu.</para>
15740 </sect3>
15742 <sect3>
15743 <title>Publication vs changement locaux</title>
15745 <para id="x_701">Une commande Subversion <command moreinfo="none">svn
15746 commit</command> publie immédiatement les modifications sur le
15747 serveur, où elles peuvent être vu par n'importe qui doté d'un privilège
15748 de lecture.</para>
15750 <para id="x_702">Avec Mercurial, les modifications sont toujours d'abord
15751 enregistrées localement, et doivent être par la suite transférés par
15752 la commande <command moreinfo="none">hg push</command>.</para>
15754 <para id="x_703">Chaque approche a ses avantages et ses inconvénients.
15755 Le modèle Subversion implique que les modifications soient publiées, et
15756 donc disponibles immédiatement. D'un autre coté, cela implique aussi
15757 que, pour pouvoir utiliser le logiciel normalement, un utilisateur doit
15758 avoir les droits d'écriture dans le dépôt, et ce privilège n'est pas concédé
15759 facilement par la plupart des projets Open Source.</para>
15761 <para id="x_704">L'approche de Mercurial permet à quiconque de faire
15762 un clone du dépôt et d'y ajouter ses modifications sans jamais avoir
15763 besoin de la permission de quiconque, et l'on peut même publier ses
15764 modifications et continuer à participer comme on le désire. Toutefois, la
15765 distinction entre les commits et le transfert de ces derniers présente
15766 le risque que quelqu'un applique ses modifications par un commit local
15767 sur son portable et parte se promener pendant quelques jours en ayant
15768 oublié de les transférer, ce qui peut, dans certains rares cas,
15769 bloquer temporairement ses collaborateurs.</para>
15770 </sect3>
15771 </sect2>
15773 <sect2>
15774 <title>Références des commandes</title>
15776 <table>
15777 <title>Commandes Subversion et leurs équivalents Mercurial</title>
15778 <tgroup cols="3">
15779 <thead>
15780 <row>
15781 <entry>Subversion</entry>
15782 <entry>Mercurial</entry>
15783 <entry>Notes</entry>
15784 </row>
15785 </thead>
15786 <tbody>
15787 <row>
15788 <entry><command moreinfo="none">svn add</command></entry>
15789 <entry><command moreinfo="none">hg add</command></entry>
15790 <entry/>
15791 </row>
15792 <row>
15793 <entry><command moreinfo="none">svn blame</command></entry>
15794 <entry><command moreinfo="none">hg annotate</command></entry>
15795 <entry/>
15796 </row>
15797 <row>
15798 <entry><command moreinfo="none">svn cat</command></entry>
15799 <entry><command moreinfo="none">hg cat</command></entry>
15800 <entry/>
15801 </row>
15802 <row>
15803 <entry><command moreinfo="none">svn checkout</command></entry>
15804 <entry><command moreinfo="none">hg clone</command></entry>
15805 <entry/>
15806 </row>
15807 <row>
15808 <entry><command moreinfo="none">svn cleanup</command></entry>
15809 <entry>n/a</entry>
15810 <entry>Aucun nettoyage nécessaire.</entry>
15811 </row>
15812 <row>
15813 <entry><command moreinfo="none">svn commit</command></entry>
15814 <entry><command moreinfo="none">hg commit</command>; <command moreinfo="none">hg
15815 push</command></entry>
15816 <entry><command moreinfo="none">hg push</command> publie les modifications
15817 après un commit.</entry>
15818 </row>
15819 <row>
15820 <entry><command moreinfo="none">svn copy</command></entry>
15821 <entry><command moreinfo="none">hg clone</command></entry>
15822 <entry>Pour créer une nouvelle branche</entry>
15823 </row>
15824 <row>
15825 <entry><command moreinfo="none">svn copy</command></entry>
15826 <entry><command moreinfo="none">hg copy</command></entry>
15827 <entry>Pour copier des fichiers ou des répertoires</entry>
15828 </row>
15829 <row>
15830 <entry><command moreinfo="none">svn delete</command> (<command moreinfo="none">svn
15831 remove</command>)</entry>
15832 <entry><command moreinfo="none">hg remove</command></entry>
15833 <entry/>
15834 </row>
15835 <row>
15836 <entry><command moreinfo="none">svn diff</command></entry>
15837 <entry><command moreinfo="none">hg diff</command></entry>
15838 <entry/>
15839 </row>
15840 <row>
15841 <entry><command moreinfo="none">svn export</command></entry>
15842 <entry><command moreinfo="none">hg archive</command></entry>
15843 <entry/>
15844 </row>
15845 <row>
15846 <entry><command moreinfo="none">svn help</command></entry>
15847 <entry><command moreinfo="none">hg help</command></entry>
15848 <entry/>
15849 </row>
15850 <row>
15851 <entry><command moreinfo="none">svn import</command></entry>
15852 <entry><command moreinfo="none">hg addremove</command>; <command moreinfo="none">hg
15853 commit</command></entry>
15854 <entry/>
15855 </row>
15856 <row>
15857 <entry><command moreinfo="none">svn info</command></entry>
15858 <entry><command moreinfo="none">hg parents</command></entry>
15859 <entry>Affiche la version sur la base de laquelle on travaille</entry>
15860 </row>
15861 <row>
15862 <entry><command moreinfo="none">svn info</command></entry>
15863 <entry><command moreinfo="none">hg showconfig
15864 paths.default</command></entry>
15865 <entry>Affiche de quelle URL est extrait ce dépôt</entry>
15866 </row>
15867 <row>
15868 <entry><command moreinfo="none">svn list</command></entry>
15869 <entry><command moreinfo="none">hg manifest</command></entry>
15870 <entry/>
15871 </row>
15872 <row>
15873 <entry><command moreinfo="none">svn log</command></entry>
15874 <entry><command moreinfo="none">hg log</command></entry>
15875 <entry/>
15876 </row>
15877 <row>
15878 <entry><command moreinfo="none">svn merge</command></entry>
15879 <entry><command moreinfo="none">hg merge</command></entry>
15880 <entry/>
15881 </row>
15882 <row>
15883 <entry><command moreinfo="none">svn mkdir</command></entry>
15884 <entry>n/a</entry>
15885 <entry>Mercurial ne versionne pas les répertoires</entry>
15886 </row>
15887 <row>
15888 <entry><command moreinfo="none">svn move</command> (<command moreinfo="none">svn
15889 rename</command>)</entry>
15890 <entry><command moreinfo="none">hg rename</command></entry>
15891 <entry/>
15892 </row>
15893 <row>
15894 <entry><command moreinfo="none">svn resolved</command></entry>
15895 <entry><command moreinfo="none">hg resolve -m</command></entry>
15896 <entry/>
15897 </row>
15898 <row>
15899 <entry><command moreinfo="none">svn revert</command></entry>
15900 <entry><command moreinfo="none">hg revert</command></entry>
15901 <entry/>
15902 </row>
15903 <row>
15904 <entry><command moreinfo="none">svn status</command></entry>
15905 <entry><command moreinfo="none">hg status</command></entry>
15906 <entry/>
15907 </row>
15908 <row>
15909 <entry><command moreinfo="none">svn update</command></entry>
15910 <entry><command moreinfo="none">hg pull -u</command></entry>
15911 <entry/>
15912 </row>
15913 </tbody>
15914 </tgroup>
15915 </table>
15916 </sect2>
15917 </sect1>
15919 <sect1>
15920 <title>Conseils utiles pour les débutants</title>
15922 <para id="x_705">Avec la plupart des gestionnaire de versions, afficher
15923 un diff associé à une révision peut être assez douloureux. Par exemple,
15924 avec Subversion, pour voir ce qui a été modifiée dans la révision 104654,
15925 vous devez saisir <command moreinfo="none">svn diff -r104653:104654</command>. Mercurial
15926 élimine le besoin de saisir l'identifiant d'une révision deux fois dans
15927 ce cas classique. Pour un simple diff, <command moreinfo="none">hg
15928 export 104654</command> suffit. Pour obtenir une entrée du journal suivie d'un diff,
15929 <command moreinfo="none">hg log -r104654 -p</command>.</para>
15931 <para id="x_706">Quand vous exécutez la commande <command moreinfo="none">hg status</command>
15932 sans aucun argument, elle affiche l'état de l'ensemble de l'arborescence,
15933 avec des chemins relatifs partant de la racine du dépôt. Ceci rend
15934 difficile de copier un nom de fichier depuis la sortie de la commande
15935 <command moreinfo="none">hg status</command> dans une autre ligne de commande. Si vous
15936 fournissez un fichier ou un répertoire à la commande <command moreinfo="none">hg
15937 status</command>, elle va afficher les chemins relatif depuis votre
15938 répertoire courant à la place. Ainsi, pour avoir un état sur l'ensemble
15939 de l'arborescence à l'aide de <command moreinfo="none">hg status</command>, avec des
15940 chemins relatifs à votre répertoire courant, et non la racine du dépôt,
15941 ajoutez la sortie de <command moreinfo="none">hg root</command> à la commande
15942 <command moreinfo="none">hg status</command>. Vous pouvez le faire aisément sur un
15943 système Unix ainsi :</para>
15945 <screen format="linespecific"><prompt moreinfo="none">$</prompt> <userinput moreinfo="none">hg status `hg root`</userinput></screen>
15946 </sect1>
15947 </appendix>
15949 <!--
15950 local variables:
15951 sgml-parent-document: ("00book.xml" "book" "appendix")
15952 end:
15953 -->
15955 <!-- BEGIN appB -->
15956 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
15958 <appendix id="chap:mqref">
15959 <?dbhtml filename="mercurial-queues-reference.html"?>
15960 <title>Mercurial Queues reference</title>
15962 <sect1 id="sec:mqref:cmdref">
15963 <title>MQ command reference</title>
15965 <para id="x_5e8">For an overview of the commands provided by MQ, use the
15966 command <command role="hg-cmd" moreinfo="none">hg help mq</command>.</para>
15968 <sect2>
15969 <title><command role="hg-ext-mq" moreinfo="none">qapplied</command>—print
15970 applied patches</title>
15972 <para id="x_5e9">The <command role="hg-ext-mq" moreinfo="none">qapplied</command> command
15973 prints the current stack of applied patches. Patches are
15974 printed in oldest-to-newest order, so the last patch in the
15975 list is the <quote>top</quote> patch.</para>
15977 </sect2>
15978 <sect2>
15979 <title><command role="hg-ext-mq" moreinfo="none">qcommit</command>—commit
15980 changes in the queue repository</title>
15982 <para id="x_5ea">The <command role="hg-ext-mq" moreinfo="none">qcommit</command> command
15983 commits any outstanding changes in the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename>
15984 repository. This command only works if the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename>
15985 directory is a repository, i.e. you created the directory
15986 using <command role="hg-cmd" moreinfo="none">hg qinit <option role="hg-ext-mq-cmd-qinit-opt">-c</option></command> or
15987 ran <command role="hg-cmd" moreinfo="none">hg init</command> in the directory
15988 after running <command role="hg-ext-mq" moreinfo="none">qinit</command>.</para>
15990 <para id="x_5eb">This command is shorthand for <command role="hg-cmd" moreinfo="none">hg
15991 commit --cwd .hg/patches</command>.</para>
15992 </sect2>
15993 <sect2>
15994 <title><command role="hg-ext-mq" moreinfo="none">qdelete</command>—delete a patch
15995 from the <filename role="special" moreinfo="none">series</filename>
15996 file</title>
15998 <para id="x_5ec">The <command role="hg-ext-mq" moreinfo="none">qdelete</command> command
15999 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>
16000 directory. It does not pop the patch if the patch is already
16001 applied. By default, it does not delete the patch file; use
16002 the <option role="hg-ext-mq-cmd-qdel-opt">-f</option> option
16003 to do that.</para>
16005 <para id="x_5ed">Options:</para>
16006 <itemizedlist>
16007 <listitem><para id="x_5ee"><option role="hg-ext-mq-cmd-qdel-opt">-f</option>: Delete the
16008 patch file.</para>
16009 </listitem></itemizedlist>
16011 </sect2>
16012 <sect2>
16013 <title><command role="hg-ext-mq" moreinfo="none">qdiff</command>—print a
16014 diff of the topmost applied patch</title>
16016 <para id="x_5ef">The <command role="hg-ext-mq" moreinfo="none">qdiff</command> command
16017 prints a diff of the topmost applied patch. It is equivalent
16018 to <command role="hg-cmd" moreinfo="none">hg diff -r-2:-1</command>.</para>
16020 </sect2>
16021 <sect2>
16022 <title><command role="hg-ext-mq" moreinfo="none">qfold</command>—move
16023 applied patches into repository history</title>
16025 <para id="x_72d">The <command moreinfo="none">hg qfinish</command> command converts the
16026 specified applied patches into permanent changes by moving
16027 them out of MQ's control so that they will be treated as
16028 normal repository history.</para>
16029 </sect2>
16031 <sect2>
16032 <title><command role="hg-ext-mq" moreinfo="none">qfold</command>—merge
16033 (<quote>fold</quote>) several patches into one</title>
16035 <para id="x_5f0">The <command role="hg-ext-mq" moreinfo="none">qfold</command> command
16036 merges multiple patches into the topmost applied patch, so
16037 that the topmost applied patch makes the union of all of the
16038 changes in the patches in question.</para>
16040 <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
16041 any is. The order in which patches are folded is significant;
16042 <command role="hg-cmd" moreinfo="none">hg qfold a b</command> means
16043 <quote>apply the current topmost patch, followed by
16044 <literal moreinfo="none">a</literal>, followed by
16045 <literal moreinfo="none">b</literal></quote>.</para>
16047 <para id="x_5f2">The comments from the folded patches are appended to the
16048 comments of the destination patch, with each block of comments
16049 separated by three asterisk
16050 (<quote><literal moreinfo="none">*</literal></quote>) characters. Use the
16051 <option role="hg-ext-mq-cmd-qfold-opt">-e</option> option to
16052 edit the commit message for the combined patch/changeset after
16053 the folding has completed.</para>
16055 <para id="x_5f3">Options:</para>
16056 <itemizedlist>
16057 <listitem><para id="x_5f4"><option role="hg-ext-mq-cmd-qfold-opt">-e</option>: Edit the
16058 commit message and patch description for the newly folded
16059 patch.</para>
16060 </listitem>
16061 <listitem><para id="x_5f5"><option role="hg-ext-mq-cmd-qfold-opt">-l</option>: Use the
16062 contents of the given file as the new commit message and
16063 patch description for the folded patch.</para>
16064 </listitem>
16065 <listitem><para id="x_5f6"><option role="hg-ext-mq-cmd-qfold-opt">-m</option>: Use the
16066 given text as the new commit message and patch description
16067 for the folded patch.</para>
16068 </listitem></itemizedlist>
16070 </sect2>
16071 <sect2>
16072 <title><command role="hg-ext-mq" moreinfo="none">qheader</command>—display the
16073 header/description of a patch</title>
16075 <para id="x_5f7">The <command role="hg-ext-mq" moreinfo="none">qheader</command> command
16076 prints the header, or description, of a patch. By default, it
16077 prints the header of the topmost applied patch. Given an
16078 argument, it prints the header of the named patch.</para>
16080 </sect2>
16081 <sect2>
16082 <title><command role="hg-ext-mq" moreinfo="none">qimport</command>—import
16083 a third-party patch into the queue</title>
16085 <para id="x_5f8">The <command role="hg-ext-mq" moreinfo="none">qimport</command> command
16086 adds an entry for an external patch to the <filename role="special" moreinfo="none">series</filename> file, and copies the patch
16087 into the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory. It adds
16088 the entry immediately after the topmost applied patch, but
16089 does not push the patch.</para>
16091 <para id="x_5f9">If the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory is a
16092 repository, <command role="hg-ext-mq" moreinfo="none">qimport</command>
16093 automatically does an <command role="hg-cmd" moreinfo="none">hg add</command>
16094 of the imported patch.</para>
16096 </sect2>
16097 <sect2>
16098 <title><command role="hg-ext-mq" moreinfo="none">qinit</command>—prepare
16099 a repository to work with MQ</title>
16101 <para id="x_5fa">The <command role="hg-ext-mq" moreinfo="none">qinit</command> command
16102 prepares a repository to work with MQ. It creates a directory
16103 called <filename role="special" class="directory" moreinfo="none">.hg/patches</filename>.</para>
16105 <para id="x_5fb">Options:</para>
16106 <itemizedlist>
16107 <listitem><para id="x_5fc"><option role="hg-ext-mq-cmd-qinit-opt">-c</option>: Create
16108 <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> as a repository
16109 in its own right. Also creates a <filename role="special" moreinfo="none">.hgignore</filename> file that will
16110 ignore the <filename role="special" moreinfo="none">status</filename>
16111 file.</para>
16112 </listitem></itemizedlist>
16114 <para id="x_5fd">When the <filename role="special" class="directory" moreinfo="none">.hg/patches</filename> directory is a
16115 repository, the <command role="hg-ext-mq" moreinfo="none">qimport</command>
16116 and <command role="hg-ext-mq" moreinfo="none">qnew</command> commands
16117 automatically <command role="hg-cmd" moreinfo="none">hg add</command> new
16118 patches.</para>
16120 </sect2>
16121 <sect2>
16122 <title><command role="hg-ext-mq" moreinfo="none">qnew</command>—create a
16123 new patch</title>
16125 <para id="x_5fe">The <command role="hg-ext-mq" moreinfo="none">qnew</command> command
16126 creates a new patch. It takes one mandatory argument, the
16127 name to use for the patch file. The newly created patch is
16128 created empty by default. It is added to the <filename role="special" moreinfo="none">series</filename> file after the current
16129 topmost applied patch, and is immediately pushed on top of
16130 that patch.</para>
16132 <para id="x_5ff">If <command role="hg-ext-mq" moreinfo="none">qnew</command> finds modified
16133 files in the working directory, it will refuse to create a new
16134 patch unless the <option role="hg-ext-mq-cmd-qnew-opt">-f</option> option is used
16135 (see below). This behavior allows you to <command role="hg-ext-mq" moreinfo="none">qrefresh</command> your topmost applied
16136 patch before you apply a new patch on top of it.</para>
16138 <para id="x_600">Options:</para>
16139 <itemizedlist>
16140 <listitem><para id="x_601"><option role="hg-ext-mq-cmd-qnew-opt">-f</option>: Create a new
16141 patch if the contents of the working directory are
16142 modified. Any outstanding modifications are added to the
16143 newly created patch, so after this command completes, the
16144 working directory will no longer be modified.</para>
16145 </listitem>
16146 <listitem><para id="x_602"><option role="hg-ext-mq-cmd-qnew-opt">-m</option>: Use the given
16147 text as the commit message. This text will be stored at
16148 the beginning of the patch file, before the patch
16149 data.</para>
16150 </listitem></itemizedlist>
16152 </sect2>
16153 <sect2>
16154 <title><command role="hg-ext-mq" moreinfo="none">qnext</command>—print
16155 the name of the next patch</title>
16157 <para id="x_603">The <command role="hg-ext-mq" moreinfo="none">qnext</command> command
16158 prints the name name of the next patch in the <filename role="special" moreinfo="none">series</filename> file after the topmost
16159 applied patch. This patch will become the topmost applied
16160 patch if you run <command role="hg-ext-mq" moreinfo="none">qpush</command>.</para>
16162 </sect2>
16163 <sect2>
16164 <title><command role="hg-ext-mq" moreinfo="none">qpop</command>—pop
16165 patches off the stack</title>
16167 <para id="x_604">The <command role="hg-ext-mq" moreinfo="none">qpop</command> command
16168 removes applied patches from the top of the stack of applied
16169 patches. By default, it removes only one patch.</para>
16171 <para id="x_605">This command removes the changesets that represent the
16172 popped patches from the repository, and updates the working
16173 directory to undo the effects of the patches.</para>
16175 <para id="x_606">This command takes an optional argument, which it uses as
16176 the name or index of the patch to pop to. If given a name, it
16177 will pop patches until the named patch is the topmost applied
16178 patch. If given a number, <command role="hg-ext-mq" moreinfo="none">qpop</command> treats the number as an
16179 index into the entries in the series file, counting from zero
16180 (empty lines and lines containing only comments do not count).
16181 It pops patches until the patch identified by the given index
16182 is the topmost applied patch.</para>
16184 <para id="x_607">The <command role="hg-ext-mq" moreinfo="none">qpop</command> command does
16185 not read or write patches or the <filename role="special" moreinfo="none">series</filename> file. It is thus safe to
16186 <command role="hg-ext-mq" moreinfo="none">qpop</command> a patch that you have
16187 removed from the <filename role="special" moreinfo="none">series</filename>
16188 file, or a patch that you have renamed or deleted entirely.
16189 In the latter two cases, use the name of the patch as it was
16190 when you applied it.</para>
16192 <para id="x_608">By default, the <command role="hg-ext-mq" moreinfo="none">qpop</command>
16193 command will not pop any patches if the working directory has
16194 been modified. You can override this behavior using the
16195 <option role="hg-ext-mq-cmd-qpop-opt">-f</option> option,
16196 which reverts all modifications in the working
16197 directory.</para>
16199 <para id="x_609">Options:</para>
16200 <itemizedlist>
16201 <listitem><para id="x_60a"><option role="hg-ext-mq-cmd-qpop-opt">-a</option>: Pop all
16202 applied patches. This returns the repository to its state
16203 before you applied any patches.</para>
16204 </listitem>
16205 <listitem><para id="x_60b"><option role="hg-ext-mq-cmd-qpop-opt">-f</option>: Forcibly
16206 revert any modifications to the working directory when
16207 popping.</para>
16208 </listitem>
16209 <listitem><para id="x_60c"><option role="hg-ext-mq-cmd-qpop-opt">-n</option>: Pop a patch
16210 from the named queue.</para>
16211 </listitem></itemizedlist>
16213 <para id="x_60d">The <command role="hg-ext-mq" moreinfo="none">qpop</command> command
16214 removes one line from the end of the <filename role="special" moreinfo="none">status</filename> file for each patch that it
16215 pops.</para>
16217 </sect2>
16218 <sect2>
16219 <title><command role="hg-ext-mq" moreinfo="none">qprev</command>—print
16220 the name of the previous patch</title>
16222 <para id="x_60e">The <command role="hg-ext-mq" moreinfo="none">qprev</command> command
16223 prints the name of the patch in the <filename role="special" moreinfo="none">series</filename> file that comes before the
16224 topmost applied patch. This will become the topmost applied
16225 patch if you run <command role="hg-ext-mq" moreinfo="none">qpop</command>.</para>
16227 </sect2>
16228 <sect2 id="sec:mqref:cmd:qpush">
16229 <title><command role="hg-ext-mq" moreinfo="none">qpush</command>—push
16230 patches onto the stack</title>
16232 <para id="x_60f">The <command role="hg-ext-mq" moreinfo="none">qpush</command> command adds
16233 patches onto the applied stack. By default, it adds only one
16234 patch.</para>
16236 <para id="x_610">This command creates a new changeset to represent each
16237 applied patch, and updates the working directory to apply the
16238 effects of the patches.</para>
16240 <para id="x_611">The default data used when creating a changeset are as
16241 follows:</para>
16242 <itemizedlist>
16243 <listitem><para id="x_612">The commit date and time zone are the current
16244 date and time zone. Because these data are used to
16245 compute the identity of a changeset, this means that if
16246 you <command role="hg-ext-mq" moreinfo="none">qpop</command> a patch and
16247 <command role="hg-ext-mq" moreinfo="none">qpush</command> it again, the
16248 changeset that you push will have a different identity
16249 than the changeset you popped.</para>
16250 </listitem>
16251 <listitem><para id="x_613">The author is the same as the default used by
16252 the <command role="hg-cmd" moreinfo="none">hg commit</command>
16253 command.</para>
16254 </listitem>
16255 <listitem><para id="x_614">The commit message is any text from the patch
16256 file that comes before the first diff header. If there is
16257 no such text, a default commit message is used that
16258 identifies the name of the patch.</para>
16259 </listitem></itemizedlist>
16260 <para id="x_615">If a patch contains a Mercurial patch header,
16261 the information in the patch header overrides these
16262 defaults.</para>
16264 <para id="x_616">Options:</para>
16265 <itemizedlist>
16266 <listitem><para id="x_617"><option role="hg-ext-mq-cmd-qpush-opt">-a</option>: Push all
16267 unapplied patches from the <filename role="special" moreinfo="none">series</filename> file until there are
16268 none left to push.</para>
16269 </listitem>
16270 <listitem><para id="x_618"><option role="hg-ext-mq-cmd-qpush-opt">-l</option>: Add the name
16271 of the patch to the end of the commit message.</para>
16272 </listitem>
16273 <listitem><para id="x_619"><option role="hg-ext-mq-cmd-qpush-opt">-m</option>: If a patch
16274 fails to apply cleanly, use the entry for the patch in
16275 another saved queue to compute the parameters for a
16276 three-way merge, and perform a three-way merge using the
16277 normal Mercurial merge machinery. Use the resolution of
16278 the merge as the new patch content.</para>
16279 </listitem>
16280 <listitem><para id="x_61a"><option role="hg-ext-mq-cmd-qpush-opt">-n</option>: Use the
16281 named queue if merging while pushing.</para>
16282 </listitem></itemizedlist>
16284 <para id="x_61b">The <command role="hg-ext-mq" moreinfo="none">qpush</command> command
16285 reads, but does not modify, the <filename role="special" moreinfo="none">series</filename> file. It appends one line
16286 to the <command role="hg-cmd" moreinfo="none">hg status</command> file for
16287 each patch that it pushes.</para>
16289 </sect2>
16290 <sect2>
16291 <title><command role="hg-ext-mq" moreinfo="none">qrefresh</command>—update the
16292 topmost applied patch</title>
16294 <para id="x_61c">The <command role="hg-ext-mq" moreinfo="none">qrefresh</command> command
16295 updates the topmost applied patch. It modifies the patch,
16296 removes the old changeset that represented the patch, and
16297 creates a new changeset to represent the modified
16298 patch.</para>
16300 <para id="x_61d">The <command role="hg-ext-mq" moreinfo="none">qrefresh</command> command
16301 looks for the following modifications:</para>
16302 <itemizedlist>
16303 <listitem><para id="x_61e">Changes to the commit message, i.e. the text
16304 before the first diff header in the patch file, are
16305 reflected in the new changeset that represents the
16306 patch.</para>
16307 </listitem>
16308 <listitem><para id="x_61f">Modifications to tracked files in the working
16309 directory are added to the patch.</para>
16310 </listitem>
16311 <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
16312 and rename destinations are added to the patch, while
16313 removed files and rename sources are removed.</para>
16314 </listitem></itemizedlist>
16316 <para id="x_621">Even if <command role="hg-ext-mq" moreinfo="none">qrefresh</command>
16317 detects no changes, it still recreates the changeset that
16318 represents the patch. This causes the identity of the
16319 changeset to differ from the previous changeset that
16320 identified the patch.</para>
16322 <para id="x_622">Options:</para>
16323 <itemizedlist>
16324 <listitem><para id="x_623"><option role="hg-ext-mq-cmd-qrefresh-opt">-e</option>: Modify
16325 the commit and patch description, using the preferred text
16326 editor.</para>
16327 </listitem>
16328 <listitem><para id="x_624"><option role="hg-ext-mq-cmd-qrefresh-opt">-m</option>: Modify
16329 the commit message and patch description, using the given
16330 text.</para>
16331 </listitem>
16332 <listitem><para id="x_625"><option role="hg-ext-mq-cmd-qrefresh-opt">-l</option>: Modify
16333 the commit message and patch description, using text from
16334 the given file.</para>
16335 </listitem></itemizedlist>
16337 </sect2>
16338 <sect2>
16339 <title><command role="hg-ext-mq" moreinfo="none">qrename</command>—rename
16340 a patch</title>
16342 <para id="x_626">The <command role="hg-ext-mq" moreinfo="none">qrename</command> command
16343 renames a patch, and changes the entry for the patch in the
16344 <filename role="special" moreinfo="none">series</filename> file.</para>
16346 <para id="x_627">With a single argument, <command role="hg-ext-mq" moreinfo="none">qrename</command> renames the topmost
16347 applied patch. With two arguments, it renames its first
16348 argument to its second.</para>
16350 </sect2>
16351 <sect2>
16352 <title><command role="hg-ext-mq" moreinfo="none">qseries</command>—print
16353 the entire patch series</title>
16355 <para id="x_62a">The <command role="hg-ext-mq" moreinfo="none">qseries</command> command
16356 prints the entire patch series from the <filename role="special" moreinfo="none">series</filename> file. It prints only patch
16357 names, not empty lines or comments. It prints in order from
16358 first to be applied to last.</para>
16360 </sect2>
16361 <sect2>
16362 <title><command role="hg-ext-mq" moreinfo="none">qtop</command>—print the
16363 name of the current patch</title>
16365 <para id="x_62b">The <command role="hg-ext-mq" moreinfo="none">qtop</command> prints the
16366 name of the topmost currently applied patch.</para>
16368 </sect2>
16369 <sect2>
16370 <title><command role="hg-ext-mq" moreinfo="none">qunapplied</command>—print patches
16371 not yet applied</title>
16373 <para id="x_62c">The <command role="hg-ext-mq" moreinfo="none">qunapplied</command> command
16374 prints the names of patches from the <filename role="special" moreinfo="none">series</filename> file that are not yet
16375 applied. It prints them in order from the next patch that
16376 will be pushed to the last.</para>
16378 </sect2>
16379 <sect2>
16380 <title><command role="hg-cmd" moreinfo="none">hg strip</command>—remove a
16381 revision and descendants</title>
16383 <para id="x_62d">The <command role="hg-cmd" moreinfo="none">hg strip</command> command
16384 removes a revision, and all of its descendants, from the
16385 repository. It undoes the effects of the removed revisions
16386 from the repository, and updates the working directory to the
16387 first parent of the removed revision.</para>
16389 <para id="x_62e">The <command role="hg-cmd" moreinfo="none">hg strip</command> command
16390 saves a backup of the removed changesets in a bundle, so that
16391 they can be reapplied if removed in error.</para>
16393 <para id="x_62f">Options:</para>
16394 <itemizedlist>
16395 <listitem><para id="x_630"><option role="hg-opt-strip">-b</option>: Save
16396 unrelated changesets that are intermixed with the stripped
16397 changesets in the backup bundle.</para>
16398 </listitem>
16399 <listitem><para id="x_631"><option role="hg-opt-strip">-f</option>: If a
16400 branch has multiple heads, remove all heads.</para>
16401 </listitem>
16402 <listitem><para id="x_632"><option role="hg-opt-strip">-n</option>: Do
16403 not save a backup bundle.</para>
16404 </listitem></itemizedlist>
16406 </sect2>
16407 </sect1>
16408 <sect1>
16409 <title>MQ file reference</title>
16411 <sect2>
16412 <title>The <filename role="special" moreinfo="none">series</filename>
16413 file</title>
16415 <para id="x_633">The <filename role="special" moreinfo="none">series</filename> file
16416 contains a list of the names of all patches that MQ can apply.
16417 It is represented as a list of names, with one name saved per
16418 line. Leading and trailing white space in each line are
16419 ignored.</para>
16421 <para id="x_634">Lines may contain comments. A comment begins with the
16422 <quote><literal moreinfo="none">#</literal></quote> character, and extends to
16423 the end of the line. Empty lines, and lines that contain only
16424 comments, are ignored.</para>
16426 <para id="x_635">You will often need to edit the <filename role="special" moreinfo="none">series</filename> file by hand, hence the
16427 support for comments and empty lines noted above. For
16428 example, you can comment out a patch temporarily, and <command role="hg-ext-mq" moreinfo="none">qpush</command> will skip over that patch
16429 when applying patches. You can also change the order in which
16430 patches are applied by reordering their entries in the
16431 <filename role="special" moreinfo="none">series</filename> file.</para>
16433 <para id="x_636">Placing the <filename role="special" moreinfo="none">series</filename>
16434 file under revision control is also supported; it is a good
16435 idea to place all of the patches that it refers to under
16436 revision control, as well. If you create a patch directory
16437 using the <option role="hg-ext-mq-cmd-qinit-opt">-c</option>
16438 option to <command role="hg-ext-mq" moreinfo="none">qinit</command>, this will
16439 be done for you automatically.</para>
16441 </sect2>
16442 <sect2>
16443 <title>The <filename role="special" moreinfo="none">status</filename>
16444 file</title>
16446 <para id="x_637">The <filename role="special" moreinfo="none">status</filename> file
16447 contains the names and changeset hashes of all patches that MQ
16448 currently has applied. Unlike the <filename role="special" moreinfo="none">series</filename> file, this file is not
16449 intended for editing. You should not place this file under
16450 revision control, or modify it in any way. It is used by MQ
16451 strictly for internal book-keeping.</para>
16453 </sect2>
16454 </sect1>
16455 </appendix>
16457 <!--
16458 local variables:
16459 sgml-parent-document: ("00book.xml" "book" "appendix")
16460 end:
16461 -->
16463 <!-- BEGIN appC -->
16464 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
16466 <appendix id="chap:srcinstall">
16467 <?dbhtml filename="installing-mercurial-from-source.html"?>
16468 <title>Installer Mercurial à partir des sources</title>
16470 <sect1 id="sec:srcinstall:unixlike">
16471 <title>Pour un système Unix ou similaire</title>
16473 <para id="x_5e0">Si vous utilisez un système Unix ou similaire, pour lequel
16474 une version récente de Python (2.3 ou plus) est disponible, l'installation
16475 de Mercurial à partir des sources est simple.</para>
16476 <orderedlist inheritnum="ignore" continuation="restarts">
16477 <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>
16478 </listitem>
16479 <listitem><para id="x_5e2">Extrayez le paquet : </para>
16480 <programlisting format="linespecific">gzip -dc mercurial-MYVERSION.tar.gz | tar xf -</programlisting>
16481 </listitem>
16482 <listitem><para id="x_5e3">Allez dans le répertoires où les sources ont
16483 été extraites et exécutez le script d'installation. Ce dernier compilera
16484 Mercurial et l'installera dans votre répertoire utilisateur.</para>
16485 <programlisting format="linespecific">cd mercurial-MYVERSION
16486 python setup.py install --force --home=$HOME</programlisting>
16487 </listitem>
16488 </orderedlist>
16489 <para id="x_5e4">Lorsque l'installation est terminée, Mercurial se
16490 trouvera dans le répertoire <literal moreinfo="none">bin</literal> de votre répertoire
16491 utilisateur.
16492 N'oubliez pas de vérifier que ce répertoire se trouve dans la liste
16493 des répertoires où votre shell recherche les exécutables.</para>
16495 <para id="x_5e5">Vous devrez vraisemblablement définir la variable
16496 d'environnement <envar>PYTHONPATH</envar> de manière à ce que
16497 l'exécutable de Mercurial puisse trouver le reste des paquets logiciels.
16498 Par exemple, sur mon ordinateur portable, je dois le définir ainsi:
16499 <literal moreinfo="none">/home/bos/lib/python</literal>. Le chemin exact à utiliser
16500 dépendra de la manière dont Python aura été construit pour votre
16501 système. Il ne devrait pas être difficile de le trouver. En cas de
16502 doute, lisez le texte généré lors de l'installation ci-dessus, et
16503 recherchez l'emplacement où le contenu du répertoire
16504 <literal moreinfo="none">mercurial</literal> a été installé.</para>
16506 </sect1>
16507 <sect1>
16508 <title>Pour Windows</title>
16510 <para id="x_5e6">Construire et installer Mercurial sous Windows nécessite
16511 des outils logiciels divers, une certaine connaissance technique et une
16512 bonne dose de patience. Je vous <emphasis>déconseille fortement</emphasis>
16513 de tenter de le faire si vous êtes un <quote>simple utilisateur</quote>.
16514 A moins que vous n'ayez l'intention de "hacker" Mercurial, je vous
16515 suggère d'avoir recours à un paquet d'installation de la version binaire.</para>
16517 <para id="x_5e7">Si vous avez vraiment l'intention de construire
16518 Mercurial à partir des sources sous Windows, suivez les indications pour
16519 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>,
16520 et préparez vous à un travail épineux.</para>
16522 </sect1>
16523 </appendix>
16525 <!--
16526 local variables:
16527 sgml-parent-document: ("00book.xml" "book" "appendix")
16528 end:
16529 -->
16531 <!-- BEGIN appD -->
16532 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
16534 <appendix id="cha:opl">
16535 <?dbhtml filename="open-publication-license.html"?>
16536 <title>Open Publication License</title>
16538 <para id="x_638">Version 1.0, 8 June 1999</para>
16540 <sect1>
16541 <title>Requirements on both unmodified and modified
16542 versions</title>
16544 <para id="x_639">The Open Publication works may be reproduced and distributed
16545 in whole or in part, in any medium physical or electronic,
16546 provided that the terms of this license are adhered to, and that
16547 this license or an incorporation of it by reference (with any
16548 options elected by the author(s) and/or publisher) is displayed
16549 in the reproduction.</para>
16551 <para id="x_63a">Proper form for an incorporation by reference is as
16552 follows:</para>
16554 <blockquote>
16555 <para id="x_63b"> Copyright (c) <emphasis>year</emphasis> by
16556 <emphasis>author's name or designee</emphasis>. This material
16557 may be distributed only subject to the terms and conditions
16558 set forth in the Open Publication License,
16559 v<emphasis>x.y</emphasis> or later (the latest version is
16560 presently available at <ulink url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).</para>
16561 </blockquote>
16563 <para id="x_63c">The reference must be immediately followed with any options
16564 elected by the author(s) and/or publisher of the document (see
16565 <xref linkend="sec:opl:options"/>).</para>
16567 <para id="x_63d">Commercial redistribution of Open Publication-licensed
16568 material is permitted.</para>
16570 <para id="x_63e">Any publication in standard (paper) book form shall require
16571 the citation of the original publisher and author. The publisher
16572 and author's names shall appear on all outer surfaces of the
16573 book. On all outer surfaces of the book the original publisher's
16574 name shall be as large as the title of the work and cited as
16575 possessive with respect to the title.</para>
16577 </sect1>
16578 <sect1>
16579 <title>Copyright</title>
16581 <para id="x_63f">The copyright to each Open Publication is owned by its
16582 author(s) or designee.</para>
16584 </sect1>
16585 <sect1>
16586 <title>Scope of license</title>
16588 <para id="x_640">The following license terms apply to all Open Publication
16589 works, unless otherwise explicitly stated in the
16590 document.</para>
16592 <para id="x_641">Mere aggregation of Open Publication works or a portion of
16593 an Open Publication work with other works or programs on the
16594 same media shall not cause this license to apply to those other
16595 works. The aggregate work shall contain a notice specifying the
16596 inclusion of the Open Publication material and appropriate
16597 copyright notice.</para>
16599 <para id="x_642"><emphasis role="bold">Severability</emphasis>. If any part
16600 of this license is found to be unenforceable in any
16601 jurisdiction, the remaining portions of the license remain in
16602 force.</para>
16604 <para id="x_643"><emphasis role="bold">No warranty</emphasis>. Open
16605 Publication works are licensed and provided <quote>as is</quote>
16606 without warranty of any kind, express or implied, including, but
16607 not limited to, the implied warranties of merchantability and
16608 fitness for a particular purpose or a warranty of
16609 non-infringement.</para>
16611 </sect1>
16612 <sect1>
16613 <title>Requirements on modified works</title>
16615 <para id="x_644">All modified versions of documents covered by this license,
16616 including translations, anthologies, compilations and partial
16617 documents, must meet the following requirements:</para>
16619 <orderedlist inheritnum="ignore" continuation="restarts">
16620 <listitem><para id="x_645">The modified version must be labeled as
16621 such.</para>
16622 </listitem>
16623 <listitem><para id="x_646">The person making the modifications must be
16624 identified and the modifications dated.</para>
16625 </listitem>
16626 <listitem><para id="x_647">Acknowledgement of the original author and
16627 publisher if applicable must be retained according to normal
16628 academic citation practices.</para>
16629 </listitem>
16630 <listitem><para id="x_648">The location of the original unmodified document
16631 must be identified.</para>
16632 </listitem>
16633 <listitem><para id="x_649">The original author's (or authors') name(s) may
16634 not be used to assert or imply endorsement of the resulting
16635 document without the original author's (or authors')
16636 permission.</para>
16637 </listitem></orderedlist>
16639 </sect1>
16640 <sect1>
16641 <title>Good-practice recommendations</title>
16643 <para id="x_64a">In addition to the requirements of this license, it is
16644 requested from and strongly recommended of redistributors
16645 that:</para>
16647 <orderedlist inheritnum="ignore" continuation="restarts">
16648 <listitem><para id="x_64b">If you are distributing Open Publication works
16649 on hardcopy or CD-ROM, you provide email notification to the
16650 authors of your intent to redistribute at least thirty days
16651 before your manuscript or media freeze, to give the authors
16652 time to provide updated documents. This notification should
16653 describe modifications, if any, made to the document.</para>
16654 </listitem>
16655 <listitem><para id="x_64c">All substantive modifications (including
16656 deletions) be either clearly marked up in the document or
16657 else described in an attachment to the document.</para>
16658 </listitem>
16659 <listitem><para id="x_64d">Finally, while it is not mandatory under this
16660 license, it is considered good form to offer a free copy of
16661 any hardcopy and CD-ROM expression of an Open
16662 Publication-licensed work to its author(s).</para>
16663 </listitem></orderedlist>
16665 </sect1>
16666 <sect1 id="sec:opl:options">
16667 <title>License options</title>
16669 <para id="x_64e">The author(s) and/or publisher of an Open
16670 Publication-licensed document may elect certain options by
16671 appending language to the reference to or copy of the license.
16672 These options are considered part of the license instance and
16673 must be included with the license (or its incorporation by
16674 reference) in derived works.</para>
16676 <orderedlist inheritnum="ignore" continuation="restarts">
16677 <listitem><para id="x_64f">To prohibit distribution of substantively
16678 modified versions without the explicit permission of the
16679 author(s). <quote>Substantive modification</quote> is
16680 defined as a change to the semantic content of the document,
16681 and excludes mere changes in format or typographical
16682 corrections.</para>
16683 </listitem>
16684 <listitem><para id="x_650"> To accomplish this, add the phrase
16685 <quote>Distribution of substantively modified versions of
16686 this document is prohibited without the explicit
16687 permission of the copyright holder.</quote> to the license
16688 reference or copy.</para>
16689 </listitem>
16690 <listitem><para id="x_651">To prohibit any publication of this work or
16691 derivative works in whole or in part in standard (paper)
16692 book form for commercial purposes is prohibited unless prior
16693 permission is obtained from the copyright holder.</para>
16694 </listitem>
16695 <listitem><para id="x_652">To accomplish this, add the phrase
16696 <quote>Distribution of the work or derivative of the work in
16697 any standard (paper) book form is prohibited unless prior
16698 permission is obtained from the copyright holder.</quote>
16699 to the license reference or copy.</para>
16700 </listitem></orderedlist>
16702 </sect1>
16703 </appendix>
16705 <!--
16706 local variables:
16707 sgml-parent-document: ("00book.xml" "book" "appendix")
16708 end:
16709 -->
16711 </book>