hgbook
view fr/ch06-collab.xml @ 1020:53dfddc566d8
French: corrections in xml tags
| author | André Sintzoff <andre.sintzoff@gmail.com> |
|---|---|
| date | Tue Dec 01 13:40:01 2009 +0100 (2009-12-01) |
| parents | 746a888fb41b |
| children | ea04ebd452b5 |
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 fonctions 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 l'utilisation 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 faible bande passante.</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 bas 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 liste à 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 populaires
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, prendre des
81 décisions sur les workflows est plus un problème d'ingénierie sociale
82 qu'un problème technique. Mercurial impose 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. Quelque soit le schéma que vous établirez, vous devriez
109 planifier un protocole pour prévenir, ou rapidement vous relever de
110 troubles que vous pouvez anticiper. Par exemple, si vous vous
111 attendez à avoir une branche pour les changements pas-pour-release,
112 vous devriez penser très tôt à 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 inopportune.</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, des personnes viennent ensemble dans un même
132 endroit (la salle de conférence d'une société, la salle de réunion
133 d'un hôtel, ce genre d'endroit) et y passent 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 quelques instants, en lisant <xref
143 linkend="sec:collab:serve"/> plus bas Ensuite, dites simplement à
144 la personne à côté 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 revoir vos
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 un 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>composant</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 un bug
181 fix provisoire, mais je m'inquiète de savoir si, dans le cas où je le publiais,
182 cela ne casserait pas l'arbre des autres contributeurs s'ils la
183 récupèreraient. 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 gèrent
207 pas uniquement les détails minutieux de la configuration du
208 serveur, tels que les comptes utilisateurs, l'authentification, les
209 protocoles sécurisés, ils fournissent aussi une infrastructure
210 additionnelle pour 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 clic. 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 uns 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 sur la
269 branche principale.</para>
271 &interaction.branching.main;
273 <para id="x_463">En utilisant le tag enregistré à l'étape importante,
274 les gens qui clonent 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.</para>
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>
322 <!-- TODO : Branches de fonctionnalité ? -->
323 <para id="x_469">Pour de plus gros projets, une façon efficace de gérer
324 les changements est de diviser l'équipe en plus petits 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'en occupe
341 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 ? À méditer -->
351 <!-- Je mettrais suite -->
353 <para id="x_46c">Certains projets sont organisés comme un
354 <quote>train</quote> élémentaire : une release est planifiée tous les
355 quelques mois, et, toutes les fonctionnalités disponibles lorsque le
356 <quote>train</quote> est prêt à s'arrêter sont autorisées ici.</para>
358 <para id="x_46d">Ce modèle ressemble à travailler avec des branches de
359 fonctionnalités. La différence est que lorsqu'une branche de
360 fonctionnalité rate le train, quelqu'un de l'équipe qui travaille sur
361 cette fonctionnalité récupère (pull) et fusionne (merge) ce qui a été
362 ajouté à la release du train dans la branche de la fonctionnalité,
363 puis, l'équipe continue son travail au-dessus de cette release afin
364 que leur fonctionnalité puisse être ajoutée à la prochaine
365 release.</para>
366 </sect2>
368 <sect2>
369 <title>Le modèle du noyau Linux</title>
371 <para id="x_46e">Le développement du noyau Linux est doté d'une
372 structure hiérarchique superficielle, entourée par un nuage de chaos
373 apparent. Parce que la plupart des développeurs Linux utilisent
374 <command>git</command>, un outil distribué de gestion de révisions
375 avec des capacités similaires à celles de Mercurial, il est utile de
376 décrire comment le travail se déroule dans cet environnement ; si
377 vous aimez ces idées, l'approche se traduit correctement à travers
378 les outils.</para>
380 <para id="x_46f">Au centre de la communauté siège Linus Torvalds, le
381 créateur de Linux. Il publie un dépôt unique de sources qui est
382 considéré comme faisant <quote>autorité</quote> sur l'arborescence
383 par la communauté entière de développeurs. Tout le monde peut cloner
384 l'arbre de Linus, mais il ne récupère (pull) pas les changements de n'importe quelle arborescence.</para>
386 <para id="x_470">Linus a plusieurs <quote>lieutenants 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
392 hacker du noyau veut apporter des modification au sous-système
393 qu'il veut voir intégré à l'arbre de Linus, il doit trouver
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 auprès d'un autre développeur
412 pour prendre vos modifications, puisqu'il n'y a vraisemblablement pas
413 d'arbre où plus d'une personne peut envoyer des changements (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 changements 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 critères d'acceptation. Plus vous enverrez du
422 <quote>bon</quote> code à un mainteneur, et plus celui-ci aura
423 confiance en votre jugement et acceptera 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>entre les gens</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 approfondi 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 le milieu est plus ordonné, le processus chaotique de
438 développement du noyau Linux en comparaison apparaît souvent totalement
439 dément. C'est sujet aux caprices d'individus ;
440 des personnes font des changements considérables quand ils les
441 jugent appropriés ; et l'allure du développement est
442 ahurissante. 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 heurts dans la communauté
450 opensource est de savoir si un modèle de développement où les
451 personnes ne peuvent que récupérer (pull) les changements d'autres est
452 <quote>meilleur</quote> que celui 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 partisans 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 contorsions 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 défi connexe, 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 dense pour mériter un
479 traitement à part dans <xref linkend="chap:branch"/>.</para>
480 </sect2>
481 </sect1>
483 <sect1>
484 <title>Le côté technique du partage</title>
486 <para id="x_47a">Le reste de ce chapitre est consacré à 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ôt 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ées pour ce dépôt jusqu'à ce que vous
504 l'arrêtiez. 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 vraisemblablement à
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 il 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 où vous ne vous inquiétez pas ou 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 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> la 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 utilisant le
577 protocole Secure Shell (<literal>ssh</literal>). Pour l'utiliser avec
578 succès, vous pourriez avoir à faire un peu de configuration du côté
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 utilisateurs
585 sur un serveur, comme ça, les utilisateurs distants peuvent se connecter 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-unes 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 a tendance à 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 à connecter 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 connecter.</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 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 risque de 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'interpréter. Certains programmes se
624 comportent différemment des autres lorsqu'ils traitent ces chemins. Il
625 ne s'agit pas d'une situation idéale, mais ce n'est pas prêt de
626 changer. Lisez 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 contient 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 suivi 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 le composant
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 paquet TortoiseHg est livré avec
663 une version de l'excellente commande <command>plink</command> de
664 Simon Tatham, et ne devrait pas avoir besoin de plus de
665 configuration.</para>
666 </sect2>
668 <sect2>
669 <title>Créer 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
673 de créer 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 la suivante jusqu'à ce que
681 vous soyez fatigué de constamment 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 TortoiseHg, 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 créer une paire de clefs. Référez-vous
693 à <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 créez une paire de clefs, il est
700 habituellement <emphasis>hautement</emphasis> recommandé 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 créer une paire de clefs n'est
706 cependant pas suffisant. Vous aurez besoin d'ajouter la clef publique
707 à l'ensemble des clefs autorisé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éconnectez et reconnectez). 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
732 de changements).</para>
734 <para id="x_49e">L'inconvénient 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 connectez. 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 TortoiseHg, 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 zone de notification (à droite de la barre
758 de tâches) qui vous permettra de
759 gérer les mots de passe stockés.</para></listitem>
760 <!-- TODO : J'ai traduit system tray par barre des tâches, mais ne
761 conaissant pas windows, je ne suis pas sûr du nom réel. A corriger
762 le cas échéant ! -->
763 <!-- J'ai précisé avec ce que j'ai trouvé sur Wikipedia -->
764 </itemizedlist>
765 </sect2>
766 <!-- TODO : part 2/4 -->
767 <sect2>
768 <title>Configuring the server side properly</title>
770 <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
771 a variety of things can go wrong. Add Mercurial
772 on top, and there's plenty more scope for head-scratching.
773 Most of these potential problems occur on the server side, not
774 the client side. The good news is that once you've gotten a
775 configuration working, it will usually continue to work
776 indefinitely.</para>
778 <para id="x_4a1">Before you try using Mercurial to talk to an ssh server,
779 it's best to make sure that you can use the normal
780 <command>ssh</command> or <command>putty</command> command to
781 talk to the server first. If you run into problems with using
782 these commands directly, Mercurial surely won't work. Worse,
783 it will obscure the underlying problem. Any time you want to
784 debug ssh-related Mercurial problems, you should drop back to
785 making sure that plain ssh client commands work first,
786 <emphasis>before</emphasis> you worry about whether there's a
787 problem with Mercurial.</para>
789 <para id="x_4a2">The first thing to be sure of on the server side is that
790 you can actually log in from another machine at all. If you
791 can't use <command>ssh</command> or <command>putty</command>
792 to log in, the error message you get may give you a few hints
793 as to what's wrong. The most common problems are as
794 follows.</para>
795 <itemizedlist>
796 <listitem><para id="x_4a3">If you get a <quote>connection refused</quote>
797 error, either there isn't an SSH daemon running on the
798 server at all, or it's inaccessible due to firewall
799 configuration.</para>
800 </listitem>
801 <listitem><para id="x_4a4">If you get a <quote>no route to host</quote>
802 error, you either have an incorrect address for the server
803 or a seriously locked down firewall that won't admit its
804 existence at all.</para>
805 </listitem>
806 <listitem><para id="x_4a5">If you get a <quote>permission denied</quote>
807 error, you may have mistyped the username on the server,
808 or you could have mistyped your key's passphrase or the
809 remote user's password.</para>
810 </listitem></itemizedlist>
811 <para id="x_4a6">In summary, if you're having trouble talking to the
812 server's ssh daemon, first make sure that one is running at
813 all. On many systems it will be installed, but disabled, by
814 default. Once you're done with this step, you should then
815 check that the server's firewall is configured to allow
816 incoming connections on the port the ssh daemon is listening
817 on (usually 22). Don't worry about more exotic possibilities
818 for misconfiguration until you've checked these two
819 first.</para>
820 <para id="x_4a7">If you're using an authentication agent on the client side
821 to store passphrases for your keys, you ought to be able to
822 log into the server without being prompted for a passphrase or
823 a password. If you're prompted for a passphrase, there are a
824 few possible culprits.</para>
825 <itemizedlist>
826 <listitem><para id="x_4a8">You might have forgotten to use
827 <command>ssh-add</command> or <command>pageant</command>
828 to store the passphrase.</para>
829 </listitem>
830 <listitem><para id="x_4a9">You might have stored the passphrase for the
831 wrong key.</para>
832 </listitem></itemizedlist>
833 <para id="x_4aa">If you're being prompted for the remote user's password,
834 there are another few possible problems to check.</para>
835 <itemizedlist>
836 <listitem><para id="x_4ab">Either the user's home directory or their
837 <filename role="special" class="directory">.ssh</filename>
838 directory might have excessively liberal permissions. As
839 a result, the ssh daemon will not trust or read their
840 <filename role="special">authorized_keys</filename> file.
841 For example, a group-writable home or <filename
842 role="special" class="directory">.ssh</filename>
843 directory will often cause this symptom.</para>
844 </listitem>
845 <listitem><para id="x_4ac">The user's <filename
846 role="special">authorized_keys</filename> file may have
847 a problem. If anyone other than the user owns or can write
848 to that file, the ssh daemon will not trust or read
849 it.</para>
850 </listitem></itemizedlist>
852 <para id="x_4ad">In the ideal world, you should be able to run the
853 following command successfully, and it should print exactly
854 one line of output, the current date and time.</para>
855 <programlisting>ssh myserver date</programlisting>
857 <para id="x_4ae">If, on your server, you have login scripts that print
858 banners or other junk even when running non-interactive
859 commands like this, you should fix them before you continue,
860 so that they only print output if they're run interactively.
861 Otherwise these banners will at least clutter up Mercurial's
862 output. Worse, they could potentially cause problems with
863 running Mercurial commands remotely. Mercurial tries to
864 detect and ignore banners in non-interactive
865 <command>ssh</command> sessions, but it is not foolproof. (If
866 you're editing your login scripts on your server, the usual
867 way to see if a login script is running in an interactive
868 shell is to check the return code from the command
869 <literal>tty -s</literal>.)</para>
871 <para id="x_4af">Once you've verified that plain old ssh is working with
872 your server, the next step is to ensure that Mercurial runs on
873 the server. The following command should run
874 successfully:</para>
876 <programlisting>ssh myserver hg version</programlisting>
878 <para id="x_4b0">If you see an error message instead of normal <command
879 role="hg-cmd">hg version</command> output, this is usually
880 because you haven't installed Mercurial to <filename
881 class="directory">/usr/bin</filename>. Don't worry if this
882 is the case; you don't need to do that. But you should check
883 for a few possible problems.</para>
884 <itemizedlist>
885 <listitem><para id="x_4b1">Is Mercurial really installed on the server at
886 all? I know this sounds trivial, but it's worth
887 checking!</para>
888 </listitem>
889 <listitem><para id="x_4b2">Maybe your shell's search path (usually set
890 via the <envar>PATH</envar> environment variable) is
891 simply misconfigured.</para>
892 </listitem>
893 <listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment
894 variable is only being set to point to the location of the
895 <command>hg</command> executable if the login session is
896 interactive. This can happen if you're setting the path
897 in the wrong shell login script. See your shell's
898 documentation for details.</para>
899 </listitem>
900 <listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment
901 variable may need to contain the path to the Mercurial
902 Python modules. It might not be set at all; it could be
903 incorrect; or it may be set only if the login is
904 interactive.</para>
905 </listitem></itemizedlist>
907 <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command>
908 over an ssh connection, well done! You've got the server and
909 client sorted out. You should now be able to use Mercurial to
910 access repositories hosted by that username on that server.
911 If you run into problems with Mercurial and ssh at this point,
912 try using the <option role="hg-opt-global">--debug</option>
913 option to get a clearer picture of what's going on.</para>
914 </sect2>
915 <sect2>
916 <title>Using compression with ssh</title>
918 <para id="x_4b6">Mercurial does not compress data when it uses the ssh
919 protocol, because the ssh protocol can transparently compress
920 data. However, the default behavior of ssh clients is
921 <emphasis>not</emphasis> to request compression.</para>
923 <para id="x_4b7">Over any network other than a fast LAN (even a wireless
924 network), using compression is likely to significantly speed
925 up Mercurial's network operations. For example, over a WAN,
926 someone measured compression as reducing the amount of time
927 required to clone a particularly large repository from 51
928 minutes to 17 minutes.</para>
930 <para id="x_4b8">Both <command>ssh</command> and <command>plink</command>
931 accept a <option role="cmd-opt-ssh">-C</option> option which
932 turns on compression. You can easily edit your <filename
933 role="special">~/.hgrc</filename> to enable compression for
934 all of Mercurial's uses of the ssh protocol. Here is how to
935 do so for regular <command>ssh</command> on Unix-like systems,
936 for example.</para>
937 <programlisting>[ui]
938 ssh = ssh -C</programlisting>
940 <para id="x_4b9">If you use <command>ssh</command> on a
941 Unix-like system, you can configure it to always use
942 compression when talking to your server. To do this, edit
943 your <filename role="special">.ssh/config</filename> file
944 (which may not yet exist), as follows.</para>
946 <programlisting>Host hg
947 Compression yes
948 HostName hg.example.com</programlisting>
950 <para id="x_4ba">This defines a hostname alias,
951 <literal>hg</literal>. When you use that hostname on the
952 <command>ssh</command> command line or in a Mercurial
953 <literal>ssh</literal>-protocol URL, it will cause
954 <command>ssh</command> to connect to
955 <literal>hg.example.com</literal> and use compression. This
956 gives you both a shorter name to type and compression, each of
957 which is a good thing in its own right.</para>
958 </sect2>
959 </sect1>
961 <sect1 id="sec:collab:cgi">
962 <title>Serving over HTTP using CGI</title>
964 <para id="x_6a8">The simplest way to host one or more repositories in a
965 permanent way is to use a web server and Mercurial's CGI
966 support.</para>
968 <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
969 CGI interface can take anything from a few moments to several
970 hours.</para>
972 <para id="x_4bc">We'll begin with the simplest of examples, and work our way
973 towards a more complex configuration. Even for the most basic
974 case, you're almost certainly going to need to read and modify
975 your web server's configuration.</para>
977 <note>
978 <title>High pain tolerance required</title>
980 <para id="x_4bd">Configuring a web server is a complex, fiddly,
981 and highly system-dependent activity. I can't possibly give
982 you instructions that will cover anything like all of the
983 cases you will encounter. Please use your discretion and
984 judgment in following the sections below. Be prepared to make
985 plenty of mistakes, and to spend a lot of time reading your
986 server's error logs.</para>
988 <para id="x_6a9">If you don't have a strong stomach for tweaking
989 configurations over and over, or a compelling need to host
990 your own services, you might want to try one of the public
991 hosting services that I mentioned earlier.</para>
992 </note>
994 <sect2>
995 <title>Web server configuration checklist</title>
997 <para id="x_4be">Before you continue, do take a few moments to check a few
998 aspects of your system's setup.</para>
1000 <orderedlist>
1001 <listitem><para id="x_4bf">Do you have a web server installed
1002 at all? Mac OS X and some Linux distributions ship with
1003 Apache, but many other systems may not have a web server
1004 installed.</para>
1005 </listitem>
1006 <listitem><para id="x_4c0">If you have a web server installed, is it
1007 actually running? On most systems, even if one is
1008 present, it will be disabled by default.</para>
1009 </listitem>
1010 <listitem><para id="x_4c1">Is your server configured to allow you to run
1011 CGI programs in the directory where you plan to do so?
1012 Most servers default to explicitly disabling the ability
1013 to run CGI programs.</para>
1014 </listitem></orderedlist>
1016 <para id="x_4c2">If you don't have a web server installed, and don't have
1017 substantial experience configuring Apache, you should consider
1018 using the <literal>lighttpd</literal> web server instead of
1019 Apache. Apache has a well-deserved reputation for baroque and
1020 confusing configuration. While <literal>lighttpd</literal> is
1021 less capable in some ways than Apache, most of these
1022 capabilities are not relevant to serving Mercurial
1023 repositories. And <literal>lighttpd</literal> is undeniably
1024 <emphasis>much</emphasis> easier to get started with than
1025 Apache.</para>
1026 </sect2>
1028 <sect2>
1029 <title>Basic CGI configuration</title>
1031 <para id="x_4c3">On Unix-like systems, it's common for users to have a
1032 subdirectory named something like <filename
1033 class="directory">public_html</filename> in their home
1034 directory, from which they can serve up web pages. A file
1035 named <filename>foo</filename> in this directory will be
1036 accessible at a URL of the form
1037 <literal>http://www.example.com/username/foo</literal>.</para>
1039 <para id="x_4c4">To get started, find the <filename
1040 role="special">hgweb.cgi</filename> script that should be
1041 present in your Mercurial installation. If you can't quickly
1042 find a local copy on your system, simply download one from the
1043 master Mercurial repository at <ulink
1044 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>
1046 <para id="x_4c5">You'll need to copy this script into your <filename
1047 class="directory">public_html</filename> directory, and
1048 ensure that it's executable.</para>
1049 <programlisting>cp .../hgweb.cgi ~/public_html
1050 chmod 755 ~/public_html/hgweb.cgi</programlisting>
1051 <para id="x_4c6">The <literal>755</literal> argument to
1052 <command>chmod</command> is a little more general than just
1053 making the script executable: it ensures that the script is
1054 executable by anyone, and that <quote>group</quote> and
1055 <quote>other</quote> write permissions are
1056 <emphasis>not</emphasis> set. If you were to leave those
1057 write permissions enabled, Apache's <literal>suexec</literal>
1058 subsystem would likely refuse to execute the script. In fact,
1059 <literal>suexec</literal> also insists that the
1060 <emphasis>directory</emphasis> in which the script resides
1061 must not be writable by others.</para>
1062 <programlisting>chmod 755 ~/public_html</programlisting>
1064 <sect3 id="sec:collab:wtf">
1065 <title>What could <emphasis>possibly</emphasis> go
1066 wrong?</title>
1068 <para id="x_4c7">Once you've copied the CGI script into place,
1069 go into a web browser, and try to open the URL
1070 <literal>http://myhostname/~myuser/hgweb.cgi</literal>,
1071 <emphasis>but</emphasis> brace yourself for instant failure.
1072 There's a high probability that trying to visit this URL
1073 will fail, and there are many possible reasons for this. In
1074 fact, you're likely to stumble over almost every one of the
1075 possible errors below, so please read carefully. The
1076 following are all of the problems I ran into on a system
1077 running Fedora 7, with a fresh installation of Apache, and a
1078 user account that I created specially to perform this
1079 exercise.</para>
1081 <para id="x_4c8">Your web server may have per-user directories disabled.
1082 If you're using Apache, search your config file for a
1083 <literal>UserDir</literal> directive. If there's none
1084 present, per-user directories will be disabled. If one
1085 exists, but its value is <literal>disabled</literal>, then
1086 per-user directories will be disabled. Otherwise, the
1087 string after <literal>UserDir</literal> gives the name of
1088 the subdirectory that Apache will look in under your home
1089 directory, for example <filename
1090 class="directory">public_html</filename>.</para>
1092 <para id="x_4c9">Your file access permissions may be too restrictive.
1093 The web server must be able to traverse your home directory
1094 and directories under your <filename
1095 class="directory">public_html</filename> directory, and
1096 read files under the latter too. Here's a quick recipe to
1097 help you to make your permissions more appropriate.</para>
1098 <programlisting>chmod 755 ~
1099 find ~/public_html -type d -print0 | xargs -0r chmod 755
1100 find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting>
1102 <para id="x_4ca">The other possibility with permissions is that you might
1103 get a completely empty window when you try to load the
1104 script. In this case, it's likely that your access
1105 permissions are <emphasis>too permissive</emphasis>. Apache's
1106 <literal>suexec</literal> subsystem won't execute a script
1107 that's group- or world-writable, for example.</para>
1109 <para id="x_4cb">Your web server may be configured to disallow execution
1110 of CGI programs in your per-user web directory. Here's
1111 Apache's default per-user configuration from my Fedora
1112 system.</para>
1114 &ch06-apache-config.lst;
1116 <para id="x_4cc">If you find a similar-looking
1117 <literal>Directory</literal> group in your Apache
1118 configuration, the directive to look at inside it is
1119 <literal>Options</literal>. Add <literal>ExecCGI</literal>
1120 to the end of this list if it's missing, and restart the web
1121 server.</para>
1123 <para id="x_4cd">If you find that Apache serves you the text of the CGI
1124 script instead of executing it, you may need to either
1125 uncomment (if already present) or add a directive like
1126 this.</para>
1127 <programlisting>AddHandler cgi-script .cgi</programlisting>
1129 <para id="x_4ce">The next possibility is that you might be served with a
1130 colourful Python backtrace claiming that it can't import a
1131 <literal>mercurial</literal>-related module. This is
1132 actually progress! The server is now capable of executing
1133 your CGI script. This error is only likely to occur if
1134 you're running a private installation of Mercurial, instead
1135 of a system-wide version. Remember that the web server runs
1136 the CGI program without any of the environment variables
1137 that you take for granted in an interactive session. If
1138 this error happens to you, edit your copy of <filename
1139 role="special">hgweb.cgi</filename> and follow the
1140 directions inside it to correctly set your
1141 <envar>PYTHONPATH</envar> environment variable.</para>
1143 <para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be
1144 served with another colourful Python backtrace: this one
1145 will complain that it can't find <filename
1146 class="directory">/path/to/repository</filename>. Edit
1147 your <filename role="special">hgweb.cgi</filename> script
1148 and replace the <filename
1149 class="directory">/path/to/repository</filename> string
1150 with the complete path to the repository you want to serve
1151 up.</para>
1153 <para id="x_4d0">At this point, when you try to reload the page, you
1154 should be presented with a nice HTML view of your
1155 repository's history. Whew!</para>
1156 </sect3>
1158 <sect3>
1159 <title>Configuring lighttpd</title>
1161 <para id="x_4d1">To be exhaustive in my experiments, I tried configuring
1162 the increasingly popular <literal>lighttpd</literal> web
1163 server to serve the same repository as I described with
1164 Apache above. I had already overcome all of the problems I
1165 outlined with Apache, many of which are not server-specific.
1166 As a result, I was fairly sure that my file and directory
1167 permissions were good, and that my <filename
1168 role="special">hgweb.cgi</filename> script was properly
1169 edited.</para>
1171 <para id="x_4d2">Once I had Apache running, getting
1172 <literal>lighttpd</literal> to serve the repository was a
1173 snap (in other words, even if you're trying to use
1174 <literal>lighttpd</literal>, you should read the Apache
1175 section). I first had to edit the
1176 <literal>mod_access</literal> section of its config file to
1177 enable <literal>mod_cgi</literal> and
1178 <literal>mod_userdir</literal>, both of which were disabled
1179 by default on my system. I then added a few lines to the
1180 end of the config file, to configure these modules.</para>
1181 <programlisting>userdir.path = "public_html"
1182 cgi.assign = (".cgi" => "" )</programlisting>
1183 <para id="x_4d3">With this done, <literal>lighttpd</literal> ran
1184 immediately for me. If I had configured
1185 <literal>lighttpd</literal> before Apache, I'd almost
1186 certainly have run into many of the same system-level
1187 configuration problems as I did with Apache. However, I
1188 found <literal>lighttpd</literal> to be noticeably easier to
1189 configure than Apache, even though I've used Apache for over
1190 a decade, and this was my first exposure to
1191 <literal>lighttpd</literal>.</para>
1192 </sect3>
1193 </sect2>
1194 <!-- TODO : part 3/4 -->
1195 <sect2>
1196 <title>Sharing multiple repositories with one CGI script</title>
1198 <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script
1199 only lets you publish a single repository, which is an
1200 annoying restriction. If you want to publish more than one
1201 without wracking yourself with multiple copies of the same
1202 script, each with different names, a better choice is to use
1203 the <filename role="special">hgwebdir.cgi</filename>
1204 script.</para>
1206 <para id="x_4d5">The procedure to configure <filename
1207 role="special">hgwebdir.cgi</filename> is only a little more
1208 involved than for <filename
1209 role="special">hgweb.cgi</filename>. First, you must obtain
1210 a copy of the script. If you don't have one handy, you can
1211 download a copy from the master Mercurial repository at <ulink
1212 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>
1214 <para id="x_4d6">You'll need to copy this script into your <filename
1215 class="directory">public_html</filename> directory, and
1216 ensure that it's executable.</para>
1218 <programlisting>cp .../hgwebdir.cgi ~/public_html
1219 chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
1221 <para id="x_4d7">With basic configuration out of the way, try to
1222 visit <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>
1223 in your browser. It should
1224 display an empty list of repositories. If you get a blank
1225 window or error message, try walking through the list of
1226 potential problems in <xref
1227 linkend="sec:collab:wtf"/>.</para>
1229 <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename>
1230 script relies on an external configuration file. By default,
1231 it searches for a file named <filename
1232 role="special">hgweb.config</filename> in the same directory
1233 as itself. You'll need to create this file, and make it
1234 world-readable. The format of the file is similar to a
1235 Windows <quote>ini</quote> file, as understood by Python's
1236 <literal>ConfigParser</literal>
1237 <citation>web:configparser</citation> module.</para>
1239 <para id="x_4d9">The easiest way to configure <filename
1240 role="special">hgwebdir.cgi</filename> is with a section
1241 named <literal>collections</literal>. This will automatically
1242 publish <emphasis>every</emphasis> repository under the
1243 directories you name. The section should look like
1244 this:</para>
1245 <programlisting>[collections]
1246 /my/root = /my/root</programlisting>
1247 <para id="x_4da">Mercurial interprets this by looking at the directory name
1248 on the <emphasis>right</emphasis> hand side of the
1249 <quote><literal>=</literal></quote> sign; finding repositories
1250 in that directory hierarchy; and using the text on the
1251 <emphasis>left</emphasis> to strip off matching text from the
1252 names it will actually list in the web interface. The
1253 remaining component of a path after this stripping has
1254 occurred is called a <quote>virtual path</quote>.</para>
1256 <para id="x_4db">Given the example above, if we have a
1257 repository whose local path is <filename
1258 class="directory">/my/root/this/repo</filename>, the CGI
1259 script will strip the leading <filename
1260 class="directory">/my/root</filename> from the name, and
1261 publish the repository with a virtual path of <filename
1262 class="directory">this/repo</filename>. If the base URL for
1263 our CGI script is
1264 <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>, the
1265 complete URL for that repository will be
1266 <literal>http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para>
1268 <para id="x_4dc">If we replace <filename
1269 class="directory">/my/root</filename> on the left hand side
1270 of this example with <filename
1271 class="directory">/my</filename>, then <filename
1272 role="special">hgwebdir.cgi</filename> will only strip off
1273 <filename class="directory">/my</filename> from the repository
1274 name, and will give us a virtual path of <filename
1275 class="directory">root/this/repo</filename> instead of
1276 <filename class="directory">this/repo</filename>.</para>
1278 <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename>
1279 script will recursively search each directory listed in the
1280 <literal>collections</literal> section of its configuration
1281 file, but it will <literal>not</literal> recurse into the
1282 repositories it finds.</para>
1284 <para id="x_4de">The <literal>collections</literal> mechanism makes it easy
1285 to publish many repositories in a <quote>fire and
1286 forget</quote> manner. You only need to set up the CGI
1287 script and configuration file one time. Afterwards, you can
1288 publish or unpublish a repository at any time by simply moving
1289 it into, or out of, the directory hierarchy in which you've
1290 configured <filename role="special">hgwebdir.cgi</filename> to
1291 look.</para>
1293 <sect3>
1294 <title>Explicitly specifying which repositories to
1295 publish</title>
1297 <para id="x_4df">In addition to the <literal>collections</literal>
1298 mechanism, the <filename
1299 role="special">hgwebdir.cgi</filename> script allows you
1300 to publish a specific list of repositories. To do so,
1301 create a <literal>paths</literal> section, with contents of
1302 the following form.</para>
1303 <programlisting>[paths]
1304 repo1 = /my/path/to/some/repo
1305 repo2 = /some/path/to/another</programlisting>
1306 <para id="x_4e0">In this case, the virtual path (the component that will
1307 appear in a URL) is on the left hand side of each
1308 definition, while the path to the repository is on the
1309 right. Notice that there does not need to be any
1310 relationship between the virtual path you choose and the
1311 location of a repository in your filesystem.</para>
1313 <para id="x_4e1">If you wish, you can use both the
1314 <literal>collections</literal> and <literal>paths</literal>
1315 mechanisms simultaneously in a single configuration
1316 file.</para>
1318 <note>
1319 <title>Beware duplicate virtual paths</title>
1321 <para id="x_4e2"> If several repositories have the same
1322 virtual path, <filename
1323 role="special">hgwebdir.cgi</filename> will not report
1324 an error. Instead, it will behave unpredictably.</para>
1325 </note>
1326 </sect3>
1327 </sect2>
1329 <sect2>
1330 <title>Downloading source archives</title>
1332 <para id="x_4e3">Mercurial's web interface lets users download an archive
1333 of any revision. This archive will contain a snapshot of the
1334 working directory as of that revision, but it will not contain
1335 a copy of the repository data.</para>
1337 <para id="x_4e4">By default, this feature is not enabled. To enable it,
1338 you'll need to add an <envar
1339 role="rc-item-web">allow_archive</envar> item to the
1340 <literal role="rc-web">web</literal> section of your <filename
1341 role="special">~/.hgrc</filename>; see below for details.</para>
1342 </sect2>
1343 <sect2>
1344 <title>Web configuration options</title>
1346 <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg
1347 serve</command> command, and the <filename
1348 role="special">hgweb.cgi</filename> and <filename
1349 role="special">hgwebdir.cgi</filename> scripts) have a
1350 number of configuration options that you can set. These
1351 belong in a section named <literal
1352 role="rc-web">web</literal>.</para>
1353 <itemizedlist>
1354 <listitem><para id="x_4e6"><envar
1355 role="rc-item-web">allow_archive</envar>: Determines
1356 which (if any) archive download mechanisms Mercurial
1357 supports. If you enable this feature, users of the web
1358 interface will be able to download an archive of whatever
1359 revision of a repository they are viewing. To enable the
1360 archive feature, this item must take the form of a
1361 sequence of words drawn from the list below.</para>
1362 <itemizedlist>
1363 <listitem><para id="x_4e7"><literal>bz2</literal>: A
1364 <command>tar</command> archive, compressed using
1365 <literal>bzip2</literal> compression. This has the
1366 best compression ratio, but uses the most CPU time on
1367 the server.</para>
1368 </listitem>
1369 <listitem><para id="x_4e8"><literal>gz</literal>: A
1370 <command>tar</command> archive, compressed using
1371 <literal>gzip</literal> compression.</para>
1372 </listitem>
1373 <listitem><para id="x_4e9"><literal>zip</literal>: A
1374 <command>zip</command> archive, compressed using LZW
1375 compression. This format has the worst compression
1376 ratio, but is widely used in the Windows world.</para>
1377 </listitem>
1378 </itemizedlist>
1379 <para id="x_4ea"> If you provide an empty list, or don't have an
1380 <envar role="rc-item-web">allow_archive</envar> entry at
1381 all, this feature will be disabled. Here is an example of
1382 how to enable all three supported formats.</para>
1383 <programlisting>[web]
1384 allow_archive = bz2 gz zip</programlisting>
1385 </listitem>
1386 <listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>:
1387 Boolean. Determines whether the web interface allows
1388 remote users to <command role="hg-cmd">hg pull</command>
1389 and <command role="hg-cmd">hg clone</command> this
1390 repository over HTTP. If set to <literal>no</literal> or
1391 <literal>false</literal>, only the
1392 <quote>human-oriented</quote> portion of the web interface
1393 is available.</para>
1394 </listitem>
1395 <listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>:
1396 String. A free-form (but preferably brief) string
1397 identifying the person or group in charge of the
1398 repository. This often contains the name and email
1399 address of a person or mailing list. It often makes sense
1400 to place this entry in a repository's own <filename
1401 role="special">.hg/hgrc</filename> file, but it can make
1402 sense to use in a global <filename
1403 role="special">~/.hgrc</filename> if every repository
1404 has a single maintainer.</para>
1405 </listitem>
1406 <listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>:
1407 Integer. The default maximum number of changesets to
1408 display in a single page of output.</para>
1409 </listitem>
1410 <listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>:
1411 Integer. The default maximum number of modified files to
1412 display in a single page of output.</para>
1413 </listitem>
1414 <listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>:
1415 Integer. If the web interface displays alternating
1416 <quote>stripes</quote> to make it easier to visually align
1417 rows when you are looking at a table, this number controls
1418 the number of rows in each stripe.</para>
1419 </listitem>
1420 <listitem><para id="x_4f0"><envar
1421 role="rc-item-web">style</envar>: Controls the template
1422 Mercurial uses to display the web interface. Mercurial
1423 ships with several web templates.</para>
1424 <itemizedlist>
1425 <listitem>
1426 <para id="x_6aa"><literal>coal</literal> is monochromatic.</para>
1427 </listitem>
1428 <listitem>
1429 <para id="x_6ab"><literal>gitweb</literal> emulates the visual
1430 style of git's web interface.</para>
1431 </listitem>
1432 <listitem>
1433 <para id="x_6ac"><literal>monoblue</literal> uses solid blues and
1434 greys.</para>
1435 </listitem>
1436 <listitem>
1437 <para id="x_6ad"><literal>paper</literal> is the default.</para>
1438 </listitem>
1439 <listitem>
1440 <para id="x_6ae"><literal>spartan</literal> was the default for a
1441 long time.</para>
1442 </listitem>
1443 </itemizedlist>
1444 <para id="x_6af">You can
1445 also specify a custom template of your own; see
1446 <xref linkend="chap:template"/> for details. Here, you can
1447 see how to enable the <literal>gitweb</literal>
1448 style.</para>
1449 <programlisting>[web]
1450 style = gitweb</programlisting>
1451 </listitem>
1452 <listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>:
1453 Path. The directory in which to search for template
1454 files. By default, Mercurial searches in the directory in
1455 which it was installed.</para>
1456 </listitem></itemizedlist>
1457 <para id="x_4f2">If you are using <filename
1458 role="special">hgwebdir.cgi</filename>, you can place a few
1459 configuration items in a <literal role="rc-web">web</literal>
1460 section of the <filename
1461 role="special">hgweb.config</filename> file instead of a
1462 <filename role="special">~/.hgrc</filename> file, for
1463 convenience. These items are <envar
1464 role="rc-item-web">motd</envar> and <envar
1465 role="rc-item-web">style</envar>.</para>
1467 <sect3>
1468 <title>Options specific to an individual repository</title>
1470 <para id="x_4f3">A few <literal role="rc-web">web</literal> configuration
1471 items ought to be placed in a repository's local <filename
1472 role="special">.hg/hgrc</filename>, rather than a user's
1473 or global <filename role="special">~/.hgrc</filename>.</para>
1474 <itemizedlist>
1475 <listitem><para id="x_4f4"><envar
1476 role="rc-item-web">description</envar>: String. A
1477 free-form (but preferably brief) string that describes
1478 the contents or purpose of the repository.</para>
1479 </listitem>
1480 <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>:
1481 String. The name to use for the repository in the web
1482 interface. This overrides the default name, which is
1483 the last component of the repository's path.</para>
1484 </listitem></itemizedlist>
1485 </sect3>
1487 <sect3>
1488 <title>Options specific to the <command role="hg-cmd">hg
1489 serve</command> command</title>
1491 <para id="x_4f6">Some of the items in the <literal
1492 role="rc-web">web</literal> section of a <filename
1493 role="special">~/.hgrc</filename> file are only for use
1494 with the <command role="hg-cmd">hg serve</command>
1495 command.</para>
1496 <itemizedlist>
1497 <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>:
1498 Path. The name of a file into which to write an access
1499 log. By default, the <command role="hg-cmd">hg
1500 serve</command> command writes this information to
1501 standard output, not to a file. Log entries are written
1502 in the standard <quote>combined</quote> file format used
1503 by almost all web servers.</para>
1504 </listitem>
1505 <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>:
1506 String. The local address on which the server should
1507 listen for incoming connections. By default, the server
1508 listens on all addresses.</para>
1509 </listitem>
1510 <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>:
1511 Path. The name of a file into which to write an error
1512 log. By default, the <command role="hg-cmd">hg
1513 serve</command> command writes this information to
1514 standard error, not to a file.</para>
1515 </listitem>
1516 <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>:
1517 Boolean. Whether to use the IPv6 protocol. By default,
1518 IPv6 is not used.</para>
1519 </listitem>
1520 <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>:
1521 Integer. The TCP port number on which the server should
1522 listen. The default port number used is 8000.</para>
1523 </listitem></itemizedlist>
1524 </sect3>
1526 <sect3>
1527 <title>Choosing the right <filename
1528 role="special">~/.hgrc</filename> file to add <literal
1529 role="rc-web">web</literal> items to</title>
1531 <para id="x_4fc">It is important to remember that a web server like
1532 Apache or <literal>lighttpd</literal> will run under a user
1533 ID that is different to yours. CGI scripts run by your
1534 server, such as <filename
1535 role="special">hgweb.cgi</filename>, will usually also run
1536 under that user ID.</para>
1538 <para id="x_4fd">If you add <literal role="rc-web">web</literal> items to
1539 your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that
1540 <filename role="special">~/.hgrc</filename> file. Those
1541 settings will thus only affect the behavior of the <command
1542 role="hg-cmd">hg serve</command> command when you run it.
1543 To cause CGI scripts to see your settings, either create a
1544 <filename role="special">~/.hgrc</filename> file in the
1545 home directory of the user ID that runs your web server, or
1546 add those settings to a system-wide <filename
1547 role="special">hgrc</filename> file.</para>
1548 </sect3>
1549 </sect2>
1550 </sect1>
1552 <sect1>
1553 <title>System-wide configuration</title>
1555 <para id="x_6b0">On Unix-like systems shared by multiple users (such as a
1556 server to which people publish changes), it often makes sense to
1557 set up some global default behaviors, such as what theme to use
1558 in web interfaces.</para>
1560 <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename>
1561 exists, Mercurial will read it at startup time and apply any
1562 configuration settings it finds in that file. It will also look
1563 for files ending in a <literal>.rc</literal> extension in a
1564 directory named <filename>/etc/mercurial/hgrc.d</filename>, and
1565 apply any configuration settings it finds in each of those
1566 files.</para>
1568 <sect2>
1569 <title>Making Mercurial more trusting</title>
1571 <para id="x_6b2">One situation in which a global <filename>hgrc</filename>
1572 can be useful is if users are pulling changes owned by other
1573 users. By default, Mercurial will not trust most of the
1574 configuration items in a <filename>.hg/hgrc</filename> file
1575 inside a repository that is owned by a different user. If we
1576 clone or pull changes from such a repository, Mercurial will
1577 print a warning stating that it does not trust their
1578 <filename>.hg/hgrc</filename>.</para>
1580 <para id="x_6b3">If everyone in a particular Unix group is on the same team
1581 and <emphasis>should</emphasis> trust each other's
1582 configuration settings, or we want to trust particular users,
1583 we can override Mercurial's skeptical defaults by creating a
1584 system-wide <filename>hgrc</filename> file such as the
1585 following:</para>
1587 <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
1588 [trusted]
1589 # Trust all entries in any hgrc file owned by the "editors" or
1590 # "www-data" groups.
1591 groups = editors, www-data
1593 # Trust entries in hgrc files owned by the following users.
1594 users = apache, bobo
1595 </programlisting>
1596 </sect2>
1597 </sect1>
1598 </chapter>
1599 <!-- TODO : part 4/4 -->
1600 <!--
1601 local variables:
1602 sgml-parent-document: ("00book.xml" "book" "chapter")
1603 end:
1604 -->