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