hgbook
view es/collab.tex @ 417:7e838acf7350
translated more paragraphs of collab to spanish
| author | Igor TAmara <igor@tamarapatino.org> |
|---|---|
| date | Thu Nov 13 23:09:45 2008 -0500 (2008-11-13) |
| parents | c7234c5d01b2 |
| children | 7f5d542be96b |
line source
1 \chapter{Colaborar con otros}
2 \label{cha:collab}
4 Debido a su naturaleza descentralizada, Mercurial no impone política
5 alguna de cómo deben trabajar los grupos de personas. Sin embargo, si
6 usted es nuevo al control distribuido de versiones, es bueno tener
7 herramientas y ejemplos a la mano al pensar en posibles modelos de
8 flujo de trabajo.
10 \section{La interfaz web de Mercurial}
12 Mercurial tiene una poderosa interfaz web que provee bastantes
13 capacidades útiles.
15 Para uso interactivo, la interfaz le permite visualizar uno o varios
16 repositorios. Puede ver la historia de un repositorio, examinar cada
17 cambio(comentarios y diferencias), y ver los contenidos de cada
18 directorio y fichero.
20 Adicionalmente la interfaz provee feeds de RSS de los cambios de los
21 repositorios. Que le permite ``subscribirse''a un repositorio usando
22 su herramienta de lectura de feeds favorita, y ser notificado
23 automáticamente de la actividad en el repositorio tan pronto como
24 sucede. Me gusta mucho más este modelo que el estar suscrito a una
25 lista de correo a la cual se envían las notificaciones, dado que no
26 requiere configuración adicional de parte de quien sea que está
27 administrando el repositorio.
29 La interfaz web también permite clonar repositorios a los usuarios
30 remotos, jalar cambios, y (cuando el servidor está configurado para
31 permitirlo) publicar cambios en el mismo. El protocolo de tunneling
32 de Mercurial comprime datos agresivamente, de forma que trabaja
33 eficientemente incluso con conexiones de red con poco ancho de banda.
35 La forma más sencilla de iniciarse con la interfaz web es usar su
36 navegador para visitar un repositorio existente, como por ejemplo el
37 repositorio principal de Mercurial \url{http://www.selenic.com/repo/hg?style=gitweb}.
39 Si está interesado en proveer una interfaz web a sus propios
40 repositorios, Mercurial provee dos formas de hacerlo. La primera es
41 usando la orden \hgcmd{serve}, que está enfocada a servir ``de forma
42 liviana'' y por intervalos cortos. Para más detalles de cómo usar
43 esta orden vea la sección~\ref{sec:collab:serve} más adelante. Si
44 tiene un repositorio que desea hacer permanente, Mercurial tiene
45 soporte embebido del \command{ssh} para publicar cambios con seguridad
46 al repositorio central, como se documenta en la
47 sección~\ref{sec:collab:ssh}. Es muy usual que se publique una copia
48 de sólo lectura en el repositorio que está corriendo sobre HTTP usando
49 CGI, como en la sección~\ref{sec:collab:cgi}. Publicar sobre HTTP
50 satisface las necesidades de la gente que no tiene permisos de
51 publicación y de aquellos que quieren usar navegadores web para
52 visualizar la historia del repositorio.
54 \subsection{Trabajo con muchas ramas}
56 Los proyectos de cierta talla tienden naturlamente a progresar de
57 forma simultánea en varios frentes. En el caso del software, es común
58 que un proyecto tenga versiones periódicas oficiales. Una versión
59 puede entrar a ``modo mantenimiento'' por un tiempo después de su
60 primera publicación; las versiones de mantenimiento tienden a contener
61 solamente arreglos de fallos, pero no nuevas características. En
62 paralelo con las versiones de mantenimiento puede haber una o muchas
63 versiones futuras pueden estar en desarrollo. La gente usa normalmente
64 la palabra ``rama'' para referirse a una de las direcciones
65 ligeramente distintas en las cuales procede el desarrollo.
67 Mercurial está especialmente preparado para administrar un buen número
68 de ramas simultáneas pero no idénticas. Cada ``dirección de
69 desarrollo'' puede vivir en su propio repositorio central, y puede
70 mezclar los cambios de una a otra de acuerdo con las necesidades. Dado
71 que los repositorios son independientes, uno del otro, los cambios
72 inestables de una rama de desarrollo nunca afectarán una rama estable
73 a menos que alguien explícitamente mezcle los cambios.
75 A continuación un ejemplo de cómo podría hacerse esto en la
76 práctica. Digamos que tiene una ``rama principal'' en un servidor
77 central.
78 \interaction{branching.init}
79 Alguien lo clona, hace cambios locales, los prueba, y los publica allí
80 mismo.
82 Una vez que la rama principal alcanza una estado de versión se puede
83 usar la orden \hgcmd{tag} para dar un nombre permanente a la revisión.
84 \interaction{branching.tag}
85 Digamos que en la rama principal ocurre más desarrollo.
86 \interaction{branching.main}
87 Cuando se usa la etiqueta con que se identificó la versión, la gente
88 puede clonar el repositorio en cualquier momento en el futuro
89 empleando \hgcmd{update} para obtener una copia del directorio de
90 trabajo exacta como cuando se creó la etiqueta de la revisión que se
91 consignó.
92 \interaction{branching.update}
94 Adicionalmente, justo después de que la rama principal se etiquete,
95 alguien puede clonarla en el servidor a una nueva rama ``estable'',
96 también en el servidor.
97 \interaction{branching.clone}
99 Alguien que requiera hacer un cambio en la rama estable puede clonar
100 \emph{ese} repositorio, hacer sus cambios, consignar y publicarlos
101 posteriormente al inicial.
102 \interaction{branching.stable}
103 Puesto que los repositorios de Mercurial son independientes, y que
104 Mercurial no mueve los cambios de un lado a otro automáticamente, las
105 ramas estable y principal están \emph{aisladas} la una de la otra.
106 Los cambios que haga en la rama principal no ``se filtran'' a la rama
107 estable o vice versa.
109 Es usual que los arreglos de fallos de la rama estable deban hacerse
110 aparecer en la rama principal también. En lugar de reescribir el
111 arreglo del fallo en la rama principal, puede jalar y mezclar los
112 cambios de la rama estable a la principal, Mercurial traerá tales
113 arreglos por usted.
114 \interaction{branching.merge}
115 La rama principal contendtrá aún los cambios que no están en la
116 estable y contendrá además todos los arreglos de fallos de la rama
117 estable. La rama estable permanece incólume a tales cambios.
119 \subsection{Ramas de Características}
121 En proyectos grandes, una forma efectiva de administrar los cambios es
122 dividir el equipo en grupos más pequeños. Cada grupo tiene una rama
123 compartida, clonada de una rama ``principal'' que conforma el proyecto
124 completo. Aquellos que trabajan en ramas individuales típicamente
125 están aislados de los desarrollos de otras ramas.
127 \begin{figure}[ht]
128 \centering
129 \grafix{feature-branches}
130 \caption{Ramas de Características}
131 \label{fig:collab:feature-branches}
132 \end{figure}
134 Cuando una rama particular alcanza un estado deseado, alguien del
135 equipo de características jala y fusiona de la rama principal hacia
136 la rama de características y publica posteriormente a la rama principal.
138 \subsection{El tren de publicación}
140 Algunos proyectos se organizan al estilo``tren'': Una versión se
141 planifica para ser liberada cada cierto tiempo, y las características
142 que estén listas cuando ha llegado el momento ``tren'', se incorporan.
144 Este modelo tiene cierta similitud a las ramas de características. La
145 diferencia es que cuando una característica pierde el tren, alguien en
146 el equipo de características jala y fusiona los cambios que se fueron
147 en la versión liberada hacia la rama de característica, y el trabajo
148 continúa sobre lo fusionado para que la característica logre estar en
149 la próxima versión.
151 \subsection{El modelo del kernel linux}
153 El desarrollo del Kernel Linux tiene una estructura jerárquica
154 bastante horizontal, rodeada de una nube de caos aparente. Dado que la
155 mayoría de desarrolladores usan \command{git}, una herramienta distribuida
156 de control de versiones con capacidades similares a Mercurial, resulta
157 de utilidad describir la forma en que el trabajo fluye en tal
158 ambiente; si le gustan las ideas, la aproximación se traduce bien
159 entre Git y Mercurial.
161 En el centro de la comunidad está Linus Torvalds, el creador de Linux.
162 Él publica un único repositorio que es considerado el árbol
163 ``oficial'' actual por la comunidad completa de
164 desarrolladores. Cualquiera puede clonar el árbol de Linus, pero él es
165 muy selectivo acerca de los árboles de los cuales jala.
167 Linux tiene varios ``lugartenientes confiables''. Como regla, él jala
168 todos los cambios que ellos publican, en la mayoría de los casos sin
169 siquiera revisarlos. Algunos de sus lugartenientes generalmente
170 aceptan ser los ``mantenedores'', responsables de subsistemas
171 específicos dentro del kernel. Si un hacker cualquiera desea hacer un
172 cambio a un subsistema y busca que termine en el árbol de Linus, debe
173 encontrar quien es el mantenedor del subsistema y solicitarle que
174 tenga en cuenta su cambio. Si el mantenedor revisa los cambios y está
175 de acuerdo en tomarlos, estos pasarán al árbol de Linus de acuerdo a
176 lo expuesto.
178 Cada lugarteniente tiene su forma particular de revisar, aceptar y
179 publicar los cambios; y para decidir cuando hacerlos presentes a
180 Linus. Adicionalmente existen varias ramas conocidas que mucha gente
181 usa para propósitos distintos. Por ejemplo, pocas personas mantienen
182 repositorios ``estables'' de versiones anteriores del kernel, a los
183 cuales aplican arreglos de fallos críticos necesarios. Algunos
184 mantenedores publican varios árboles: uno para cambios
185 experimentales; uno para cambios que van a ofrecer al mantenedor
186 principal; y así sucesivamente. Otros publican un solo árbol.
188 Este modelo tiene dos características notables. La primera es que son
189 de ``jalar exclusivamente''. Usted debe solicitar, convencer o
190 incluso rogar a otro desarrollador para que tome sus cabmios, porque
191 casi no hay árboles en los cuales más de una persona pueda publicar, y
192 no hay forma de publicar cambios en un árbol que otra persona controla.
194 El segundo está basado en reputación y meritocracia. Si usted es un
195 desconocido, Linus probablemente ignorará sus cambios, sin siquiera
196 responderle. Pero un mantenedor de un subsistema probablemente los
197 revisara, y los acogerá en caso de que aprueben su criterio de
198 aplicabilidad. A medida que usted ofrezca ``mejores'' cambios a un
199 mantenedor, habrá más posibilidad de que se confie en su juicio y se
200 acepten los cambios. Si usted es reconocido y matiene una rama
201 durante bastante tiempo para algo que Linus no ha aceptado, personas
202 con intereses similares pueden jalar sus cambios regularmente para
203 estar al día con su trabajo.
205 La reputación y meritocracia no necesariamente es transversal entre
206 ``personas'' de diferentes subsistemas. Si usted es respetado pero es
207 un hacker en almacenamiento y trata de arreglar un fallo de redes,
208 tal cambio puede recibir un nivel de escrutinio de un mantenedor de
209 redes comparable con el que se le haría a un completo extraño.
211 Personas que vienen de proyectos con un ordenamiento distinto, sienten
212 que el proceso comparativamente caótico del Kernel Linux es
213 completamente lunático. Es objeto de los caprichos individuales; la
214 gente desecha cambios cuando lo desean; y la fase de desarrollo es
215 alucinante. A pesar de eso Linux es una pieza de software exitosa y
216 bien reconocida.
218 \subsection{Solamente jalar frente a colaboración pública}
220 Una fuente perpetua de discusiones en la comunidad de código abierto
221 yace en el modelo de desarrollo en el cual la gente solamente jala
222 cambios de otros ``es mejor que'' uno en el cual muchas personas
223 pueden publicar cambios a un repositorio compartido.
225 Tícamente los partidarios del modelo de publicar usan las herramientas
226 que se apegan a este modelo. Si usted usa una herramienta
227 centralizada de control de versiones como Subversion, no hay forma de
228 elegir qué modelo va a usar: La herramienta le ofrece publicación
229 compartida, y si desea hacer cualquier otra cosa, va a tener que
230 aplicar una aproximación artificial (tal como aplicar parches a mano).
232 Una buena herramienta distribuida de control de versiones, tal como
233 Mercurial soportará los dos modelos. Usted y sus colaboradores
234 pueden estructurar cómo trabajarán juntos basados en sus propias
235 necesidades y preferencias, sin depender de las peripecias que la
236 herramienta les obligue a hacer.
238 \subsection{Cuando la colaboración encuentra la administración ramificada}
240 Una vez que usted y su equipo configurar algunos repositorios
241 compartidos y comienzan a propagar cambios entre sus repositorios
242 locales y compartidos, comenzará a encarar un reto relacionado, pero
243 un poco distinto: Administrar las direcciones en las cuales su equipo
244 puede moverse. A pesar de que está intimamente ligado acerca de cómo
245 interactúa su equipo, es lo suficientemente denso para ameritar un
246 tratamiento en el capítulo~\ref{chap:branch}.
248 \section{Aspectos técnicos de la colaboración}
250 Lo que resta del capítulo lo dedicamos a las cuestiones de servir
251 datos a sus colaboradores.
253 \section{Compartir informalmente con \hgcmd{serve}}
254 \label{sec:collab:serve}
256 La orden \hgcmd{serve} de Mercurial satisface de forma espectacular
257 las necesidades de un grupo pequeño, acoplado y de corto
258 tiempo. Se constituye en una demostración de cómo se siente usar los
259 comandos usando la red.
261 Ejecute \hgcmd{serve} dentro de un repositorio, y en pocos segundos
262 iniciará un servidor HTTP especializado; aceptará conexiones desde
263 cualquier cliente y servirá datos de este repositorio mientrs lo
264 mantenga funcionando. Todo el que sepa el URL del servidor que ha
265 iniciado, y que puede comunicarse con su computador por la red, puede
266 usar un navegador web o Mercurial para leer datos del repositorio. Un
267 URL para una instancia de \hgcmd{serve} ejecutándose en un portátil
268 debería lucir algo \Verb|http://my-laptop.local:8000/|.
270 La orden \hgcmd{serve} \emph{no} es un servidor web de propósito
271 general. Solamente puede hacer dos cosas:
272 \begin{itemize}
273 \item Permitir que se pueda visualizar la historia del repositorio que
274 está sirviendo desde navegadores web.
275 \item Hablar el protocolo de conexión de Mercurial para que puedan hacer
276 \hgcmd{clone} o \hgcmd{pull} (jalar) cambios de tal repositorio.
277 \end{itemize}
278 En particular, \hgcmd{serve} no permitirá que los usuarios remotos
279 puedan \emph{modificar} su repositorio. Es de tipo solo lectura.
281 Si está comenzando con Mercurial, no hay nada que le impida usar
282 \hgcmd{serve} para servir un repositorio en su propio computador, y
283 usar posteriormente órdenes como \hgcmd{clone}, \hgcmd{incoming}, para
284 comunicarse con el servidor como si el repositorio estuviera alojado
285 remotamente. Lo que además puede ayudarle a adecuarse rápidamente para
286 usar comandos en repositorios alojados en la red.
288 \subsection{Cuestiones adicionales para tener en cuenta}
290 Dado que permite lectura sin autenticación a todos sus clientes,
291 debería usar \hgcmd{serve} exclusivamente en ambientes en los cuáles
292 no tenga problema en que otros vean, o en los cuales tenga control
293 completo acerca de quien puede acceder a su red y jalar cambios de su
294 repositorio.
296 La orden \hgcmd{serve} no tiene conocimiento acerca de programas
297 cortafuegos que puedan estar instalados en su sistema o en su red. No
298 puede detectar o controlar sus cortafuegos. Si otras personas no
299 pueden acceder a su instancia \hgcmd{serve}, lo siguiente que debería hacer
300 (\emph{después} de asegurarse que tienen el URL correcto) es verificar
301 su configuración de cortafuegos.
303 De forma predeterminada, \hgcmd{serve} escucha conexiones entrantes en
304 el puerto~8000. Si otro proceso está escuchando en tal puerto, usted
305 podrá especificar un puerto distinto para escuchar con la opción
306 \hgopt{serve}{-p} .
308 Normalmente, cuando se inicia \hgcmd{serve}, no imprime nada, lo cual
309 puede ser desconcertante. Si desea confirmar que en efecto está
310 ejecutándose correctamente, y darse cuenta qué URL debería enviar a
311 sus colaboradores, inícielo con la opción \hggopt{-v}.
313 \section{Using the Secure Shell (ssh) protocol}
314 \label{sec:collab:ssh}
316 You can pull and push changes securely over a network connection using
317 the Secure Shell (\texttt{ssh}) protocol. To use this successfully,
318 you may have to do a little bit of configuration on the client or
319 server sides.
321 If you're not familiar with ssh, it's a network protocol that lets you
322 securely communicate with another computer. To use it with Mercurial,
323 you'll be setting up one or more user accounts on a server so that
324 remote users can log in and execute commands.
326 (If you \emph{are} familiar with ssh, you'll probably find some of the
327 material that follows to be elementary in nature.)
329 \subsection{How to read and write ssh URLs}
331 An ssh URL tends to look like this:
332 \begin{codesample2}
333 ssh://bos@hg.serpentine.com:22/hg/hgbook
334 \end{codesample2}
335 \begin{enumerate}
336 \item The ``\texttt{ssh://}'' part tells Mercurial to use the ssh
337 protocol.
338 \item The ``\texttt{bos@}'' component indicates what username to log
339 into the server as. You can leave this out if the remote username
340 is the same as your local username.
341 \item The ``\texttt{hg.serpentine.com}'' gives the hostname of the
342 server to log into.
343 \item The ``:22'' identifies the port number to connect to the server
344 on. The default port is~22, so you only need to specify this part
345 if you're \emph{not} using port~22.
346 \item The remainder of the URL is the local path to the repository on
347 the server.
348 \end{enumerate}
350 There's plenty of scope for confusion with the path component of ssh
351 URLs, as there is no standard way for tools to interpret it. Some
352 programs behave differently than others when dealing with these paths.
353 This isn't an ideal situation, but it's unlikely to change. Please
354 read the following paragraphs carefully.
356 Mercurial treats the path to a repository on the server as relative to
357 the remote user's home directory. For example, if user \texttt{foo}
358 on the server has a home directory of \dirname{/home/foo}, then an ssh
359 URL that contains a path component of \dirname{bar}
360 \emph{really} refers to the directory \dirname{/home/foo/bar}.
362 If you want to specify a path relative to another user's home
363 directory, you can use a path that starts with a tilde character
364 followed by the user's name (let's call them \texttt{otheruser}), like
365 this.
366 \begin{codesample2}
367 ssh://server/~otheruser/hg/repo
368 \end{codesample2}
370 And if you really want to specify an \emph{absolute} path on the
371 server, begin the path component with two slashes, as in this example.
372 \begin{codesample2}
373 ssh://server//absolute/path
374 \end{codesample2}
376 \subsection{Finding an ssh client for your system}
378 Almost every Unix-like system comes with OpenSSH preinstalled. If
379 you're using such a system, run \Verb|which ssh| to find out if
380 the \command{ssh} command is installed (it's usually in
381 \dirname{/usr/bin}). In the unlikely event that it isn't present,
382 take a look at your system documentation to figure out how to install
383 it.
385 On Windows, you'll first need to choose download a suitable ssh
386 client. There are two alternatives.
387 \begin{itemize}
388 \item Simon Tatham's excellent PuTTY package~\cite{web:putty} provides
389 a complete suite of ssh client commands.
390 \item If you have a high tolerance for pain, you can use the Cygwin
391 port of OpenSSH.
392 \end{itemize}
393 In either case, you'll need to edit your \hgini\ file to tell
394 Mercurial where to find the actual client command. For example, if
395 you're using PuTTY, you'll need to use the \command{plink} command as
396 a command-line ssh client.
397 \begin{codesample2}
398 [ui]
399 ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"
400 \end{codesample2}
402 \begin{note}
403 The path to \command{plink} shouldn't contain any whitespace
404 characters, or Mercurial may not be able to run it correctly (so
405 putting it in \dirname{C:\\Program Files} is probably not a good
406 idea).
407 \end{note}
409 \subsection{Generating a key pair}
411 To avoid the need to repetitively type a password every time you need
412 to use your ssh client, I recommend generating a key pair. On a
413 Unix-like system, the \command{ssh-keygen} command will do the trick.
414 On Windows, if you're using PuTTY, the \command{puttygen} command is
415 what you'll need.
417 When you generate a key pair, it's usually \emph{highly} advisable to
418 protect it with a passphrase. (The only time that you might not want
419 to do this id when you're using the ssh protocol for automated tasks
420 on a secure network.)
422 Simply generating a key pair isn't enough, however. You'll need to
423 add the public key to the set of authorised keys for whatever user
424 you're logging in remotely as. For servers using OpenSSH (the vast
425 majority), this will mean adding the public key to a list in a file
426 called \sfilename{authorized\_keys} in their \sdirname{.ssh}
427 directory.
429 On a Unix-like system, your public key will have a \filename{.pub}
430 extension. If you're using \command{puttygen} on Windows, you can
431 save the public key to a file of your choosing, or paste it from the
432 window it's displayed in straight into the
433 \sfilename{authorized\_keys} file.
435 \subsection{Using an authentication agent}
437 An authentication agent is a daemon that stores passphrases in memory
438 (so it will forget passphrases if you log out and log back in again).
439 An ssh client will notice if it's running, and query it for a
440 passphrase. If there's no authentication agent running, or the agent
441 doesn't store the necessary passphrase, you'll have to type your
442 passphrase every time Mercurial tries to communicate with a server on
443 your behalf (e.g.~whenever you pull or push changes).
445 The downside of storing passphrases in an agent is that it's possible
446 for a well-prepared attacker to recover the plain text of your
447 passphrases, in some cases even if your system has been power-cycled.
448 You should make your own judgment as to whether this is an acceptable
449 risk. It certainly saves a lot of repeated typing.
451 On Unix-like systems, the agent is called \command{ssh-agent}, and
452 it's often run automatically for you when you log in. You'll need to
453 use the \command{ssh-add} command to add passphrases to the agent's
454 store. On Windows, if you're using PuTTY, the \command{pageant}
455 command acts as the agent. It adds an icon to your system tray that
456 will let you manage stored passphrases.
458 \subsection{Configuring the server side properly}
460 Because ssh can be fiddly to set up if you're new to it, there's a
461 variety of things that can go wrong. Add Mercurial on top, and
462 there's plenty more scope for head-scratching. Most of these
463 potential problems occur on the server side, not the client side. The
464 good news is that once you've gotten a configuration working, it will
465 usually continue to work indefinitely.
467 Before you try using Mercurial to talk to an ssh server, it's best to
468 make sure that you can use the normal \command{ssh} or \command{putty}
469 command to talk to the server first. If you run into problems with
470 using these commands directly, Mercurial surely won't work. Worse, it
471 will obscure the underlying problem. Any time you want to debug
472 ssh-related Mercurial problems, you should drop back to making sure
473 that plain ssh client commands work first, \emph{before} you worry
474 about whether there's a problem with Mercurial.
476 The first thing to be sure of on the server side is that you can
477 actually log in from another machine at all. If you can't use
478 \command{ssh} or \command{putty} to log in, the error message you get
479 may give you a few hints as to what's wrong. The most common problems
480 are as follows.
481 \begin{itemize}
482 \item If you get a ``connection refused'' error, either there isn't an
483 SSH daemon running on the server at all, or it's inaccessible due to
484 firewall configuration.
485 \item If you get a ``no route to host'' error, you either have an
486 incorrect address for the server or a seriously locked down firewall
487 that won't admit its existence at all.
488 \item If you get a ``permission denied'' error, you may have mistyped
489 the username on the server, or you could have mistyped your key's
490 passphrase or the remote user's password.
491 \end{itemize}
492 In summary, if you're having trouble talking to the server's ssh
493 daemon, first make sure that one is running at all. On many systems
494 it will be installed, but disabled, by default. Once you're done with
495 this step, you should then check that the server's firewall is
496 configured to allow incoming connections on the port the ssh daemon is
497 listening on (usually~22). Don't worry about more exotic
498 possibilities for misconfiguration until you've checked these two
499 first.
501 If you're using an authentication agent on the client side to store
502 passphrases for your keys, you ought to be able to log into the server
503 without being prompted for a passphrase or a password. If you're
504 prompted for a passphrase, there are a few possible culprits.
505 \begin{itemize}
506 \item You might have forgotten to use \command{ssh-add} or
507 \command{pageant} to store the passphrase.
508 \item You might have stored the passphrase for the wrong key.
509 \end{itemize}
510 If you're being prompted for the remote user's password, there are
511 another few possible problems to check.
512 \begin{itemize}
513 \item Either the user's home directory or their \sdirname{.ssh}
514 directory might have excessively liberal permissions. As a result,
515 the ssh daemon will not trust or read their
516 \sfilename{authorized\_keys} file. For example, a group-writable
517 home or \sdirname{.ssh} directory will often cause this symptom.
518 \item The user's \sfilename{authorized\_keys} file may have a problem.
519 If anyone other than the user owns or can write to that file, the
520 ssh daemon will not trust or read it.
521 \end{itemize}
523 In the ideal world, you should be able to run the following command
524 successfully, and it should print exactly one line of output, the
525 current date and time.
526 \begin{codesample2}
527 ssh myserver date
528 \end{codesample2}
530 If, on your server, you have login scripts that print banners or other
531 junk even when running non-interactive commands like this, you should
532 fix them before you continue, so that they only print output if
533 they're run interactively. Otherwise these banners will at least
534 clutter up Mercurial's output. Worse, they could potentially cause
535 problems with running Mercurial commands remotely. Mercurial makes
536 tries to detect and ignore banners in non-interactive \command{ssh}
537 sessions, but it is not foolproof. (If you're editing your login
538 scripts on your server, the usual way to see if a login script is
539 running in an interactive shell is to check the return code from the
540 command \Verb|tty -s|.)
542 Once you've verified that plain old ssh is working with your server,
543 the next step is to ensure that Mercurial runs on the server. The
544 following command should run successfully:
545 \begin{codesample2}
546 ssh myserver hg version
547 \end{codesample2}
548 If you see an error message instead of normal \hgcmd{version} output,
549 this is usually because you haven't installed Mercurial to
550 \dirname{/usr/bin}. Don't worry if this is the case; you don't need
551 to do that. But you should check for a few possible problems.
552 \begin{itemize}
553 \item Is Mercurial really installed on the server at all? I know this
554 sounds trivial, but it's worth checking!
555 \item Maybe your shell's search path (usually set via the \envar{PATH}
556 environment variable) is simply misconfigured.
557 \item Perhaps your \envar{PATH} environment variable is only being set
558 to point to the location of the \command{hg} executable if the login
559 session is interactive. This can happen if you're setting the path
560 in the wrong shell login script. See your shell's documentation for
561 details.
562 \item The \envar{PYTHONPATH} environment variable may need to contain
563 the path to the Mercurial Python modules. It might not be set at
564 all; it could be incorrect; or it may be set only if the login is
565 interactive.
566 \end{itemize}
568 If you can run \hgcmd{version} over an ssh connection, well done!
569 You've got the server and client sorted out. You should now be able
570 to use Mercurial to access repositories hosted by that username on
571 that server. If you run into problems with Mercurial and ssh at this
572 point, try using the \hggopt{--debug} option to get a clearer picture
573 of what's going on.
575 \subsection{Using compression with ssh}
577 Mercurial does not compress data when it uses the ssh protocol,
578 because the ssh protocol can transparently compress data. However,
579 the default behaviour of ssh clients is \emph{not} to request
580 compression.
582 Over any network other than a fast LAN (even a wireless network),
583 using compression is likely to significantly speed up Mercurial's
584 network operations. For example, over a WAN, someone measured
585 compression as reducing the amount of time required to clone a
586 particularly large repository from~51 minutes to~17 minutes.
588 Both \command{ssh} and \command{plink} accept a \cmdopt{ssh}{-C}
589 option which turns on compression. You can easily edit your \hgrc\ to
590 enable compression for all of Mercurial's uses of the ssh protocol.
591 \begin{codesample2}
592 [ui]
593 ssh = ssh -C
594 \end{codesample2}
596 If you use \command{ssh}, you can configure it to always use
597 compression when talking to your server. To do this, edit your
598 \sfilename{.ssh/config} file (which may not yet exist), as follows.
599 \begin{codesample2}
600 Host hg
601 Compression yes
602 HostName hg.example.com
603 \end{codesample2}
604 This defines an alias, \texttt{hg}. When you use it on the
605 \command{ssh} command line or in a Mercurial \texttt{ssh}-protocol
606 URL, it will cause \command{ssh} to connect to \texttt{hg.example.com}
607 and use compression. This gives you both a shorter name to type and
608 compression, each of which is a good thing in its own right.
610 \section{Serving over HTTP using CGI}
611 \label{sec:collab:cgi}
613 Depending on how ambitious you are, configuring Mercurial's CGI
614 interface can take anything from a few moments to several hours.
616 We'll begin with the simplest of examples, and work our way towards a
617 more complex configuration. Even for the most basic case, you're
618 almost certainly going to need to read and modify your web server's
619 configuration.
621 \begin{note}
622 Configuring a web server is a complex, fiddly, and highly
623 system-dependent activity. I can't possibly give you instructions
624 that will cover anything like all of the cases you will encounter.
625 Please use your discretion and judgment in following the sections
626 below. Be prepared to make plenty of mistakes, and to spend a lot
627 of time reading your server's error logs.
628 \end{note}
630 \subsection{Web server configuration checklist}
632 Before you continue, do take a few moments to check a few aspects of
633 your system's setup.
635 \begin{enumerate}
636 \item Do you have a web server installed at all? Mac OS X ships with
637 Apache, but many other systems may not have a web server installed.
638 \item If you have a web server installed, is it actually running? On
639 most systems, even if one is present, it will be disabled by
640 default.
641 \item Is your server configured to allow you to run CGI programs in
642 the directory where you plan to do so? Most servers default to
643 explicitly disabling the ability to run CGI programs.
644 \end{enumerate}
646 If you don't have a web server installed, and don't have substantial
647 experience configuring Apache, you should consider using the
648 \texttt{lighttpd} web server instead of Apache. Apache has a
649 well-deserved reputation for baroque and confusing configuration.
650 While \texttt{lighttpd} is less capable in some ways than Apache, most
651 of these capabilities are not relevant to serving Mercurial
652 repositories. And \texttt{lighttpd} is undeniably \emph{much} easier
653 to get started with than Apache.
655 \subsection{Basic CGI configuration}
657 On Unix-like systems, it's common for users to have a subdirectory
658 named something like \dirname{public\_html} in their home directory,
659 from which they can serve up web pages. A file named \filename{foo}
660 in this directory will be accessible at a URL of the form
661 \texttt{http://www.example.com/\~username/foo}.
663 To get started, find the \sfilename{hgweb.cgi} script that should be
664 present in your Mercurial installation. If you can't quickly find a
665 local copy on your system, simply download one from the master
666 Mercurial repository at
667 \url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}.
669 You'll need to copy this script into your \dirname{public\_html}
670 directory, and ensure that it's executable.
671 \begin{codesample2}
672 cp .../hgweb.cgi ~/public_html
673 chmod 755 ~/public_html/hgweb.cgi
674 \end{codesample2}
675 The \texttt{755} argument to \command{chmod} is a little more general
676 than just making the script executable: it ensures that the script is
677 executable by anyone, and that ``group'' and ``other'' write
678 permissions are \emph{not} set. If you were to leave those write
679 permissions enabled, Apache's \texttt{suexec} subsystem would likely
680 refuse to execute the script. In fact, \texttt{suexec} also insists
681 that the \emph{directory} in which the script resides must not be
682 writable by others.
683 \begin{codesample2}
684 chmod 755 ~/public_html
685 \end{codesample2}
687 \subsubsection{What could \emph{possibly} go wrong?}
688 \label{sec:collab:wtf}
690 Once you've copied the CGI script into place, go into a web browser,
691 and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi},
692 \emph{but} brace yourself for instant failure. There's a high
693 probability that trying to visit this URL will fail, and there are
694 many possible reasons for this. In fact, you're likely to stumble
695 over almost every one of the possible errors below, so please read
696 carefully. The following are all of the problems I ran into on a
697 system running Fedora~7, with a fresh installation of Apache, and a
698 user account that I created specially to perform this exercise.
700 Your web server may have per-user directories disabled. If you're
701 using Apache, search your config file for a \texttt{UserDir}
702 directive. If there's none present, per-user directories will be
703 disabled. If one exists, but its value is \texttt{disabled}, then
704 per-user directories will be disabled. Otherwise, the string after
705 \texttt{UserDir} gives the name of the subdirectory that Apache will
706 look in under your home directory, for example \dirname{public\_html}.
708 Your file access permissions may be too restrictive. The web server
709 must be able to traverse your home directory and directories under
710 your \dirname{public\_html} directory, and read files under the latter
711 too. Here's a quick recipe to help you to make your permissions more
712 appropriate.
713 \begin{codesample2}
714 chmod 755 ~
715 find ~/public_html -type d -print0 | xargs -0r chmod 755
716 find ~/public_html -type f -print0 | xargs -0r chmod 644
717 \end{codesample2}
719 The other possibility with permissions is that you might get a
720 completely empty window when you try to load the script. In this
721 case, it's likely that your access permissions are \emph{too
722 permissive}. Apache's \texttt{suexec} subsystem won't execute a
723 script that's group-~or world-writable, for example.
725 Your web server may be configured to disallow execution of CGI
726 programs in your per-user web directory. Here's Apache's
727 default per-user configuration from my Fedora system.
728 \begin{codesample2}
729 <Directory /home/*/public_html>
730 AllowOverride FileInfo AuthConfig Limit
731 Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
732 <Limit GET POST OPTIONS>
733 Order allow,deny
734 Allow from all
735 </Limit>
736 <LimitExcept GET POST OPTIONS>
737 Order deny,allow
738 Deny from all
739 </LimitExcept>
740 </Directory>
741 \end{codesample2}
742 If you find a similar-looking \texttt{Directory} group in your Apache
743 configuration, the directive to look at inside it is \texttt{Options}.
744 Add \texttt{ExecCGI} to the end of this list if it's missing, and
745 restart the web server.
747 If you find that Apache serves you the text of the CGI script instead
748 of executing it, you may need to either uncomment (if already present)
749 or add a directive like this.
750 \begin{codesample2}
751 AddHandler cgi-script .cgi
752 \end{codesample2}
754 The next possibility is that you might be served with a colourful
755 Python backtrace claiming that it can't import a
756 \texttt{mercurial}-related module. This is actually progress! The
757 server is now capable of executing your CGI script. This error is
758 only likely to occur if you're running a private installation of
759 Mercurial, instead of a system-wide version. Remember that the web
760 server runs the CGI program without any of the environment variables
761 that you take for granted in an interactive session. If this error
762 happens to you, edit your copy of \sfilename{hgweb.cgi} and follow the
763 directions inside it to correctly set your \envar{PYTHONPATH}
764 environment variable.
766 Finally, you are \emph{certain} to by served with another colourful
767 Python backtrace: this one will complain that it can't find
768 \dirname{/path/to/repository}. Edit your \sfilename{hgweb.cgi} script
769 and replace the \dirname{/path/to/repository} string with the complete
770 path to the repository you want to serve up.
772 At this point, when you try to reload the page, you should be
773 presented with a nice HTML view of your repository's history. Whew!
775 \subsubsection{Configuring lighttpd}
777 To be exhaustive in my experiments, I tried configuring the
778 increasingly popular \texttt{lighttpd} web server to serve the same
779 repository as I described with Apache above. I had already overcome
780 all of the problems I outlined with Apache, many of which are not
781 server-specific. As a result, I was fairly sure that my file and
782 directory permissions were good, and that my \sfilename{hgweb.cgi}
783 script was properly edited.
785 Once I had Apache running, getting \texttt{lighttpd} to serve the
786 repository was a snap (in other words, even if you're trying to use
787 \texttt{lighttpd}, you should read the Apache section). I first had
788 to edit the \texttt{mod\_access} section of its config file to enable
789 \texttt{mod\_cgi} and \texttt{mod\_userdir}, both of which were
790 disabled by default on my system. I then added a few lines to the end
791 of the config file, to configure these modules.
792 \begin{codesample2}
793 userdir.path = "public_html"
794 cgi.assign = ( ".cgi" => "" )
795 \end{codesample2}
796 With this done, \texttt{lighttpd} ran immediately for me. If I had
797 configured \texttt{lighttpd} before Apache, I'd almost certainly have
798 run into many of the same system-level configuration problems as I did
799 with Apache. However, I found \texttt{lighttpd} to be noticeably
800 easier to configure than Apache, even though I've used Apache for over
801 a decade, and this was my first exposure to \texttt{lighttpd}.
803 \subsection{Sharing multiple repositories with one CGI script}
805 The \sfilename{hgweb.cgi} script only lets you publish a single
806 repository, which is an annoying restriction. If you want to publish
807 more than one without wracking yourself with multiple copies of the
808 same script, each with different names, a better choice is to use the
809 \sfilename{hgwebdir.cgi} script.
811 The procedure to configure \sfilename{hgwebdir.cgi} is only a little
812 more involved than for \sfilename{hgweb.cgi}. First, you must obtain
813 a copy of the script. If you don't have one handy, you can download a
814 copy from the master Mercurial repository at
815 \url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}.
817 You'll need to copy this script into your \dirname{public\_html}
818 directory, and ensure that it's executable.
819 \begin{codesample2}
820 cp .../hgwebdir.cgi ~/public_html
821 chmod 755 ~/public_html ~/public_html/hgwebdir.cgi
822 \end{codesample2}
823 With basic configuration out of the way, try to visit
824 \url{http://myhostname/~myuser/hgwebdir.cgi} in your browser. It
825 should display an empty list of repositories. If you get a blank
826 window or error message, try walking through the list of potential
827 problems in section~\ref{sec:collab:wtf}.
829 The \sfilename{hgwebdir.cgi} script relies on an external
830 configuration file. By default, it searches for a file named
831 \sfilename{hgweb.config} in the same directory as itself. You'll need
832 to create this file, and make it world-readable. The format of the
833 file is similar to a Windows ``ini'' file, as understood by Python's
834 \texttt{ConfigParser}~\cite{web:configparser} module.
836 The easiest way to configure \sfilename{hgwebdir.cgi} is with a
837 section named \texttt{collections}. This will automatically publish
838 \emph{every} repository under the directories you name. The section
839 should look like this:
840 \begin{codesample2}
841 [collections]
842 /my/root = /my/root
843 \end{codesample2}
844 Mercurial interprets this by looking at the directory name on the
845 \emph{right} hand side of the ``\texttt{=}'' sign; finding
846 repositories in that directory hierarchy; and using the text on the
847 \emph{left} to strip off matching text from the names it will actually
848 list in the web interface. The remaining component of a path after
849 this stripping has occurred is called a ``virtual path''.
851 Given the example above, if we have a repository whose local path is
852 \dirname{/my/root/this/repo}, the CGI script will strip the leading
853 \dirname{/my/root} from the name, and publish the repository with a
854 virtual path of \dirname{this/repo}. If the base URL for our CGI
855 script is \url{http://myhostname/~myuser/hgwebdir.cgi}, the complete
856 URL for that repository will be
857 \url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}.
859 If we replace \dirname{/my/root} on the left hand side of this example
860 with \dirname{/my}, then \sfilename{hgwebdir.cgi} will only strip off
861 \dirname{/my} from the repository name, and will give us a virtual
862 path of \dirname{root/this/repo} instead of \dirname{this/repo}.
864 The \sfilename{hgwebdir.cgi} script will recursively search each
865 directory listed in the \texttt{collections} section of its
866 configuration file, but it will \texttt{not} recurse into the
867 repositories it finds.
869 The \texttt{collections} mechanism makes it easy to publish many
870 repositories in a ``fire and forget'' manner. You only need to set up
871 the CGI script and configuration file one time. Afterwards, you can
872 publish or unpublish a repository at any time by simply moving it
873 into, or out of, the directory hierarchy in which you've configured
874 \sfilename{hgwebdir.cgi} to look.
876 \subsubsection{Explicitly specifying which repositories to publish}
878 In addition to the \texttt{collections} mechanism, the
879 \sfilename{hgwebdir.cgi} script allows you to publish a specific list
880 of repositories. To do so, create a \texttt{paths} section, with
881 contents of the following form.
882 \begin{codesample2}
883 [paths]
884 repo1 = /my/path/to/some/repo
885 repo2 = /some/path/to/another
886 \end{codesample2}
887 In this case, the virtual path (the component that will appear in a
888 URL) is on the left hand side of each definition, while the path to
889 the repository is on the right. Notice that there does not need to be
890 any relationship between the virtual path you choose and the location
891 of a repository in your filesystem.
893 If you wish, you can use both the \texttt{collections} and
894 \texttt{paths} mechanisms simultaneously in a single configuration
895 file.
897 \begin{note}
898 If multiple repositories have the same virtual path,
899 \sfilename{hgwebdir.cgi} will not report an error. Instead, it will
900 behave unpredictably.
901 \end{note}
903 \subsection{Downloading source archives}
905 Mercurial's web interface lets users download an archive of any
906 revision. This archive will contain a snapshot of the working
907 directory as of that revision, but it will not contain a copy of the
908 repository data.
910 By default, this feature is not enabled. To enable it, you'll need to
911 add an \rcitem{web}{allow\_archive} item to the \rcsection{web}
912 section of your \hgrc.
914 \subsection{Web configuration options}
916 Mercurial's web interfaces (the \hgcmd{serve} command, and the
917 \sfilename{hgweb.cgi} and \sfilename{hgwebdir.cgi} scripts) have a
918 number of configuration options that you can set. These belong in a
919 section named \rcsection{web}.
920 \begin{itemize}
921 \item[\rcitem{web}{allow\_archive}] Determines which (if any) archive
922 download mechanisms Mercurial supports. If you enable this
923 feature, users of the web interface will be able to download an
924 archive of whatever revision of a repository they are viewing.
925 To enable the archive feature, this item must take the form of a
926 sequence of words drawn from the list below.
927 \begin{itemize}
928 \item[\texttt{bz2}] A \command{tar} archive, compressed using
929 \texttt{bzip2} compression. This has the best compression ratio,
930 but uses the most CPU time on the server.
931 \item[\texttt{gz}] A \command{tar} archive, compressed using
932 \texttt{gzip} compression.
933 \item[\texttt{zip}] A \command{zip} archive, compressed using LZW
934 compression. This format has the worst compression ratio, but is
935 widely used in the Windows world.
936 \end{itemize}
937 If you provide an empty list, or don't have an
938 \rcitem{web}{allow\_archive} entry at all, this feature will be
939 disabled. Here is an example of how to enable all three supported
940 formats.
941 \begin{codesample4}
942 [web]
943 allow_archive = bz2 gz zip
944 \end{codesample4}
945 \item[\rcitem{web}{allowpull}] Boolean. Determines whether the web
946 interface allows remote users to \hgcmd{pull} and \hgcmd{clone} this
947 repository over~HTTP. If set to \texttt{no} or \texttt{false}, only
948 the ``human-oriented'' portion of the web interface is available.
949 \item[\rcitem{web}{contact}] String. A free-form (but preferably
950 brief) string identifying the person or group in charge of the
951 repository. This often contains the name and email address of a
952 person or mailing list. It often makes sense to place this entry in
953 a repository's own \sfilename{.hg/hgrc} file, but it can make sense
954 to use in a global \hgrc\ if every repository has a single
955 maintainer.
956 \item[\rcitem{web}{maxchanges}] Integer. The default maximum number
957 of changesets to display in a single page of output.
958 \item[\rcitem{web}{maxfiles}] Integer. The default maximum number
959 of modified files to display in a single page of output.
960 \item[\rcitem{web}{stripes}] Integer. If the web interface displays
961 alternating ``stripes'' to make it easier to visually align rows
962 when you are looking at a table, this number controls the number of
963 rows in each stripe.
964 \item[\rcitem{web}{style}] Controls the template Mercurial uses to
965 display the web interface. Mercurial ships with two web templates,
966 named \texttt{default} and \texttt{gitweb} (the latter is much more
967 visually attractive). You can also specify a custom template of
968 your own; see chapter~\ref{chap:template} for details. Here, you
969 can see how to enable the \texttt{gitweb} style.
970 \begin{codesample4}
971 [web]
972 style = gitweb
973 \end{codesample4}
974 \item[\rcitem{web}{templates}] Path. The directory in which to search
975 for template files. By default, Mercurial searches in the directory
976 in which it was installed.
977 \end{itemize}
978 If you are using \sfilename{hgwebdir.cgi}, you can place a few
979 configuration items in a \rcsection{web} section of the
980 \sfilename{hgweb.config} file instead of a \hgrc\ file, for
981 convenience. These items are \rcitem{web}{motd} and
982 \rcitem{web}{style}.
984 \subsubsection{Options specific to an individual repository}
986 A few \rcsection{web} configuration items ought to be placed in a
987 repository's local \sfilename{.hg/hgrc}, rather than a user's or
988 global \hgrc.
989 \begin{itemize}
990 \item[\rcitem{web}{description}] String. A free-form (but preferably
991 brief) string that describes the contents or purpose of the
992 repository.
993 \item[\rcitem{web}{name}] String. The name to use for the repository
994 in the web interface. This overrides the default name, which is the
995 last component of the repository's path.
996 \end{itemize}
998 \subsubsection{Options specific to the \hgcmd{serve} command}
1000 Some of the items in the \rcsection{web} section of a \hgrc\ file are
1001 only for use with the \hgcmd{serve} command.
1002 \begin{itemize}
1003 \item[\rcitem{web}{accesslog}] Path. The name of a file into which to
1004 write an access log. By default, the \hgcmd{serve} command writes
1005 this information to standard output, not to a file. Log entries are
1006 written in the standard ``combined'' file format used by almost all
1007 web servers.
1008 \item[\rcitem{web}{address}] String. The local address on which the
1009 server should listen for incoming connections. By default, the
1010 server listens on all addresses.
1011 \item[\rcitem{web}{errorlog}] Path. The name of a file into which to
1012 write an error log. By default, the \hgcmd{serve} command writes this
1013 information to standard error, not to a file.
1014 \item[\rcitem{web}{ipv6}] Boolean. Whether to use the IPv6 protocol.
1015 By default, IPv6 is not used.
1016 \item[\rcitem{web}{port}] Integer. The TCP~port number on which the
1017 server should listen. The default port number used is~8000.
1018 \end{itemize}
1020 \subsubsection{Choosing the right \hgrc\ file to add \rcsection{web}
1021 items to}
1023 It is important to remember that a web server like Apache or
1024 \texttt{lighttpd} will run under a user~ID that is different to yours.
1025 CGI scripts run by your server, such as \sfilename{hgweb.cgi}, will
1026 usually also run under that user~ID.
1028 If you add \rcsection{web} items to your own personal \hgrc\ file, CGI
1029 scripts won't read that \hgrc\ file. Those settings will thus only
1030 affect the behaviour of the \hgcmd{serve} command when you run it. To
1031 cause CGI scripts to see your settings, either create a \hgrc\ file in
1032 the home directory of the user ID that runs your web server, or add
1033 those settings to a system-wide \hgrc\ file.
1036 %%% Local Variables:
1037 %%% mode: latex
1038 %%% TeX-master: "00book"
1039 %%% End: