hgbook
view fr/ch06-collab.xml @ 1010:cd06c45e1631
French translation : ch06-collab.xml - about 50% translated
| author | Frédéric Bouquet <youshe.jaalon@gmail.com> |
|---|---|
| date | Mon Sep 21 00:02:10 2009 +0200 (2009-09-21) |
| parents | 304c6a1758ae |
| children | 746a888fb41b |
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>
446 <sect2>
447 <title>Collaboration pull seulement versus pull partagé</title>
449 <para id="x_476">Une source perpétuelle de heurs dans une communauté
450 opensource est si un modèle de développement est celui où les
451 personnes ne peuvent que récupérer (pull) les changements ou l'autre
452 <quote>meilleur</quote> dans lequel de multiples personnes peuvent
453 envoyer (push) leurs changements vers un dépôt partagé.</para>
455 <para id="x_477">Typiquement, les bailleurs de fonds du modèle push
456 partagé utilisent des outils qui renforcent activement cette
457 approche. Si vous utilisez un outil centralisé de gestion de révision
458 comme Subversion, il n'y a pas la possibilité de choisir quel modèle
459 utiliser : l'outil vous fournit un push partagé, et si vous voulez
460 faire quelque chose d'autre, vous avez à changer votre propre
461 approche à la base (comme appliquer les patchs manuellement).</para>
463 <para id="x_478">Un bon outil de gestion distribuée de révisions doit
464 supporter les deux modèles. Vous et vos collaborateurs pouvez ensuite
465 structurer la façon dont vous travaillez ensemble en vous basant sur
466 vos besoins et vos préférences, et non sur les contortions que vos
467 outils vous forcent à effectuer.</para>
468 </sect2>
469 <sect2>
470 <title>Lorsque la collaboration rencontre la gestion de branches</title>
472 <para id="x_479">Lorsque vous et votre équipe configurez des dépôts
473 partagés et commencez à propager vos changement dans tous les sens
474 entre les dépôts locaux et partagés, vous commencez à être face à un
475 challenge apparenté, mais un peu différent : celui de gérer les
476 multiples directions vers lesquelles votre équipe pourrait aller au
477 même moment. Même si ce sujet est intimement lié à la façon dont
478 votre équipe collabore, il est suffisement dence pour mériter un
479 traitement à part dans <xref linkend="chap:branch"/>.</para>
480 </sect2>
481 </sect1>
483 <sect1>
484 <title>Le coté technique du partage</title>
486 <para id="x_47a">Le reste de ce chapitre est dévoué à la question du
487 partage des changements avec vos collaborateurs.</para>
488 </sect1>
490 <sect1 id="sec:collab:serve">
491 <title>Partage informel avec <command role="hg-cmd">hg
492 serve</command></title>
494 <para id="x_47b">La commande <command role="hg-cmd">hg serve</command> de
495 Mercurial est magnifiquement conçue pour un environnement de petit
496 groupe, soudé et rapide. Elle fournit aussi un très bon moyen d'avoir
497 un sentiment de l'utilisation des commandes Meruciral sur un
498 réseau.</para>
500 <para id="x_47c">Exécutez <command role="hg-cmd">hg serve</command> à
501 l'intérieur d'un dépôtn et en moins d'une seconde, cela mettra en place
502 un serveur HTTP spécialisé ; qui va accepter les connexions de tout
503 client, et servir les donnée pour ce dépôt jusqu'à ce que vous le
504 terminiez. Toute personne qui connaît l'URL du serveur que vous venez
505 de démarrer, peut ensuite utiliser un navigateur web ou Mercurial pour
506 lire les données de ce dépôt. Une URL pour une instance exécutée de
507 <command role="hg-cmd">hg serve</command> sur un ordinateur portable
508 ressemblera vraissemblablement à
509 <literal>http://my-laptop.local:8000/</literal>.</para>
511 <para id="x_47d">La commande <command role="hg-cmd">hg serve</command>
512 <emphasis>n'</emphasis>est <emphasis>pas</emphasis> un serveur web
513 générique. Il ne peut faire que deux choses : </para>
514 <itemizedlist>
515 <listitem><para id="x_47e">Autoriser les personnes à explorer
516 l'historique du dépôt qu'il rend accessible, à partir d'un
517 navigateur web normal.</para>
518 </listitem>
519 <listitem><para id="x_47f">Discuter à travers le protocole de
520 communication de Mercurial, ainsi, les personnes peuvent exécuter <command
521 role="hg-cmd">hg clone</command> ou <command role="hg-cmd">hg
522 pull</command> sur les changements de ce dépôt.</para>
523 </listitem></itemizedlist>
524 <para id="x_480">En particulier, <command role="hg-cmd">hg serve</command>
525 ne permettra pas aux utilisateurs distants de
526 <emphasis>modifier</emphasis> votre dépôt. C'est destiné à une
527 utilisation en lecture seule.</para>
529 <para id="x_481">Si vous commencez avec Mercurial, il n'y a rien qui vous
530 empèche d'utiliser <command role="hg-cmd">hg serve</command> pour
531 publier un dépôt sur votre ordinateur, utilisez ensuite des commandes
532 telles que <command role="hg-cmd">hg clone</command>, <command
533 role="hg-cmd">hg incoming</command>, et ainsi de suite pour parler à
534 ce serveur comme si ce dépôt était hébergé à distance. Ceci peut vous
535 aider à rapidement familiarisé avec les commandes sur les dépôts
536 hébergés sur un réseau.</para>
538 <sect2>
539 <title>Quelques choses à garder à l'esprit</title>
541 <para id="x_482">Puisque ceci fournit un accès en lecture sans
542 authentification à tous les clients, vous devriez utiliser la
543 commande <command role="hg-cmd">hg serve</command> dans un
544 environnement dans lequel vous ne vous inquiétez pas ou où vous avez
545 tout contrôle sur qui peut avoir accès au réseau et récupérer les
546 données de votre dépôt.</para>
548 <para id="x_483">La commande <command role="hg-cmd">hg serve</command>
549 ne connaît sait rien sur un quelconque firewall que vous auriez
550 installé sur votre système ou réseau. Elle ne peut pas détecter ou
551 contrôler votre logiciel de pare-feu. Si d'autre personnes ont la
552 possibilité de dialoguer avec une instance de <command
553 role="hg-cmd">hg serve</command> ma seconde chose que vous devriez
554 faire (<emphasis>après</emphasis> être sûr qu'ils utilisent l'URL
555 correcte) est de vérifier la configuration de votre firewall.</para>
557 <para id="x_484">Par défaut, <command role="hg-cmd">hg serve</command>
558 écoute pour les connexions entrantes sur le port 8000. Si un autre
559 processus est déjà en train d'écouter sur le port que vous voulez
560 écouter, vous pouvez spécifier un port différent sur lequel écouter à
561 l'aide de l'option <option role="hg-opt-serve">-p</option>.</para>
563 <para id="x_485">Normalement, lorsque <command role="hg-cmd">hg
564 serve</command> se lance, il n'affiche aucune sortie, ce qui peut
565 être un peu énervant. Si vous voulez une confirmation que tout s'est
566 déroulé correctement, et connaître l'URL que vous devriez fournir à
567 vos collaborateurs, démarrez avec l'option <option
568 role="hg-opt-global">-v</option>.</para>
569 </sect2>
570 </sect1>
572 <sect1 id="sec:collab:ssh">
573 <title>Utiliser le protocole Secure Shell (ssh)</title>
575 <para id="x_486">Vous pouvez récupérer (pull) ou envoyer (push) des
576 changements de façon sécurisé au dessus d'une connexion utilisatnt le
577 protocole Secure Shell (<literal>ssh</literal>). Pour l'utiliser avec
578 succès, vous pouriez avoir à faire un peu de configuration du coté
579 client ou serveur.</para>
581 <para id="x_487">Si vous n'êtes pas familiers avec ssh, c'est le nom de
582 la commande et d'un protocole réseau qui vous permet d'établir une
583 communication sécurisée avec un autre ordinateur. Pour l'utiliser avec
584 Mercurial, vous allez configurer un ou plusieurs comptes utilisateur
585 sur un serveur, comme ça, les utilisateurs distants peuvent logger et
586 exécuter les commandes.</para>
588 <para id="x_488">(Si vous <emphasis>êtes</emphasis> familiers avec ssh,
589 vous allez probablement trouver quelques une des informations qui
590 suivent élémentaires par nature.)</para>
592 <sect2>
593 <title>Comment lire et écrire des URLs ssh</title>
595 <para id="x_489">Une URL ssh tent à ressembler à ceci :</para>
596 <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting>
597 <orderedlist>
598 <listitem><para id="x_48a">Le préfixe
599 <quote><literal>ssh://</literal></quote> dit à Mercurial
600 d'utiliser le protocole ssh.</para>
601 </listitem>
602 <listitem><para id="x_48b">Le composant
603 <quote><literal>bos@</literal></quote> indique que le nom
604 d'utilisateur à logger sur le serveur. Vous pouvez le laisser
605 vide si le nom d'utilisateur sur le serveur distant est le même
606 que localement.</para>
607 </listitem>
608 <listitem><para id="x_48c">La partie
609 <quote><literal>hg.serpentine.com</literal></quote> donne le nom
610 d'hôte du serveur sur lequel se logger.</para>
611 </listitem>
612 <listitem><para id="x_48d">Le <quote>:22</quote> identifie le numéro
613 de port où se connecter au serveur. Le port par défaut est 22,
614 donc vous n'avez besoin de spécifier ceci que si vous
615 <emphasis>n'</emphasis>utilisez <emphasis>pas</emphasis> le port
616 22.</para>
617 </listitem>
618 <listitem><para id="x_48e">Le reste de l'URL est le chemin local du
619 dépôt sur le serveur.</para></listitem></orderedlist>
621 <para id="x_48f">Il y a beaucoup de place pour la confusion sur le
622 chemin du composant d'une URL ssh puisqu'il n'y a pas de façon
623 standard pour les outils de l'intérpréter. Certains programmes se
624 comportent différemment des autres lorsqu'ils traient ces chemins. Il
625 ne s'agit pas d'une situation idéale, mais ce n'est pas prêt de
626 changer. Lisez SVP les prochains paragraphes avec attention.</para>
628 <para id="x_490">Mercurial traite le chemin vers un dépôt sur le
629 serveur comme relatif au répertoire personnel de l'utilisateur sur le
630 serveur distant. Par exemple, si un utilisateur
631 <literal>foo</literal> sur le serveur a un répertoire personnel
632 <filename class="directory">/home/foo</filename>, alors l'URL ssh qui
633 vientient un composant chemin de <filename
634 class="directory">bar</filename> réfère en
635 <emphasis>réalité</emphasis> au répertoire <filename
636 class="directory">/home/foo/bar</filename>.</para>
638 <para id="x_491">Si vous voulez spécifier un chemin relatif à au
639 répertoire personnel d'un autre utilisateur, vous pouvez préciser un
640 chemin qui commence à l'aide du caractère tilde suivit du nom de
641 l'utilisateur (appelons le <literal>otheruser</literal>),
642 ainsi.</para>
643 <programlisting>ssh://server/~otheruser/hg/repo</programlisting>
645 <para id="x_492">Et si vous voulez vraiment spécifier un chemin
646 <emphasis>absolu</emphasis> sur le serveur, débutez la composante
647 chemin par deux slashs comme dans cet exemple.</para>
648 <programlisting>ssh://server//absolute/path</programlisting>
649 </sect2>
651 <sect2>
652 <title>Trouver un client ssh pour votre système</title>
654 <para id="x_493">La plupart des systèmes du type Unix arrivent avec
655 OpenSSH préinstallé. Si vous utilisez un tel système, utilisez
656 <literal>which ssh</literal> pour trouver où la commande
657 <command>ssh</command> est installée (il s'agit généralement de
658 <filename class="directory">/usr/bin</filename>). Dans le cas peu
659 probable où il ne serait pas présent, regarder à la documentation de
660 votre système pour voir comment l'installer.</para>
662 <para id="x_494">Sous Windows, le packetage ToirtoiseHg est livré avec
663 une version de l'excellente commande <command>plink</command> de
664 Simon Tatham's, et ne devrait pas avoir besoin de plus de
665 configuration.</para>
666 </sect2>
668 <sect2>
669 <title>Générer une paire de clef</title>
671 <para id="x_499">Pour éviter d'avoir à chaque fois taper un mot de
672 passe lorsque vous utilisez votre client ssh, je recommande le fait
673 de générer une paire de clefs.</para>
675 <tip>
676 <title>Les paires de clefs ne sont pas obligatoires</title>
678 <para id="x_6a4">Mercurial ne sait rien du tout de l'authentification
679 de ssh ou de la paire de clefs. Vous pouvez, si vous le désirez,
680 ignorer sans risque cette section et ce qu'il suit jusqu'à ce que
681 vous soyez fatigué de constament retaper des mots de passe
682 ssh.</para>
683 </tip>
685 <itemizedlist>
686 <listitem> <para id="x_6a5">Sur un système de type Unix, la commande
687 <command>ssh-keygen</command> fera l'affaire.</para></listitem>
688 <listitem> <para id="x_6a6">Sous Windows, si vous utilisez
689 ToirtoiseHg, vous devriez avoir besoin de télécharger la commande
690 nommée <command>puttygen</command> à partir du <ulink
691 url="http://www.chiark.greenend.org.uk/~sgtatham/putty">site
692 web de PuTTY</ulink> pour générer une paire de clefs. Référez
693 vous à <ulink
694 url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">la
695 documentation <command>puttygen</command></ulink> pour les
696 détails sur l'utilisation de cette commande.</para></listitem>
697 </itemizedlist>
699 <para id="x_49a">Lorsque vous générez une paire de clefs, il est
700 habituellement <emphasis>autement</emphasis> recommendé de la
701 protéger avec un mot de passe. (Le seul moment où vous pourriez ne
702 pas devoir le faire est lorsque vous utilisez le protocole ssh pour
703 des tâches automatisées sur un réseau sécurisé.)</para>
705 <para id="x_49b">Le simple fait de générer une paire de clefs n'est
706 cependant pas suffisent. Vous aurez besoin d'ajouter la clef publique
707 à l'ensemble des clefs authorisées pour tout utilisateur que vous
708 utilisez pour vous connecter à distance. Pour les serveurs utilisant
709 OpenSSh (la grande majorité), ceci voudra dire d'ajouter la clef
710 publique à la liste dans un fichier appelé <filename
711 role="special">authorized_keys</filename> dans leur répertoire
712 <filename role="special" class="directory">.ssh</filename>.</para>
714 <para id="x_49c">Sur un système de type Unix, votre clef publique aura
715 l'extension <filename>.pub</filename>. Si vous utilisez la commande
716 <command>puttygen</command> sous Windows, vous pouvez sauvegarder la
717 clef publique dans un fichier que vous choisissez ou la copier à
718 partir de la fenêtre qui apparait directement dans le fichier
719 <filename role="special">authorized_keys</filename>.</para>
720 </sect2>
721 <sect2>
722 <title>Utiliser un agent d'authentification</title>
724 <para id="x_49d">Un agent d'authentification est un démon qui
725 enregistre les mots de passe en mémoire (il oublira ainsi les mots de
726 passe si vous vous déloggez et reloggez). Un client ssh sera averti
727 si un tel agent est en fonctionnement, et lui demandera un mot de
728 passe. S'il n'y a pas d'agent en fonctionnement, ou si l'agent ne
729 connaît pas le mot de passe nécessaire, vous aurez à taper votre mot
730 de passe chaque fois que Mercurial tente de communiquer avec un
731 serveur en votre nom (ex. lorsque vous faite un pull ou un push sur
732 des changements).</para>
734 <para id="x_49e">L'inconveignant de sauvegarder les mots de passes dans
735 un agent est qu'il est possible pour un attaquant bien préparé de
736 retrouver le mot de passe clair, dans certains cas, même si votre
737 système a été redémarré. Vous devriez vous faire votre propre
738 jugement pour savoir si ce risque est acceptable. Ceci vous exempte
739 certainement d'un tas de répétitions.</para>
741 <itemizedlist>
742 <listitem> <para id="x_49f">Sur les systèmes de type Unix, l'agent
743 est appelé <command>ssh-agent</command>, et est souvent lancé
744 automatiquement pour vous lorsque vous vous loggez. Vous aurez
745 besoin d'utiliser la commande <command>ssh-add</command> pour
746 ajouter des mots de passe à l'entrepôt de l'agent.</para>
747 </listitem>
748 <listitem>
749 <para id="x_6a7">Sous Windows, si vous utilisez ToirtoiseHg, la
750 commande <command>pageant</command> agit comme un agent. Comme
751 avec <command>puttygen</command>, vous aurez besoin de <ulink
752 url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">télécharger
753 <command>pageant</command></ulink> à partir du site web de
754 PuTTY et lire <ulink
755 url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">sa
756 documentation</ulink>. La commande <command>pageant</command>
757 ajoute une icône à votre barre de tâches qui vous permettra de
758 gérer les mots de passe stockés.</para></listitem>
759 <!-- TODO : J'ai traduit system tray par barre des tâches, mais ne
760 conaissant pas windows, je ne suis pas sûr du nom réel. A corriger
761 le cas échéant ! -->
762 </itemizedlist>
763 </sect2>
764 <!-- TODO : part 2/4 -->
765 <sect2>
766 <title>Configuring the server side properly</title>
768 <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
769 a variety of things can go wrong. Add Mercurial
770 on top, and there's plenty more scope for head-scratching.
771 Most of these potential problems occur on the server side, not
772 the client side. The good news is that once you've gotten a
773 configuration working, it will usually continue to work
774 indefinitely.</para>
776 <para id="x_4a1">Before you try using Mercurial to talk to an ssh server,
777 it's best to make sure that you can use the normal
778 <command>ssh</command> or <command>putty</command> command to
779 talk to the server first. If you run into problems with using
780 these commands directly, Mercurial surely won't work. Worse,
781 it will obscure the underlying problem. Any time you want to
782 debug ssh-related Mercurial problems, you should drop back to
783 making sure that plain ssh client commands work first,
784 <emphasis>before</emphasis> you worry about whether there's a
785 problem with Mercurial.</para>
787 <para id="x_4a2">The first thing to be sure of on the server side is that
788 you can actually log in from another machine at all. If you
789 can't use <command>ssh</command> or <command>putty</command>
790 to log in, the error message you get may give you a few hints
791 as to what's wrong. The most common problems are as
792 follows.</para>
793 <itemizedlist>
794 <listitem><para id="x_4a3">If you get a <quote>connection refused</quote>
795 error, either there isn't an SSH daemon running on the
796 server at all, or it's inaccessible due to firewall
797 configuration.</para>
798 </listitem>
799 <listitem><para id="x_4a4">If you get a <quote>no route to host</quote>
800 error, you either have an incorrect address for the server
801 or a seriously locked down firewall that won't admit its
802 existence at all.</para>
803 </listitem>
804 <listitem><para id="x_4a5">If you get a <quote>permission denied</quote>
805 error, you may have mistyped the username on the server,
806 or you could have mistyped your key's passphrase or the
807 remote user's password.</para>
808 </listitem></itemizedlist>
809 <para id="x_4a6">In summary, if you're having trouble talking to the
810 server's ssh daemon, first make sure that one is running at
811 all. On many systems it will be installed, but disabled, by
812 default. Once you're done with this step, you should then
813 check that the server's firewall is configured to allow
814 incoming connections on the port the ssh daemon is listening
815 on (usually 22). Don't worry about more exotic possibilities
816 for misconfiguration until you've checked these two
817 first.</para>
818 <para id="x_4a7">If you're using an authentication agent on the client side
819 to store passphrases for your keys, you ought to be able to
820 log into the server without being prompted for a passphrase or
821 a password. If you're prompted for a passphrase, there are a
822 few possible culprits.</para>
823 <itemizedlist>
824 <listitem><para id="x_4a8">You might have forgotten to use
825 <command>ssh-add</command> or <command>pageant</command>
826 to store the passphrase.</para>
827 </listitem>
828 <listitem><para id="x_4a9">You might have stored the passphrase for the
829 wrong key.</para>
830 </listitem></itemizedlist>
831 <para id="x_4aa">If you're being prompted for the remote user's password,
832 there are another few possible problems to check.</para>
833 <itemizedlist>
834 <listitem><para id="x_4ab">Either the user's home directory or their
835 <filename role="special" class="directory">.ssh</filename>
836 directory might have excessively liberal permissions. As
837 a result, the ssh daemon will not trust or read their
838 <filename role="special">authorized_keys</filename> file.
839 For example, a group-writable home or <filename
840 role="special" class="directory">.ssh</filename>
841 directory will often cause this symptom.</para>
842 </listitem>
843 <listitem><para id="x_4ac">The user's <filename
844 role="special">authorized_keys</filename> file may have
845 a problem. If anyone other than the user owns or can write
846 to that file, the ssh daemon will not trust or read
847 it.</para>
848 </listitem></itemizedlist>
850 <para id="x_4ad">In the ideal world, you should be able to run the
851 following command successfully, and it should print exactly
852 one line of output, the current date and time.</para>
853 <programlisting>ssh myserver date</programlisting>
855 <para id="x_4ae">If, on your server, you have login scripts that print
856 banners or other junk even when running non-interactive
857 commands like this, you should fix them before you continue,
858 so that they only print output if they're run interactively.
859 Otherwise these banners will at least clutter up Mercurial's
860 output. Worse, they could potentially cause problems with
861 running Mercurial commands remotely. Mercurial tries to
862 detect and ignore banners in non-interactive
863 <command>ssh</command> sessions, but it is not foolproof. (If
864 you're editing your login scripts on your server, the usual
865 way to see if a login script is running in an interactive
866 shell is to check the return code from the command
867 <literal>tty -s</literal>.)</para>
869 <para id="x_4af">Once you've verified that plain old ssh is working with
870 your server, the next step is to ensure that Mercurial runs on
871 the server. The following command should run
872 successfully:</para>
874 <programlisting>ssh myserver hg version</programlisting>
876 <para id="x_4b0">If you see an error message instead of normal <command
877 role="hg-cmd">hg version</command> output, this is usually
878 because you haven't installed Mercurial to <filename
879 class="directory">/usr/bin</filename>. Don't worry if this
880 is the case; you don't need to do that. But you should check
881 for a few possible problems.</para>
882 <itemizedlist>
883 <listitem><para id="x_4b1">Is Mercurial really installed on the server at
884 all? I know this sounds trivial, but it's worth
885 checking!</para>
886 </listitem>
887 <listitem><para id="x_4b2">Maybe your shell's search path (usually set
888 via the <envar>PATH</envar> environment variable) is
889 simply misconfigured.</para>
890 </listitem>
891 <listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment
892 variable is only being set to point to the location of the
893 <command>hg</command> executable if the login session is
894 interactive. This can happen if you're setting the path
895 in the wrong shell login script. See your shell's
896 documentation for details.</para>
897 </listitem>
898 <listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment
899 variable may need to contain the path to the Mercurial
900 Python modules. It might not be set at all; it could be
901 incorrect; or it may be set only if the login is
902 interactive.</para>
903 </listitem></itemizedlist>
905 <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command>
906 over an ssh connection, well done! You've got the server and
907 client sorted out. You should now be able to use Mercurial to
908 access repositories hosted by that username on that server.
909 If you run into problems with Mercurial and ssh at this point,
910 try using the <option role="hg-opt-global">--debug</option>
911 option to get a clearer picture of what's going on.</para>
912 </sect2>
913 <sect2>
914 <title>Using compression with ssh</title>
916 <para id="x_4b6">Mercurial does not compress data when it uses the ssh
917 protocol, because the ssh protocol can transparently compress
918 data. However, the default behavior of ssh clients is
919 <emphasis>not</emphasis> to request compression.</para>
921 <para id="x_4b7">Over any network other than a fast LAN (even a wireless
922 network), using compression is likely to significantly speed
923 up Mercurial's network operations. For example, over a WAN,
924 someone measured compression as reducing the amount of time
925 required to clone a particularly large repository from 51
926 minutes to 17 minutes.</para>
928 <para id="x_4b8">Both <command>ssh</command> and <command>plink</command>
929 accept a <option role="cmd-opt-ssh">-C</option> option which
930 turns on compression. You can easily edit your <filename
931 role="special">~/.hgrc</filename> to enable compression for
932 all of Mercurial's uses of the ssh protocol. Here is how to
933 do so for regular <command>ssh</command> on Unix-like systems,
934 for example.</para>
935 <programlisting>[ui]
936 ssh = ssh -C</programlisting>
938 <para id="x_4b9">If you use <command>ssh</command> on a
939 Unix-like system, you can configure it to always use
940 compression when talking to your server. To do this, edit
941 your <filename role="special">.ssh/config</filename> file
942 (which may not yet exist), as follows.</para>
944 <programlisting>Host hg
945 Compression yes
946 HostName hg.example.com</programlisting>
948 <para id="x_4ba">This defines a hostname alias,
949 <literal>hg</literal>. When you use that hostname on the
950 <command>ssh</command> command line or in a Mercurial
951 <literal>ssh</literal>-protocol URL, it will cause
952 <command>ssh</command> to connect to
953 <literal>hg.example.com</literal> and use compression. This
954 gives you both a shorter name to type and compression, each of
955 which is a good thing in its own right.</para>
956 </sect2>
957 </sect1>
959 <sect1 id="sec:collab:cgi">
960 <title>Serving over HTTP using CGI</title>
962 <para id="x_6a8">The simplest way to host one or more repositories in a
963 permanent way is to use a web server and Mercurial's CGI
964 support.</para>
966 <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
967 CGI interface can take anything from a few moments to several
968 hours.</para>
970 <para id="x_4bc">We'll begin with the simplest of examples, and work our way
971 towards a more complex configuration. Even for the most basic
972 case, you're almost certainly going to need to read and modify
973 your web server's configuration.</para>
975 <note>
976 <title>High pain tolerance required</title>
978 <para id="x_4bd">Configuring a web server is a complex, fiddly,
979 and highly system-dependent activity. I can't possibly give
980 you instructions that will cover anything like all of the
981 cases you will encounter. Please use your discretion and
982 judgment in following the sections below. Be prepared to make
983 plenty of mistakes, and to spend a lot of time reading your
984 server's error logs.</para>
986 <para id="x_6a9">If you don't have a strong stomach for tweaking
987 configurations over and over, or a compelling need to host
988 your own services, you might want to try one of the public
989 hosting services that I mentioned earlier.</para>
990 </note>
992 <sect2>
993 <title>Web server configuration checklist</title>
995 <para id="x_4be">Before you continue, do take a few moments to check a few
996 aspects of your system's setup.</para>
998 <orderedlist>
999 <listitem><para id="x_4bf">Do you have a web server installed
1000 at all? Mac OS X and some Linux distributions ship with
1001 Apache, but many other systems may not have a web server
1002 installed.</para>
1003 </listitem>
1004 <listitem><para id="x_4c0">If you have a web server installed, is it
1005 actually running? On most systems, even if one is
1006 present, it will be disabled by default.</para>
1007 </listitem>
1008 <listitem><para id="x_4c1">Is your server configured to allow you to run
1009 CGI programs in the directory where you plan to do so?
1010 Most servers default to explicitly disabling the ability
1011 to run CGI programs.</para>
1012 </listitem></orderedlist>
1014 <para id="x_4c2">If you don't have a web server installed, and don't have
1015 substantial experience configuring Apache, you should consider
1016 using the <literal>lighttpd</literal> web server instead of
1017 Apache. Apache has a well-deserved reputation for baroque and
1018 confusing configuration. While <literal>lighttpd</literal> is
1019 less capable in some ways than Apache, most of these
1020 capabilities are not relevant to serving Mercurial
1021 repositories. And <literal>lighttpd</literal> is undeniably
1022 <emphasis>much</emphasis> easier to get started with than
1023 Apache.</para>
1024 </sect2>
1026 <sect2>
1027 <title>Basic CGI configuration</title>
1029 <para id="x_4c3">On Unix-like systems, it's common for users to have a
1030 subdirectory named something like <filename
1031 class="directory">public_html</filename> in their home
1032 directory, from which they can serve up web pages. A file
1033 named <filename>foo</filename> in this directory will be
1034 accessible at a URL of the form
1035 <literal>http://www.example.com/username/foo</literal>.</para>
1037 <para id="x_4c4">To get started, find the <filename
1038 role="special">hgweb.cgi</filename> script that should be
1039 present in your Mercurial installation. If you can't quickly
1040 find a local copy on your system, simply download one from the
1041 master Mercurial repository at <ulink
1042 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>
1044 <para id="x_4c5">You'll need to copy this script into your <filename
1045 class="directory">public_html</filename> directory, and
1046 ensure that it's executable.</para>
1047 <programlisting>cp .../hgweb.cgi ~/public_html
1048 chmod 755 ~/public_html/hgweb.cgi</programlisting>
1049 <para id="x_4c6">The <literal>755</literal> argument to
1050 <command>chmod</command> is a little more general than just
1051 making the script executable: it ensures that the script is
1052 executable by anyone, and that <quote>group</quote> and
1053 <quote>other</quote> write permissions are
1054 <emphasis>not</emphasis> set. If you were to leave those
1055 write permissions enabled, Apache's <literal>suexec</literal>
1056 subsystem would likely refuse to execute the script. In fact,
1057 <literal>suexec</literal> also insists that the
1058 <emphasis>directory</emphasis> in which the script resides
1059 must not be writable by others.</para>
1060 <programlisting>chmod 755 ~/public_html</programlisting>
1062 <sect3 id="sec:collab:wtf">
1063 <title>What could <emphasis>possibly</emphasis> go
1064 wrong?</title>
1066 <para id="x_4c7">Once you've copied the CGI script into place,
1067 go into a web browser, and try to open the URL
1068 <literal>http://myhostname/~myuser/hgweb.cgi</literal>,
1069 <emphasis>but</emphasis> brace yourself for instant failure.
1070 There's a high probability that trying to visit this URL
1071 will fail, and there are many possible reasons for this. In
1072 fact, you're likely to stumble over almost every one of the
1073 possible errors below, so please read carefully. The
1074 following are all of the problems I ran into on a system
1075 running Fedora 7, with a fresh installation of Apache, and a
1076 user account that I created specially to perform this
1077 exercise.</para>
1079 <para id="x_4c8">Your web server may have per-user directories disabled.
1080 If you're using Apache, search your config file for a
1081 <literal>UserDir</literal> directive. If there's none
1082 present, per-user directories will be disabled. If one
1083 exists, but its value is <literal>disabled</literal>, then
1084 per-user directories will be disabled. Otherwise, the
1085 string after <literal>UserDir</literal> gives the name of
1086 the subdirectory that Apache will look in under your home
1087 directory, for example <filename
1088 class="directory">public_html</filename>.</para>
1090 <para id="x_4c9">Your file access permissions may be too restrictive.
1091 The web server must be able to traverse your home directory
1092 and directories under your <filename
1093 class="directory">public_html</filename> directory, and
1094 read files under the latter too. Here's a quick recipe to
1095 help you to make your permissions more appropriate.</para>
1096 <programlisting>chmod 755 ~
1097 find ~/public_html -type d -print0 | xargs -0r chmod 755
1098 find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting>
1100 <para id="x_4ca">The other possibility with permissions is that you might
1101 get a completely empty window when you try to load the
1102 script. In this case, it's likely that your access
1103 permissions are <emphasis>too permissive</emphasis>. Apache's
1104 <literal>suexec</literal> subsystem won't execute a script
1105 that's group- or world-writable, for example.</para>
1107 <para id="x_4cb">Your web server may be configured to disallow execution
1108 of CGI programs in your per-user web directory. Here's
1109 Apache's default per-user configuration from my Fedora
1110 system.</para>
1112 &ch06-apache-config.lst;
1114 <para id="x_4cc">If you find a similar-looking
1115 <literal>Directory</literal> group in your Apache
1116 configuration, the directive to look at inside it is
1117 <literal>Options</literal>. Add <literal>ExecCGI</literal>
1118 to the end of this list if it's missing, and restart the web
1119 server.</para>
1121 <para id="x_4cd">If you find that Apache serves you the text of the CGI
1122 script instead of executing it, you may need to either
1123 uncomment (if already present) or add a directive like
1124 this.</para>
1125 <programlisting>AddHandler cgi-script .cgi</programlisting>
1127 <para id="x_4ce">The next possibility is that you might be served with a
1128 colourful Python backtrace claiming that it can't import a
1129 <literal>mercurial</literal>-related module. This is
1130 actually progress! The server is now capable of executing
1131 your CGI script. This error is only likely to occur if
1132 you're running a private installation of Mercurial, instead
1133 of a system-wide version. Remember that the web server runs
1134 the CGI program without any of the environment variables
1135 that you take for granted in an interactive session. If
1136 this error happens to you, edit your copy of <filename
1137 role="special">hgweb.cgi</filename> and follow the
1138 directions inside it to correctly set your
1139 <envar>PYTHONPATH</envar> environment variable.</para>
1141 <para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be
1142 served with another colourful Python backtrace: this one
1143 will complain that it can't find <filename
1144 class="directory">/path/to/repository</filename>. Edit
1145 your <filename role="special">hgweb.cgi</filename> script
1146 and replace the <filename
1147 class="directory">/path/to/repository</filename> string
1148 with the complete path to the repository you want to serve
1149 up.</para>
1151 <para id="x_4d0">At this point, when you try to reload the page, you
1152 should be presented with a nice HTML view of your
1153 repository's history. Whew!</para>
1154 </sect3>
1156 <sect3>
1157 <title>Configuring lighttpd</title>
1159 <para id="x_4d1">To be exhaustive in my experiments, I tried configuring
1160 the increasingly popular <literal>lighttpd</literal> web
1161 server to serve the same repository as I described with
1162 Apache above. I had already overcome all of the problems I
1163 outlined with Apache, many of which are not server-specific.
1164 As a result, I was fairly sure that my file and directory
1165 permissions were good, and that my <filename
1166 role="special">hgweb.cgi</filename> script was properly
1167 edited.</para>
1169 <para id="x_4d2">Once I had Apache running, getting
1170 <literal>lighttpd</literal> to serve the repository was a
1171 snap (in other words, even if you're trying to use
1172 <literal>lighttpd</literal>, you should read the Apache
1173 section). I first had to edit the
1174 <literal>mod_access</literal> section of its config file to
1175 enable <literal>mod_cgi</literal> and
1176 <literal>mod_userdir</literal>, both of which were disabled
1177 by default on my system. I then added a few lines to the
1178 end of the config file, to configure these modules.</para>
1179 <programlisting>userdir.path = "public_html"
1180 cgi.assign = (".cgi" => "" )</programlisting>
1181 <para id="x_4d3">With this done, <literal>lighttpd</literal> ran
1182 immediately for me. If I had configured
1183 <literal>lighttpd</literal> before Apache, I'd almost
1184 certainly have run into many of the same system-level
1185 configuration problems as I did with Apache. However, I
1186 found <literal>lighttpd</literal> to be noticeably easier to
1187 configure than Apache, even though I've used Apache for over
1188 a decade, and this was my first exposure to
1189 <literal>lighttpd</literal>.</para>
1190 </sect3>
1191 </sect2>
1192 <!-- TODO : part 3/4 -->
1193 <sect2>
1194 <title>Sharing multiple repositories with one CGI script</title>
1196 <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script
1197 only lets you publish a single repository, which is an
1198 annoying restriction. If you want to publish more than one
1199 without wracking yourself with multiple copies of the same
1200 script, each with different names, a better choice is to use
1201 the <filename role="special">hgwebdir.cgi</filename>
1202 script.</para>
1204 <para id="x_4d5">The procedure to configure <filename
1205 role="special">hgwebdir.cgi</filename> is only a little more
1206 involved than for <filename
1207 role="special">hgweb.cgi</filename>. First, you must obtain
1208 a copy of the script. If you don't have one handy, you can
1209 download a copy from the master Mercurial repository at <ulink
1210 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>
1212 <para id="x_4d6">You'll need to copy this script into your <filename
1213 class="directory">public_html</filename> directory, and
1214 ensure that it's executable.</para>
1216 <programlisting>cp .../hgwebdir.cgi ~/public_html
1217 chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
1219 <para id="x_4d7">With basic configuration out of the way, try to
1220 visit <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>
1221 in your browser. It should
1222 display an empty list of repositories. If you get a blank
1223 window or error message, try walking through the list of
1224 potential problems in <xref
1225 linkend="sec:collab:wtf"/>.</para>
1227 <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename>
1228 script relies on an external configuration file. By default,
1229 it searches for a file named <filename
1230 role="special">hgweb.config</filename> in the same directory
1231 as itself. You'll need to create this file, and make it
1232 world-readable. The format of the file is similar to a
1233 Windows <quote>ini</quote> file, as understood by Python's
1234 <literal>ConfigParser</literal>
1235 <citation>web:configparser</citation> module.</para>
1237 <para id="x_4d9">The easiest way to configure <filename
1238 role="special">hgwebdir.cgi</filename> is with a section
1239 named <literal>collections</literal>. This will automatically
1240 publish <emphasis>every</emphasis> repository under the
1241 directories you name. The section should look like
1242 this:</para>
1243 <programlisting>[collections]
1244 /my/root = /my/root</programlisting>
1245 <para id="x_4da">Mercurial interprets this by looking at the directory name
1246 on the <emphasis>right</emphasis> hand side of the
1247 <quote><literal>=</literal></quote> sign; finding repositories
1248 in that directory hierarchy; and using the text on the
1249 <emphasis>left</emphasis> to strip off matching text from the
1250 names it will actually list in the web interface. The
1251 remaining component of a path after this stripping has
1252 occurred is called a <quote>virtual path</quote>.</para>
1254 <para id="x_4db">Given the example above, if we have a
1255 repository whose local path is <filename
1256 class="directory">/my/root/this/repo</filename>, the CGI
1257 script will strip the leading <filename
1258 class="directory">/my/root</filename> from the name, and
1259 publish the repository with a virtual path of <filename
1260 class="directory">this/repo</filename>. If the base URL for
1261 our CGI script is
1262 <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>, the
1263 complete URL for that repository will be
1264 <literal>http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para>
1266 <para id="x_4dc">If we replace <filename
1267 class="directory">/my/root</filename> on the left hand side
1268 of this example with <filename
1269 class="directory">/my</filename>, then <filename
1270 role="special">hgwebdir.cgi</filename> will only strip off
1271 <filename class="directory">/my</filename> from the repository
1272 name, and will give us a virtual path of <filename
1273 class="directory">root/this/repo</filename> instead of
1274 <filename class="directory">this/repo</filename>.</para>
1276 <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename>
1277 script will recursively search each directory listed in the
1278 <literal>collections</literal> section of its configuration
1279 file, but it will <literal>not</literal> recurse into the
1280 repositories it finds.</para>
1282 <para id="x_4de">The <literal>collections</literal> mechanism makes it easy
1283 to publish many repositories in a <quote>fire and
1284 forget</quote> manner. You only need to set up the CGI
1285 script and configuration file one time. Afterwards, you can
1286 publish or unpublish a repository at any time by simply moving
1287 it into, or out of, the directory hierarchy in which you've
1288 configured <filename role="special">hgwebdir.cgi</filename> to
1289 look.</para>
1291 <sect3>
1292 <title>Explicitly specifying which repositories to
1293 publish</title>
1295 <para id="x_4df">In addition to the <literal>collections</literal>
1296 mechanism, the <filename
1297 role="special">hgwebdir.cgi</filename> script allows you
1298 to publish a specific list of repositories. To do so,
1299 create a <literal>paths</literal> section, with contents of
1300 the following form.</para>
1301 <programlisting>[paths]
1302 repo1 = /my/path/to/some/repo
1303 repo2 = /some/path/to/another</programlisting>
1304 <para id="x_4e0">In this case, the virtual path (the component that will
1305 appear in a URL) is on the left hand side of each
1306 definition, while the path to the repository is on the
1307 right. Notice that there does not need to be any
1308 relationship between the virtual path you choose and the
1309 location of a repository in your filesystem.</para>
1311 <para id="x_4e1">If you wish, you can use both the
1312 <literal>collections</literal> and <literal>paths</literal>
1313 mechanisms simultaneously in a single configuration
1314 file.</para>
1316 <note>
1317 <title>Beware duplicate virtual paths</title>
1319 <para id="x_4e2"> If several repositories have the same
1320 virtual path, <filename
1321 role="special">hgwebdir.cgi</filename> will not report
1322 an error. Instead, it will behave unpredictably.</para>
1323 </note>
1324 </sect3>
1325 </sect2>
1327 <sect2>
1328 <title>Downloading source archives</title>
1330 <para id="x_4e3">Mercurial's web interface lets users download an archive
1331 of any revision. This archive will contain a snapshot of the
1332 working directory as of that revision, but it will not contain
1333 a copy of the repository data.</para>
1335 <para id="x_4e4">By default, this feature is not enabled. To enable it,
1336 you'll need to add an <envar
1337 role="rc-item-web">allow_archive</envar> item to the
1338 <literal role="rc-web">web</literal> section of your <filename
1339 role="special">~/.hgrc</filename>; see below for details.</para>
1340 </sect2>
1341 <sect2>
1342 <title>Web configuration options</title>
1344 <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg
1345 serve</command> command, and the <filename
1346 role="special">hgweb.cgi</filename> and <filename
1347 role="special">hgwebdir.cgi</filename> scripts) have a
1348 number of configuration options that you can set. These
1349 belong in a section named <literal
1350 role="rc-web">web</literal>.</para>
1351 <itemizedlist>
1352 <listitem><para id="x_4e6"><envar
1353 role="rc-item-web">allow_archive</envar>: Determines
1354 which (if any) archive download mechanisms Mercurial
1355 supports. If you enable this feature, users of the web
1356 interface will be able to download an archive of whatever
1357 revision of a repository they are viewing. To enable the
1358 archive feature, this item must take the form of a
1359 sequence of words drawn from the list below.</para>
1360 <itemizedlist>
1361 <listitem><para id="x_4e7"><literal>bz2</literal>: A
1362 <command>tar</command> archive, compressed using
1363 <literal>bzip2</literal> compression. This has the
1364 best compression ratio, but uses the most CPU time on
1365 the server.</para>
1366 </listitem>
1367 <listitem><para id="x_4e8"><literal>gz</literal>: A
1368 <command>tar</command> archive, compressed using
1369 <literal>gzip</literal> compression.</para>
1370 </listitem>
1371 <listitem><para id="x_4e9"><literal>zip</literal>: A
1372 <command>zip</command> archive, compressed using LZW
1373 compression. This format has the worst compression
1374 ratio, but is widely used in the Windows world.</para>
1375 </listitem>
1376 </itemizedlist>
1377 <para id="x_4ea"> If you provide an empty list, or don't have an
1378 <envar role="rc-item-web">allow_archive</envar> entry at
1379 all, this feature will be disabled. Here is an example of
1380 how to enable all three supported formats.</para>
1381 <programlisting>[web]
1382 allow_archive = bz2 gz zip</programlisting>
1383 </listitem>
1384 <listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>:
1385 Boolean. Determines whether the web interface allows
1386 remote users to <command role="hg-cmd">hg pull</command>
1387 and <command role="hg-cmd">hg clone</command> this
1388 repository over HTTP. If set to <literal>no</literal> or
1389 <literal>false</literal>, only the
1390 <quote>human-oriented</quote> portion of the web interface
1391 is available.</para>
1392 </listitem>
1393 <listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>:
1394 String. A free-form (but preferably brief) string
1395 identifying the person or group in charge of the
1396 repository. This often contains the name and email
1397 address of a person or mailing list. It often makes sense
1398 to place this entry in a repository's own <filename
1399 role="special">.hg/hgrc</filename> file, but it can make
1400 sense to use in a global <filename
1401 role="special">~/.hgrc</filename> if every repository
1402 has a single maintainer.</para>
1403 </listitem>
1404 <listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>:
1405 Integer. The default maximum number of changesets to
1406 display in a single page of output.</para>
1407 </listitem>
1408 <listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>:
1409 Integer. The default maximum number of modified files to
1410 display in a single page of output.</para>
1411 </listitem>
1412 <listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>:
1413 Integer. If the web interface displays alternating
1414 <quote>stripes</quote> to make it easier to visually align
1415 rows when you are looking at a table, this number controls
1416 the number of rows in each stripe.</para>
1417 </listitem>
1418 <listitem><para id="x_4f0"><envar
1419 role="rc-item-web">style</envar>: Controls the template
1420 Mercurial uses to display the web interface. Mercurial
1421 ships with several web templates.</para>
1422 <itemizedlist>
1423 <listitem>
1424 <para id="x_6aa"><literal>coal</literal> is monochromatic.</para>
1425 </listitem>
1426 <listitem>
1427 <para id="x_6ab"><literal>gitweb</literal> emulates the visual
1428 style of git's web interface.</para>
1429 </listitem>
1430 <listitem>
1431 <para id="x_6ac"><literal>monoblue</literal> uses solid blues and
1432 greys.</para>
1433 </listitem>
1434 <listitem>
1435 <para id="x_6ad"><literal>paper</literal> is the default.</para>
1436 </listitem>
1437 <listitem>
1438 <para id="x_6ae"><literal>spartan</literal> was the default for a
1439 long time.</para>
1440 </listitem>
1441 </itemizedlist>
1442 <para id="x_6af">You can
1443 also specify a custom template of your own; see
1444 <xref linkend="chap:template"/> for details. Here, you can
1445 see how to enable the <literal>gitweb</literal>
1446 style.</para>
1447 <programlisting>[web]
1448 style = gitweb</programlisting>
1449 </listitem>
1450 <listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>:
1451 Path. The directory in which to search for template
1452 files. By default, Mercurial searches in the directory in
1453 which it was installed.</para>
1454 </listitem></itemizedlist>
1455 <para id="x_4f2">If you are using <filename
1456 role="special">hgwebdir.cgi</filename>, you can place a few
1457 configuration items in a <literal role="rc-web">web</literal>
1458 section of the <filename
1459 role="special">hgweb.config</filename> file instead of a
1460 <filename role="special">~/.hgrc</filename> file, for
1461 convenience. These items are <envar
1462 role="rc-item-web">motd</envar> and <envar
1463 role="rc-item-web">style</envar>.</para>
1465 <sect3>
1466 <title>Options specific to an individual repository</title>
1468 <para id="x_4f3">A few <literal role="rc-web">web</literal> configuration
1469 items ought to be placed in a repository's local <filename
1470 role="special">.hg/hgrc</filename>, rather than a user's
1471 or global <filename role="special">~/.hgrc</filename>.</para>
1472 <itemizedlist>
1473 <listitem><para id="x_4f4"><envar
1474 role="rc-item-web">description</envar>: String. A
1475 free-form (but preferably brief) string that describes
1476 the contents or purpose of the repository.</para>
1477 </listitem>
1478 <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>:
1479 String. The name to use for the repository in the web
1480 interface. This overrides the default name, which is
1481 the last component of the repository's path.</para>
1482 </listitem></itemizedlist>
1483 </sect3>
1485 <sect3>
1486 <title>Options specific to the <command role="hg-cmd">hg
1487 serve</command> command</title>
1489 <para id="x_4f6">Some of the items in the <literal
1490 role="rc-web">web</literal> section of a <filename
1491 role="special">~/.hgrc</filename> file are only for use
1492 with the <command role="hg-cmd">hg serve</command>
1493 command.</para>
1494 <itemizedlist>
1495 <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>:
1496 Path. The name of a file into which to write an access
1497 log. By default, the <command role="hg-cmd">hg
1498 serve</command> command writes this information to
1499 standard output, not to a file. Log entries are written
1500 in the standard <quote>combined</quote> file format used
1501 by almost all web servers.</para>
1502 </listitem>
1503 <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>:
1504 String. The local address on which the server should
1505 listen for incoming connections. By default, the server
1506 listens on all addresses.</para>
1507 </listitem>
1508 <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>:
1509 Path. The name of a file into which to write an error
1510 log. By default, the <command role="hg-cmd">hg
1511 serve</command> command writes this information to
1512 standard error, not to a file.</para>
1513 </listitem>
1514 <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>:
1515 Boolean. Whether to use the IPv6 protocol. By default,
1516 IPv6 is not used.</para>
1517 </listitem>
1518 <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>:
1519 Integer. The TCP port number on which the server should
1520 listen. The default port number used is 8000.</para>
1521 </listitem></itemizedlist>
1522 </sect3>
1524 <sect3>
1525 <title>Choosing the right <filename
1526 role="special">~/.hgrc</filename> file to add <literal
1527 role="rc-web">web</literal> items to</title>
1529 <para id="x_4fc">It is important to remember that a web server like
1530 Apache or <literal>lighttpd</literal> will run under a user
1531 ID that is different to yours. CGI scripts run by your
1532 server, such as <filename
1533 role="special">hgweb.cgi</filename>, will usually also run
1534 under that user ID.</para>
1536 <para id="x_4fd">If you add <literal role="rc-web">web</literal> items to
1537 your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that
1538 <filename role="special">~/.hgrc</filename> file. Those
1539 settings will thus only affect the behavior of the <command
1540 role="hg-cmd">hg serve</command> command when you run it.
1541 To cause CGI scripts to see your settings, either create a
1542 <filename role="special">~/.hgrc</filename> file in the
1543 home directory of the user ID that runs your web server, or
1544 add those settings to a system-wide <filename
1545 role="special">hgrc</filename> file.</para>
1546 </sect3>
1547 </sect2>
1548 </sect1>
1550 <sect1>
1551 <title>System-wide configuration</title>
1553 <para id="x_6b0">On Unix-like systems shared by multiple users (such as a
1554 server to which people publish changes), it often makes sense to
1555 set up some global default behaviors, such as what theme to use
1556 in web interfaces.</para>
1558 <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename>
1559 exists, Mercurial will read it at startup time and apply any
1560 configuration settings it finds in that file. It will also look
1561 for files ending in a <literal>.rc</literal> extension in a
1562 directory named <filename>/etc/mercurial/hgrc.d</filename>, and
1563 apply any configuration settings it finds in each of those
1564 files.</para>
1566 <sect2>
1567 <title>Making Mercurial more trusting</title>
1569 <para id="x_6b2">One situation in which a global <filename>hgrc</filename>
1570 can be useful is if users are pulling changes owned by other
1571 users. By default, Mercurial will not trust most of the
1572 configuration items in a <filename>.hg/hgrc</filename> file
1573 inside a repository that is owned by a different user. If we
1574 clone or pull changes from such a repository, Mercurial will
1575 print a warning stating that it does not trust their
1576 <filename>.hg/hgrc</filename>.</para>
1578 <para id="x_6b3">If everyone in a particular Unix group is on the same team
1579 and <emphasis>should</emphasis> trust each other's
1580 configuration settings, or we want to trust particular users,
1581 we can override Mercurial's skeptical defaults by creating a
1582 system-wide <filename>hgrc</filename> file such as the
1583 following:</para>
1585 <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
1586 [trusted]
1587 # Trust all entries in any hgrc file owned by the "editors" or
1588 # "www-data" groups.
1589 groups = editors, www-data
1591 # Trust entries in hgrc files owned by the following users.
1592 users = apache, bobo
1593 </programlisting>
1594 </sect2>
1595 </sect1>
1596 </chapter>
1597 <!-- TODO : part 4/4 -->
1598 <!--
1599 local variables:
1600 sgml-parent-document: ("00book.xml" "book" "chapter")
1601 end:
1602 -->