bos@559: <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
bos@559: 
bos@559: <chapter id="cha:collab">
bos@572:   <?dbhtml filename="collaborating-with-other-people.html"?>
youshe@1009:   <title>Collaborer avec d'autres personnes</title>
youshe@1009: 
youshe@1009:   <para id="x_44a">Comme tout outil complètement décentralisé, Mercurial
youshe@1009:     n'impose pas de politique sur la façon dont les personnes devraient
youshe@1009:     travailler ensemble. Cependant, si vous êtes nouveau dans les systèmes de
youshe@1009:     gestion de révisions distribués, cela aide d'avoir des outils et exemples
youshe@1009:     en tête lorsque vous réfléchissez à de possibles modèles de
youshe@1009:     workflow.</para>
youshe@1009:   <!--TODO : workflow peut éventuellement être traduit ici par travail -->
bos@559: 
bos@559:   <sect1>
youshe@1009:     <title>Interface web de Mercurial</title>
youshe@1009: 
youshe@1009:     <para id="x_44b">Mercurial possède une interface web puissante qui
andre@1019:       propose plusieurs fonctions utiles.</para>
youshe@1009: 
youshe@1009:     <para id="x_44c">Pour une utilisation intensive, l'interface web vous
youshe@1009:       permet de naviguer dans un ou une collection de dépôt. Vous pouvez voir
youshe@1009:       l'historique d'un dépôt, examiner chaque modification (commentaires et
youshe@1009:       "diffs"), et voir le contenu de chaque répertoire et fichier. Vous
youshe@1009:       pouvez même accéder à une vue de l'historique qui vous donne une vue
youshe@1009:       graphique de la relation entre les modifications individuelles et les
youshe@1009:       fusions (merge).</para>
youshe@1009: 
andre@1019:     <para id="x_44d">De plus, pour l'utilisation humaine, l'interface web
youshe@1009:       fournit des flux Atom et RSS des changements dans un dépôt. Ceci vous
youshe@1009:       permet de <quote>souscrire</quote> à un dépôt en utilisant votre
youshe@1009:       lecteur de flux favori, et être automatiquement avertis de l'activité
youshe@1009:       dans ce dépôt aussi tôt qu'elle change. Je trouve cette fonctionnalité
youshe@1009:       bien plus commode que le modèle qui consiste à souscrire à une mailing
youshe@1009:       list à laquelle les avertissements sont envoyés, puisque cela demande
youshe@1009:       aucune configuration supplémentaire de la part de la personne qui
youshe@1009:       publie un dépôt.</para>
youshe@1009: 
youshe@1009:     <para id="x_44e">L'interface web permet aussi aux utilisateurs distants
youshe@1009:       de cloner un dépôt, récupérer (pull) les changement à partir de celui
youshe@1009:       ci, et (lorsque le serveur est configuré pour l'autoriser) lui envoyer
youshe@1009:       (push) des changements. Le protocole de tunnel HTTP de Mercurial
youshe@1009:       compresse agressivement les données, ainsi, il fonctionne efficacement,
andre@1019:       même au-dessus des réseaux avec une faible bande passante.</para>
youshe@1009: 
youshe@1009:     <para id="x_44f">La plus simple façon de démarrer avec l'interface
youshe@1009:       utilisateur est d'utiliser votre navigateur web pour visiter un dépôt
youshe@1009:       existant, tel que le dépôt principal de Mercurial à l'adresse <ulink
youshe@1009:         url="http://www.selenic.com/repo/hg">http://www.selenic.com/repo/hg</ulink>.</para>
youshe@1009: 
youshe@1009:     <para id="x_450">Si vous êtes intéressés pour proposer une interface web
youshe@1009:       de vos propres dépôts, il y a plusieurs façons de le faire.</para>
youshe@1009:     
youshe@1009:     <para id="x_69d">La façon la plus simple et la plus rapide pour commencer
youshe@1009:       dans un environnement informel est d'utiliser la commande <command
youshe@1009:         role="hg-cmd">hg serve</command> qui est la plus adaptée à un service
andre@1019:       à court terme et <quote>léger</quote>. Référez-vous à <xref
andre@1019:         linkend="sec:collab:serve"/> plus bas pour les détails d'utilisation
youshe@1009:       de cette commande.</para>
youshe@1009: 
youshe@1009:     <para id="x_69e">Pour des dépôts dont la durée de vie est plus longue, où
youshe@1009:       vous voudriez un service accessible en permanence, il existe plusieurs
youshe@1009:       services publics d'hébergement qui sont accessibles. Certains sont
youshe@1009:       libres et gratuits pour les projets Open Source, alors que d'autres
andre@1019:       offrent un hébergement commercial et payant. Une liste à jour est
youshe@1009:       disponible à l'adresse : <ulink
youshe@1009:         url="http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting">http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting</ulink>.</para>
youshe@1009: 
youshe@1009:     <para id="x_6a0">Si vous préférez héberger vos propres dépôts, Mercurial
andre@1019:       possède un support intégré pour plusieurs technologies populaires
youshe@1009:       d'hébergement, plus particulièrement CGI (Common Gateway Interface) et
andre@1019:       WSGI (Web Services Gateway Interface). Référez-vous à <xref
youshe@1009:         linkend="sec:collab:cgi"/> pour des détails sur la configuration CGI
youshe@1009:       et WSGI.</para>
bos@559:   </sect1>
bos@675: 
bos@559:   <sect1>
youshe@1009:     <title>Modèles de collaboration</title>
youshe@1009: 
andre@1019:     <para id="x_451">Avec un outil convenablement flexible, prendre des
andre@1019:       décisions sur les workflows est plus un problème d'ingénierie sociale
andre@1019:       qu'un problème technique. Mercurial impose peu de limitations sur
youshe@1009:       la façon dont vous pouvez structurer le flux de travail dans un projet,
youshe@1009:       donc, c'est à vous et votre groupe de fixer et vivre avec un modèle qui
youshe@1009:       convient à vos besoins particuliers.</para>
youshe@1009: 
youshe@1009:     <sect2>
youshe@1009:       <title>Facteurs à garder en tête</title>
youshe@1009: 
youshe@1009:       <para id="x_452">L'aspect le plus important de tout modèle que vous
youshe@1009:         devez garder en tête est la façon dont il subvient aux besoins et
youshe@1009:         capacités des personnes qui l'utiliseront. Ceci pourrait sembler
youshe@1009:         évident en soi ; pourtant, vous ne pouvez pas vous permettre de
youshe@1009:         l'oublier à un seul moment.</para>
youshe@1009: 
youshe@1009:       <para id="x_453">Une fois, j'ai mis en place un modèle de workflow qui
youshe@1009:         m'apparaissait comme parfait, mais il a causé la consternation et des
youshe@1009:         conflits au sein de mon équipe de développement. En dépit de mes
youshe@1009:         tentatives pour expliquer pourquoi nous avions besoin d'un ensemble
youshe@1009:         complexe de branches, et comment les changements devaient couler
youshe@1009:         entre eux, certains membres de l'équipe se révoltèrent. Alors qu'ils
youshe@1009:         étaient pourtant des personnes sympathiques, ils ne voulaient pas
youshe@1009:         prêter attention aux contraintes sur lesquelles nous étions en train
youshe@1009:         d'opérer, ou, face aux conséquences de ces contraintes dans les
youshe@1009:         détails du modèle que je préconisais.</para>
youshe@1009: 
youshe@1009:       <para id="x_454">Ne balayez pas les problèmes sociaux ou techniques de
andre@1019:         la main. Quelque soit le schéma que vous établirez, vous devriez
andre@1019:         planifier un protocole pour prévenir, ou rapidement vous relever de
youshe@1009:         troubles que vous pouvez anticiper. Par exemple, si vous vous
andre@1019:         attendez à avoir une branche pour les changements pas-pour-release,
andre@1019:         vous devriez penser très tôt à la possibilité qu'une personne
youshe@1009:         fusionne (merge) accidentellement ces changements avec une branche de
youshe@1009:         release. Vous pouvez empécher ce problème particulier en écrivant un
youshe@1009:         hook qui prévient les changements d'être fusionnés à partir d'une
andre@1019:         branche inopportune.</para>
youshe@1009:     </sect2>
youshe@1009: 
youshe@1009:     <sect2>
youshe@1009:       <title>Anarchie informelle</title>
youshe@1009: 
youshe@1009:       <para id="x_455">Je ne voudrais pas suggérer qu'une approche
youshe@1009:         <quote>tout peut arriver</quote> comme quelque chose de durable, mais
youshe@1009:         il s'agit d'un modèle qui est simple à saisir et qui fonctionne
youshe@1009:         parfaitement dans quelques situations inhabituelles.</para>
youshe@1009: 
youshe@1009:       <para id="x_456">Par exemple, beaucoup de projets ont un groupe distant
youshe@1009:         de collaborateurs qui ne se rencontre physiquement que très rarement.
youshe@1009:         Certains groupes aiment vaincre l'isolation du travail à distance en
youshe@1009:         organisant occasionnellement des <quote>sprints</quote>. Dans un
andre@1019:         sprint, des personnes viennent ensemble dans un même
andre@1019:         endroit (la salle de conférence d'une société, la salle de réunion
andre@1019:         d'un hôtel, ce genre d'endroit) et y passent plusieurs jours, plus ou
youshe@1009:         moins enfermés, et hackant intensément sur une poignée de
youshe@1009:         projets.</para>
youshe@1009: 
youshe@1009:       <para id="x_457">Un "sprint" ou une session de "hacking" dans un café
youshe@1009:         sont les endroits parfaits pour utiliser la commande <command
youshe@1009:           role="hg-cmd">hg serve</command> puisque <command role="hg-cmd">hg
youshe@1009:           serve</command> n'a pas besoin d'une infrastructure extraordinaire
youshe@1009:         de serveurs. Vous pouvez commencer avec la commande <command
andre@1019:           role="hg-cmd">hg serve</command> en quelques instants, en lisant <xref
youshe@1009:           linkend="sec:collab:serve"/> plus bas  Ensuite, dites simplement à
andre@1019:         la personne à côté de vous que vous exécutez un serveur, envoyez-lui
youshe@1009:         l'URL par un message instantané, et vous avez immédiatement un moyen
youshe@1009:         simple et rapide de travailler ensemble. Ils peuvent taper votre URL
andre@1019:         dans leur navigateur web et rapidement revoir vos
youshe@1009:         changements ; ou ils peuvent récupérer chez vous un bugfix et le
youshe@1009:         vérifier ; ou ils peuvent cloner une branche contenant une nouvelle
youshe@1009:         fonctionnalité et la tester.</para>
youshe@1009:         
youshe@1009:       <para id="x_458">Le charme et le problème en faisant les choses ainsi,
andre@1019:         dans un mode ad-hoc est que seules les personnes qui sont au courant
youshe@1009:         de vos changements, et de leur emplacement, peuvent les voir. Une
youshe@1009:         telle approche informelle ne passe simplement pas à l'échelle au delà
youshe@1009:         d'une poignée de personnes, puisque chacun a besoin de connaître
youshe@1009:         <emphasis>n</emphasis> différents dépôts à partir des quels récupérer
youshe@1009:         les changements (pull).</para>
youshe@1009:     </sect2>
youshe@1009: 
youshe@1009:     <sect2>
youshe@1009:       <title>Un simple dépôt central</title>
youshe@1009: 
youshe@1009:       <para id="x_459">Pour de plus petits projets qui migrent depuis un
youshe@1009:         outil de gestion de révision centralisé, la façon la
youshe@1009:         plus simple de commencer est certainement d'avoir un flux de
youshe@1009:         changement à partir d'un unique dépôt central. Il s'agit aussi du
andre@1019:         <quote>composant</quote> pour des schémas de workflow plus
youshe@1009:         ambitieux.</para>
youshe@1009: 
youshe@1009:       <para id="x_45a">Les contributeurs commencent par cloner une copie de
youshe@1009:         ce dépôt. Ils peuvent récupérer les changements à n'importe quel
youshe@1009:         moment où ils en ressentent le besoin, et certains (sûrement tous)
youshe@1009:         développeurs ont les persmissions qui leur permettent d'envoyer leurs
youshe@1009:         modifications (push) en retour lorsqu'elles sont prêtes pour que les
youshe@1009:         autres personnes puissent les voir.</para>
youshe@1009: 
youshe@1009:       <para id="x_45b">Dans ce modèle, il peut encore être sensé pour les
youshe@1009:         gens de récupérer les changements directement entre eux, sans passer
andre@1019:         par le dépôt central. Considérez le cas où j'ai un bug
andre@1019:         fix provisoire, mais je m'inquiète de savoir si, dans le cas où je le publiais,
youshe@1009:         cela ne casserait pas l'arbre des autres contributeurs s'ils la
andre@1019:         récupèreraient. Pour réduire les dommages potentiels, je peux vous
youshe@1009:         demander de cloner mon dépôt dans un dépôt temporaire qui vous
youshe@1009:         appartient et de le tester. Ceci nous permet de ne pas publier les
youshe@1009:         modification potentiellement dangereuses tant qu'elles n'ont pas
youshe@1009:         encore été un peu testées.</para>
youshe@1009: 
youshe@1009:       <para id="x_45c">Si une équipe héberge son propre dépôt dans ce type de
youshe@1009:         scénario, les personnes qui utilisent habituellement le protocole
youshe@1009:         <command>ssh</command> pour envoyer (push) en toute sécurité leurs
youshe@1009:         changements au dépôt central, comme docummenté dans <xref
youshe@1009:           linkend="sec:collab:ssh"/>. Il est aussi usuel de publier une copie
youshe@1009:         en lecture seule du dépôt sur HTTP comme dans <xref
youshe@1009:           linkend="sec:collab:cgi"/>. Publier sur HTTP satisfait le besoin
youshe@1009:         des personnes qui n'ont pas d'accès en écriture, et ceux qui veulent
youshe@1009:         utiliser leur navigateur web pour explorer l'historique du
youshe@1009:         dépôt.</para>
youshe@1009:     </sect2>
youshe@1009: 
youshe@1009:     <sect2>
youshe@1009:       <title>Un dépôt central hébergé</title>
youshe@1009: 
youshe@1009:       <para id="x_6a1">Une chose magnifique au sujet des services
youshe@1009:         d'hébergement comme <ulink
andre@1019:           url="http://bitbucket.org/">Bitbucket</ulink> est qu'ils ne gèrent
andre@1019:         pas uniquement les détails minutieux de la configuration du
andre@1019:         serveur, tels que les comptes utilisateurs, l'authentification, les
youshe@1009:         protocoles sécurisés, ils fournissent aussi une infrastructure
andre@1019:         additionnelle pour que ce modèle fonctionne
youshe@1009:         bien.</para>
youshe@1009: 
youshe@1009:       <para id="x_6a2">Par exemple, un service d'hébergement bien conçu
youshe@1009:         laissera les personnes cloner leurs copies d'un dépôt à l'aide d'un
andre@1019:         simple clic. Ceci laisse les personnes travailler dans des espaces
youshe@1009:         séparés et partager leurs changements lorsqu'ils sont prêts.</para>
youshe@1009: 
youshe@1009:       <para id="x_6a3">De plus, un bon service d'hébergement laissera les
youshe@1009:         personnes communiquer ensemble, par exemple pour dire <quote>Il y a
youshe@1009:           des changements prêts pour toi pour relecture dans cet
youshe@1009:           arbre</quote>.</para>
youshe@1009:         
youshe@1009:     </sect2>
youshe@1009: 
youshe@1009:     <sect2>
youshe@1009:       <title>Travailler avec plusieurs branches</title>
youshe@1009: 
youshe@1009:       <para id="x_45d">Les projets d'une taille significative ont tendance à
youshe@1009:         avancer sur plusieurs fronts en même temps. Dans le cas de logiciel,
youshe@1009:         il est commun qu'un projet sorte périodiquement des releases
youshe@1009:         officielles. Une release devrait ensuite aller dans le <quote>mode de
youshe@1009:           maintenance</quote> pour un moment après sa première publication ;
youshe@1009:         les releases de maintenance tendent à contenir seulement des
youshe@1009:         corrections de bugs, et non de nouvelles fonctionnalités. En
youshe@1009:         parallèle de ces releases de maintenance, une ou plusieurs futures
youshe@1009:         releases doivent être en cours de développement. Les gens utilisent
youshe@1009:         en général le mot <quote>branche</quote> pour référer à l'une de ces
youshe@1009:         nombreuses directions légèrement différentes dans lesquelles le
youshe@1009:         développement évolue.</para>
youshe@1009: 
youshe@1009:       <para id="x_45e">Mercurial est particulièrement bien adapté pour gérer
youshe@1009:         plusieurs branches simultanées mais non identiques. Chaque
youshe@1009:         <quote>direction de développement</quote> peut vivre dans son propre
youshe@1009:         dépôt central, et vous pouvez récupérez les changements de l'un ou
youshe@1009:         l'autre lorsque le besoin s'en fait sentir. Parce que les dépôts sont
andre@1019:         indépendant les uns des autres, les modifications instables dans une
youshe@1009:         branche de développement n'affecteront jamais une branche stable,
youshe@1009:         sauf si quelqu'un fusionne (merge) explicitement ces changements dans
youshe@1009:         la branche stable.</para>
youshe@1009: 
youshe@1009:       <para id="x_45f">Voici un exemple sur comment cela peut se passer en
youshe@1009:         pratique. Disons que vous avez une <quote>branche principale</quote>
youshe@1009:         sur un serveur central.</para>
bos@567: 
bos@567:       &interaction.branching.init;
bos@567: 
youshe@1009:       <para id="x_460">Les contributeurs le clonent, y apportent localement
youshe@1009:         des modifications, les testent et envoient (push) en retour leurs
youshe@1009:         changements.</para>
youshe@1009: 
youshe@1009:       <para id="x_461">Une fois que la branche principale atteint une étape
youshe@1009:         assez importante pour une release, vous pouvez utiliser la commande
youshe@1009:         <command role="hg-cmd">hg tag</command> pour donner un nom permanent
youshe@1009:         à cette étape de révision.</para>
youshe@1009:     
youshe@1009:       &interaction.branching.tag;
youshe@1009: 
andre@1019:       <para id="x_462">Disons que du developpement continue sur la
youshe@1009:         branche principale.</para>
bos@567: 
bos@567:       &interaction.branching.main;
bos@567: 
andre@1019:       <para id="x_463">En utilisant le tag enregistré à l'étape importante,
andre@1019:         les gens qui clonent ce dépôt peuvent à tout moment dans le futur
youshe@1009:         utiliser la commande <command role="hg-cmd">hg update</command> pour
youshe@1009:         avoir une copie du répertoire de travail exactement comme il était
youshe@1009:         lorsque cette révision "tag" a été committée.</para>
bos@567: 
bos@567:       &interaction.branching.update;
bos@559: 
youshe@1009:       <para id="x_464">De plus, immédiatement après que la branche principale
youshe@1009:         soit taggée, nous pouvons maintenant cloner la branche principale sur
youshe@1009:         le serveur vers une nouvelle branche <quote>stable</quote> sur le
andre@1020:         même serveur.</para>
bos@567: 
bos@567:       &interaction.branching.clone;
bos@559: 
youshe@1009:       <para id="x_465">Si nous avons besoin d'effectuer des modifications à
youshe@1009:         la branche stable, nous pouvons alors cloner <emphasis>ce</emphasis>
youshe@1009:         dépôt, effectuer nos modifications, committer, et envoyer nos
youshe@1009:         changements en retour là bas.</para>
bos@567: 
bos@567:       &interaction.branching.stable;
bos@567: 
youshe@1009:       <para id="x_466">Puisque les dépôts Mercurial sont indépendants, et que
youshe@1009:         Mercurial ne déplace pas les changements automatiquement, les
youshe@1009:         branches stable et principale sont <emphasis>isolées</emphasis> l'une
youshe@1009:         de l'autre. Les changements qui sont faits à la branche principale ne
youshe@1009:         <quote>fuient</quote> pas vers la branche stable, et vice
youshe@1009:         versa.</para>
youshe@1009: 
youshe@1009:       <para id="x_467">Nous allons souvent avoir envie que toutes nos
youshe@1009:         correction de bugs sur la branche stable soient reportées sur la
youshe@1009:         branche principale. Plutôt que de réécrire une correction de bug pour
youshe@1009:         la branche principale, nous pouvons simplement récupérer (pull) et
youshe@1009:         fusionner (merge) les changements de la branche stable vers la
youshe@1009:         branche principal, et Mercurial se débrouillera pour rapporter ces
youshe@1009:         corrections de bugs pour nous.</para>
bos@675: 
bos@675:       &interaction.branching.merge;
bos@675: 
youshe@1009:       <para id="x_468">La branche principale contiendra toujours des
youshe@1009:         changements qui ne sont pas dans la branche stable, mais elle
youshe@1009:         contiendra aussi les corrections de bugs de la branche stable. La
youshe@1009:         branche stable restera non affectée par ces changements, tant qu'ils
youshe@1009:         coulent de la branche stable vers la branche principale, et non dans
youshe@1009:         l'autre sens.</para>
bos@675:     </sect2>
bos@675: 
bos@559:     <sect2>
bos@559:       <title>Feature branches</title>
andre@1019: <!-- TODO : Branches de fonctionnalité ? -->
youshe@1009:       <para id="x_469">Pour de plus gros projets, une façon efficace de gérer
andre@1019:         les changements est de diviser l'équipe en plus petits groupes. Chaque
youshe@1009:         groupe a une branche partagée qui lui est attitrée, clonée à partir
youshe@1009:         d'une unique branche <quote>principale</quote> utilisée pour le
youshe@1009:         projet entier. Les personnes travaillant sur une branche individuelle
youshe@1009:         sont typiquement isolées des développements sur les autres
youshe@1009:         branches.</para>
bos@559: 
bos@591:       <figure id="fig:collab:feature-branches">
youshe@1009:         <title>Feature branches</title>
youshe@1009:         <mediaobject>
youshe@1009:           <imageobject><imagedata width="100%" fileref="figs/feature-branches.png"/></imageobject>
youshe@1009:           <textobject><phrase>XXX add text</phrase></textobject>
youshe@1009:         </mediaobject>
bos@591:       </figure>
bos@559: 
youshe@1009:       <para id="x_46b">Lorsqu'une fonctionnalité particulière est réputée
andre@1019:         pour être dans une forme adaptée, quelqu'un de l'équipe qui s'en occupe
andre@1019:         récupère les changements (pull) à partir de
youshe@1009:         la branche principale vers la branche de cette fonctionnalité,
youshe@1009:         fusionne (merge) et renvoie (push) le tout vers la branche
youshe@1009:         principale.</para>
youshe@1009:     </sect2>
youshe@1009: 
youshe@1009:     <sect2>
youshe@1009:       <title>Le train des releases</title>
youshe@1009: <!-- J'ai laissé train en traduction à train mais peut être que suite, file,
andre@1019: ... sont des mots qui conviennent mieux ? À méditer -->
andre@1019: <!-- Je mettrais suite -->
youshe@1009: 
youshe@1009:       <para id="x_46c">Certains projets sont organisés comme un
andre@1019:         <quote>train</quote> élémentaire : une release est planifiée tous les
youshe@1009:         quelques mois, et, toutes les fonctionnalités disponibles lorsque le
andre@1020:         <quote>train</quote> est prêt à s'arrêter sont autorisées ici.</para>
youshe@1009: 
youshe@1009:       <para id="x_46d">Ce modèle ressemble à travailler avec des branches de
youshe@1009:         fonctionnalités. La différence est que lorsqu'une branche de
youshe@1009:         fonctionnalité rate le train, quelqu'un de l'équipe qui travaille sur
youshe@1009:         cette fonctionnalité récupère (pull) et fusionne (merge) ce qui a été
youshe@1009:         ajouté à la release du train dans la branche de la fonctionnalité,
andre@1019:         puis, l'équipe continue son travail au-dessus de cette release afin
youshe@1009:         que leur fonctionnalité puisse être ajoutée à la prochaine
youshe@1009:         release.</para>
youshe@1009:     </sect2>
youshe@1009: 
youshe@1009:     <sect2>
andre@1019:       <title>Le modèle du noyau Linux</title>
youshe@1009: 
youshe@1009:       <para id="x_46e">Le développement du noyau Linux est doté d'une
youshe@1009:         structure hiérarchique superficielle, entourée par un nuage de chaos
youshe@1009:         apparent. Parce que la plupart des développeurs Linux utilisent
youshe@1009:         <command>git</command>, un outil distribué de gestion de révisions
youshe@1009:         avec des capacités similaires à celles de Mercurial, il est utile de
youshe@1009:         décrire comment le travail se déroule dans cet environnement ; si
youshe@1009:         vous aimez ces idées, l'approche se traduit correctement à travers
youshe@1009:         les outils.</para>
youshe@1009: 
andre@1019:       <para id="x_46f">Au centre de la communauté siège Linus Torvalds, le
andre@1019:         créateur de Linux. Il publie un dépôt unique de sources qui est
andre@1019:         considéré comme faisant <quote>autorité</quote> sur l'arborescence
youshe@1009:         par la communauté entière de développeurs. Tout le monde peut cloner
andre@1019:         l'arbre de Linus, mais il ne récupère (pull) pas les changements de n'importe quelle arborescence.</para>
andre@1019: 
andre@1019:       <para id="x_470">Linus a plusieurs <quote>lieutenants de
youshe@1009:           confiance</quote>. Comme règle générale, il récupère (pull) tous
youshe@1009:         les changements qu'ils publient, dans la plupart des cas sans même
youshe@1009:         relire ces modifications. Certains de ces lieutenants sont
youshe@1009:         généralement autorisés à être <quote>mainteneurs</quote>,
andre@1019:         responsables pour un sous-système spécifique du noyau. Si un 
andre@1019:         hacker du noyau veut apporter des modification au sous-système
andre@1019:         qu'il veut voir intégré à l'arbre de Linus, il doit trouver 
youshe@1009:         le mainteneur du sous-système, et lui demander de récupérer ses
youshe@1009:         changements. Si le mainteneur relit ses changements et les accepte,
youshe@1009:         ils seront transmis à Linus le moment venu.</para>
youshe@1009: 
youshe@1009:       <para id="x_471">Les lieutenants individuels ont leur propre approche
youshe@1009:         pour relire, accepter et publier les changements ; et pour décider
youshe@1009:         quand les apporter à Linus. De plus, il y a plusieurs branches
youshe@1009:         connues que les personnes utilisent pour différentes choses.
youshe@1009:         Par exemple, quelques personnes maintiennent des dépôts
youshe@1009:         <quote>stables</quote> de leurs versions du noyau, pour lesquels ils
youshe@1009:         apportent des corrections critiques lorsque nécessaire. Certains
youshe@1009:         mainteneurs publient plusieurs arbres : l'un pour les changements
youshe@1009:         expérimentaux, l'un pour les changements qu'ils vont faire remonter,
youshe@1009:         etc. D'autres ne publient qu'un unique arbre.</para>
youshe@1009: 
youshe@1009:       <para id="x_472">Ce modèle a deux caractéristiques remarquables. La
youshe@1009:         première est qu'il s'agit de <quote>pull seulement</quote>. Vous
andre@1019:         devez demander, convaincre, ou mendier auprès d'un autre développeur
andre@1019:         pour prendre vos modifications, puisqu'il n'y a vraisemblablement pas
andre@1019:         d'arbre où plus d'une personne peut envoyer des changements (push), et
youshe@1009:         qu'il n'y a pas de possibilité d'envoyer des changements (push) vers
youshe@1009:         un arbre que quelqu'un d'autre contrôle.</para>
youshe@1009: 
youshe@1009:       <para id="x_473">La seconde est que c'est basé sur la réputation et
youshe@1009:         l'acclamation. Si vous êtes un inconnu, Linus va probablement ignorer
andre@1019:         vos changements sans même répondre. Cependant, un mainteneur de
youshe@1009:         sous-système les relira probablement, et les acceptera sûrement s'ils
andre@1019:         passent ses critères d'acceptation. Plus vous enverrez du
andre@1019:         <quote>bon</quote> code à un mainteneur, et plus celui-ci aura
andre@1019:         confiance en votre jugement et acceptera vos changements. Si vous
youshe@1009:         êtes bien connu et maintenez une branche ancienne pour quelque chose
youshe@1009:         que Linus n'a pas encore accepté, les gens avec un intérêt similaire
youshe@1009:         devraient récupérer vos changements régulièrement pour rester à jour
andre@1019:         vis-à-vis de votre travail.</para>
youshe@1009: 
youshe@1009:       <para id="x_474">La réputation et l'acclamation ne nécessite pas de
andre@1019:         système croisé ou de limites <quote>entre les gens</quote>. Si vous
youshe@1009:         êtes respectés mais que vous êtes un hacker spécialisé dans la
youshe@1009:         sauvegarde, et que vous tentez de corriger un bug réseau, ce
andre@1019:         changement recevra un examen approfondi de la part du mainteneur
youshe@1009:         responsable du réseau comparable à celui d'un total étranger.</para>
youshe@1009: 
youshe@1009:       <para id="x_475">Pour les personnes qui viennent d'un projet dont
andre@1019:         le milieu est plus ordonné, le processus chaotique de
andre@1019:         développement du noyau Linux en comparaison apparaît souvent totalement
andre@1019:         dément. C'est sujet aux caprices d'individus ;
andre@1019:         des personnes font des changements considérables quand ils les
andre@1019:         jugent appropriés ; et l'allure du développement est
andre@1019:         ahurissante. Et pourtant, Linux est un bout de logiciel d'une grande
youshe@1009:         réussite et bien considéré.</para>
youshe@1009:     </sect2>
youshe@1010: 
youshe@1009:     <sect2>
youshe@1009:       <title>Collaboration pull seulement versus pull partagé</title>
bos@559: 
andre@1019:       <para id="x_476">Une source perpétuelle de heurts dans la communauté
andre@1019:         opensource est de savoir si un modèle de développement où les
andre@1019:         personnes ne peuvent que récupérer (pull) les changements d'autres est
andre@1019:         <quote>meilleur</quote> que celui dans lequel de multiples personnes peuvent
youshe@1010:         envoyer (push) leurs changements vers un dépôt partagé.</para>
youshe@1010: 
andre@1019:       <para id="x_477">Typiquement, les partisans du modèle push
youshe@1010:         partagé utilisent des outils qui renforcent activement cette
youshe@1010:         approche. Si vous utilisez un outil centralisé de gestion de révision
youshe@1010:         comme Subversion, il n'y a pas la possibilité de choisir quel modèle
youshe@1010:         utiliser : l'outil vous fournit un push partagé, et si vous voulez
youshe@1010:         faire quelque chose d'autre, vous avez à changer votre propre
youshe@1010:         approche à la base (comme appliquer les patchs manuellement).</para>
youshe@1010: 
youshe@1010:       <para id="x_478">Un bon outil de gestion distribuée de révisions doit
youshe@1010:         supporter les deux modèles. Vous et vos collaborateurs pouvez ensuite
youshe@1010:         structurer la façon dont vous travaillez ensemble en vous basant sur
andre@1019:         vos besoins et vos préférences, et non sur les contorsions que vos
youshe@1010:         outils vous forcent à effectuer.</para>
youshe@1010:     </sect2>
youshe@1010:     <sect2>
youshe@1010:       <title>Lorsque la collaboration rencontre la gestion de branches</title>
youshe@1010: 
youshe@1010:       <para id="x_479">Lorsque vous et votre équipe configurez des dépôts
youshe@1010:         partagés et commencez à propager vos changement dans tous les sens
youshe@1010:         entre les dépôts locaux et partagés, vous commencez à être face à un
andre@1019:         défi connexe, mais un peu différent : celui de gérer les
youshe@1010:         multiples directions vers lesquelles votre équipe pourrait aller au
youshe@1010:         même moment. Même si ce sujet est intimement lié à la façon dont
andre@1019:         votre équipe collabore, il est suffisement dense pour mériter un
youshe@1010:         traitement à part dans <xref linkend="chap:branch"/>.</para>
bos@559:     </sect2>
bos@559:   </sect1>
bos@675: 
bos@559:   <sect1>
andre@1019:     <title>Le côté technique du partage</title>
andre@1019: 
andre@1019:     <para id="x_47a">Le reste de ce chapitre est consacré à la question du
youshe@1010:       partage des changements avec vos collaborateurs.</para>
bos@559:   </sect1>
bos@675: 
bos@559:   <sect1 id="sec:collab:serve">
youshe@1010:     <title>Partage informel avec <command role="hg-cmd">hg
youshe@1010:     serve</command></title>
youshe@1010: 
youshe@1010:     <para id="x_47b">La commande <command role="hg-cmd">hg serve</command> de
youshe@1010:       Mercurial est magnifiquement conçue pour un environnement de petit
youshe@1010:       groupe, soudé et rapide. Elle fournit aussi un très bon moyen d'avoir
youshe@1010:       un sentiment de l'utilisation des commandes Meruciral sur un
youshe@1010:       réseau.</para>
youshe@1010: 
youshe@1010:     <para id="x_47c">Exécutez <command role="hg-cmd">hg serve</command> à
andre@1019:       l'intérieur d'un dépôt et en moins d'une seconde, cela mettra en place
youshe@1010:       un serveur HTTP spécialisé ; qui va accepter les connexions de tout
andre@1019:       client, et servir les données pour ce dépôt jusqu'à ce que vous 
andre@1019:       l'arrêtiez. Toute personne qui connaît l'URL du serveur que vous venez
youshe@1010:       de démarrer, peut ensuite utiliser un navigateur web ou Mercurial pour
youshe@1010:       lire les données de ce dépôt. Une URL pour une instance exécutée de 
youshe@1010:       <command role="hg-cmd">hg serve</command> sur un ordinateur portable
andre@1019:       ressemblera vraisemblablement à
bos@559:       <literal>http://my-laptop.local:8000/</literal>.</para>
bos@559: 
youshe@1010:     <para id="x_47d">La commande <command role="hg-cmd">hg serve</command>
youshe@1010:       <emphasis>n'</emphasis>est <emphasis>pas</emphasis> un serveur web
youshe@1010:       générique. Il ne peut faire que deux choses : </para>
bos@559:     <itemizedlist>
youshe@1010:       <listitem><para id="x_47e">Autoriser les personnes à explorer
youshe@1010:           l'historique du dépôt qu'il rend accessible, à partir d'un
youshe@1010:           navigateur web normal.</para>
bos@559:       </listitem>
youshe@1010:       <listitem><para id="x_47f">Discuter à travers le protocole de
youshe@1010:           communication de Mercurial, ainsi, les personnes peuvent exécuter <command
youshe@1010:             role="hg-cmd">hg clone</command> ou <command role="hg-cmd">hg
youshe@1010:             pull</command> sur les changements de ce dépôt.</para>
bos@559:       </listitem></itemizedlist>
youshe@1010:     <para id="x_480">En particulier, <command role="hg-cmd">hg serve</command>
youshe@1010:       ne permettra pas aux utilisateurs distants de
youshe@1010:       <emphasis>modifier</emphasis> votre dépôt. C'est destiné à une
youshe@1010:       utilisation en lecture seule.</para>
youshe@1010: 
youshe@1010:     <para id="x_481">Si vous commencez avec Mercurial, il n'y a rien qui vous
andre@1019:       empêche d'utiliser <command role="hg-cmd">hg serve</command> pour
youshe@1010:       publier un dépôt sur votre ordinateur, utilisez ensuite des commandes
youshe@1010:       telles que <command role="hg-cmd">hg clone</command>, <command
youshe@1010:         role="hg-cmd">hg incoming</command>, et ainsi de suite pour parler à
youshe@1010:       ce serveur comme si ce dépôt était hébergé à distance. Ceci peut vous
youshe@1010:       aider à rapidement familiarisé avec les commandes sur les dépôts
youshe@1010:       hébergés sur un réseau.</para>
youshe@1010: 
youshe@1010:     <sect2>
youshe@1010:       <title>Quelques choses à garder à l'esprit</title>
youshe@1010: 
andre@1019:       <para id="x_482">Puisque il fournit un accès en lecture sans
youshe@1010:         authentification à tous les clients, vous devriez utiliser la
youshe@1010:         commande <command role="hg-cmd">hg serve</command> dans un
andre@1019:         environnement où vous ne vous inquiétez pas ou vous avez
youshe@1010:         tout contrôle sur qui peut avoir accès au réseau et récupérer les
youshe@1010:         données de votre dépôt.</para>
youshe@1010: 
youshe@1010:       <para id="x_483">La commande <command role="hg-cmd">hg serve</command>
andre@1019:         ne sait rien sur un quelconque firewall que vous auriez
youshe@1010:         installé sur votre système ou réseau. Elle ne peut pas détecter ou
youshe@1010:         contrôler votre logiciel de pare-feu. Si d'autre personnes ont la
youshe@1010:         possibilité de dialoguer avec une instance de <command
andre@1019:           role="hg-cmd">hg serve</command> la seconde chose que vous devriez
youshe@1010:         faire (<emphasis>après</emphasis> être sûr qu'ils utilisent l'URL
youshe@1010:         correcte) est de vérifier la configuration de votre firewall.</para>
youshe@1010: 
youshe@1010:       <para id="x_484">Par défaut, <command role="hg-cmd">hg serve</command>
youshe@1010:         écoute pour les connexions entrantes sur le port 8000. Si un autre
youshe@1010:         processus est déjà en train d'écouter sur le port que vous voulez
youshe@1010:         écouter, vous pouvez spécifier un port différent sur lequel écouter à
youshe@1010:         l'aide de l'option <option role="hg-opt-serve">-p</option>.</para>
youshe@1010: 
youshe@1010:       <para id="x_485">Normalement, lorsque <command role="hg-cmd">hg
youshe@1010:           serve</command> se lance, il n'affiche aucune sortie, ce qui peut
youshe@1010:         être un peu énervant. Si vous voulez une confirmation que tout s'est
youshe@1010:         déroulé correctement, et connaître l'URL que vous devriez fournir à
youshe@1010:         vos collaborateurs, démarrez avec l'option <option
youshe@1010:           role="hg-opt-global">-v</option>.</para>
bos@559:     </sect2>
bos@559:   </sect1>
bos@675: 
bos@559:   <sect1 id="sec:collab:ssh">
youshe@1010:     <title>Utiliser le protocole Secure Shell (ssh)</title>
youshe@1010: 
youshe@1010:     <para id="x_486">Vous pouvez récupérer (pull) ou envoyer (push) des
andre@1019:       changements de façon sécurisé au dessus d'une connexion utilisant le
youshe@1010:       protocole Secure Shell (<literal>ssh</literal>). Pour l'utiliser avec
andre@1019:       succès, vous pourriez avoir à faire un peu de configuration du côté
youshe@1010:       client ou serveur.</para>
youshe@1010: 
youshe@1010:     <para id="x_487">Si vous n'êtes pas familiers avec ssh, c'est le nom de
youshe@1010:       la commande et d'un protocole réseau qui vous permet d'établir une
youshe@1010:       communication sécurisée avec un autre ordinateur. Pour l'utiliser avec
andre@1019:       Mercurial, vous allez configurer un ou plusieurs comptes utilisateurs
andre@1019:       sur un serveur, comme ça, les utilisateurs distants peuvent se connecter et
youshe@1010:       exécuter les commandes.</para>
youshe@1010: 
youshe@1010:     <para id="x_488">(Si vous <emphasis>êtes</emphasis> familiers avec ssh,
andre@1019:       vous allez probablement trouver quelques-unes des informations qui
youshe@1010:       suivent élémentaires par nature.)</para>
youshe@1010: 
youshe@1010:     <sect2>
youshe@1010:       <title>Comment lire et écrire des URLs ssh</title>
youshe@1010: 
andre@1019:       <para id="x_489">Une URL ssh a tendance à ressembler à ceci :</para>
bos@559:       <programlisting>ssh://bos@hg.serpentine.com:22/hg/hgbook</programlisting>
bos@559:       <orderedlist>
youshe@1010:         <listitem><para id="x_48a">Le préfixe
youshe@1010:             <quote><literal>ssh://</literal></quote> dit à Mercurial
youshe@1010:             d'utiliser le protocole ssh.</para>
youshe@1010:         </listitem>
youshe@1010:         <listitem><para id="x_48b">Le composant
youshe@1010:             <quote><literal>bos@</literal></quote> indique que le nom
andre@1019:             d'utilisateur à connecter sur le serveur. Vous pouvez le laisser
youshe@1010:             vide si le nom d'utilisateur sur le serveur distant est le même
youshe@1010:             que localement.</para>
youshe@1010:         </listitem>
youshe@1010:         <listitem><para id="x_48c">La partie
youshe@1010:             <quote><literal>hg.serpentine.com</literal></quote> donne le nom
andre@1019:             d'hôte du serveur sur lequel se connecter.</para>
youshe@1010:         </listitem>
youshe@1010:         <listitem><para id="x_48d">Le <quote>:22</quote> identifie le numéro
youshe@1010:             de port où se connecter au serveur. Le port par défaut est 22,
andre@1019:             donc vous avez besoin de spécifier ceci que si vous
youshe@1010:             <emphasis>n'</emphasis>utilisez <emphasis>pas</emphasis> le port
youshe@1010:             22.</para>
youshe@1010:         </listitem>
youshe@1010:         <listitem><para id="x_48e">Le reste de l'URL est le chemin local du
youshe@1010:             dépôt sur le serveur.</para></listitem></orderedlist>
youshe@1010:     
andre@1019:       <para id="x_48f">Il y a beaucoup de risque de confusion sur le
youshe@1010:         chemin du composant d'une URL ssh puisqu'il n'y a pas de façon
andre@1019:         standard pour les outils de l'interpréter. Certains programmes se
andre@1019:         comportent différemment des autres lorsqu'ils traitent ces chemins. Il
youshe@1010:         ne s'agit pas d'une situation idéale, mais ce n'est pas prêt de
andre@1019:         changer. Lisez les prochains paragraphes avec attention.</para>
youshe@1010: 
youshe@1010:       <para id="x_490">Mercurial traite le chemin vers un dépôt sur le
youshe@1010:         serveur comme relatif au répertoire personnel de l'utilisateur sur le
youshe@1010:         serveur distant. Par exemple, si un utilisateur
youshe@1010:         <literal>foo</literal> sur le serveur a un répertoire personnel
youshe@1010:         <filename class="directory">/home/foo</filename>, alors l'URL ssh qui
andre@1019:         contient un composant chemin de <filename
youshe@1010:           class="directory">bar</filename> réfère en
youshe@1010:         <emphasis>réalité</emphasis> au répertoire <filename
youshe@1010:           class="directory">/home/foo/bar</filename>.</para>
youshe@1010: 
andre@1019:       <para id="x_491">Si vous voulez spécifier un chemin relatif au
youshe@1010:         répertoire personnel d'un autre utilisateur, vous pouvez préciser un
andre@1019:         chemin qui commence à l'aide du caractère tilde suivi du nom de
youshe@1010:         l'utilisateur (appelons le <literal>otheruser</literal>),
youshe@1010:         ainsi.</para>
bos@559:       <programlisting>ssh://server/~otheruser/hg/repo</programlisting>
bos@559: 
youshe@1010:       <para id="x_492">Et si vous voulez vraiment spécifier un chemin
andre@1019:         <emphasis>absolu</emphasis> sur le serveur, débutez le composant
youshe@1010:         chemin par deux slashs comme dans cet exemple.</para>
bos@559:       <programlisting>ssh://server//absolute/path</programlisting>
bos@675:     </sect2>
bos@675: 
bos@559:     <sect2>
youshe@1010:       <title>Trouver un client ssh pour votre système</title>
youshe@1010: 
youshe@1010:       <para id="x_493">La plupart des systèmes du type Unix arrivent avec
youshe@1010:         OpenSSH préinstallé. Si vous utilisez un tel système, utilisez
youshe@1010:         <literal>which ssh</literal> pour trouver où la commande
youshe@1010:         <command>ssh</command> est installée (il s'agit généralement de
youshe@1010:         <filename class="directory">/usr/bin</filename>). Dans le cas peu
andre@1019:         probable où il ne serait pas présent, regarder la documentation de
youshe@1010:         votre système pour voir comment l'installer.</para>
youshe@1010: 
andre@1019:       <para id="x_494">Sous Windows, le paquet TortoiseHg est livré avec
youshe@1010:         une version de l'excellente commande <command>plink</command> de
andre@1019:         Simon Tatham, et ne devrait pas avoir besoin de plus de
youshe@1010:         configuration.</para>
youshe@1010:     </sect2>
youshe@1010: 
youshe@1010:     <sect2>
andre@1019:       <title>Créer une paire de clef</title>
youshe@1010: 
youshe@1010:       <para id="x_499">Pour éviter d'avoir à chaque fois taper un mot de
andre@1019:         passe lorsque vous utilisez votre client ssh, je recommande 
andre@1019:         de créer une paire de clefs.</para>
bos@675: 
bos@675:       <tip>
youshe@1010:         <title>Les paires de clefs ne sont pas obligatoires</title>
youshe@1010:       
youshe@1010:         <para id="x_6a4">Mercurial ne sait rien du tout de l'authentification
youshe@1010:           de ssh ou de la paire de clefs. Vous pouvez, si vous le désirez,
andre@1019:           ignorer sans risque cette section et la suivante jusqu'à ce que
andre@1019:           vous soyez fatigué de constamment retaper des mots de passe
youshe@1010:           ssh.</para>
bos@675:       </tip>
bos@675: 
bos@559:       <itemizedlist>
youshe@1010:         <listitem> <para id="x_6a5">Sur un système de type Unix, la commande
youshe@1010:             <command>ssh-keygen</command> fera l'affaire.</para></listitem>
youshe@1010:         <listitem> <para id="x_6a6">Sous Windows, si vous utilisez
andre@1019:             TortoiseHg, vous devriez avoir besoin de télécharger la commande
youshe@1010:             nommée <command>puttygen</command> à partir du <ulink
youshe@1010:               url="http://www.chiark.greenend.org.uk/~sgtatham/putty">site
andre@1019:               web de PuTTY</ulink> pour créer une paire de clefs.  Référez-vous
andre@1019:                à <ulink
youshe@1010:               url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-puttygen">la
youshe@1010:               documentation <command>puttygen</command></ulink> pour les
youshe@1010:             détails sur l'utilisation de cette commande.</para></listitem>
bos@675:       </itemizedlist>
bos@559: 
andre@1019:       <para id="x_49a">Lorsque vous créez une paire de clefs, il est
andre@1019:         habituellement <emphasis>hautement</emphasis> recommandé de la
youshe@1010:         protéger avec un mot de passe. (Le seul moment où vous pourriez ne
youshe@1010:         pas devoir le faire est lorsque vous utilisez le protocole ssh pour
youshe@1010:         des tâches automatisées sur un réseau sécurisé.)</para>
youshe@1010: 
andre@1019:       <para id="x_49b">Le simple fait de créer une paire de clefs n'est
andre@1019:         cependant pas suffisant. Vous aurez besoin d'ajouter la clef publique
andre@1019:         à l'ensemble des clefs autorisées pour tout utilisateur que vous
youshe@1010:         utilisez pour vous connecter à distance. Pour les serveurs utilisant
youshe@1010:         OpenSSh (la grande majorité), ceci voudra dire d'ajouter la clef
youshe@1010:         publique à la liste dans un fichier appelé <filename
youshe@1010:           role="special">authorized_keys</filename> dans leur répertoire
youshe@1010:         <filename role="special" class="directory">.ssh</filename>.</para>
youshe@1010: 
youshe@1010:       <para id="x_49c">Sur un système de type Unix, votre clef publique aura
youshe@1010:         l'extension <filename>.pub</filename>. Si vous utilisez la commande
youshe@1010:         <command>puttygen</command> sous Windows, vous pouvez sauvegarder la
youshe@1010:         clef publique dans un fichier que vous choisissez ou la copier à
youshe@1010:         partir de la fenêtre qui apparait directement dans le fichier
youshe@1010:         <filename role="special">authorized_keys</filename>.</para>
youshe@1010:     </sect2>
youshe@1010:     <sect2>
youshe@1010:       <title>Utiliser un agent d'authentification</title>
youshe@1010: 
youshe@1010:       <para id="x_49d">Un agent d'authentification est un démon qui
youshe@1010:         enregistre les mots de passe en mémoire (il oublira ainsi les mots de
andre@1019:         passe si vous vous déconnectez et reconnectez). Un client ssh sera averti
youshe@1010:         si un tel agent est en fonctionnement, et lui demandera un mot de
youshe@1010:         passe. S'il n'y a pas d'agent en fonctionnement, ou si l'agent ne
youshe@1010:         connaît pas le mot de passe nécessaire, vous aurez à taper votre mot
youshe@1010:         de passe chaque fois que Mercurial tente de communiquer avec un
andre@1019:         serveur en votre nom (ex. lorsque vous faite un pull ou un push 
andre@1019:         de changements).</para>
andre@1019: 
andre@1019:       <para id="x_49e">L'inconvénient de sauvegarder les mots de passes dans
youshe@1010:         un agent est qu'il est possible pour un attaquant bien préparé de
youshe@1010:         retrouver le mot de passe clair, dans certains cas, même si votre
youshe@1010:         système a été redémarré. Vous devriez vous faire votre propre
youshe@1010:         jugement pour savoir si ce risque est acceptable. Ceci vous exempte
youshe@1010:         certainement d'un tas de répétitions.</para>
bos@559: 
bos@675:       <itemizedlist>
youshe@1010:         <listitem> <para id="x_49f">Sur les systèmes de type Unix, l'agent
youshe@1010:             est appelé <command>ssh-agent</command>, et est souvent lancé
andre@1019:             automatiquement pour vous lorsque vous vous connectez. Vous aurez
youshe@1010:             besoin d'utiliser la commande <command>ssh-add</command> pour
youshe@1010:             ajouter des mots de passe à l'entrepôt de l'agent.</para>
youshe@1010:         </listitem>
youshe@1010:         <listitem>
andre@1019:           <para id="x_6a7">Sous Windows, si vous utilisez TortoiseHg, la
youshe@1010:             commande <command>pageant</command> agit comme un agent. Comme
youshe@1010:             avec <command>puttygen</command>, vous aurez besoin de <ulink
youshe@1010:               url="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">télécharger
youshe@1010:               <command>pageant</command></ulink> à partir du site web de
youshe@1010:             PuTTY et lire <ulink
youshe@1010:               url="http://the.earth.li/~sgtatham/putty/0.60/htmldoc/Chapter9.html#pageant">sa
youshe@1010:               documentation</ulink>.  La commande <command>pageant</command>
andre@1019:             ajoute une icône à votre zone de notification (à droite de la barre
andre@1019:             de tâches) qui vous permettra de
youshe@1010:             gérer les mots de passe stockés.</para></listitem>
youshe@1010:           <!-- TODO : J'ai traduit system tray par barre des tâches, mais ne
youshe@1010:           conaissant pas windows, je ne suis pas sûr du nom réel. A corriger
youshe@1010:           le cas échéant ! -->
andre@1019:           <!-- J'ai précisé avec ce que j'ai trouvé sur Wikipedia -->
bos@675:       </itemizedlist>
bos@675:     </sect2>
youshe@1010: <!-- TODO : part 2/4 -->
bos@559:     <sect2>
bos@559:       <title>Configuring the server side properly</title>
bos@559: 
bos@584:       <para id="x_4a0">Because ssh can be fiddly to set up if you're new to it,
bos@675: 	a variety of things can go wrong.  Add Mercurial
bos@559: 	on top, and there's plenty more scope for head-scratching.
bos@559: 	Most of these potential problems occur on the server side, not
bos@559: 	the client side.  The good news is that once you've gotten a
bos@559: 	configuration working, it will usually continue to work
bos@559: 	indefinitely.</para>
bos@559: 
bos@584:       <para id="x_4a1">Before you try using Mercurial to talk to an ssh server,
bos@559: 	it's best to make sure that you can use the normal
bos@559: 	<command>ssh</command> or <command>putty</command> command to
bos@559: 	talk to the server first.  If you run into problems with using
bos@559: 	these commands directly, Mercurial surely won't work.  Worse,
bos@559: 	it will obscure the underlying problem.  Any time you want to
bos@559: 	debug ssh-related Mercurial problems, you should drop back to
bos@559: 	making sure that plain ssh client commands work first,
bos@559: 	<emphasis>before</emphasis> you worry about whether there's a
bos@559: 	problem with Mercurial.</para>
bos@559: 
bos@584:       <para id="x_4a2">The first thing to be sure of on the server side is that
bos@559: 	you can actually log in from another machine at all.  If you
bos@559: 	can't use <command>ssh</command> or <command>putty</command>
bos@559: 	to log in, the error message you get may give you a few hints
bos@559: 	as to what's wrong.  The most common problems are as
bos@559: 	follows.</para>
bos@559:       <itemizedlist>
bos@584: 	<listitem><para id="x_4a3">If you get a <quote>connection refused</quote>
bos@559: 	    error, either there isn't an SSH daemon running on the
bos@559: 	    server at all, or it's inaccessible due to firewall
bos@559: 	    configuration.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_4a4">If you get a <quote>no route to host</quote>
bos@559: 	    error, you either have an incorrect address for the server
bos@559: 	    or a seriously locked down firewall that won't admit its
bos@559: 	    existence at all.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_4a5">If you get a <quote>permission denied</quote>
bos@559: 	    error, you may have mistyped the username on the server,
bos@559: 	    or you could have mistyped your key's passphrase or the
bos@559: 	    remote user's password.</para>
bos@559: 	</listitem></itemizedlist>
bos@584:       <para id="x_4a6">In summary, if you're having trouble talking to the
bos@559: 	server's ssh daemon, first make sure that one is running at
bos@559: 	all.  On many systems it will be installed, but disabled, by
bos@559: 	default.  Once you're done with this step, you should then
bos@559: 	check that the server's firewall is configured to allow
bos@559: 	incoming connections on the port the ssh daemon is listening
bos@559: 	on (usually 22).  Don't worry about more exotic possibilities
bos@559: 	for misconfiguration until you've checked these two
bos@559: 	first.</para>
bos@584:       <para id="x_4a7">If you're using an authentication agent on the client side
bos@559: 	to store passphrases for your keys, you ought to be able to
bos@559: 	log into the server without being prompted for a passphrase or
bos@559: 	a password.  If you're prompted for a passphrase, there are a
bos@559: 	few possible culprits.</para>
bos@559:       <itemizedlist>
bos@584: 	<listitem><para id="x_4a8">You might have forgotten to use
bos@559: 	    <command>ssh-add</command> or <command>pageant</command>
bos@559: 	    to store the passphrase.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_4a9">You might have stored the passphrase for the
bos@559: 	    wrong key.</para>
bos@559: 	</listitem></itemizedlist>
bos@584:       <para id="x_4aa">If you're being prompted for the remote user's password,
bos@559: 	there are another few possible problems to check.</para>
bos@559:       <itemizedlist>
bos@584: 	<listitem><para id="x_4ab">Either the user's home directory or their
bos@559: 	    <filename role="special" class="directory">.ssh</filename>
bos@559: 	    directory might have excessively liberal permissions.  As
bos@559: 	    a result, the ssh daemon will not trust or read their
bos@559: 	    <filename role="special">authorized_keys</filename> file.
bos@559: 	    For example, a group-writable home or <filename
bos@559: 	      role="special" class="directory">.ssh</filename>
bos@559: 	    directory will often cause this symptom.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_4ac">The user's <filename
bos@559: 	      role="special">authorized_keys</filename> file may have
bos@559: 	    a problem. If anyone other than the user owns or can write
bos@559: 	    to that file, the ssh daemon will not trust or read
bos@559: 	    it.</para>
bos@559: 	</listitem></itemizedlist>
bos@559: 
bos@584:       <para id="x_4ad">In the ideal world, you should be able to run the
bos@559: 	following command successfully, and it should print exactly
bos@559: 	one line of output, the current date and time.</para>
bos@559:       <programlisting>ssh myserver date</programlisting>
bos@559: 
bos@584:       <para id="x_4ae">If, on your server, you have login scripts that print
bos@559: 	banners or other junk even when running non-interactive
bos@559: 	commands like this, you should fix them before you continue,
bos@559: 	so that they only print output if they're run interactively.
bos@559: 	Otherwise these banners will at least clutter up Mercurial's
bos@559: 	output.  Worse, they could potentially cause problems with
bos@701: 	running Mercurial commands remotely.  Mercurial tries to
bos@559: 	detect and ignore banners in non-interactive
bos@559: 	<command>ssh</command> sessions, but it is not foolproof.  (If
bos@559: 	you're editing your login scripts on your server, the usual
bos@559: 	way to see if a login script is running in an interactive
bos@559: 	shell is to check the return code from the command
bos@559: 	<literal>tty -s</literal>.)</para>
bos@559: 
bos@584:       <para id="x_4af">Once you've verified that plain old ssh is working with
bos@559: 	your server, the next step is to ensure that Mercurial runs on
bos@559: 	the server.  The following command should run
bos@559: 	successfully:</para>
bos@580: 
bos@559:       <programlisting>ssh myserver hg version</programlisting>
bos@580: 
bos@584:       <para id="x_4b0">If you see an error message instead of normal <command
bos@559: 	  role="hg-cmd">hg version</command> output, this is usually
bos@559: 	because you haven't installed Mercurial to <filename
bos@559: 	  class="directory">/usr/bin</filename>.  Don't worry if this
bos@559: 	is the case; you don't need to do that.  But you should check
bos@559: 	for a few possible problems.</para>
bos@559:       <itemizedlist>
bos@584: 	<listitem><para id="x_4b1">Is Mercurial really installed on the server at
bos@559: 	    all?  I know this sounds trivial, but it's worth
bos@559: 	    checking!</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_4b2">Maybe your shell's search path (usually set
bos@559: 	    via the <envar>PATH</envar> environment variable) is
bos@559: 	    simply misconfigured.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_4b3">Perhaps your <envar>PATH</envar> environment
bos@559: 	    variable is only being set to point to the location of the
bos@559: 	    <command>hg</command> executable if the login session is
bos@559: 	    interactive.  This can happen if you're setting the path
bos@559: 	    in the wrong shell login script.  See your shell's
bos@559: 	    documentation for details.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_4b4">The <envar>PYTHONPATH</envar> environment
bos@559: 	    variable may need to contain the path to the Mercurial
bos@559: 	    Python modules.  It might not be set at all; it could be
bos@559: 	    incorrect; or it may be set only if the login is
bos@559: 	    interactive.</para>
bos@559: 	</listitem></itemizedlist>
bos@559: 
bos@584:       <para id="x_4b5">If you can run <command role="hg-cmd">hg version</command>
bos@559: 	over an ssh connection, well done! You've got the server and
bos@559: 	client sorted out.  You should now be able to use Mercurial to
bos@559: 	access repositories hosted by that username on that server.
bos@559: 	If you run into problems with Mercurial and ssh at this point,
bos@559: 	try using the <option role="hg-opt-global">--debug</option>
bos@559: 	option to get a clearer picture of what's going on.</para>
bos@559:     </sect2>
bos@559:     <sect2>
bos@559:       <title>Using compression with ssh</title>
bos@559: 
bos@584:       <para id="x_4b6">Mercurial does not compress data when it uses the ssh
bos@559: 	protocol, because the ssh protocol can transparently compress
bos@672: 	data.  However, the default behavior of ssh clients is
bos@559: 	<emphasis>not</emphasis> to request compression.</para>
bos@559: 
bos@584:       <para id="x_4b7">Over any network other than a fast LAN (even a wireless
bos@559: 	network), using compression is likely to significantly speed
bos@559: 	up Mercurial's network operations.  For example, over a WAN,
bos@559: 	someone measured compression as reducing the amount of time
bos@559: 	required to clone a particularly large repository from 51
bos@559: 	minutes to 17 minutes.</para>
bos@559: 
bos@584:       <para id="x_4b8">Both <command>ssh</command> and <command>plink</command>
bos@559: 	accept a <option role="cmd-opt-ssh">-C</option> option which
bos@559: 	turns on compression.  You can easily edit your <filename
bos@580: 	  role="special">~/.hgrc</filename> to enable compression for
bos@675: 	all of Mercurial's uses of the ssh protocol.  Here is how to
bos@675: 	do so for regular <command>ssh</command> on Unix-like systems,
bos@675: 	for example.</para>
bos@579:       <programlisting>[ui]
bos@579: ssh = ssh -C</programlisting>
bos@559: 
bos@675:       <para id="x_4b9">If you use <command>ssh</command> on a
bos@675: 	Unix-like system, you can configure it to always use
bos@675: 	compression when talking to your server.  To do this, edit
bos@675: 	your <filename role="special">.ssh/config</filename> file
bos@675: 	(which may not yet exist), as follows.</para>
bos@675: 
bos@579:       <programlisting>Host hg
bos@579:   Compression yes
bos@579:   HostName hg.example.com</programlisting>
bos@675: 
bos@675:       <para id="x_4ba">This defines a hostname alias,
bos@675: 	<literal>hg</literal>.  When you use that hostname on the
bos@675: 	<command>ssh</command> command line or in a Mercurial
bos@675: 	<literal>ssh</literal>-protocol URL, it will cause
bos@559: 	<command>ssh</command> to connect to
bos@559: 	<literal>hg.example.com</literal> and use compression.  This
bos@559: 	gives you both a shorter name to type and compression, each of
bos@559: 	which is a good thing in its own right.</para>
bos@559:     </sect2>
bos@559:   </sect1>
bos@675: 
bos@559:   <sect1 id="sec:collab:cgi">
bos@559:     <title>Serving over HTTP using CGI</title>
bos@559: 
bos@676:     <para id="x_6a8">The simplest way to host one or more repositories in a
bos@675:       permanent way is to use a web server and Mercurial's CGI
bos@675:       support.</para>
bos@675: 
bos@584:     <para id="x_4bb">Depending on how ambitious you are, configuring Mercurial's
bos@559:       CGI interface can take anything from a few moments to several
bos@559:       hours.</para>
bos@559: 
bos@584:     <para id="x_4bc">We'll begin with the simplest of examples, and work our way
bos@559:       towards a more complex configuration.  Even for the most basic
bos@559:       case, you're almost certainly going to need to read and modify
bos@559:       your web server's configuration.</para>
bos@559: 
bos@559:     <note>
bos@675:       <title>High pain tolerance required</title>
bos@675: 
bos@675:       <para id="x_4bd">Configuring a web server is a complex, fiddly,
bos@675: 	and highly system-dependent activity.  I can't possibly give
bos@675: 	you instructions that will cover anything like all of the
bos@675: 	cases you will encounter. Please use your discretion and
bos@675: 	judgment in following the sections below.  Be prepared to make
bos@675: 	plenty of mistakes, and to spend a lot of time reading your
bos@675: 	server's error logs.</para>
bos@675: 
bos@676:       <para id="x_6a9">If you don't have a strong stomach for tweaking
bos@675: 	configurations over and over, or a compelling need to host
bos@675: 	your own services, you might want to try one of the public
bos@675: 	hosting services that I mentioned earlier.</para>
bos@559:     </note>
bos@559: 
bos@559:     <sect2>
bos@559:       <title>Web server configuration checklist</title>
bos@559: 
bos@584:       <para id="x_4be">Before you continue, do take a few moments to check a few
bos@559: 	aspects of your system's setup.</para>
bos@559: 
bos@559:       <orderedlist>
bos@675: 	<listitem><para id="x_4bf">Do you have a web server installed
bos@675: 	    at all? Mac OS X and some Linux distributions ship with
bos@675: 	    Apache, but many other systems may not have a web server
bos@675: 	    installed.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_4c0">If you have a web server installed, is it
bos@559: 	    actually running?  On most systems, even if one is
bos@559: 	    present, it will be disabled by default.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_4c1">Is your server configured to allow you to run
bos@559: 	    CGI programs in the directory where you plan to do so?
bos@559: 	    Most servers default to explicitly disabling the ability
bos@559: 	    to run CGI programs.</para>
bos@559: 	</listitem></orderedlist>
bos@559: 
bos@584:       <para id="x_4c2">If you don't have a web server installed, and don't have
bos@559: 	substantial experience configuring Apache, you should consider
bos@559: 	using the <literal>lighttpd</literal> web server instead of
bos@559: 	Apache.  Apache has a well-deserved reputation for baroque and
bos@559: 	confusing configuration. While <literal>lighttpd</literal> is
bos@559: 	less capable in some ways than Apache, most of these
bos@559: 	capabilities are not relevant to serving Mercurial
bos@559: 	repositories.  And <literal>lighttpd</literal> is undeniably
bos@559: 	<emphasis>much</emphasis> easier to get started with than
bos@559: 	Apache.</para>
bos@675:     </sect2>
bos@675: 
bos@559:     <sect2>
bos@559:       <title>Basic CGI configuration</title>
bos@559: 
bos@584:       <para id="x_4c3">On Unix-like systems, it's common for users to have a
bos@559: 	subdirectory named something like <filename
bos@559: 	  class="directory">public_html</filename> in their home
bos@559: 	directory, from which they can serve up web pages.  A file
bos@559: 	named <filename>foo</filename> in this directory will be
bos@559: 	accessible at a URL of the form
bos@580: 	<literal>http://www.example.com/username/foo</literal>.</para>
bos@559: 
bos@584:       <para id="x_4c4">To get started, find the <filename
bos@559: 	  role="special">hgweb.cgi</filename> script that should be
bos@559: 	present in your Mercurial installation.  If you can't quickly
bos@559: 	find a local copy on your system, simply download one from the
bos@559: 	master Mercurial repository at <ulink
bos@559: 	  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>
bos@559: 
bos@584:       <para id="x_4c5">You'll need to copy this script into your <filename
bos@559: 	  class="directory">public_html</filename> directory, and
bos@559: 	ensure that it's executable.</para>
bos@579:       <programlisting>cp .../hgweb.cgi ~/public_html
bos@579: chmod 755 ~/public_html/hgweb.cgi</programlisting>
bos@584:       <para id="x_4c6">The <literal>755</literal> argument to
bos@559: 	<command>chmod</command> is a little more general than just
bos@559: 	making the script executable: it ensures that the script is
bos@559: 	executable by anyone, and that <quote>group</quote> and
bos@559: 	<quote>other</quote> write permissions are
bos@559: 	<emphasis>not</emphasis> set.  If you were to leave those
bos@559: 	write permissions enabled, Apache's <literal>suexec</literal>
bos@559: 	subsystem would likely refuse to execute the script.  In fact,
bos@559: 	<literal>suexec</literal> also insists that the
bos@559: 	<emphasis>directory</emphasis> in which the script resides
bos@559: 	must not be writable by others.</para>
bos@559:       <programlisting>chmod 755 ~/public_html</programlisting>
bos@559: 
bos@559:       <sect3 id="sec:collab:wtf">
bos@559: 	<title>What could <emphasis>possibly</emphasis> go
bos@559: 	  wrong?</title>
bos@559: 
hg@677: 	<para id="x_4c7">Once you've copied the CGI script into place,
bos@679: 	  go into a web browser, and try to open the URL
bos@679: 	  <literal>http://myhostname/~myuser/hgweb.cgi</literal>,
bos@679: 	  <emphasis>but</emphasis> brace yourself for instant failure.
bos@679: 	  There's a high probability that trying to visit this URL
bos@679: 	  will fail, and there are many possible reasons for this.  In
bos@679: 	  fact, you're likely to stumble over almost every one of the
bos@679: 	  possible errors below, so please read carefully.  The
bos@679: 	  following are all of the problems I ran into on a system
bos@679: 	  running Fedora 7, with a fresh installation of Apache, and a
bos@679: 	  user account that I created specially to perform this
bos@679: 	  exercise.</para>
bos@559: 
bos@584: 	<para id="x_4c8">Your web server may have per-user directories disabled.
bos@559: 	  If you're using Apache, search your config file for a
bos@559: 	  <literal>UserDir</literal> directive.  If there's none
bos@559: 	  present, per-user directories will be disabled.  If one
bos@559: 	  exists, but its value is <literal>disabled</literal>, then
bos@559: 	  per-user directories will be disabled.  Otherwise, the
bos@559: 	  string after <literal>UserDir</literal> gives the name of
bos@559: 	  the subdirectory that Apache will look in under your home
bos@559: 	  directory, for example <filename
bos@559: 	    class="directory">public_html</filename>.</para>
bos@559: 
bos@584: 	<para id="x_4c9">Your file access permissions may be too restrictive.
bos@559: 	  The web server must be able to traverse your home directory
bos@559: 	  and directories under your <filename
bos@559: 	    class="directory">public_html</filename> directory, and
bos@559: 	  read files under the latter too.  Here's a quick recipe to
bos@559: 	  help you to make your permissions more appropriate.</para>
bos@579: 	<programlisting>chmod 755 ~
bos@579: find ~/public_html -type d -print0 | xargs -0r chmod 755
bos@579: find ~/public_html -type f -print0 | xargs -0r chmod 644</programlisting>
bos@559: 
bos@584: 	<para id="x_4ca">The other possibility with permissions is that you might
bos@559: 	  get a completely empty window when you try to load the
bos@559: 	  script.  In this case, it's likely that your access
ori@561: 	  permissions are <emphasis>too permissive</emphasis>.  Apache's
bos@559: 	  <literal>suexec</literal> subsystem won't execute a script
bos@559: 	  that's group- or world-writable, for example.</para>
bos@559: 
bos@584: 	<para id="x_4cb">Your web server may be configured to disallow execution
bos@559: 	  of CGI programs in your per-user web directory.  Here's
bos@559: 	  Apache's default per-user configuration from my Fedora
bos@559: 	  system.</para>
bos@579: 
bos@579: 	&ch06-apache-config.lst;
bos@579: 
bos@584: 	<para id="x_4cc">If you find a similar-looking
bos@559: 	  <literal>Directory</literal> group in your Apache
bos@559: 	  configuration, the directive to look at inside it is
bos@559: 	  <literal>Options</literal>. Add <literal>ExecCGI</literal>
bos@559: 	  to the end of this list if it's missing, and restart the web
bos@559: 	  server.</para>
bos@559: 
bos@584: 	<para id="x_4cd">If you find that Apache serves you the text of the CGI
bos@559: 	  script instead of executing it, you may need to either
bos@559: 	  uncomment (if already present) or add a directive like
bos@559: 	  this.</para>
bos@559: 	<programlisting>AddHandler cgi-script .cgi</programlisting>
bos@559: 
bos@584: 	<para id="x_4ce">The next possibility is that you might be served with a
bos@559: 	  colourful Python backtrace claiming that it can't import a
bos@559: 	  <literal>mercurial</literal>-related module.  This is
bos@559: 	  actually progress!  The server is now capable of executing
bos@559: 	  your CGI script.  This error is only likely to occur if
bos@559: 	  you're running a private installation of Mercurial, instead
bos@559: 	  of a system-wide version.  Remember that the web server runs
bos@559: 	  the CGI program without any of the environment variables
bos@559: 	  that you take for granted in an interactive session.  If
bos@559: 	  this error happens to you, edit your copy of <filename
bos@559: 	    role="special">hgweb.cgi</filename> and follow the
bos@559: 	  directions inside it to correctly set your
bos@559: 	  <envar>PYTHONPATH</envar> environment variable.</para>
bos@559: 
bos@701: 	<para id="x_4cf">Finally, you are <emphasis>certain</emphasis> to be
bos@559: 	  served with another colourful Python backtrace: this one
bos@559: 	  will complain that it can't find <filename
bos@559: 	    class="directory">/path/to/repository</filename>.  Edit
bos@559: 	  your <filename role="special">hgweb.cgi</filename> script
bos@559: 	  and replace the <filename
bos@559: 	    class="directory">/path/to/repository</filename> string
bos@559: 	  with the complete path to the repository you want to serve
bos@559: 	  up.</para>
bos@559: 
bos@584: 	<para id="x_4d0">At this point, when you try to reload the page, you
bos@559: 	  should be presented with a nice HTML view of your
bos@559: 	  repository's history.  Whew!</para>
bos@559:       </sect3>
bos@675: 
bos@559:       <sect3>
bos@559: 	<title>Configuring lighttpd</title>
bos@559: 
bos@584: 	<para id="x_4d1">To be exhaustive in my experiments, I tried configuring
bos@559: 	  the increasingly popular <literal>lighttpd</literal> web
bos@559: 	  server to serve the same repository as I described with
bos@559: 	  Apache above.  I had already overcome all of the problems I
bos@559: 	  outlined with Apache, many of which are not server-specific.
bos@559: 	  As a result, I was fairly sure that my file and directory
bos@559: 	  permissions were good, and that my <filename
bos@559: 	    role="special">hgweb.cgi</filename> script was properly
bos@559: 	  edited.</para>
bos@559: 
bos@584: 	<para id="x_4d2">Once I had Apache running, getting
bos@559: 	  <literal>lighttpd</literal> to serve the repository was a
bos@559: 	  snap (in other words, even if you're trying to use
bos@559: 	  <literal>lighttpd</literal>, you should read the Apache
bos@559: 	  section).  I first had to edit the
bos@559: 	  <literal>mod_access</literal> section of its config file to
bos@559: 	  enable <literal>mod_cgi</literal> and
bos@559: 	  <literal>mod_userdir</literal>, both of which were disabled
bos@559: 	  by default on my system.  I then added a few lines to the
bos@559: 	  end of the config file, to configure these modules.</para>
bos@580: 	<programlisting>userdir.path = "public_html"
bos@580: cgi.assign = (".cgi" =&gt; "" )</programlisting>
bos@584: 	<para id="x_4d3">With this done, <literal>lighttpd</literal> ran
bos@559: 	  immediately for me.  If I had configured
bos@559: 	  <literal>lighttpd</literal> before Apache, I'd almost
bos@559: 	  certainly have run into many of the same system-level
bos@559: 	  configuration problems as I did with Apache.  However, I
bos@559: 	  found <literal>lighttpd</literal> to be noticeably easier to
bos@559: 	  configure than Apache, even though I've used Apache for over
bos@559: 	  a decade, and this was my first exposure to
bos@559: 	  <literal>lighttpd</literal>.</para>
bos@559:       </sect3>
bos@559:     </sect2>
youshe@1009: <!-- TODO : part 3/4 -->
bos@559:     <sect2>
bos@559:       <title>Sharing multiple repositories with one CGI script</title>
bos@559: 
bos@584:       <para id="x_4d4">The <filename role="special">hgweb.cgi</filename> script
bos@559: 	only lets you publish a single repository, which is an
bos@559: 	annoying restriction.  If you want to publish more than one
bos@559: 	without wracking yourself with multiple copies of the same
bos@559: 	script, each with different names, a better choice is to use
bos@559: 	the <filename role="special">hgwebdir.cgi</filename>
bos@559: 	script.</para>
bos@559: 
bos@584:       <para id="x_4d5">The procedure to configure <filename
bos@559: 	  role="special">hgwebdir.cgi</filename> is only a little more
bos@559: 	involved than for <filename
bos@559: 	  role="special">hgweb.cgi</filename>.  First, you must obtain
bos@559: 	a copy of the script.  If you don't have one handy, you can
bos@559: 	download a copy from the master Mercurial repository at <ulink
bos@559: 	  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>
bos@559: 
bos@584:       <para id="x_4d6">You'll need to copy this script into your <filename
bos@559: 	  class="directory">public_html</filename> directory, and
bos@559: 	ensure that it's executable.</para>
bos@592: 
bos@580:       <programlisting>cp .../hgwebdir.cgi ~/public_html
bos@580: chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
bos@592: 
bos@592:       <para id="x_4d7">With basic configuration out of the way, try to
bos@679: 	visit <literal>http://myhostname/~myuser/hgwebdir.cgi</literal>
hg@677: 	in your	browser.  It should
bos@559: 	display an empty list of repositories.  If you get a blank
bos@559: 	window or error message, try walking through the list of
bos@592: 	potential problems in <xref
bos@559: 	  linkend="sec:collab:wtf"/>.</para>
bos@559: 
bos@584:       <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename>
bos@559: 	script relies on an external configuration file.  By default,
bos@559: 	it searches for a file named <filename
bos@559: 	  role="special">hgweb.config</filename> in the same directory
bos@559: 	as itself.  You'll need to create this file, and make it
bos@559: 	world-readable.  The format of the file is similar to a
bos@559: 	Windows <quote>ini</quote> file, as understood by Python's
bos@559: 	<literal>ConfigParser</literal>
bos@559: 	<citation>web:configparser</citation> module.</para>
bos@559: 
bos@584:       <para id="x_4d9">The easiest way to configure <filename
bos@559: 	  role="special">hgwebdir.cgi</filename> is with a section
bos@559: 	named <literal>collections</literal>.  This will automatically
bos@559: 	publish <emphasis>every</emphasis> repository under the
bos@559: 	directories you name.  The section should look like
bos@559: 	this:</para>
bos@580:       <programlisting>[collections]
bos@580: /my/root = /my/root</programlisting>
bos@584:       <para id="x_4da">Mercurial interprets this by looking at the directory name
bos@559: 	on the <emphasis>right</emphasis> hand side of the
bos@559: 	<quote><literal>=</literal></quote> sign; finding repositories
bos@559: 	in that directory hierarchy; and using the text on the
bos@559: 	<emphasis>left</emphasis> to strip off matching text from the
bos@559: 	names it will actually list in the web interface.  The
bos@559: 	remaining component of a path after this stripping has
bos@559: 	occurred is called a <quote>virtual path</quote>.</para>
bos@559: 
bos@679:       <para id="x_4db">Given the example above, if we have a
bos@679: 	repository whose local path is <filename
bos@559: 	  class="directory">/my/root/this/repo</filename>, the CGI
bos@559: 	script will strip the leading <filename
bos@559: 	  class="directory">/my/root</filename> from the name, and
bos@559: 	publish the repository with a virtual path of <filename
bos@559: 	  class="directory">this/repo</filename>.  If the base URL for
bos@679: 	our CGI script is
bos@679: 	<literal>http://myhostname/~myuser/hgwebdir.cgi</literal>, the
bos@679: 	complete URL for that repository will be
bos@679: 	<literal>http://myhostname/~myuser/hgwebdir.cgi/this/repo</literal>.</para>
bos@559: 
bos@584:       <para id="x_4dc">If we replace <filename
bos@559: 	  class="directory">/my/root</filename> on the left hand side
bos@559: 	of this example with <filename
bos@559: 	  class="directory">/my</filename>, then <filename
bos@559: 	  role="special">hgwebdir.cgi</filename> will only strip off
bos@559: 	<filename class="directory">/my</filename> from the repository
bos@559: 	name, and will give us a virtual path of <filename
bos@559: 	  class="directory">root/this/repo</filename> instead of
bos@559: 	<filename class="directory">this/repo</filename>.</para>
bos@559: 
bos@584:       <para id="x_4dd">The <filename role="special">hgwebdir.cgi</filename>
bos@559: 	script will recursively search each directory listed in the
bos@559: 	<literal>collections</literal> section of its configuration
bos@559: 	file, but it will <literal>not</literal> recurse into the
bos@559: 	repositories it finds.</para>
bos@559: 
bos@584:       <para id="x_4de">The <literal>collections</literal> mechanism makes it easy
bos@559: 	to publish many repositories in a <quote>fire and
bos@559: 	  forget</quote> manner.  You only need to set up the CGI
bos@559: 	script and configuration file one time.  Afterwards, you can
bos@559: 	publish or unpublish a repository at any time by simply moving
bos@559: 	it into, or out of, the directory hierarchy in which you've
bos@559: 	configured <filename role="special">hgwebdir.cgi</filename> to
bos@559: 	look.</para>
bos@559: 
bos@559:       <sect3>
bos@559: 	<title>Explicitly specifying which repositories to
bos@559: 	  publish</title>
bos@559: 
bos@584: 	<para id="x_4df">In addition to the <literal>collections</literal>
bos@559: 	  mechanism, the <filename
bos@559: 	    role="special">hgwebdir.cgi</filename> script allows you
bos@559: 	  to publish a specific list of repositories.  To do so,
bos@559: 	  create a <literal>paths</literal> section, with contents of
bos@559: 	  the following form.</para>
bos@580: 	<programlisting>[paths]
bos@580: repo1 = /my/path/to/some/repo
bos@580: repo2 = /some/path/to/another</programlisting>
bos@584: 	<para id="x_4e0">In this case, the virtual path (the component that will
bos@559: 	  appear in a URL) is on the left hand side of each
bos@559: 	  definition, while the path to the repository is on the
bos@559: 	  right.  Notice that there does not need to be any
bos@559: 	  relationship between the virtual path you choose and the
bos@559: 	  location of a repository in your filesystem.</para>
bos@559: 
bos@584: 	<para id="x_4e1">If you wish, you can use both the
bos@559: 	  <literal>collections</literal> and <literal>paths</literal>
bos@559: 	  mechanisms simultaneously in a single configuration
bos@559: 	  file.</para>
bos@559: 
bos@559: 	<note>
bos@675: 	  <title>Beware duplicate virtual paths</title>
bos@675: 
bos@675: 	  <para id="x_4e2">  If several repositories have the same
bos@675: 	    virtual path, <filename
bos@675: 	      role="special">hgwebdir.cgi</filename> will not report
bos@675: 	    an error.  Instead, it will behave unpredictably.</para>
bos@559: 	</note>
bos@559:       </sect3>
bos@559:     </sect2>
bos@675: 
bos@559:     <sect2>
bos@559:       <title>Downloading source archives</title>
bos@559: 
bos@584:       <para id="x_4e3">Mercurial's web interface lets users download an archive
bos@559: 	of any revision.  This archive will contain a snapshot of the
bos@559: 	working directory as of that revision, but it will not contain
bos@559: 	a copy of the repository data.</para>
bos@559: 
bos@584:       <para id="x_4e4">By default, this feature is not enabled.  To enable it,
bos@559: 	you'll need to add an <envar
bos@559: 	  role="rc-item-web">allow_archive</envar> item to the
bos@559: 	<literal role="rc-web">web</literal> section of your <filename
bos@675: 	  role="special">~/.hgrc</filename>; see below for details.</para>
bos@559:     </sect2>
bos@559:     <sect2>
bos@559:       <title>Web configuration options</title>
bos@559: 
bos@584:       <para id="x_4e5">Mercurial's web interfaces (the <command role="hg-cmd">hg
bos@559: 	  serve</command> command, and the <filename
bos@559: 	  role="special">hgweb.cgi</filename> and <filename
bos@559: 	  role="special">hgwebdir.cgi</filename> scripts) have a
bos@559: 	number of configuration options that you can set.  These
bos@559: 	belong in a section named <literal
bos@559: 	  role="rc-web">web</literal>.</para>
bos@559:       <itemizedlist>
bos@584: 	<listitem><para id="x_4e6"><envar
bos@559: 	      role="rc-item-web">allow_archive</envar>: Determines
bos@559: 	    which (if any) archive download mechanisms Mercurial
bos@559: 	    supports.  If you enable this feature, users of the web
bos@559: 	    interface will be able to download an archive of whatever
bos@559: 	    revision of a repository they are viewing. To enable the
bos@559: 	    archive feature, this item must take the form of a
bos@559: 	    sequence of words drawn from the list below.</para>
bos@559: 	  <itemizedlist>
bos@584: 	    <listitem><para id="x_4e7"><literal>bz2</literal>: A
bos@559: 		<command>tar</command> archive, compressed using
bos@559: 		<literal>bzip2</literal> compression.  This has the
bos@559: 		best compression ratio, but uses the most CPU time on
bos@559: 		the server.</para>
bos@559: 	    </listitem>
bos@584: 	    <listitem><para id="x_4e8"><literal>gz</literal>: A
bos@559: 		<command>tar</command> archive, compressed using
bos@559: 		<literal>gzip</literal> compression.</para>
bos@559: 	    </listitem>
bos@584: 	    <listitem><para id="x_4e9"><literal>zip</literal>: A
bos@559: 		<command>zip</command> archive, compressed using LZW
bos@559: 		compression.  This format has the worst compression
bos@559: 		ratio, but is widely used in the Windows world.</para>
bos@559: 	    </listitem>
bos@559: 	  </itemizedlist>
bos@584: 	  <para id="x_4ea">  If you provide an empty list, or don't have an
bos@559: 	    <envar role="rc-item-web">allow_archive</envar> entry at
bos@559: 	    all, this feature will be disabled.  Here is an example of
bos@559: 	    how to enable all three supported formats.</para>
bos@580: 	  <programlisting>[web]
bos@580: allow_archive = bz2 gz zip</programlisting>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_4eb"><envar role="rc-item-web">allowpull</envar>:
bos@559: 	    Boolean.  Determines whether the web interface allows
bos@559: 	    remote users to <command role="hg-cmd">hg pull</command>
bos@559: 	    and <command role="hg-cmd">hg clone</command> this
bos@559: 	    repository over HTTP.  If set to <literal>no</literal> or
bos@559: 	    <literal>false</literal>, only the
bos@559: 	    <quote>human-oriented</quote> portion of the web interface
bos@559: 	    is available.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_4ec"><envar role="rc-item-web">contact</envar>:
bos@559: 	    String.  A free-form (but preferably brief) string
bos@559: 	    identifying the person or group in charge of the
bos@559: 	    repository.  This often contains the name and email
bos@559: 	    address of a person or mailing list.  It often makes sense
bos@559: 	    to place this entry in a repository's own <filename
bos@559: 	      role="special">.hg/hgrc</filename> file, but it can make
bos@580: 	    sense to use in a global <filename
bos@580: 	      role="special">~/.hgrc</filename> if every repository
bos@580: 	    has a single maintainer.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_4ed"><envar role="rc-item-web">maxchanges</envar>:
bos@559: 	    Integer.  The default maximum number of changesets to
bos@559: 	    display in a single page of output.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_4ee"><envar role="rc-item-web">maxfiles</envar>:
bos@559: 	    Integer.  The default maximum number of modified files to
bos@559: 	    display in a single page of output.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_4ef"><envar role="rc-item-web">stripes</envar>:
bos@559: 	    Integer.  If the web interface displays alternating
bos@559: 	    <quote>stripes</quote> to make it easier to visually align
bos@559: 	    rows when you are looking at a table, this number controls
bos@559: 	    the number of rows in each stripe.</para>
bos@559: 	</listitem>
bos@592: 	<listitem><para id="x_4f0"><envar
bos@592: 	      role="rc-item-web">style</envar>: Controls the template
bos@592: 	    Mercurial uses to display the web interface.  Mercurial
bos@675: 	    ships with several web templates.</para>
bos@675: 	  <itemizedlist>
bos@675: 	    <listitem>
bos@676: 	      <para id="x_6aa"><literal>coal</literal> is monochromatic.</para>
bos@675: 	    </listitem>
bos@675: 	    <listitem>
bos@676: 	      <para id="x_6ab"><literal>gitweb</literal> emulates the visual
bos@675: 		style of git's web interface.</para>
bos@675: 	    </listitem>
bos@675: 	    <listitem>
bos@676: 	      <para id="x_6ac"><literal>monoblue</literal> uses solid blues and
bos@675: 		greys.</para>
bos@675: 	    </listitem>
bos@675: 	    <listitem>
bos@676: 	      <para id="x_6ad"><literal>paper</literal> is the default.</para>
bos@675: 	    </listitem>
bos@675: 	    <listitem>
bos@676: 	      <para id="x_6ae"><literal>spartan</literal> was the default for a
bos@675: 		long time.</para>
bos@675: 	    </listitem>
bos@675: 	  </itemizedlist>
bos@676: 	  <para id="x_6af">You can
bos@592: 	    also specify a custom template of your own; see 
bos@592: 	    <xref linkend="chap:template"/> for details. Here, you can
bos@592: 	    see how to enable the <literal>gitweb</literal>
bos@592: 	    style.</para>
bos@580: 	  <programlisting>[web]
bos@580: style = gitweb</programlisting>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>:
bos@559: 	    Path.  The directory in which to search for template
bos@559: 	    files.  By default, Mercurial searches in the directory in
bos@559: 	    which it was installed.</para>
bos@559: 	</listitem></itemizedlist>
bos@584:       <para id="x_4f2">If you are using <filename
bos@559: 	  role="special">hgwebdir.cgi</filename>, you can place a few
bos@559: 	configuration items in a <literal role="rc-web">web</literal>
bos@559: 	section of the <filename
bos@559: 	  role="special">hgweb.config</filename> file instead of a
bos@580: 	<filename role="special">~/.hgrc</filename> file, for
bos@559: 	convenience.  These items are <envar
bos@559: 	  role="rc-item-web">motd</envar> and <envar
bos@559: 	  role="rc-item-web">style</envar>.</para>
bos@559: 
bos@559:       <sect3>
bos@559: 	<title>Options specific to an individual repository</title>
bos@559: 
bos@584: 	<para id="x_4f3">A few <literal role="rc-web">web</literal> configuration
bos@559: 	  items ought to be placed in a repository's local <filename
bos@559: 	    role="special">.hg/hgrc</filename>, rather than a user's
bos@580: 	  or global <filename role="special">~/.hgrc</filename>.</para>
bos@559: 	<itemizedlist>
bos@584: 	  <listitem><para id="x_4f4"><envar
bos@559: 		role="rc-item-web">description</envar>: String.  A
bos@559: 	      free-form (but preferably brief) string that describes
bos@559: 	      the contents or purpose of the repository.</para>
bos@559: 	  </listitem>
bos@584: 	  <listitem><para id="x_4f5"><envar role="rc-item-web">name</envar>:
bos@559: 	      String.  The name to use for the repository in the web
bos@559: 	      interface.  This overrides the default name, which is
bos@559: 	      the last component of the repository's path.</para>
bos@559: 	  </listitem></itemizedlist>
bos@559:       </sect3>
bos@675: 
bos@559:       <sect3>
bos@559: 	<title>Options specific to the <command role="hg-cmd">hg
bos@559: 	    serve</command> command</title>
bos@559: 
bos@584: 	<para id="x_4f6">Some of the items in the <literal
bos@559: 	    role="rc-web">web</literal> section of a <filename
bos@580: 	    role="special">~/.hgrc</filename> file are only for use
bos@559: 	  with the <command role="hg-cmd">hg serve</command>
bos@559: 	  command.</para>
bos@559: 	<itemizedlist>
bos@584: 	  <listitem><para id="x_4f7"><envar role="rc-item-web">accesslog</envar>:
bos@559: 	      Path.  The name of a file into which to write an access
bos@559: 	      log.  By default, the <command role="hg-cmd">hg
bos@559: 		serve</command> command writes this information to
bos@559: 	      standard output, not to a file.  Log entries are written
bos@559: 	      in the standard <quote>combined</quote> file format used
bos@559: 	      by almost all web servers.</para>
bos@559: 	  </listitem>
bos@584: 	  <listitem><para id="x_4f8"><envar role="rc-item-web">address</envar>:
bos@559: 	      String.  The local address on which the server should
bos@559: 	      listen for incoming connections.  By default, the server
bos@559: 	      listens on all addresses.</para>
bos@559: 	  </listitem>
bos@584: 	  <listitem><para id="x_4f9"><envar role="rc-item-web">errorlog</envar>:
bos@559: 	      Path.  The name of a file into which to write an error
bos@559: 	      log.  By default, the <command role="hg-cmd">hg
bos@559: 		serve</command> command writes this information to
bos@559: 	      standard error, not to a file.</para>
bos@559: 	  </listitem>
bos@584: 	  <listitem><para id="x_4fa"><envar role="rc-item-web">ipv6</envar>:
bos@559: 	      Boolean.  Whether to use the IPv6 protocol. By default,
bos@559: 	      IPv6 is not used.</para>
bos@559: 	  </listitem>
bos@584: 	  <listitem><para id="x_4fb"><envar role="rc-item-web">port</envar>:
bos@559: 	      Integer.  The TCP port number on which the server should
bos@559: 	      listen.  The default port number used is 8000.</para>
bos@559: 	  </listitem></itemizedlist>
bos@559:       </sect3>
bos@675: 
bos@559:       <sect3>
bos@580: 	<title>Choosing the right <filename
bos@580: 	    role="special">~/.hgrc</filename> file to add <literal
bos@559: 	    role="rc-web">web</literal> items to</title>
bos@559: 
bos@584: 	<para id="x_4fc">It is important to remember that a web server like
bos@559: 	  Apache or <literal>lighttpd</literal> will run under a user
bos@559: 	  ID that is different to yours. CGI scripts run by your
bos@559: 	  server, such as <filename
bos@559: 	    role="special">hgweb.cgi</filename>, will usually also run
bos@559: 	  under that user ID.</para>
bos@559: 
bos@584: 	<para id="x_4fd">If you add <literal role="rc-web">web</literal> items to
bos@580: 	  your own personal <filename role="special">~/.hgrc</filename> file, CGI scripts won't read that
bos@580: 	  <filename role="special">~/.hgrc</filename> file.  Those
bos@672: 	  settings will thus only affect the behavior of the <command
bos@559: 	    role="hg-cmd">hg serve</command> command when you run it.
bos@559: 	  To cause CGI scripts to see your settings, either create a
bos@580: 	  <filename role="special">~/.hgrc</filename> file in the
bos@559: 	  home directory of the user ID that runs your web server, or
bos@559: 	  add those settings to a system-wide <filename
bos@675: 	    role="special">hgrc</filename> file.</para>
bos@559:       </sect3>
bos@559:     </sect2>
bos@559:   </sect1>
bos@675: 
bos@675:   <sect1>
bos@675:     <title>System-wide configuration</title>
bos@675: 
bos@676:     <para id="x_6b0">On Unix-like systems shared by multiple users (such as a
bos@675:       server to which people publish changes), it often makes sense to
bos@675:       set up some global default behaviors, such as what theme to use
bos@675:       in web interfaces.</para>
bos@675: 
bos@676:     <para id="x_6b1">If a file named <filename>/etc/mercurial/hgrc</filename>
bos@675:       exists, Mercurial will read it at startup time and apply any
bos@675:       configuration settings it finds in that file.  It will also look
bos@675:       for files ending in a <literal>.rc</literal> extension in a
bos@675:       directory named <filename>/etc/mercurial/hgrc.d</filename>, and
bos@675:       apply any configuration settings it finds in each of those
bos@675:       files.</para>
bos@675: 
bos@675:     <sect2>
bos@675:       <title>Making Mercurial more trusting</title>
bos@675: 
bos@676:       <para id="x_6b2">One situation in which a global <filename>hgrc</filename>
bos@675: 	can be useful is if users are pulling changes owned by other
bos@675: 	users.  By default, Mercurial will not trust most of the
bos@675: 	configuration items in a <filename>.hg/hgrc</filename> file
bos@675: 	inside a repository that is owned by a different user. If we
bos@675: 	clone or pull changes from such a repository, Mercurial will
bos@675: 	print a warning stating that it does not trust their
bos@675: 	<filename>.hg/hgrc</filename>.</para>
bos@675: 
bos@676:       <para id="x_6b3">If everyone in a particular Unix group is on the same team
bos@675: 	and <emphasis>should</emphasis> trust each other's
bos@675: 	configuration settings, or we want to trust particular users,
bos@675: 	we can override Mercurial's skeptical defaults by creating a
bos@675: 	system-wide <filename>hgrc</filename> file such as the
bos@675: 	following:</para>
bos@675: 
bos@675:     <programlisting># Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
bos@675: [trusted]
bos@675: # Trust all entries in any hgrc file owned by the "editors" or
bos@675: # "www-data" groups.
bos@675: groups = editors, www-data
bos@675: 
bos@675: # Trust entries in hgrc files owned by the following users.
bos@675: users = apache, bobo
bos@675: </programlisting>
bos@675:     </sect2>
bos@675:   </sect1>
bos@559: </chapter>
youshe@1009: <!-- TODO : part 4/4 -->
bos@559: <!--
bos@559: local variables: 
bos@559: sgml-parent-document: ("00book.xml" "book" "chapter")
bos@559: end:
bos@559: -->