hgbook
view fr/ch06-collab.xml @ 1009:304c6a1758ae
French translation : ch06-collab.xml - 25% translated
| author | Frédéric Bouquet <youshe.jaalon@gmail.com> |
|---|---|
| date | Sun Sep 20 13:09:33 2009 +0200 (2009-09-20) |
| parents | 6f8c48362758 |
| children | cd06c45e1631 |
line source
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
3 <chapter id="cha:collab">
4 <?dbhtml filename="collaborating-with-other-people.html"?>
5 <title>Collaborer avec d'autres personnes</title>
7 <para id="x_44a">Comme tout outil complètement décentralisé, Mercurial
8 n'impose pas de politique sur la façon dont les personnes devraient
9 travailler ensemble. Cependant, si vous êtes nouveau dans les systèmes de
10 gestion de révisions distribués, cela aide d'avoir des outils et exemples
11 en tête lorsque vous réfléchissez à de possibles modèles de
12 workflow.</para>
13 <!--TODO : workflow peut éventuellement être traduit ici par travail -->
15 <sect1>
16 <title>Interface web de Mercurial</title>
18 <para id="x_44b">Mercurial possède une interface web puissante qui
19 propose plusieurs capacités utiles.</para>
21 <para id="x_44c">Pour une utilisation intensive, l'interface web vous
22 permet de naviguer dans un ou une collection de dépôt. Vous pouvez voir
23 l'historique d'un dépôt, examiner chaque modification (commentaires et
24 "diffs"), et voir le contenu de chaque répertoire et fichier. Vous
25 pouvez même accéder à une vue de l'historique qui vous donne une vue
26 graphique de la relation entre les modifications individuelles et les
27 fusions (merge).</para>
29 <para id="x_44d">De plus, pour la consommation humaine, l'interface web
30 fournit des flux Atom et RSS des changements dans un dépôt. Ceci vous
31 permet de <quote>souscrire</quote> à un dépôt en utilisant votre
32 lecteur de flux favori, et être automatiquement avertis de l'activité
33 dans ce dépôt aussi tôt qu'elle change. Je trouve cette fonctionnalité
34 bien plus commode que le modèle qui consiste à souscrire à une mailing
35 list à laquelle les avertissements sont envoyés, puisque cela demande
36 aucune configuration supplémentaire de la part de la personne qui
37 publie un dépôt.</para>
39 <para id="x_44e">L'interface web permet aussi aux utilisateurs distants
40 de cloner un dépôt, récupérer (pull) les changement à partir de celui
41 ci, et (lorsque le serveur est configuré pour l'autoriser) lui envoyer
42 (push) des changements. Le protocole de tunnel HTTP de Mercurial
43 compresse agressivement les données, ainsi, il fonctionne efficacement,
44 même au dessus des réseaux avec une bande passante faible.</para>
46 <para id="x_44f">La plus simple façon de démarrer avec l'interface
47 utilisateur est d'utiliser votre navigateur web pour visiter un dépôt
48 existant, tel que le dépôt principal de Mercurial à l'adresse <ulink
49 url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para>
51 <para id="x_450">Si vous êtes intéressés pour proposer une interface web
52 de vos propres dépôts, il y a plusieurs façons de le faire.</para>
54 <para id="x_69d">La façon la plus simple et la plus rapide pour commencer
55 dans un environnement informel est d'utiliser la commande <command
56 role="hg-cmd">hg serve</command> qui est la plus adaptée à un service
57 à court terme et <quote>léger</quote>. Référez vous à <xref
58 linkend="sec:collab:serve"/> plus pas pour les détails d'utilisation
59 de cette commande.</para>
61 <para id="x_69e">Pour des dépôts dont la durée de vie est plus longue, où
62 vous voudriez un service accessible en permanence, il existe plusieurs
63 services publics d'hébergement qui sont accessibles. Certains sont
64 libres et gratuits pour les projets Open Source, alors que d'autres
65 offrent un hébergement commercial et payant. Une lise à jour est
66 disponible à l'adresse : <ulink
67 url="http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting">http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting</ulink>.</para>
69 <para id="x_6a0">Si vous préférez héberger vos propres dépôts, Mercurial
70 possède un support intégré pour plusieurs technologies pupulaires
71 d'hébergement, plus particulièrement CGI (Common Gateway Interface) et
72 WSGI (Web Services Gateway Interface). Référez vous à <xref
73 linkend="sec:collab:cgi"/> pour des détails sur la configuration CGI
74 et WSGI.</para>
75 </sect1>
77 <sect1>
78 <title>Modèles de collaboration</title>
80 <para id="x_451">Avec un outil convenablement flexible, faire des
81 décisions sur les workflow est plus un problème d'ingénierie sociale
82 qu'un problème technique. Mercurial n'impose que peu de limitations sur
83 la façon dont vous pouvez structurer le flux de travail dans un projet,
84 donc, c'est à vous et votre groupe de fixer et vivre avec un modèle qui
85 convient à vos besoins particuliers.</para>
87 <sect2>
88 <title>Facteurs à garder en tête</title>
90 <para id="x_452">L'aspect le plus important de tout modèle que vous
91 devez garder en tête est la façon dont il subvient aux besoins et
92 capacités des personnes qui l'utiliseront. Ceci pourrait sembler
93 évident en soi ; pourtant, vous ne pouvez pas vous permettre de
94 l'oublier à un seul moment.</para>
96 <para id="x_453">Une fois, j'ai mis en place un modèle de workflow qui
97 m'apparaissait comme parfait, mais il a causé la consternation et des
98 conflits au sein de mon équipe de développement. En dépit de mes
99 tentatives pour expliquer pourquoi nous avions besoin d'un ensemble
100 complexe de branches, et comment les changements devaient couler
101 entre eux, certains membres de l'équipe se révoltèrent. Alors qu'ils
102 étaient pourtant des personnes sympathiques, ils ne voulaient pas
103 prêter attention aux contraintes sur lesquelles nous étions en train
104 d'opérer, ou, face aux conséquences de ces contraintes dans les
105 détails du modèle que je préconisais.</para>
107 <para id="x_454">Ne balayez pas les problèmes sociaux ou techniques de
108 la main. Quelquesoit le schéma que vous promulguez, vous devriez
109 plannifier un protocole pour prévenir, ou rapidement vous relever de
110 troubles que vous pouvez anticiper. Par exemple, si vous vous
111 attentez à avoir une branche pour les changements pas-pour-release,
112 vous devriez penser très tôt sur la possibilité qu'une personne
113 fusionne (merge) accidentellement ces changements avec une branche de
114 release. Vous pouvez empécher ce problème particulier en écrivant un
115 hook qui prévient les changements d'être fusionnés à partir d'une
116 branche inapropriée.</para>
117 </sect2>
119 <sect2>
120 <title>Anarchie informelle</title>
122 <para id="x_455">Je ne voudrais pas suggérer qu'une approche
123 <quote>tout peut arriver</quote> comme quelque chose de durable, mais
124 il s'agit d'un modèle qui est simple à saisir et qui fonctionne
125 parfaitement dans quelques situations inhabituelles.</para>
127 <para id="x_456">Par exemple, beaucoup de projets ont un groupe distant
128 de collaborateurs qui ne se rencontre physiquement que très rarement.
129 Certains groupes aiment vaincre l'isolation du travail à distance en
130 organisant occasionnellement des <quote>sprints</quote>. Dans un
131 sprint, le nombre de personne qui viennent ensemble dans un même
132 localité (la salle de conférence d'une companie, la salle de réunion
133 d'un hotel, ce type d'endroit) et y passe plusieurs jours, plus ou
134 moins enfermés, et hackant intensément sur une poignée de
135 projets.</para>
137 <para id="x_457">Un "sprint" ou une session de "hacking" dans un café
138 sont les endroits parfaits pour utiliser la commande <command
139 role="hg-cmd">hg serve</command> puisque <command role="hg-cmd">hg
140 serve</command> n'a pas besoin d'une infrastructure extraordinaire
141 de serveurs. Vous pouvez commencer avec la commande <command
142 role="hg-cmd">hg serve</command> en un moment, en lisant <xref
143 linkend="sec:collab:serve"/> plus bas Ensuite, dites simplement à
144 la personne à coté de vous que vous exécutez un serveur, envoyez lui
145 l'URL par un message instantané, et vous avez immédiatement un moyen
146 simple et rapide de travailler ensemble. Ils peuvent taper votre URL
147 dans leur navigateur web et rapidement avoir une revue des
148 changements ; ou ils peuvent récupérer chez vous un bugfix et le
149 vérifier ; ou ils peuvent cloner une branche contenant une nouvelle
150 fonctionnalité et la tester.</para>
152 <para id="x_458">Le charme et le problème en faisant les choses ainsi,
153 dans une mode ad-hoc est que seules les personnes qui sont au courant
154 de vos changements, et de leur emplacement, peuvent les voir. Une
155 telle approche informelle ne passe simplement pas à l'échelle au delà
156 d'une poignée de personnes, puisque chacun a besoin de connaître
157 <emphasis>n</emphasis> différents dépôts à partir des quels récupérer
158 les changements (pull).</para>
159 </sect2>
161 <sect2>
162 <title>Un simple dépôt central</title>
164 <para id="x_459">Pour de plus petits projets qui migrent depuis un
165 outil de gestion de révision centralisé, la façon la
166 plus simple de commencer est certainement d'avoir un flux de
167 changement à partir d'un unique dépôt central. Il s'agit aussi du
168 <quote>bloc de construction</quote> pour des schémas de workflow plus
169 ambitieux.</para>
171 <para id="x_45a">Les contributeurs commencent par cloner une copie de
172 ce dépôt. Ils peuvent récupérer les changements à n'importe quel
173 moment où ils en ressentent le besoin, et certains (sûrement tous)
174 développeurs ont les persmissions qui leur permettent d'envoyer leurs
175 modifications (push) en retour lorsqu'elles sont prêtes pour que les
176 autres personnes puissent les voir.</para>
178 <para id="x_45b">Dans ce modèle, il peut encore être sensé pour les
179 gens de récupérer les changements directement entre eux, sans passer
180 par le dépôt central. Considérez le cas où j'ai une tentative de bug
181 fix, mais je m'inquiète de savoir si, dans le cas où je la publiais,
182 cela ne casserait pas l'arbre des autres contributeurs s'ils la
183 récupèrerais. Pour réduire les dommages potentiels, je peux vous
184 demander de cloner mon dépôt dans un dépôt temporaire qui vous
185 appartient et de le tester. Ceci nous permet de ne pas publier les
186 modification potentiellement dangereuses tant qu'elles n'ont pas
187 encore été un peu testées.</para>
189 <para id="x_45c">Si une équipe héberge son propre dépôt dans ce type de
190 scénario, les personnes qui utilisent habituellement le protocole
191 <command>ssh</command> pour envoyer (push) en toute sécurité leurs
192 changements au dépôt central, comme docummenté dans <xref
193 linkend="sec:collab:ssh"/>. Il est aussi usuel de publier une copie
194 en lecture seule du dépôt sur HTTP comme dans <xref
195 linkend="sec:collab:cgi"/>. Publier sur HTTP satisfait le besoin
196 des personnes qui n'ont pas d'accès en écriture, et ceux qui veulent
197 utiliser leur navigateur web pour explorer l'historique du
198 dépôt.</para>
199 </sect2>
201 <sect2>
202 <title>Un dépôt central hébergé</title>
204 <para id="x_6a1">Une chose magnifique au sujet des services
205 d'hébergement comme <ulink
206 url="http://bitbucket.org/">Bitbucket</ulink> est qu'ils ne font
207 pas seulement gérer les détails minutieux de la configuration du
208 serveur, tels que les comptes utilisateur, l'authentification, les
209 protocoles sécurisés, ils fournissent aussi une infrastructure
210 additionnelle pour faire en sorte que ce modèle fonctionne
211 bien.</para>
213 <para id="x_6a2">Par exemple, un service d'hébergement bien conçu
214 laissera les personnes cloner leurs copies d'un dépôt à l'aide d'un
215 simple click. Ceci laisse les personnes travailler dans des espaces
216 séparés et partager leurs changements lorsqu'ils sont prêts.</para>
218 <para id="x_6a3">De plus, un bon service d'hébergement laissera les
219 personnes communiquer ensemble, par exemple pour dire <quote>Il y a
220 des changements prêts pour toi pour relecture dans cet
221 arbre</quote>.</para>
223 </sect2>
225 <sect2>
226 <title>Travailler avec plusieurs branches</title>
228 <para id="x_45d">Les projets d'une taille significative ont tendance à
229 avancer sur plusieurs fronts en même temps. Dans le cas de logiciel,
230 il est commun qu'un projet sorte périodiquement des releases
231 officielles. Une release devrait ensuite aller dans le <quote>mode de
232 maintenance</quote> pour un moment après sa première publication ;
233 les releases de maintenance tendent à contenir seulement des
234 corrections de bugs, et non de nouvelles fonctionnalités. En
235 parallèle de ces releases de maintenance, une ou plusieurs futures
236 releases doivent être en cours de développement. Les gens utilisent
237 en général le mot <quote>branche</quote> pour référer à l'une de ces
238 nombreuses directions légèrement différentes dans lesquelles le
239 développement évolue.</para>
241 <para id="x_45e">Mercurial est particulièrement bien adapté pour gérer
242 plusieurs branches simultanées mais non identiques. Chaque
243 <quote>direction de développement</quote> peut vivre dans son propre
244 dépôt central, et vous pouvez récupérez les changements de l'un ou
245 l'autre lorsque le besoin s'en fait sentir. Parce que les dépôts sont
246 indépendant les un des autres, les modifications instables dans une
247 branche de développement n'affecteront jamais une branche stable,
248 sauf si quelqu'un fusionne (merge) explicitement ces changements dans
249 la branche stable.</para>
251 <para id="x_45f">Voici un exemple sur comment cela peut se passer en
252 pratique. Disons que vous avez une <quote>branche principale</quote>
253 sur un serveur central.</para>
255 &interaction.branching.init;
257 <para id="x_460">Les contributeurs le clonent, y apportent localement
258 des modifications, les testent et envoient (push) en retour leurs
259 changements.</para>
261 <para id="x_461">Une fois que la branche principale atteint une étape
262 assez importante pour une release, vous pouvez utiliser la commande
263 <command role="hg-cmd">hg tag</command> pour donner un nom permanent
264 à cette étape de révision.</para>
266 &interaction.branching.tag;
268 <para id="x_462">Disons que du developpement continue a lieu sur la
269 branche principale.</para>
271 &interaction.branching.main;
273 <para id="x_463">En utilisant le tag qui enregistre l'étape importante,
274 les gens qui clonenent ce dépôt peuvent à tout moment dans le futur
275 utiliser la commande <command role="hg-cmd">hg update</command> pour
276 avoir une copie du répertoire de travail exactement comme il était
277 lorsque cette révision "tag" a été committée.</para>
279 &interaction.branching.update;
281 <para id="x_464">De plus, immédiatement après que la branche principale
282 soit taggée, nous pouvons maintenant cloner la branche principale sur
283 le serveur vers une nouvelle branche <quote>stable</quote> sur le
284 même serveur.</quote>
286 &interaction.branching.clone;
288 <para id="x_465">Si nous avons besoin d'effectuer des modifications à
289 la branche stable, nous pouvons alors cloner <emphasis>ce</emphasis>
290 dépôt, effectuer nos modifications, committer, et envoyer nos
291 changements en retour là bas.</para>
293 &interaction.branching.stable;
295 <para id="x_466">Puisque les dépôts Mercurial sont indépendants, et que
296 Mercurial ne déplace pas les changements automatiquement, les
297 branches stable et principale sont <emphasis>isolées</emphasis> l'une
298 de l'autre. Les changements qui sont faits à la branche principale ne
299 <quote>fuient</quote> pas vers la branche stable, et vice
300 versa.</para>
302 <para id="x_467">Nous allons souvent avoir envie que toutes nos
303 correction de bugs sur la branche stable soient reportées sur la
304 branche principale. Plutôt que de réécrire une correction de bug pour
305 la branche principale, nous pouvons simplement récupérer (pull) et
306 fusionner (merge) les changements de la branche stable vers la
307 branche principal, et Mercurial se débrouillera pour rapporter ces
308 corrections de bugs pour nous.</para>
310 &interaction.branching.merge;
312 <para id="x_468">La branche principale contiendra toujours des
313 changements qui ne sont pas dans la branche stable, mais elle
314 contiendra aussi les corrections de bugs de la branche stable. La
315 branche stable restera non affectée par ces changements, tant qu'ils
316 coulent de la branche stable vers la branche principale, et non dans
317 l'autre sens.</para>
318 </sect2>
320 <sect2>
321 <title>Feature branches</title>
323 <para id="x_469">Pour de plus gros projets, une façon efficace de gérer
324 les changements est de casser l'équipe en plus pettis groupes. Chaque
325 groupe a une branche partagée qui lui est attitrée, clonée à partir
326 d'une unique branche <quote>principale</quote> utilisée pour le
327 projet entier. Les personnes travaillant sur une branche individuelle
328 sont typiquement isolées des développements sur les autres
329 branches.</para>
331 <figure id="fig:collab:feature-branches">
332 <title>Feature branches</title>
333 <mediaobject>
334 <imageobject><imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject>
335 <textobject><phrase>XXX add text</phrase></textobject>
336 </mediaobject>
337 </figure>
339 <para id="x_46b">Lorsqu'une fonctionnalité particulière est réputée
340 pour être dans une forme adaptée, quelqu'un de l'équipe qui s'occupe
341 de cette fonctionnalité récupère les changements (pull) à partir de
342 la branche principale vers la branche de cette fonctionnalité,
343 fusionne (merge) et renvoie (push) le tout vers la branche
344 principale.</para>
345 </sect2>
347 <sect2>
348 <title>Le train des releases</title>
349 <!-- J'ai laissé train en traduction à train mais peut être que suite, file,
350 ... sont des mots qui conviennent mieux ? A méditer -->
352 <para id="x_46c">Certains projets sont organisés comme un
353 <quote>train</quote> basique : une release est planifiée tous les
354 quelques mois, et, toutes les fonctionnalités disponibles lorsque le
355 <quote>train</quote> est prêt à s'arrêter sont autorisées ici.
357 <para id="x_46d">Ce modèle ressemble à travailler avec des branches de
358 fonctionnalités. La différence est que lorsqu'une branche de
359 fonctionnalité rate le train, quelqu'un de l'équipe qui travaille sur
360 cette fonctionnalité récupère (pull) et fusionne (merge) ce qui a été
361 ajouté à la release du train dans la branche de la fonctionnalité,
362 puis, l'équipe continue son travail au dessus de cette release afin
363 que leur fonctionnalité puisse être ajoutée à la prochaine
364 release.</para>
365 </sect2>
367 <sect2>
368 <title>Le modèle du Noyau Linux</title>
370 <para id="x_46e">Le développement du noyau Linux est doté d'une
371 structure hiérarchique superficielle, entourée par un nuage de chaos
372 apparent. Parce que la plupart des développeurs Linux utilisent
373 <command>git</command>, un outil distribué de gestion de révisions
374 avec des capacités similaires à celles de Mercurial, il est utile de
375 décrire comment le travail se déroule dans cet environnement ; si
376 vous aimez ces idées, l'approche se traduit correctement à travers
377 les outils.</para>
379 <para id="x_46f">Au centre de la communauté siège Linux Torvalds, le
380 créateur de Linux. Il publie un unique dépôt de sources qui est
381 considéré comme faisant <quote>authorité</quote> sur l'arborescence
382 par la communauté entière de développeurs. Tout le monde peut cloner
383 l'arbre de Linus, mais il est très difficile d'être choisi pour que
384 ses changements soient intégrés à l'arbre principal.</para>
386 <para id="x_470">Linus a plusieurs <quote>leutenants de
387 confiance</quote>. Comme règle générale, il récupère (pull) tous
388 les changements qu'ils publient, dans la plupart des cas sans même
389 relire ces modifications. Certains de ces lieutenants sont
390 généralement autorisés à être <quote>mainteneurs</quote>,
391 responsables pour un sous-système spécifique du noyau. Si un kernel
392 hacker aléatoire veut apporter des modification au sous-système
393 qu'ils veut voir intégré à l'arbre de Linus, il doit trouver qui est
394 le mainteneur du sous-système, et lui demander de récupérer ses
395 changements. Si le mainteneur relit ses changements et les accepte,
396 ils seront transmis à Linus le moment venu.</para>
398 <para id="x_471">Les lieutenants individuels ont leur propre approche
399 pour relire, accepter et publier les changements ; et pour décider
400 quand les apporter à Linus. De plus, il y a plusieurs branches
401 connues que les personnes utilisent pour différentes choses.
402 Par exemple, quelques personnes maintiennent des dépôts
403 <quote>stables</quote> de leurs versions du noyau, pour lesquels ils
404 apportent des corrections critiques lorsque nécessaire. Certains
405 mainteneurs publient plusieurs arbres : l'un pour les changements
406 expérimentaux, l'un pour les changements qu'ils vont faire remonter,
407 etc. D'autres ne publient qu'un unique arbre.</para>
409 <para id="x_472">Ce modèle a deux caractéristiques remarquables. La
410 première est qu'il s'agit de <quote>pull seulement</quote>. Vous
411 devez demander, convaincre, ou mendier au près d'un autre développeur
412 pour prendre vos modifications, puiqu'il n'y a vraissemblablement pas
413 d'abre où plus d'une personne peut envoyer des changement (push), et
414 qu'il n'y a pas de possibilité d'envoyer des changements (push) vers
415 un arbre que quelqu'un d'autre contrôle.</para>
417 <para id="x_473">La seconde est que c'est basé sur la réputation et
418 l'acclamation. Si vous êtes un inconnu, Linus va probablement ignorer
419 vos changement sans même répondre. Cependant, un mainteneur de
420 sous-système les relira probablement, et les acceptera sûrement s'ils
421 passent ses critaires d'acceptation. Plus vous contriburez du
422 <quote>bon</quote> code à un mainteneur, et plus celui ci aura
423 confiance en votre jugement pour accepter vos changements. Si vous
424 êtes bien connu et maintenez une branche ancienne pour quelque chose
425 que Linus n'a pas encore accepté, les gens avec un intérêt similaire
426 devraient récupérer vos changements régulièrement pour rester à jour
427 vis à vis de votre travail.</para>
429 <para id="x_474">La réputation et l'acclamation ne nécessite pas de
430 système croisé ou de limites <quote>personnelles</quote>. Si vous
431 êtes respectés mais que vous êtes un hacker spécialisé dans la
432 sauvegarde, et que vous tentez de corriger un bug réseau, ce
433 changement recevra un examen approfondu de la part du mainteneur
434 responsable du réseau comparable à celui d'un total étranger.</para>
436 <para id="x_475">Pour les personnes qui viennent d'un projet dont
437 l'arrière plan est plus ordonné, le processus chaotique de
438 développement du noyau Linux en comparaison apparaît totalement
439 dément. C'est le sujet de bien des caprices d'individualistes ;
440 des personnes qui balayent les changements même s'ils croient que
441 c'est approprié ; et l'allure du développement de Linux est
442 ahurissant. Et pourtant, Linux est un bout de logiciel d'une grande
443 réussite et bien considéré.</para>
444 </sect2>
445 <!-- TODO : part 1/4 -->
446 <sect2>
447 <title>Collaboration pull seulement versus pull partagé</title>
449 <para id="x_476">A perpetual source of heat in the open source community is
450 whether a development model in which people only ever pull
451 changes from others is <quote>better than</quote> one in which
452 multiple people can push changes to a shared
453 repository.</para>
455 <para id="x_477">Typically, the backers of the shared-push model use tools
456 that actively enforce this approach. If you're using a
457 centralised revision control tool such as Subversion, there's
458 no way to make a choice over which model you'll use: the tool
459 gives you shared-push, and if you want to do anything else,
460 you'll have to roll your own approach on top (such as applying
461 a patch by hand).</para>
463 <para id="x_478">A good distributed revision control tool will
464 support both models. You and your collaborators can then
465 structure how you work together based on your own needs and
466 preferences, not on what contortions your tools force you
467 into.</para>
468 </sect2>
469 <sect2>
470 <title>Where collaboration meets branch management</title>
472 <para id="x_479">Once you and your team set up some shared
473 repositories and start propagating changes back and forth
474 between local and shared repos, you begin to face a related,
475 but slightly different challenge: that of managing the
476 multiple directions in which your team may be moving at once.
477 Even though this subject is intimately related to how your
478 team collaborates, it's dense enough to merit treatment of its
479 own, in <xref linkend="chap:branch"/>.</para>
480 </sect2>
481 </sect1>
483 <sect1>
484 <title>The technical side of sharing</title>
486 <para id="x_47a">The remainder of this chapter is devoted to the question of
487 sharing changes with your collaborators.</para>
488 </sect1>
490 <sect1 id="sec:collab:serve">
491 <title>Informal sharing with <command role="hg-cmd">hg
492 serve</command></title>
494 <para id="x_47b">Mercurial's <command role="hg-cmd">hg serve</command>
495 command is wonderfully suited to small, tight-knit, and
496 fast-paced group environments. It also provides a great way to
497 get a feel for using Mercurial commands over a network.</para>
499 <para id="x_47c">Run <command role="hg-cmd">hg serve</command> inside a
500 repository, and in under a second it will bring up a specialised
501 HTTP server; this will accept connections from any client, and
502 serve up data for that repository until you terminate it.
503 Anyone who knows the URL of the server you just started, and can
504 talk to your computer over the network, can then use a web
505 browser or Mercurial to read data from that repository. A URL
506 for a <command role="hg-cmd">hg serve</command> instance running
507 on a laptop is likely to look something like
508 <literal>http://my-laptop.local:8000/</literal>.</para>
510 <para id="x_47d">The <command role="hg-cmd">hg serve</command> command is
511 <emphasis>not</emphasis> a general-purpose web server. It can do
512 only two things:</para>
513 <itemizedlist>
514 <listitem><para id="x_47e">Allow people to browse the history of the
515 repository it's serving, from their normal web
516 browsers.</para>
517 </listitem>
518 <listitem><para id="x_47f">Speak Mercurial's wire protocol, so that people
519 can <command role="hg-cmd">hg clone</command> or <command
520 role="hg-cmd">hg pull</command> changes from that
521 repository.</para>
522 </listitem></itemizedlist>
523 <para id="x_480">In particular, <command role="hg-cmd">hg serve</command>
524 won't allow remote users to <emphasis>modify</emphasis> your
525 repository. It's intended for read-only use.</para>
527 <para id="x_481">If you're getting started with Mercurial, there's nothing to
528 prevent you from using <command role="hg-cmd">hg serve</command>
529 to serve up a repository on your own computer, then use commands
530 like <command role="hg-cmd">hg clone</command>, <command
531 role="hg-cmd">hg incoming</command>, and so on to talk to that
532 server as if the repository was hosted remotely. This can help
533 you to quickly get acquainted with using commands on
534 network-hosted repositories.</para>
536 <sect2>
537 <title>A few things to keep in mind</title>
539 <para id="x_482">Because it provides unauthenticated read access to all
540 clients, you should only use <command role="hg-cmd">hg
541 serve</command> in an environment where you either don't
542 care, or have complete control over, who can access your
543 network and pull data from your repository.</para>
545 <para id="x_483">The <command role="hg-cmd">hg serve</command> command
546 knows nothing about any firewall software you might have
547 installed on your system or network. It cannot detect or
548 control your firewall software. If other people are unable to
549 talk to a running <command role="hg-cmd">hg serve</command>
550 instance, the second thing you should do
551 (<emphasis>after</emphasis> you make sure that they're using
552 the correct URL) is check your firewall configuration.</para>
554 <para id="x_484">By default, <command role="hg-cmd">hg serve</command>
555 listens for incoming connections on port 8000. If another
556 process is already listening on the port you want to use, you
557 can specify a different port to listen on using the <option
558 role="hg-opt-serve">-p</option> option.</para>
560 <para id="x_485">Normally, when <command role="hg-cmd">hg serve</command>
561 starts, it prints no output, which can be a bit unnerving. If
562 you'd like to confirm that it is indeed running correctly, and
563 find out what URL you should send to your collaborators, start
564 it with the <option role="hg-opt-global">-v</option>
565 option.</para>
566 </sect2>
567 </sect1>
569 <sect1 id="sec:collab:ssh">
570 <title>Using the Secure Shell (ssh) protocol</title>
572 <para id="x_486">You can pull and push changes securely over a network
573 connection using the Secure Shell (<literal>ssh</literal>)
574 protocol. To use this successfully, you may have to do a little
575 bit of configuration on the client or server sides.</para>
577 <para id="x_487">If you're not familiar with ssh, it's the name of
578 both a command and a network protocol that let you securely
579 communicate with another computer. To use it with Mercurial,
580 you'll be setting up one or more user accounts on a server so
581 that remote users can log in and execute commands.</para>
583 <para id="x_488">(If you <emphasis>are</emphasis> familiar with ssh, you'll
584 probably find some of the material that follows to be elementary
585 in nature.)</para>
587 <sect2>
588 <title>How to read and write ssh URLs</title>
590 <para id="x_489">An ssh URL tends to look like this:</para>
591 <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting>
592 <orderedlist>
593 <listitem><para id="x_48a">The <quote><literal>ssh://</literal></quote>
594 part tells Mercurial to use the ssh protocol.</para>
595 </listitem>
596 <listitem><para id="x_48b">The <quote><literal>bos@</literal></quote>
597 component indicates what username to log into the server
598 as. You can leave this out if the remote username is the
599 same as your local username.</para>
600 </listitem>
601 <listitem><para id="x_48c">The
602 <quote><literal>hg.serpentine.com</literal></quote> gives
603 the hostname of the server to log into.</para>
604 </listitem>
605 <listitem><para id="x_48d">The <quote>:22</quote> identifies the port
606 number to connect to the server on. The default port is
607 22, so you only need to specify a colon and port number if
608 you're <emphasis>not</emphasis> using port 22.</para>
609 </listitem>
610 <listitem><para id="x_48e">The remainder of the URL is the local path to
611 the repository on the server.</para>
612 </listitem></orderedlist>
614 <para id="x_48f">There's plenty of scope for confusion with the path
615 component of ssh URLs, as there is no standard way for tools
616 to interpret it. Some programs behave differently than others
617 when dealing with these paths. This isn't an ideal situation,
618 but it's unlikely to change. Please read the following
619 paragraphs carefully.</para>
621 <para id="x_490">Mercurial treats the path to a repository on the server as
622 relative to the remote user's home directory. For example, if
623 user <literal>foo</literal> on the server has a home directory
624 of <filename class="directory">/home/foo</filename>, then an
625 ssh URL that contains a path component of <filename
626 class="directory">bar</filename> <emphasis>really</emphasis>
627 refers to the directory <filename
628 class="directory">/home/foo/bar</filename>.</para>
630 <para id="x_491">If you want to specify a path relative to another user's
631 home directory, you can use a path that starts with a tilde
632 character followed by the user's name (let's call them
633 <literal>otheruser</literal>), like this.</para>
634 <programlisting>ssh://server/~otheruser/hg/repo</programlisting>
636 <para id="x_492">And if you really want to specify an
637 <emphasis>absolute</emphasis> path on the server, begin the
638 path component with two slashes, as in this example.</para>
639 <programlisting>ssh://server//absolute/path</programlisting>
640 </sect2>
642 <sect2>
643 <title>Finding an ssh client for your system</title>
645 <para id="x_493">Almost every Unix-like system comes with OpenSSH
646 preinstalled. If you're using such a system, run
647 <literal>which ssh</literal> to find out if the
648 <command>ssh</command> command is installed (it's usually in
649 <filename class="directory">/usr/bin</filename>). In the
650 unlikely event that it isn't present, take a look at your
651 system documentation to figure out how to install it.</para>
653 <para id="x_494">On Windows, the TortoiseHg package is bundled
654 with a version of Simon Tatham's excellent
655 <command>plink</command> command, and you should not need to
656 do any further configuration.</para>
657 </sect2>
659 <sect2>
660 <title>Generating a key pair</title>
662 <para id="x_499">To avoid the need to repetitively type a
663 password every time you need to use your ssh client, I
664 recommend generating a key pair.</para>
666 <tip>
667 <title>Key pairs are not mandatory</title>
669 <para id="x_6a4">Mercurial knows nothing about ssh authentication or key
670 pairs. You can, if you like, safely ignore this section and
671 the one that follows until you grow tired of repeatedly
672 typing ssh passwords.</para>
673 </tip>
675 <itemizedlist>
676 <listitem>
677 <para id="x_6a5">On a Unix-like system, the
678 <command>ssh-keygen</command> command will do the
679 trick.</para>
680 <para id="x_6a6">On Windows, if you're using TortoiseHg, you may need
681 to download a command named <command>puttygen</command>
682 from <ulink
683 url="http://www.chiark.greenend.org.uk/~sgtatham/putty">the
684 PuTTY web site</ulink> to generate a key pair. See
685 <ulink
686 url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">the
687 <command>puttygen</command> documentation</ulink> for
688 details of how use the command.</para>
689 </listitem>
690 </itemizedlist>
692 <para id="x_49a">When you generate a key pair, it's usually
693 <emphasis>highly</emphasis> advisable to protect it with a
694 passphrase. (The only time that you might not want to do this
695 is when you're using the ssh protocol for automated tasks on a
696 secure network.)</para>
698 <para id="x_49b">Simply generating a key pair isn't enough, however.
699 You'll need to add the public key to the set of authorised
700 keys for whatever user you're logging in remotely as. For
701 servers using OpenSSH (the vast majority), this will mean
702 adding the public key to a list in a file called <filename
703 role="special">authorized_keys</filename> in their <filename
704 role="special" class="directory">.ssh</filename>
705 directory.</para>
707 <para id="x_49c">On a Unix-like system, your public key will have a
708 <filename>.pub</filename> extension. If you're using
709 <command>puttygen</command> on Windows, you can save the
710 public key to a file of your choosing, or paste it from the
711 window it's displayed in straight into the <filename
712 role="special">authorized_keys</filename> file.</para>
713 </sect2>
714 <sect2>
715 <title>Using an authentication agent</title>
717 <para id="x_49d">An authentication agent is a daemon that stores
718 passphrases in memory (so it will forget passphrases if you
719 log out and log back in again). An ssh client will notice if
720 it's running, and query it for a passphrase. If there's no
721 authentication agent running, or the agent doesn't store the
722 necessary passphrase, you'll have to type your passphrase
723 every time Mercurial tries to communicate with a server on
724 your behalf (e.g. whenever you pull or push changes).</para>
726 <para id="x_49e">The downside of storing passphrases in an agent is that
727 it's possible for a well-prepared attacker to recover the
728 plain text of your passphrases, in some cases even if your
729 system has been power-cycled. You should make your own
730 judgment as to whether this is an acceptable risk. It
731 certainly saves a lot of repeated typing.</para>
733 <itemizedlist>
734 <listitem>
735 <para id="x_49f">On Unix-like systems, the agent is called
736 <command>ssh-agent</command>, and it's often run
737 automatically for you when you log in. You'll need to use
738 the <command>ssh-add</command> command to add passphrases
739 to the agent's store.</para>
740 </listitem>
741 <listitem>
742 <para id="x_6a7">On Windows, if you're using TortoiseHg, the
743 <command>pageant</command> command acts as the agent. As
744 with <command>puttygen</command>, you'll need to <ulink
745 url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">download
746 <command>pageant</command></ulink> from the PuTTY web
747 site and read <ulink
748 url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">its
749 documentation</ulink>. The <command>pageant</command>
750 command adds an icon to your system tray that will let you
751 manage stored passphrases.</para>
752 </listitem>
753 </itemizedlist>
754 </sect2>
756 <sect2>
757 <title>Configuring the server side properly</title>
759 <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
760 a variety of things can go wrong. Add Mercurial
761 on top, and there's plenty more scope for head-scratching.
762 Most of these potential problems occur on the server side, not
763 the client side. The good news is that once you've gotten a
764 configuration working, it will usually continue to work
765 indefinitely.</para>
767 <para id="x_4a1">Before you try using Mercurial to talk to an ssh server,
768 it's best to make sure that you can use the normal
769 <command>ssh</command> or <command>putty</command> command to
770 talk to the server first. If you run into problems with using
771 these commands directly, Mercurial surely won't work. Worse,
772 it will obscure the underlying problem. Any time you want to
773 debug ssh-related Mercurial problems, you should drop back to
774 making sure that plain ssh client commands work first,
775 <emphasis>before</emphasis> you worry about whether there's a
776 problem with Mercurial.</para>
778 <para id="x_4a2">The first thing to be sure of on the server side is that
779 you can actually log in from another machine at all. If you
780 can't use <command>ssh</command> or <command>putty</command>
781 to log in, the error message you get may give you a few hints
782 as to what's wrong. The most common problems are as
783 follows.</para>
784 <itemizedlist>
785 <listitem><para id="x_4a3">If you get a <quote>connection refused</quote>
786 error, either there isn't an SSH daemon running on the
787 server at all, or it's inaccessible due to firewall
788 configuration.</para>
789 </listitem>
790 <listitem><para id="x_4a4">If you get a <quote>no route to host</quote>
791 error, you either have an incorrect address for the server
792 or a seriously locked down firewall that won't admit its
793 existence at all.</para>
794 </listitem>
795 <listitem><para id="x_4a5">If you get a <quote>permission denied</quote>
796 error, you may have mistyped the username on the server,
797 or you could have mistyped your key's passphrase or the
798 remote user's password.</para>
799 </listitem></itemizedlist>
800 <para id="x_4a6">In summary, if you're having trouble talking to the
801 server's ssh daemon, first make sure that one is running at
802 all. On many systems it will be installed, but disabled, by
803 default. Once you're done with this step, you should then
804 check that the server's firewall is configured to allow
805 incoming connections on the port the ssh daemon is listening
806 on (usually 22). Don't worry about more exotic possibilities
807 for misconfiguration until you've checked these two
808 first.</para>
809 <!-- TODO : part 2/4 -->
810 <para id="x_4a7">If you're using an authentication agent on the client side
811 to store passphrases for your keys, you ought to be able to
812 log into the server without being prompted for a passphrase or
813 a password. If you're prompted for a passphrase, there are a
814 few possible culprits.</para>
815 <itemizedlist>
816 <listitem><para id="x_4a8">You might have forgotten to use
817 <command>ssh-add</command> or <command>pageant</command>
818 to store the passphrase.</para>
819 </listitem>
820 <listitem><para id="x_4a9">You might have stored the passphrase for the
821 wrong key.</para>
822 </listitem></itemizedlist>
823 <para id="x_4aa">If you're being prompted for the remote user's password,
824 there are another few possible problems to check.</para>
825 <itemizedlist>
826 <listitem><para id="x_4ab">Either the user's home directory or their
827 <filename role="special" class="directory">.ssh</filename>
828 directory might have excessively liberal permissions. As
829 a result, the ssh daemon will not trust or read their
830 <filename role="special">authorized_keys</filename> file.
831 For example, a group-writable home or <filename
832 role="special" class="directory">.ssh</filename>
833 directory will often cause this symptom.</para>
834 </listitem>
835 <listitem><para id="x_4ac">The user's <filename
836 role="special">authorized_keys</filename> file may have
837 a problem. If anyone other than the user owns or can write
838 to that file, the ssh daemon will not trust or read
839 it.</para>
840 </listitem></itemizedlist>
842 <para id="x_4ad">In the ideal world, you should be able to run the
843 following command successfully, and it should print exactly
844 one line of output, the current date and time.</para>
845 <programlisting>ssh myserver date</programlisting>
847 <para id="x_4ae">If, on your server, you have login scripts that print
848 banners or other junk even when running non-interactive
849 commands like this, you should fix them before you continue,
850 so that they only print output if they're run interactively.
851 Otherwise these banners will at least clutter up Mercurial's
852 output. Worse, they could potentially cause problems with
853 running Mercurial commands remotely. Mercurial tries to
854 detect and ignore banners in non-interactive
855 <command>ssh</command> sessions, but it is not foolproof. (If
856 you're editing your login scripts on your server, the usual
857 way to see if a login script is running in an interactive
858 shell is to check the return code from the command
859 <literal>tty -s</literal>.)</para>
861 <para id="x_4af">Once you've verified that plain old ssh is working with
862 your server, the next step is to ensure that Mercurial runs on
863 the server. The following command should run
864 successfully:</para>
866 <programlisting>ssh myserver hg version</programlisting>
868 <para id="x_4b0">If you see an error message instead of normal <command
869 role="hg-cmd">hg version</command> output, this is usually
870 because you haven't installed Mercurial to <filename
871 class="directory">/usr/bin</filename>. Don't worry if this
872 is the case; you don't need to do that. But you should check
873 for a few possible problems.</para>
874 <itemizedlist>
875 <listitem><para id="x_4b1">Is Mercurial really installed on the server at
876 all? I know this sounds trivial, but it's worth
877 checking!</para>
878 </listitem>
879 <listitem><para id="x_4b2">Maybe your shell's search path (usually set
880 via the <envar>PATH</envar> environment variable) is
881 simply misconfigured.</para>
882 </listitem>
883 <listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment
884 variable is only being set to point to the location of the
885 <command>hg</command> executable if the login session is
886 interactive. This can happen if you're setting the path
887 in the wrong shell login script. See your shell's
888 documentation for details.</para>
889 </listitem>
890 <listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment
891 variable may need to contain the path to the Mercurial
892 Python modules. It might not be set at all; it could be
893 incorrect; or it may be set only if the login is
894 interactive.</para>
895 </listitem></itemizedlist>
897 <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command>
898 over an ssh connection, well done! You've got the server and
899 client sorted out. You should now be able to use Mercurial to
900 access repositories hosted by that username on that server.
901 If you run into problems with Mercurial and ssh at this point,
902 try using the <option role="hg-opt-global">--debug</option>
903 option to get a clearer picture of what's going on.</para>
904 </sect2>
905 <sect2>
906 <title>Using compression with ssh</title>
908 <para id="x_4b6">Mercurial does not compress data when it uses the ssh
909 protocol, because the ssh protocol can transparently compress
910 data. However, the default behavior of ssh clients is
911 <emphasis>not</emphasis> to request compression.</para>
913 <para id="x_4b7">Over any network other than a fast LAN (even a wireless
914 network), using compression is likely to significantly speed
915 up Mercurial's network operations. For example, over a WAN,
916 someone measured compression as reducing the amount of time
917 required to clone a particularly large repository from 51
918 minutes to 17 minutes.</para>
920 <para id="x_4b8">Both <command>ssh</command> and <command>plink</command>
921 accept a <option role="cmd-opt-ssh">-C</option> option which
922 turns on compression. You can easily edit your <filename
923 role="special">~/.hgrc</filename> to enable compression for
924 all of Mercurial's uses of the ssh protocol. Here is how to
925 do so for regular <command>ssh</command> on Unix-like systems,
926 for example.</para>
927 <programlisting>[ui]
928 ssh = ssh -C</programlisting>
930 <para id="x_4b9">If you use <command>ssh</command> on a
931 Unix-like system, you can configure it to always use
932 compression when talking to your server. To do this, edit
933 your <filename role="special">.ssh/config</filename> file
934 (which may not yet exist), as follows.</para>
936 <programlisting>Host hg
937 Compression yes
938 HostName hg.example.com</programlisting>
940 <para id="x_4ba">This defines a hostname alias,
941 <literal>hg</literal>. When you use that hostname on the
942 <command>ssh</command> command line or in a Mercurial
943 <literal>ssh</literal>-protocol URL, it will cause
944 <command>ssh</command> to connect to
945 <literal>hg.example.com</literal> and use compression. This
946 gives you both a shorter name to type and compression, each of
947 which is a good thing in its own right.</para>
948 </sect2>
949 </sect1>
951 <sect1 id="sec:collab:cgi">
952 <title>Serving over HTTP using CGI</title>
954 <para id="x_6a8">The simplest way to host one or more repositories in a
955 permanent way is to use a web server and Mercurial's CGI
956 support.</para>
958 <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
959 CGI interface can take anything from a few moments to several
960 hours.</para>
962 <para id="x_4bc">We'll begin with the simplest of examples, and work our way
963 towards a more complex configuration. Even for the most basic
964 case, you're almost certainly going to need to read and modify
965 your web server's configuration.</para>
967 <note>
968 <title>High pain tolerance required</title>
970 <para id="x_4bd">Configuring a web server is a complex, fiddly,
971 and highly system-dependent activity. I can't possibly give
972 you instructions that will cover anything like all of the
973 cases you will encounter. Please use your discretion and
974 judgment in following the sections below. Be prepared to make
975 plenty of mistakes, and to spend a lot of time reading your
976 server's error logs.</para>
978 <para id="x_6a9">If you don't have a strong stomach for tweaking
979 configurations over and over, or a compelling need to host
980 your own services, you might want to try one of the public
981 hosting services that I mentioned earlier.</para>
982 </note>
984 <sect2>
985 <title>Web server configuration checklist</title>
987 <para id="x_4be">Before you continue, do take a few moments to check a few
988 aspects of your system's setup.</para>
990 <orderedlist>
991 <listitem><para id="x_4bf">Do you have a web server installed
992 at all? Mac OS X and some Linux distributions ship with
993 Apache, but many other systems may not have a web server
994 installed.</para>
995 </listitem>
996 <listitem><para id="x_4c0">If you have a web server installed, is it
997 actually running? On most systems, even if one is
998 present, it will be disabled by default.</para>
999 </listitem>
1000 <listitem><para id="x_4c1">Is your server configured to allow you to run
1001 CGI programs in the directory where you plan to do so?
1002 Most servers default to explicitly disabling the ability
1003 to run CGI programs.</para>
1004 </listitem></orderedlist>
1006 <para id="x_4c2">If you don't have a web server installed, and don't have
1007 substantial experience configuring Apache, you should consider
1008 using the <literal>lighttpd</literal> web server instead of
1009 Apache. Apache has a well-deserved reputation for baroque and
1010 confusing configuration. While <literal>lighttpd</literal> is
1011 less capable in some ways than Apache, most of these
1012 capabilities are not relevant to serving Mercurial
1013 repositories. And <literal>lighttpd</literal> is undeniably
1014 <emphasis>much</emphasis> easier to get started with than
1015 Apache.</para>
1016 </sect2>
1018 <sect2>
1019 <title>Basic CGI configuration</title>
1021 <para id="x_4c3">On Unix-like systems, it's common for users to have a
1022 subdirectory named something like <filename
1023 class="directory">public_html</filename> in their home
1024 directory, from which they can serve up web pages. A file
1025 named <filename>foo</filename> in this directory will be
1026 accessible at a URL of the form
1027 <literal>http://www.example.com/username/foo</literal>.</para>
1029 <para id="x_4c4">To get started, find the <filename
1030 role="special">hgweb.cgi</filename> script that should be
1031 present in your Mercurial installation. If you can't quickly
1032 find a local copy on your system, simply download one from the
1033 master Mercurial repository at <ulink
1034 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>
1036 <para id="x_4c5">You'll need to copy this script into your <filename
1037 class="directory">public_html</filename> directory, and
1038 ensure that it's executable.</para>
1039 <programlisting>cp .../hgweb.cgi ~/public_html
1040 chmod 755 ~/public_html/hgweb.cgi</programlisting>
1041 <para id="x_4c6">The <literal>755</literal> argument to
1042 <command>chmod</command> is a little more general than just
1043 making the script executable: it ensures that the script is
1044 executable by anyone, and that <quote>group</quote> and
1045 <quote>other</quote> write permissions are
1046 <emphasis>not</emphasis> set. If you were to leave those
1047 write permissions enabled, Apache's <literal>suexec</literal>
1048 subsystem would likely refuse to execute the script. In fact,
1049 <literal>suexec</literal> also insists that the
1050 <emphasis>directory</emphasis> in which the script resides
1051 must not be writable by others.</para>
1052 <programlisting>chmod 755 ~/public_html</programlisting>
1054 <sect3 id="sec:collab:wtf">
1055 <title>What could <emphasis>possibly</emphasis> go
1056 wrong?</title>
1058 <para id="x_4c7">Once you've copied the CGI script into place,
1059 go into a web browser, and try to open the URL
1060 <literal>http://myhostname/~myuser/hgweb.cgi</literal>,
1061 <emphasis>but</emphasis> brace yourself for instant failure.
1062 There's a high probability that trying to visit this URL
1063 will fail, and there are many possible reasons for this. In
1064 fact, you're likely to stumble over almost every one of the
1065 possible errors below, so please read carefully. The
1066 following are all of the problems I ran into on a system
1067 running Fedora 7, with a fresh installation of Apache, and a
1068 user account that I created specially to perform this
1069 exercise.</para>
1071 <para id="x_4c8">Your web server may have per-user directories disabled.
1072 If you're using Apache, search your config file for a
1073 <literal>UserDir</literal> directive. If there's none
1074 present, per-user directories will be disabled. If one
1075 exists, but its value is <literal>disabled</literal>, then
1076 per-user directories will be disabled. Otherwise, the
1077 string after <literal>UserDir</literal> gives the name of
1078 the subdirectory that Apache will look in under your home
1079 directory, for example <filename
1080 class="directory">public_html</filename>.</para>
1082 <para id="x_4c9">Your file access permissions may be too restrictive.
1083 The web server must be able to traverse your home directory
1084 and directories under your <filename
1085 class="directory">public_html</filename> directory, and
1086 read files under the latter too. Here's a quick recipe to
1087 help you to make your permissions more appropriate.</para>
1088 <programlisting>chmod 755 ~
1089 find ~/public_html -type d -print0 | xargs -0r chmod 755
1090 find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting>
1092 <para id="x_4ca">The other possibility with permissions is that you might
1093 get a completely empty window when you try to load the
1094 script. In this case, it's likely that your access
1095 permissions are <emphasis>too permissive</emphasis>. Apache's
1096 <literal>suexec</literal> subsystem won't execute a script
1097 that's group- or world-writable, for example.</para>
1099 <para id="x_4cb">Your web server may be configured to disallow execution
1100 of CGI programs in your per-user web directory. Here's
1101 Apache's default per-user configuration from my Fedora
1102 system.</para>
1104 &ch06-apache-config.lst;
1106 <para id="x_4cc">If you find a similar-looking
1107 <literal>Directory</literal> group in your Apache
1108 configuration, the directive to look at inside it is
1109 <literal>Options</literal>. Add <literal>ExecCGI</literal>
1110 to the end of this list if it's missing, and restart the web
1111 server.</para>
1113 <para id="x_4cd">If you find that Apache serves you the text of the CGI
1114 script instead of executing it, you may need to either
1115 uncomment (if already present) or add a directive like
1116 this.</para>
1117 <programlisting>AddHandler cgi-script .cgi</programlisting>
1119 <para id="x_4ce">The next possibility is that you might be served with a
1120 colourful Python backtrace claiming that it can't import a
1121 <literal>mercurial</literal>-related module. This is
1122 actually progress! The server is now capable of executing
1123 your CGI script. This error is only likely to occur if
1124 you're running a private installation of Mercurial, instead
1125 of a system-wide version. Remember that the web server runs
1126 the CGI program without any of the environment variables
1127 that you take for granted in an interactive session. If
1128 this error happens to you, edit your copy of <filename
1129 role="special">hgweb.cgi</filename> and follow the
1130 directions inside it to correctly set your
1131 <envar>PYTHONPATH</envar> environment variable.</para>
1133 <para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be
1134 served with another colourful Python backtrace: this one
1135 will complain that it can't find <filename
1136 class="directory">/path/to/repository</filename>. Edit
1137 your <filename role="special">hgweb.cgi</filename> script
1138 and replace the <filename
1139 class="directory">/path/to/repository</filename> string
1140 with the complete path to the repository you want to serve
1141 up.</para>
1143 <para id="x_4d0">At this point, when you try to reload the page, you
1144 should be presented with a nice HTML view of your
1145 repository's history. Whew!</para>
1146 </sect3>
1148 <sect3>
1149 <title>Configuring lighttpd</title>
1151 <para id="x_4d1">To be exhaustive in my experiments, I tried configuring
1152 the increasingly popular <literal>lighttpd</literal> web
1153 server to serve the same repository as I described with
1154 Apache above. I had already overcome all of the problems I
1155 outlined with Apache, many of which are not server-specific.
1156 As a result, I was fairly sure that my file and directory
1157 permissions were good, and that my <filename
1158 role="special">hgweb.cgi</filename> script was properly
1159 edited.</para>
1161 <para id="x_4d2">Once I had Apache running, getting
1162 <literal>lighttpd</literal> to serve the repository was a
1163 snap (in other words, even if you're trying to use
1164 <literal>lighttpd</literal>, you should read the Apache
1165 section). I first had to edit the
1166 <literal>mod_access</literal> section of its config file to
1167 enable <literal>mod_cgi</literal> and
1168 <literal>mod_userdir</literal>, both of which were disabled
1169 by default on my system. I then added a few lines to the
1170 end of the config file, to configure these modules.</para>
1171 <programlisting>userdir.path = "public_html"
1172 cgi.assign = (".cgi" => "" )</programlisting>
1173 <para id="x_4d3">With this done, <literal>lighttpd</literal> ran
1174 immediately for me. If I had configured
1175 <literal>lighttpd</literal> before Apache, I'd almost
1176 certainly have run into many of the same system-level
1177 configuration problems as I did with Apache. However, I
1178 found <literal>lighttpd</literal> to be noticeably easier to
1179 configure than Apache, even though I've used Apache for over
1180 a decade, and this was my first exposure to
1181 <literal>lighttpd</literal>.</para>
1182 </sect3>
1183 </sect2>
1184 <!-- TODO : part 3/4 -->
1185 <sect2>
1186 <title>Sharing multiple repositories with one CGI script</title>
1188 <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script
1189 only lets you publish a single repository, which is an
1190 annoying restriction. If you want to publish more than one
1191 without wracking yourself with multiple copies of the same
1192 script, each with different names, a better choice is to use
1193 the <filename role="special">hgwebdir.cgi</filename>
1194 script.</para>
1196 <para id="x_4d5">The procedure to configure <filename
1197 role="special">hgwebdir.cgi</filename> is only a little more
1198 involved than for <filename
1199 role="special">hgweb.cgi</filename>. First, you must obtain
1200 a copy of the script. If you don't have one handy, you can
1201 download a copy from the master Mercurial repository at <ulink
1202 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>
1204 <para id="x_4d6">You'll need to copy this script into your <filename
1205 class="directory">public_html</filename> directory, and
1206 ensure that it's executable.</para>
1208 <programlisting>cp .../hgwebdir.cgi ~/public_html
1209 chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
1211 <para id="x_4d7">With basic configuration out of the way, try to
1212 visit <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>
1213 in your browser. It should
1214 display an empty list of repositories. If you get a blank
1215 window or error message, try walking through the list of
1216 potential problems in <xref
1217 linkend="sec:collab:wtf"/>.</para>
1219 <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename>
1220 script relies on an external configuration file. By default,
1221 it searches for a file named <filename
1222 role="special">hgweb.config</filename> in the same directory
1223 as itself. You'll need to create this file, and make it
1224 world-readable. The format of the file is similar to a
1225 Windows <quote>ini</quote> file, as understood by Python's
1226 <literal>ConfigParser</literal>
1227 <citation>web:configparser</citation> module.</para>
1229 <para id="x_4d9">The easiest way to configure <filename
1230 role="special">hgwebdir.cgi</filename> is with a section
1231 named <literal>collections</literal>. This will automatically
1232 publish <emphasis>every</emphasis> repository under the
1233 directories you name. The section should look like
1234 this:</para>
1235 <programlisting>[collections]
1236 /my/root = /my/root</programlisting>
1237 <para id="x_4da">Mercurial interprets this by looking at the directory name
1238 on the <emphasis>right</emphasis> hand side of the
1239 <quote><literal>=</literal></quote> sign; finding repositories
1240 in that directory hierarchy; and using the text on the
1241 <emphasis>left</emphasis> to strip off matching text from the
1242 names it will actually list in the web interface. The
1243 remaining component of a path after this stripping has
1244 occurred is called a <quote>virtual path</quote>.</para>
1246 <para id="x_4db">Given the example above, if we have a
1247 repository whose local path is <filename
1248 class="directory">/my/root/this/repo</filename>, the CGI
1249 script will strip the leading <filename
1250 class="directory">/my/root</filename> from the name, and
1251 publish the repository with a virtual path of <filename
1252 class="directory">this/repo</filename>. If the base URL for
1253 our CGI script is
1254 <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>, the
1255 complete URL for that repository will be
1256 <literal>http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para>
1258 <para id="x_4dc">If we replace <filename
1259 class="directory">/my/root</filename> on the left hand side
1260 of this example with <filename
1261 class="directory">/my</filename>, then <filename
1262 role="special">hgwebdir.cgi</filename> will only strip off
1263 <filename class="directory">/my</filename> from the repository
1264 name, and will give us a virtual path of <filename
1265 class="directory">root/this/repo</filename> instead of
1266 <filename class="directory">this/repo</filename>.</para>
1268 <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename>
1269 script will recursively search each directory listed in the
1270 <literal>collections</literal> section of its configuration
1271 file, but it will <literal>not</literal> recurse into the
1272 repositories it finds.</para>
1274 <para id="x_4de">The <literal>collections</literal> mechanism makes it easy
1275 to publish many repositories in a <quote>fire and
1276 forget</quote> manner. You only need to set up the CGI
1277 script and configuration file one time. Afterwards, you can
1278 publish or unpublish a repository at any time by simply moving
1279 it into, or out of, the directory hierarchy in which you've
1280 configured <filename role="special">hgwebdir.cgi</filename> to
1281 look.</para>
1283 <sect3>
1284 <title>Explicitly specifying which repositories to
1285 publish</title>
1287 <para id="x_4df">In addition to the <literal>collections</literal>
1288 mechanism, the <filename
1289 role="special">hgwebdir.cgi</filename> script allows you
1290 to publish a specific list of repositories. To do so,
1291 create a <literal>paths</literal> section, with contents of
1292 the following form.</para>
1293 <programlisting>[paths]
1294 repo1 = /my/path/to/some/repo
1295 repo2 = /some/path/to/another</programlisting>
1296 <para id="x_4e0">In this case, the virtual path (the component that will
1297 appear in a URL) is on the left hand side of each
1298 definition, while the path to the repository is on the
1299 right. Notice that there does not need to be any
1300 relationship between the virtual path you choose and the
1301 location of a repository in your filesystem.</para>
1303 <para id="x_4e1">If you wish, you can use both the
1304 <literal>collections</literal> and <literal>paths</literal>
1305 mechanisms simultaneously in a single configuration
1306 file.</para>
1308 <note>
1309 <title>Beware duplicate virtual paths</title>
1311 <para id="x_4e2"> If several repositories have the same
1312 virtual path, <filename
1313 role="special">hgwebdir.cgi</filename> will not report
1314 an error. Instead, it will behave unpredictably.</para>
1315 </note>
1316 </sect3>
1317 </sect2>
1319 <sect2>
1320 <title>Downloading source archives</title>
1322 <para id="x_4e3">Mercurial's web interface lets users download an archive
1323 of any revision. This archive will contain a snapshot of the
1324 working directory as of that revision, but it will not contain
1325 a copy of the repository data.</para>
1327 <para id="x_4e4">By default, this feature is not enabled. To enable it,
1328 you'll need to add an <envar
1329 role="rc-item-web">allow_archive</envar> item to the
1330 <literal role="rc-web">web</literal> section of your <filename
1331 role="special">~/.hgrc</filename>; see below for details.</para>
1332 </sect2>
1333 <sect2>
1334 <title>Web configuration options</title>
1336 <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg
1337 serve</command> command, and the <filename
1338 role="special">hgweb.cgi</filename> and <filename
1339 role="special">hgwebdir.cgi</filename> scripts) have a
1340 number of configuration options that you can set. These
1341 belong in a section named <literal
1342 role="rc-web">web</literal>.</para>
1343 <itemizedlist>
1344 <listitem><para id="x_4e6"><envar
1345 role="rc-item-web">allow_archive</envar>: Determines
1346 which (if any) archive download mechanisms Mercurial
1347 supports. If you enable this feature, users of the web
1348 interface will be able to download an archive of whatever
1349 revision of a repository they are viewing. To enable the
1350 archive feature, this item must take the form of a
1351 sequence of words drawn from the list below.</para>
1352 <itemizedlist>
1353 <listitem><para id="x_4e7"><literal>bz2</literal>: A
1354 <command>tar</command> archive, compressed using
1355 <literal>bzip2</literal> compression. This has the
1356 best compression ratio, but uses the most CPU time on
1357 the server.</para>
1358 </listitem>
1359 <listitem><para id="x_4e8"><literal>gz</literal>: A
1360 <command>tar</command> archive, compressed using
1361 <literal>gzip</literal> compression.</para>
1362 </listitem>
1363 <listitem><para id="x_4e9"><literal>zip</literal>: A
1364 <command>zip</command> archive, compressed using LZW
1365 compression. This format has the worst compression
1366 ratio, but is widely used in the Windows world.</para>
1367 </listitem>
1368 </itemizedlist>
1369 <para id="x_4ea"> If you provide an empty list, or don't have an
1370 <envar role="rc-item-web">allow_archive</envar> entry at
1371 all, this feature will be disabled. Here is an example of
1372 how to enable all three supported formats.</para>
1373 <programlisting>[web]
1374 allow_archive = bz2 gz zip</programlisting>
1375 </listitem>
1376 <listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>:
1377 Boolean. Determines whether the web interface allows
1378 remote users to <command role="hg-cmd">hg pull</command>
1379 and <command role="hg-cmd">hg clone</command> this
1380 repository over HTTP. If set to <literal>no</literal> or
1381 <literal>false</literal>, only the
1382 <quote>human-oriented</quote> portion of the web interface
1383 is available.</para>
1384 </listitem>
1385 <listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>:
1386 String. A free-form (but preferably brief) string
1387 identifying the person or group in charge of the
1388 repository. This often contains the name and email
1389 address of a person or mailing list. It often makes sense
1390 to place this entry in a repository's own <filename
1391 role="special">.hg/hgrc</filename> file, but it can make
1392 sense to use in a global <filename
1393 role="special">~/.hgrc</filename> if every repository
1394 has a single maintainer.</para>
1395 </listitem>
1396 <listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>:
1397 Integer. The default maximum number of changesets to
1398 display in a single page of output.</para>
1399 </listitem>
1400 <listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>:
1401 Integer. The default maximum number of modified files to
1402 display in a single page of output.</para>
1403 </listitem>
1404 <listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>:
1405 Integer. If the web interface displays alternating
1406 <quote>stripes</quote> to make it easier to visually align
1407 rows when you are looking at a table, this number controls
1408 the number of rows in each stripe.</para>
1409 </listitem>
1410 <listitem><para id="x_4f0"><envar
1411 role="rc-item-web">style</envar>: Controls the template
1412 Mercurial uses to display the web interface. Mercurial
1413 ships with several web templates.</para>
1414 <itemizedlist>
1415 <listitem>
1416 <para id="x_6aa"><literal>coal</literal> is monochromatic.</para>
1417 </listitem>
1418 <listitem>
1419 <para id="x_6ab"><literal>gitweb</literal> emulates the visual
1420 style of git's web interface.</para>
1421 </listitem>
1422 <listitem>
1423 <para id="x_6ac"><literal>monoblue</literal> uses solid blues and
1424 greys.</para>
1425 </listitem>
1426 <listitem>
1427 <para id="x_6ad"><literal>paper</literal> is the default.</para>
1428 </listitem>
1429 <listitem>
1430 <para id="x_6ae"><literal>spartan</literal> was the default for a
1431 long time.</para>
1432 </listitem>
1433 </itemizedlist>
1434 <para id="x_6af">You can
1435 also specify a custom template of your own; see
1436 <xref linkend="chap:template"/> for details. Here, you can
1437 see how to enable the <literal>gitweb</literal>
1438 style.</para>
1439 <programlisting>[web]
1440 style = gitweb</programlisting>
1441 </listitem>
1442 <listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>:
1443 Path. The directory in which to search for template
1444 files. By default, Mercurial searches in the directory in
1445 which it was installed.</para>
1446 </listitem></itemizedlist>
1447 <para id="x_4f2">If you are using <filename
1448 role="special">hgwebdir.cgi</filename>, you can place a few
1449 configuration items in a <literal role="rc-web">web</literal>
1450 section of the <filename
1451 role="special">hgweb.config</filename> file instead of a
1452 <filename role="special">~/.hgrc</filename> file, for
1453 convenience. These items are <envar
1454 role="rc-item-web">motd</envar> and <envar
1455 role="rc-item-web">style</envar>.</para>
1457 <sect3>
1458 <title>Options specific to an individual repository</title>
1460 <para id="x_4f3">A few <literal role="rc-web">web</literal> configuration
1461 items ought to be placed in a repository's local <filename
1462 role="special">.hg/hgrc</filename>, rather than a user's
1463 or global <filename role="special">~/.hgrc</filename>.</para>
1464 <itemizedlist>
1465 <listitem><para id="x_4f4"><envar
1466 role="rc-item-web">description</envar>: String. A
1467 free-form (but preferably brief) string that describes
1468 the contents or purpose of the repository.</para>
1469 </listitem>
1470 <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>:
1471 String. The name to use for the repository in the web
1472 interface. This overrides the default name, which is
1473 the last component of the repository's path.</para>
1474 </listitem></itemizedlist>
1475 </sect3>
1477 <sect3>
1478 <title>Options specific to the <command role="hg-cmd">hg
1479 serve</command> command</title>
1481 <para id="x_4f6">Some of the items in the <literal
1482 role="rc-web">web</literal> section of a <filename
1483 role="special">~/.hgrc</filename> file are only for use
1484 with the <command role="hg-cmd">hg serve</command>
1485 command.</para>
1486 <itemizedlist>
1487 <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>:
1488 Path. The name of a file into which to write an access
1489 log. By default, the <command role="hg-cmd">hg
1490 serve</command> command writes this information to
1491 standard output, not to a file. Log entries are written
1492 in the standard <quote>combined</quote> file format used
1493 by almost all web servers.</para>
1494 </listitem>
1495 <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>:
1496 String. The local address on which the server should
1497 listen for incoming connections. By default, the server
1498 listens on all addresses.</para>
1499 </listitem>
1500 <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>:
1501 Path. The name of a file into which to write an error
1502 log. By default, the <command role="hg-cmd">hg
1503 serve</command> command writes this information to
1504 standard error, not to a file.</para>
1505 </listitem>
1506 <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>:
1507 Boolean. Whether to use the IPv6 protocol. By default,
1508 IPv6 is not used.</para>
1509 </listitem>
1510 <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>:
1511 Integer. The TCP port number on which the server should
1512 listen. The default port number used is 8000.</para>
1513 </listitem></itemizedlist>
1514 </sect3>
1516 <sect3>
1517 <title>Choosing the right <filename
1518 role="special">~/.hgrc</filename> file to add <literal
1519 role="rc-web">web</literal> items to</title>
1521 <para id="x_4fc">It is important to remember that a web server like
1522 Apache or <literal>lighttpd</literal> will run under a user
1523 ID that is different to yours. CGI scripts run by your
1524 server, such as <filename
1525 role="special">hgweb.cgi</filename>, will usually also run
1526 under that user ID.</para>
1528 <para id="x_4fd">If you add <literal role="rc-web">web</literal> items to
1529 your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that
1530 <filename role="special">~/.hgrc</filename> file. Those
1531 settings will thus only affect the behavior of the <command
1532 role="hg-cmd">hg serve</command> command when you run it.
1533 To cause CGI scripts to see your settings, either create a
1534 <filename role="special">~/.hgrc</filename> file in the
1535 home directory of the user ID that runs your web server, or
1536 add those settings to a system-wide <filename
1537 role="special">hgrc</filename> file.</para>
1538 </sect3>
1539 </sect2>
1540 </sect1>
1542 <sect1>
1543 <title>System-wide configuration</title>
1545 <para id="x_6b0">On Unix-like systems shared by multiple users (such as a
1546 server to which people publish changes), it often makes sense to
1547 set up some global default behaviors, such as what theme to use
1548 in web interfaces.</para>
1550 <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename>
1551 exists, Mercurial will read it at startup time and apply any
1552 configuration settings it finds in that file. It will also look
1553 for files ending in a <literal>.rc</literal> extension in a
1554 directory named <filename>/etc/mercurial/hgrc.d</filename>, and
1555 apply any configuration settings it finds in each of those
1556 files.</para>
1558 <sect2>
1559 <title>Making Mercurial more trusting</title>
1561 <para id="x_6b2">One situation in which a global <filename>hgrc</filename>
1562 can be useful is if users are pulling changes owned by other
1563 users. By default, Mercurial will not trust most of the
1564 configuration items in a <filename>.hg/hgrc</filename> file
1565 inside a repository that is owned by a different user. If we
1566 clone or pull changes from such a repository, Mercurial will
1567 print a warning stating that it does not trust their
1568 <filename>.hg/hgrc</filename>.</para>
1570 <para id="x_6b3">If everyone in a particular Unix group is on the same team
1571 and <emphasis>should</emphasis> trust each other's
1572 configuration settings, or we want to trust particular users,
1573 we can override Mercurial's skeptical defaults by creating a
1574 system-wide <filename>hgrc</filename> file such as the
1575 following:</para>
1577 <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
1578 [trusted]
1579 # Trust all entries in any hgrc file owned by the "editors" or
1580 # "www-data" groups.
1581 groups = editors, www-data
1583 # Trust entries in hgrc files owned by the following users.
1584 users = apache, bobo
1585 </programlisting>
1586 </sect2>
1587 </sect1>
1588 </chapter>
1589 <!-- TODO : part 4/4 -->
1590 <!--
1591 local variables:
1592 sgml-parent-document: ("00book.xml" "book" "chapter")
1593 end:
1594 -->