annotate es/collab.tex @ 511:a9ea523446cc

Started translating collab chapter to spanish
author Igor TAmara <igor@tamarapatino.org>
date Mon, 10 Nov 2008 23:38:36 -0500
parents b05e35d641e4
children c7234c5d01b2
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
1 \chapter{Colaborar con otros}
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
2 \label{cha:collab}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
3
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
4 Debido a su naturaleza descentralizada, Mercurial no impone política
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
5 alguna de cómo deben trabajar los grupos de personas. Sin embargo, si
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
6 usted es nuvo al control distribuido de versiones, es bueno tener
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
7 herramientas y ejemplos a la mano al pensar en posibles modelos de
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
8 flujo de trabajo.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
9
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
10 \section{La interfaz web de Mercurial}
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
11
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
12 Mercurial tiene una poderosa interfaz web que provee bastantes
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
13 capacidades útiles.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
14
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
15 Para uso interactivo, la interfaz le permite visualizar uno o varios
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
16 repositorios. Puede ver la historia de un repositorio, examinar cada
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
17 cambio(comentarios y diferencias), y ver los contenidos de cada
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
18 directorio y fichero.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
19
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
20 Adicionalmente la interfaz provee feeds de RSS de los cambios de los
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
21 repositorios. Que le permite ``subscribirse''a un repositorio usando
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
22 su herramienta de lectura de feeds favorita, y ser notificado
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
23 automáticamente de la actividad en el repositorio tan pronto como
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
24 sucede. Me gusta mucho más este modelo que el estar suscrito a una
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
25 lista de correo a la cual se envían las notificaciones, dado que no
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
26 requiere configuración adicional de parte de quien sea que está
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
27 administrando el repositorio.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
28
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
29 La interfaz web también permite clonar repositorios a los usuarios
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
30 remotos, jalar cambios, y (cuando el servidor está configurado para
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
31 permitirlo) publicar cambios en el mismo. El protocolo de tunneling
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
32 de Mercurial comprime datos agresivamente, de forma que trabaja
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
33 eficientemente incluso con conexiones de red con poco ancho de banda.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
34
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
35 La forma más sencilla de iniciarse con la interfaz web es usar su
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
36 navegador para visitar un repositorio existente, como por ejemplo el
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
37 repositorio principal de Mercurial \url{http://www.selenic.com/repo/hg?style=gitweb}.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
38
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
39 Si está interesado en proveer una interfaz web a sus propios
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
40 repositorios, Mercurial provee dos formas de hacerlo. La primera es
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
41 usando la orden \hgcmd{serve}, que está enfocada a servir ``de forma
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
42 liviana'' y por intervalos cortos. Para más detalles de cómo usar
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
43 esta orden vea la sección~\ref{sec:collab:serve} más adelante. Si
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
44 tiene un repositorio que desea hacer permanente, Mercurial tiene
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
45 soporte embebido del \command{ssh} para publicar cambios con seguridad
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
46 al repositorio central, como se documenta en la
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
47 sección~\ref{sec:collab:ssh}. Es muy usual que se publique una copia
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
48 de sólo lectura en el repositorio que está corriendo sobre HTTP usando
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
49 CGI, como en la sección~\ref{sec:collab:cgi}. Publicar sobre HTTP
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
50 satisface las necesidades de la gente que no tiene permisos de
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
51 publicación y de aquellos que quieren usar navegadores web para
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
52 visualizar la historia del repositorio.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
53
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
54 \subsection{Trabajo con muchas ramas}
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
55
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
56 Los proyectos de cierta talla tienden naturlamente a progresar de
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
57 forma simultánea en varios frentes. En el caso del software, es común
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
58 que un proyecto tenga versiones periódicas oficiales. Una versión
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
59 puede entrar a ``modo mantenimiento'' por un tiempo después de su
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
60 primera publicación; las versiones de mantenimiento tienden a contener
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
61 solamente arreglos de fallos, pero no nuevas características. En
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
62 paralelo con las versiones de mantenimiento puede haber una o muchas
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
63 versiones futuras pueden estar en desarrollo. La gente usa normalmente
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
64 la palabra ``rama'' para referirse a una de las direcciones
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
65 ligeramente distintas en las cuales procede el desarrollo.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
66
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
67 Mercurial está especialmente preparado para administrar un buen número
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
68 de ramas simultáneas pero no idénticas. Cada ``dirección de
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
69 desarrollo'' puede vivir en su propio repositorio central, y puede
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
70 mezclar los cambios de una a otra de acuerdo con las necesidades. Dado
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
71 que los repositorios son independientes, uno del otro, los cambios
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
72 inestables de una rama de desarrollo nunca afectarán una rama estable
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
73 a menos que alguien explícitamente mezcle los cambios.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
74
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
75 A continuación un ejemplo de cómo podría hacerse esto en la
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
76 práctica. Digamos que tiene una ``rama principal'' en un servidor
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
77 central.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
78 \interaction{branching.init}
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
79 Alguien lo clona, hace cambios locales, los prueba, y los publica allí
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
80 mismo.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
81
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
82 Una vez que la rama principal alcanza una estado de versión se puede
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
83 usar la orden \hgcmd{tag} para dar un nombre permanente a la revisión.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
84 \interaction{branching.tag}
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
85 Digamos que en la rama principal ocurre más desarrollo.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
86 \interaction{branching.main}
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
87 Cuando se usa la etiqueta con que se identificó la versión, la gente
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
88 puede clonar el repositorio en cualquier momento en el futuro
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
89 empleando \hgcmd{update} para obtener una copia del directorio de
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
90 trabajo exacta como cuando se creó la etiqueta de la revisión que se
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
91 consignó.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
92 \interaction{branching.update}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
93
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
94 Adicionalmente, justo después de que la rama principal se etiquete,
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
95 alguien puede clonarla en el servidor a una nueva rama ``estable'',
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
96 también en el servidor.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
97 \interaction{branching.clone}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
98
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
99 Alguien que requiera hacer un cambio en la rama estable puede clonar
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
100 \emph{ese} repositorio, hacer sus cambios, consignar y publicarlos
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
101 posteriormente al inicial.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
102 \interaction{branching.stable}
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
103 Puesto que los repositorios de Mercurial son independientes, y que
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
104 Mercurial no mueve los cambios de un lado a otro automáticamente, las
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
105 ramas estable y principal están \emph{aisladas} la una de la otra.
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
106 Los cambios que haga en la rama principal no ``se filtran'' a la rama
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
107 estable o vice versa.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
108
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
109 Es usual que los arreglos de fallos de la rama estable deban hacerse
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
110 aparecer en la rama principal también. En lugar de reescribir el
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
111 arreglo del fallo en la rama principal, puede jalar y mezclar los
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
112 cambios de la rama estable a la principal, Mercurial traerá tales
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
113 arreglos por usted.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
114 \interaction{branching.merge}
511
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
115 La rama principal contendtrá aún los cambios que no están en la
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
116 estable y contendrá además todos los arreglos de fallos de la rama
a9ea523446cc Started translating collab chapter to spanish
Igor TAmara <igor@tamarapatino.org>
parents: 501
diff changeset
117 estable. La rama estable permanece incólume a tales cambios.
501
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
118
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
119 \subsection{Feature branches}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
120
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
121 For larger projects, an effective way to manage change is to break up
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
122 a team into smaller groups. Each group has a shared branch of its
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
123 own, cloned from a single ``master'' branch used by the entire
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
124 project. People working on an individual branch are typically quite
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
125 isolated from developments on other branches.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
126
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
127 \begin{figure}[ht]
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
128 \centering
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
129 \grafix{feature-branches}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
130 \caption{Feature branches}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
131 \label{fig:collab:feature-branches}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
132 \end{figure}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
133
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
134 When a particular feature is deemed to be in suitable shape, someone
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
135 on that feature team pulls and merges from the master branch into the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
136 feature branch, then pushes back up to the master branch.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
137
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
138 \subsection{The release train}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
139
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
140 Some projects are organised on a ``train'' basis: a release is
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
141 scheduled to happen every few months, and whatever features are ready
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
142 when the ``train'' is ready to leave are allowed in.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
143
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
144 This model resembles working with feature branches. The difference is
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
145 that when a feature branch misses a train, someone on the feature team
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
146 pulls and merges the changes that went out on that train release into
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
147 the feature branch, and the team continues its work on top of that
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
148 release so that their feature can make the next release.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
149
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
150 \subsection{The Linux kernel model}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
151
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
152 The development of the Linux kernel has a shallow hierarchical
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
153 structure, surrounded by a cloud of apparent chaos. Because most
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
154 Linux developers use \command{git}, a distributed revision control
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
155 tool with capabilities similar to Mercurial, it's useful to describe
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
156 the way work flows in that environment; if you like the ideas, the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
157 approach translates well across tools.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
158
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
159 At the center of the community sits Linus Torvalds, the creator of
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
160 Linux. He publishes a single source repository that is considered the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
161 ``authoritative'' current tree by the entire developer community.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
162 Anyone can clone Linus's tree, but he is very choosy about whose trees
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
163 he pulls from.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
164
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
165 Linus has a number of ``trusted lieutenants''. As a general rule, he
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
166 pulls whatever changes they publish, in most cases without even
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
167 reviewing those changes. Some of those lieutenants are generally
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
168 agreed to be ``maintainers'', responsible for specific subsystems
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
169 within the kernel. If a random kernel hacker wants to make a change
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
170 to a subsystem that they want to end up in Linus's tree, they must
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
171 find out who the subsystem's maintainer is, and ask that maintainer to
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
172 take their change. If the maintainer reviews their changes and agrees
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
173 to take them, they'll pass them along to Linus in due course.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
174
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
175 Individual lieutenants have their own approaches to reviewing,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
176 accepting, and publishing changes; and for deciding when to feed them
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
177 to Linus. In addition, there are several well known branches that
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
178 people use for different purposes. For example, a few people maintain
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
179 ``stable'' repositories of older versions of the kernel, to which they
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
180 apply critical fixes as needed. Some maintainers publish multiple
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
181 trees: one for experimental changes; one for changes that they are
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
182 about to feed upstream; and so on. Others just publish a single
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
183 tree.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
184
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
185 This model has two notable features. The first is that it's ``pull
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
186 only''. You have to ask, convince, or beg another developer to take a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
187 change from you, because there are almost no trees to which more than
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
188 one person can push, and there's no way to push changes into a tree
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
189 that someone else controls.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
190
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
191 The second is that it's based on reputation and acclaim. If you're an
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
192 unknown, Linus will probably ignore changes from you without even
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
193 responding. But a subsystem maintainer will probably review them, and
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
194 will likely take them if they pass their criteria for suitability.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
195 The more ``good'' changes you contribute to a maintainer, the more
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
196 likely they are to trust your judgment and accept your changes. If
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
197 you're well-known and maintain a long-lived branch for something Linus
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
198 hasn't yet accepted, people with similar interests may pull your
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
199 changes regularly to keep up with your work.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
200
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
201 Reputation and acclaim don't necessarily cross subsystem or ``people''
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
202 boundaries. If you're a respected but specialised storage hacker, and
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
203 you try to fix a networking bug, that change will receive a level of
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
204 scrutiny from a network maintainer comparable to a change from a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
205 complete stranger.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
206
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
207 To people who come from more orderly project backgrounds, the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
208 comparatively chaotic Linux kernel development process often seems
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
209 completely insane. It's subject to the whims of individuals; people
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
210 make sweeping changes whenever they deem it appropriate; and the pace
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
211 of development is astounding. And yet Linux is a highly successful,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
212 well-regarded piece of software.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
213
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
214 \subsection{Pull-only versus shared-push collaboration}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
215
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
216 A perpetual source of heat in the open source community is whether a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
217 development model in which people only ever pull changes from others
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
218 is ``better than'' one in which multiple people can push changes to a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
219 shared repository.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
220
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
221 Typically, the backers of the shared-push model use tools that
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
222 actively enforce this approach. If you're using a centralised
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
223 revision control tool such as Subversion, there's no way to make a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
224 choice over which model you'll use: the tool gives you shared-push,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
225 and if you want to do anything else, you'll have to roll your own
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
226 approach on top (such as applying a patch by hand).
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
227
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
228 A good distributed revision control tool, such as Mercurial, will
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
229 support both models. You and your collaborators can then structure
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
230 how you work together based on your own needs and preferences, not on
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
231 what contortions your tools force you into.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
232
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
233 \subsection{Where collaboration meets branch management}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
234
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
235 Once you and your team set up some shared repositories and start
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
236 propagating changes back and forth between local and shared repos, you
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
237 begin to face a related, but slightly different challenge: that of
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
238 managing the multiple directions in which your team may be moving at
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
239 once. Even though this subject is intimately related to how your team
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
240 collaborates, it's dense enough to merit treatment of its own, in
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
241 chapter~\ref{chap:branch}.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
242
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
243 \section{The technical side of sharing}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
244
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
245 The remainder of this chapter is devoted to the question of serving
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
246 data to your collaborators.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
247
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
248 \section{Informal sharing with \hgcmd{serve}}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
249 \label{sec:collab:serve}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
250
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
251 Mercurial's \hgcmd{serve} command is wonderfully suited to small,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
252 tight-knit, and fast-paced group environments. It also provides a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
253 great way to get a feel for using Mercurial commands over a network.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
254
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
255 Run \hgcmd{serve} inside a repository, and in under a second it will
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
256 bring up a specialised HTTP server; this will accept connections from
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
257 any client, and serve up data for that repository until you terminate
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
258 it. Anyone who knows the URL of the server you just started, and can
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
259 talk to your computer over the network, can then use a web browser or
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
260 Mercurial to read data from that repository. A URL for a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
261 \hgcmd{serve} instance running on a laptop is likely to look something
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
262 like \Verb|http://my-laptop.local:8000/|.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
263
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
264 The \hgcmd{serve} command is \emph{not} a general-purpose web server.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
265 It can do only two things:
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
266 \begin{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
267 \item Allow people to browse the history of the repository it's
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
268 serving, from their normal web browsers.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
269 \item Speak Mercurial's wire protocol, so that people can
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
270 \hgcmd{clone} or \hgcmd{pull} changes from that repository.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
271 \end{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
272 In particular, \hgcmd{serve} won't allow remote users to \emph{modify}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
273 your repository. It's intended for read-only use.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
274
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
275 If you're getting started with Mercurial, there's nothing to prevent
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
276 you from using \hgcmd{serve} to serve up a repository on your own
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
277 computer, then use commands like \hgcmd{clone}, \hgcmd{incoming}, and
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
278 so on to talk to that server as if the repository was hosted remotely.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
279 This can help you to quickly get acquainted with using commands on
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
280 network-hosted repositories.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
281
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
282 \subsection{A few things to keep in mind}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
283
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
284 Because it provides unauthenticated read access to all clients, you
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
285 should only use \hgcmd{serve} in an environment where you either don't
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
286 care, or have complete control over, who can access your network and
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
287 pull data from your repository.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
288
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
289 The \hgcmd{serve} command knows nothing about any firewall software
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
290 you might have installed on your system or network. It cannot detect
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
291 or control your firewall software. If other people are unable to talk
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
292 to a running \hgcmd{serve} instance, the second thing you should do
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
293 (\emph{after} you make sure that they're using the correct URL) is
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
294 check your firewall configuration.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
295
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
296 By default, \hgcmd{serve} listens for incoming connections on
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
297 port~8000. If another process is already listening on the port you
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
298 want to use, you can specify a different port to listen on using the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
299 \hgopt{serve}{-p} option.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
300
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
301 Normally, when \hgcmd{serve} starts, it prints no output, which can be
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
302 a bit unnerving. If you'd like to confirm that it is indeed running
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
303 correctly, and find out what URL you should send to your
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
304 collaborators, start it with the \hggopt{-v} option.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
305
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
306 \section{Using the Secure Shell (ssh) protocol}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
307 \label{sec:collab:ssh}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
308
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
309 You can pull and push changes securely over a network connection using
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
310 the Secure Shell (\texttt{ssh}) protocol. To use this successfully,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
311 you may have to do a little bit of configuration on the client or
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
312 server sides.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
313
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
314 If you're not familiar with ssh, it's a network protocol that lets you
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
315 securely communicate with another computer. To use it with Mercurial,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
316 you'll be setting up one or more user accounts on a server so that
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
317 remote users can log in and execute commands.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
318
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
319 (If you \emph{are} familiar with ssh, you'll probably find some of the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
320 material that follows to be elementary in nature.)
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
321
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
322 \subsection{How to read and write ssh URLs}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
323
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
324 An ssh URL tends to look like this:
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
325 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
326 ssh://bos@hg.serpentine.com:22/hg/hgbook
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
327 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
328 \begin{enumerate}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
329 \item The ``\texttt{ssh://}'' part tells Mercurial to use the ssh
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
330 protocol.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
331 \item The ``\texttt{bos@}'' component indicates what username to log
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
332 into the server as. You can leave this out if the remote username
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
333 is the same as your local username.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
334 \item The ``\texttt{hg.serpentine.com}'' gives the hostname of the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
335 server to log into.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
336 \item The ``:22'' identifies the port number to connect to the server
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
337 on. The default port is~22, so you only need to specify this part
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
338 if you're \emph{not} using port~22.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
339 \item The remainder of the URL is the local path to the repository on
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
340 the server.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
341 \end{enumerate}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
342
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
343 There's plenty of scope for confusion with the path component of ssh
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
344 URLs, as there is no standard way for tools to interpret it. Some
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
345 programs behave differently than others when dealing with these paths.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
346 This isn't an ideal situation, but it's unlikely to change. Please
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
347 read the following paragraphs carefully.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
348
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
349 Mercurial treats the path to a repository on the server as relative to
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
350 the remote user's home directory. For example, if user \texttt{foo}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
351 on the server has a home directory of \dirname{/home/foo}, then an ssh
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
352 URL that contains a path component of \dirname{bar}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
353 \emph{really} refers to the directory \dirname{/home/foo/bar}.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
354
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
355 If you want to specify a path relative to another user's home
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
356 directory, you can use a path that starts with a tilde character
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
357 followed by the user's name (let's call them \texttt{otheruser}), like
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
358 this.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
359 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
360 ssh://server/~otheruser/hg/repo
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
361 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
362
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
363 And if you really want to specify an \emph{absolute} path on the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
364 server, begin the path component with two slashes, as in this example.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
365 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
366 ssh://server//absolute/path
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
367 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
368
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
369 \subsection{Finding an ssh client for your system}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
370
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
371 Almost every Unix-like system comes with OpenSSH preinstalled. If
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
372 you're using such a system, run \Verb|which ssh| to find out if
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
373 the \command{ssh} command is installed (it's usually in
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
374 \dirname{/usr/bin}). In the unlikely event that it isn't present,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
375 take a look at your system documentation to figure out how to install
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
376 it.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
377
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
378 On Windows, you'll first need to choose download a suitable ssh
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
379 client. There are two alternatives.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
380 \begin{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
381 \item Simon Tatham's excellent PuTTY package~\cite{web:putty} provides
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
382 a complete suite of ssh client commands.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
383 \item If you have a high tolerance for pain, you can use the Cygwin
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
384 port of OpenSSH.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
385 \end{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
386 In either case, you'll need to edit your \hgini\ file to tell
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
387 Mercurial where to find the actual client command. For example, if
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
388 you're using PuTTY, you'll need to use the \command{plink} command as
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
389 a command-line ssh client.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
390 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
391 [ui]
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
392 ssh = C:/path/to/plink.exe -ssh -i "C:/path/to/my/private/key"
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
393 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
394
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
395 \begin{note}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
396 The path to \command{plink} shouldn't contain any whitespace
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
397 characters, or Mercurial may not be able to run it correctly (so
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
398 putting it in \dirname{C:\\Program Files} is probably not a good
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
399 idea).
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
400 \end{note}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
401
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
402 \subsection{Generating a key pair}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
403
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
404 To avoid the need to repetitively type a password every time you need
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
405 to use your ssh client, I recommend generating a key pair. On a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
406 Unix-like system, the \command{ssh-keygen} command will do the trick.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
407 On Windows, if you're using PuTTY, the \command{puttygen} command is
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
408 what you'll need.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
409
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
410 When you generate a key pair, it's usually \emph{highly} advisable to
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
411 protect it with a passphrase. (The only time that you might not want
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
412 to do this id when you're using the ssh protocol for automated tasks
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
413 on a secure network.)
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
414
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
415 Simply generating a key pair isn't enough, however. You'll need to
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
416 add the public key to the set of authorised keys for whatever user
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
417 you're logging in remotely as. For servers using OpenSSH (the vast
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
418 majority), this will mean adding the public key to a list in a file
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
419 called \sfilename{authorized\_keys} in their \sdirname{.ssh}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
420 directory.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
421
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
422 On a Unix-like system, your public key will have a \filename{.pub}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
423 extension. If you're using \command{puttygen} on Windows, you can
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
424 save the public key to a file of your choosing, or paste it from the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
425 window it's displayed in straight into the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
426 \sfilename{authorized\_keys} file.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
427
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
428 \subsection{Using an authentication agent}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
429
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
430 An authentication agent is a daemon that stores passphrases in memory
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
431 (so it will forget passphrases if you log out and log back in again).
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
432 An ssh client will notice if it's running, and query it for a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
433 passphrase. If there's no authentication agent running, or the agent
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
434 doesn't store the necessary passphrase, you'll have to type your
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
435 passphrase every time Mercurial tries to communicate with a server on
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
436 your behalf (e.g.~whenever you pull or push changes).
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
437
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
438 The downside of storing passphrases in an agent is that it's possible
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
439 for a well-prepared attacker to recover the plain text of your
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
440 passphrases, in some cases even if your system has been power-cycled.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
441 You should make your own judgment as to whether this is an acceptable
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
442 risk. It certainly saves a lot of repeated typing.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
443
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
444 On Unix-like systems, the agent is called \command{ssh-agent}, and
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
445 it's often run automatically for you when you log in. You'll need to
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
446 use the \command{ssh-add} command to add passphrases to the agent's
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
447 store. On Windows, if you're using PuTTY, the \command{pageant}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
448 command acts as the agent. It adds an icon to your system tray that
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
449 will let you manage stored passphrases.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
450
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
451 \subsection{Configuring the server side properly}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
452
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
453 Because ssh can be fiddly to set up if you're new to it, there's a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
454 variety of things that can go wrong. Add Mercurial on top, and
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
455 there's plenty more scope for head-scratching. Most of these
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
456 potential problems occur on the server side, not the client side. The
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
457 good news is that once you've gotten a configuration working, it will
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
458 usually continue to work indefinitely.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
459
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
460 Before you try using Mercurial to talk to an ssh server, it's best to
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
461 make sure that you can use the normal \command{ssh} or \command{putty}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
462 command to talk to the server first. If you run into problems with
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
463 using these commands directly, Mercurial surely won't work. Worse, it
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
464 will obscure the underlying problem. Any time you want to debug
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
465 ssh-related Mercurial problems, you should drop back to making sure
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
466 that plain ssh client commands work first, \emph{before} you worry
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
467 about whether there's a problem with Mercurial.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
468
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
469 The first thing to be sure of on the server side is that you can
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
470 actually log in from another machine at all. If you can't use
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
471 \command{ssh} or \command{putty} to log in, the error message you get
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
472 may give you a few hints as to what's wrong. The most common problems
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
473 are as follows.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
474 \begin{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
475 \item If you get a ``connection refused'' error, either there isn't an
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
476 SSH daemon running on the server at all, or it's inaccessible due to
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
477 firewall configuration.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
478 \item If you get a ``no route to host'' error, you either have an
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
479 incorrect address for the server or a seriously locked down firewall
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
480 that won't admit its existence at all.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
481 \item If you get a ``permission denied'' error, you may have mistyped
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
482 the username on the server, or you could have mistyped your key's
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
483 passphrase or the remote user's password.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
484 \end{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
485 In summary, if you're having trouble talking to the server's ssh
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
486 daemon, first make sure that one is running at all. On many systems
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
487 it will be installed, but disabled, by default. Once you're done with
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
488 this step, you should then check that the server's firewall is
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
489 configured to allow incoming connections on the port the ssh daemon is
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
490 listening on (usually~22). Don't worry about more exotic
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
491 possibilities for misconfiguration until you've checked these two
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
492 first.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
493
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
494 If you're using an authentication agent on the client side to store
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
495 passphrases for your keys, you ought to be able to log into the server
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
496 without being prompted for a passphrase or a password. If you're
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
497 prompted for a passphrase, there are a few possible culprits.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
498 \begin{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
499 \item You might have forgotten to use \command{ssh-add} or
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
500 \command{pageant} to store the passphrase.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
501 \item You might have stored the passphrase for the wrong key.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
502 \end{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
503 If you're being prompted for the remote user's password, there are
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
504 another few possible problems to check.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
505 \begin{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
506 \item Either the user's home directory or their \sdirname{.ssh}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
507 directory might have excessively liberal permissions. As a result,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
508 the ssh daemon will not trust or read their
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
509 \sfilename{authorized\_keys} file. For example, a group-writable
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
510 home or \sdirname{.ssh} directory will often cause this symptom.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
511 \item The user's \sfilename{authorized\_keys} file may have a problem.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
512 If anyone other than the user owns or can write to that file, the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
513 ssh daemon will not trust or read it.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
514 \end{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
515
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
516 In the ideal world, you should be able to run the following command
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
517 successfully, and it should print exactly one line of output, the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
518 current date and time.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
519 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
520 ssh myserver date
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
521 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
522
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
523 If, on your server, you have login scripts that print banners or other
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
524 junk even when running non-interactive commands like this, you should
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
525 fix them before you continue, so that they only print output if
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
526 they're run interactively. Otherwise these banners will at least
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
527 clutter up Mercurial's output. Worse, they could potentially cause
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
528 problems with running Mercurial commands remotely. Mercurial makes
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
529 tries to detect and ignore banners in non-interactive \command{ssh}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
530 sessions, but it is not foolproof. (If you're editing your login
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
531 scripts on your server, the usual way to see if a login script is
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
532 running in an interactive shell is to check the return code from the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
533 command \Verb|tty -s|.)
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
534
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
535 Once you've verified that plain old ssh is working with your server,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
536 the next step is to ensure that Mercurial runs on the server. The
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
537 following command should run successfully:
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
538 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
539 ssh myserver hg version
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
540 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
541 If you see an error message instead of normal \hgcmd{version} output,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
542 this is usually because you haven't installed Mercurial to
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
543 \dirname{/usr/bin}. Don't worry if this is the case; you don't need
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
544 to do that. But you should check for a few possible problems.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
545 \begin{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
546 \item Is Mercurial really installed on the server at all? I know this
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
547 sounds trivial, but it's worth checking!
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
548 \item Maybe your shell's search path (usually set via the \envar{PATH}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
549 environment variable) is simply misconfigured.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
550 \item Perhaps your \envar{PATH} environment variable is only being set
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
551 to point to the location of the \command{hg} executable if the login
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
552 session is interactive. This can happen if you're setting the path
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
553 in the wrong shell login script. See your shell's documentation for
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
554 details.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
555 \item The \envar{PYTHONPATH} environment variable may need to contain
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
556 the path to the Mercurial Python modules. It might not be set at
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
557 all; it could be incorrect; or it may be set only if the login is
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
558 interactive.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
559 \end{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
560
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
561 If you can run \hgcmd{version} over an ssh connection, well done!
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
562 You've got the server and client sorted out. You should now be able
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
563 to use Mercurial to access repositories hosted by that username on
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
564 that server. If you run into problems with Mercurial and ssh at this
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
565 point, try using the \hggopt{--debug} option to get a clearer picture
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
566 of what's going on.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
567
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
568 \subsection{Using compression with ssh}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
569
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
570 Mercurial does not compress data when it uses the ssh protocol,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
571 because the ssh protocol can transparently compress data. However,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
572 the default behaviour of ssh clients is \emph{not} to request
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
573 compression.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
574
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
575 Over any network other than a fast LAN (even a wireless network),
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
576 using compression is likely to significantly speed up Mercurial's
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
577 network operations. For example, over a WAN, someone measured
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
578 compression as reducing the amount of time required to clone a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
579 particularly large repository from~51 minutes to~17 minutes.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
580
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
581 Both \command{ssh} and \command{plink} accept a \cmdopt{ssh}{-C}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
582 option which turns on compression. You can easily edit your \hgrc\ to
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
583 enable compression for all of Mercurial's uses of the ssh protocol.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
584 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
585 [ui]
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
586 ssh = ssh -C
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
587 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
588
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
589 If you use \command{ssh}, you can configure it to always use
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
590 compression when talking to your server. To do this, edit your
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
591 \sfilename{.ssh/config} file (which may not yet exist), as follows.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
592 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
593 Host hg
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
594 Compression yes
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
595 HostName hg.example.com
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
596 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
597 This defines an alias, \texttt{hg}. When you use it on the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
598 \command{ssh} command line or in a Mercurial \texttt{ssh}-protocol
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
599 URL, it will cause \command{ssh} to connect to \texttt{hg.example.com}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
600 and use compression. This gives you both a shorter name to type and
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
601 compression, each of which is a good thing in its own right.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
602
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
603 \section{Serving over HTTP using CGI}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
604 \label{sec:collab:cgi}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
605
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
606 Depending on how ambitious you are, configuring Mercurial's CGI
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
607 interface can take anything from a few moments to several hours.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
608
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
609 We'll begin with the simplest of examples, and work our way towards a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
610 more complex configuration. Even for the most basic case, you're
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
611 almost certainly going to need to read and modify your web server's
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
612 configuration.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
613
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
614 \begin{note}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
615 Configuring a web server is a complex, fiddly, and highly
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
616 system-dependent activity. I can't possibly give you instructions
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
617 that will cover anything like all of the cases you will encounter.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
618 Please use your discretion and judgment in following the sections
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
619 below. Be prepared to make plenty of mistakes, and to spend a lot
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
620 of time reading your server's error logs.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
621 \end{note}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
622
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
623 \subsection{Web server configuration checklist}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
624
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
625 Before you continue, do take a few moments to check a few aspects of
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
626 your system's setup.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
627
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
628 \begin{enumerate}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
629 \item Do you have a web server installed at all? Mac OS X ships with
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
630 Apache, but many other systems may not have a web server installed.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
631 \item If you have a web server installed, is it actually running? On
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
632 most systems, even if one is present, it will be disabled by
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
633 default.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
634 \item Is your server configured to allow you to run CGI programs in
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
635 the directory where you plan to do so? Most servers default to
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
636 explicitly disabling the ability to run CGI programs.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
637 \end{enumerate}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
638
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
639 If you don't have a web server installed, and don't have substantial
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
640 experience configuring Apache, you should consider using the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
641 \texttt{lighttpd} web server instead of Apache. Apache has a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
642 well-deserved reputation for baroque and confusing configuration.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
643 While \texttt{lighttpd} is less capable in some ways than Apache, most
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
644 of these capabilities are not relevant to serving Mercurial
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
645 repositories. And \texttt{lighttpd} is undeniably \emph{much} easier
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
646 to get started with than Apache.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
647
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
648 \subsection{Basic CGI configuration}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
649
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
650 On Unix-like systems, it's common for users to have a subdirectory
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
651 named something like \dirname{public\_html} in their home directory,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
652 from which they can serve up web pages. A file named \filename{foo}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
653 in this directory will be accessible at a URL of the form
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
654 \texttt{http://www.example.com/\~username/foo}.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
655
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
656 To get started, find the \sfilename{hgweb.cgi} script that should be
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
657 present in your Mercurial installation. If you can't quickly find a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
658 local copy on your system, simply download one from the master
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
659 Mercurial repository at
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
660 \url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
661
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
662 You'll need to copy this script into your \dirname{public\_html}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
663 directory, and ensure that it's executable.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
664 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
665 cp .../hgweb.cgi ~/public_html
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
666 chmod 755 ~/public_html/hgweb.cgi
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
667 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
668 The \texttt{755} argument to \command{chmod} is a little more general
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
669 than just making the script executable: it ensures that the script is
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
670 executable by anyone, and that ``group'' and ``other'' write
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
671 permissions are \emph{not} set. If you were to leave those write
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
672 permissions enabled, Apache's \texttt{suexec} subsystem would likely
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
673 refuse to execute the script. In fact, \texttt{suexec} also insists
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
674 that the \emph{directory} in which the script resides must not be
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
675 writable by others.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
676 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
677 chmod 755 ~/public_html
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
678 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
679
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
680 \subsubsection{What could \emph{possibly} go wrong?}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
681 \label{sec:collab:wtf}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
682
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
683 Once you've copied the CGI script into place, go into a web browser,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
684 and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi},
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
685 \emph{but} brace yourself for instant failure. There's a high
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
686 probability that trying to visit this URL will fail, and there are
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
687 many possible reasons for this. In fact, you're likely to stumble
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
688 over almost every one of the possible errors below, so please read
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
689 carefully. The following are all of the problems I ran into on a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
690 system running Fedora~7, with a fresh installation of Apache, and a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
691 user account that I created specially to perform this exercise.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
692
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
693 Your web server may have per-user directories disabled. If you're
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
694 using Apache, search your config file for a \texttt{UserDir}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
695 directive. If there's none present, per-user directories will be
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
696 disabled. If one exists, but its value is \texttt{disabled}, then
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
697 per-user directories will be disabled. Otherwise, the string after
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
698 \texttt{UserDir} gives the name of the subdirectory that Apache will
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
699 look in under your home directory, for example \dirname{public\_html}.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
700
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
701 Your file access permissions may be too restrictive. The web server
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
702 must be able to traverse your home directory and directories under
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
703 your \dirname{public\_html} directory, and read files under the latter
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
704 too. Here's a quick recipe to help you to make your permissions more
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
705 appropriate.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
706 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
707 chmod 755 ~
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
708 find ~/public_html -type d -print0 | xargs -0r chmod 755
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
709 find ~/public_html -type f -print0 | xargs -0r chmod 644
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
710 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
711
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
712 The other possibility with permissions is that you might get a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
713 completely empty window when you try to load the script. In this
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
714 case, it's likely that your access permissions are \emph{too
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
715 permissive}. Apache's \texttt{suexec} subsystem won't execute a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
716 script that's group-~or world-writable, for example.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
717
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
718 Your web server may be configured to disallow execution of CGI
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
719 programs in your per-user web directory. Here's Apache's
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
720 default per-user configuration from my Fedora system.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
721 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
722 <Directory /home/*/public_html>
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
723 AllowOverride FileInfo AuthConfig Limit
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
724 Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
725 <Limit GET POST OPTIONS>
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
726 Order allow,deny
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
727 Allow from all
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
728 </Limit>
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
729 <LimitExcept GET POST OPTIONS>
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
730 Order deny,allow
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
731 Deny from all
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
732 </LimitExcept>
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
733 </Directory>
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
734 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
735 If you find a similar-looking \texttt{Directory} group in your Apache
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
736 configuration, the directive to look at inside it is \texttt{Options}.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
737 Add \texttt{ExecCGI} to the end of this list if it's missing, and
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
738 restart the web server.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
739
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
740 If you find that Apache serves you the text of the CGI script instead
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
741 of executing it, you may need to either uncomment (if already present)
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
742 or add a directive like this.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
743 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
744 AddHandler cgi-script .cgi
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
745 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
746
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
747 The next possibility is that you might be served with a colourful
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
748 Python backtrace claiming that it can't import a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
749 \texttt{mercurial}-related module. This is actually progress! The
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
750 server is now capable of executing your CGI script. This error is
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
751 only likely to occur if you're running a private installation of
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
752 Mercurial, instead of a system-wide version. Remember that the web
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
753 server runs the CGI program without any of the environment variables
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
754 that you take for granted in an interactive session. If this error
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
755 happens to you, edit your copy of \sfilename{hgweb.cgi} and follow the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
756 directions inside it to correctly set your \envar{PYTHONPATH}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
757 environment variable.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
758
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
759 Finally, you are \emph{certain} to by served with another colourful
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
760 Python backtrace: this one will complain that it can't find
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
761 \dirname{/path/to/repository}. Edit your \sfilename{hgweb.cgi} script
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
762 and replace the \dirname{/path/to/repository} string with the complete
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
763 path to the repository you want to serve up.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
764
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
765 At this point, when you try to reload the page, you should be
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
766 presented with a nice HTML view of your repository's history. Whew!
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
767
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
768 \subsubsection{Configuring lighttpd}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
769
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
770 To be exhaustive in my experiments, I tried configuring the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
771 increasingly popular \texttt{lighttpd} web server to serve the same
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
772 repository as I described with Apache above. I had already overcome
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
773 all of the problems I outlined with Apache, many of which are not
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
774 server-specific. As a result, I was fairly sure that my file and
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
775 directory permissions were good, and that my \sfilename{hgweb.cgi}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
776 script was properly edited.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
777
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
778 Once I had Apache running, getting \texttt{lighttpd} to serve the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
779 repository was a snap (in other words, even if you're trying to use
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
780 \texttt{lighttpd}, you should read the Apache section). I first had
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
781 to edit the \texttt{mod\_access} section of its config file to enable
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
782 \texttt{mod\_cgi} and \texttt{mod\_userdir}, both of which were
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
783 disabled by default on my system. I then added a few lines to the end
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
784 of the config file, to configure these modules.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
785 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
786 userdir.path = "public_html"
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
787 cgi.assign = ( ".cgi" => "" )
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
788 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
789 With this done, \texttt{lighttpd} ran immediately for me. If I had
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
790 configured \texttt{lighttpd} before Apache, I'd almost certainly have
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
791 run into many of the same system-level configuration problems as I did
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
792 with Apache. However, I found \texttt{lighttpd} to be noticeably
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
793 easier to configure than Apache, even though I've used Apache for over
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
794 a decade, and this was my first exposure to \texttt{lighttpd}.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
795
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
796 \subsection{Sharing multiple repositories with one CGI script}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
797
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
798 The \sfilename{hgweb.cgi} script only lets you publish a single
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
799 repository, which is an annoying restriction. If you want to publish
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
800 more than one without wracking yourself with multiple copies of the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
801 same script, each with different names, a better choice is to use the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
802 \sfilename{hgwebdir.cgi} script.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
803
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
804 The procedure to configure \sfilename{hgwebdir.cgi} is only a little
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
805 more involved than for \sfilename{hgweb.cgi}. First, you must obtain
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
806 a copy of the script. If you don't have one handy, you can download a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
807 copy from the master Mercurial repository at
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
808 \url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
809
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
810 You'll need to copy this script into your \dirname{public\_html}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
811 directory, and ensure that it's executable.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
812 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
813 cp .../hgwebdir.cgi ~/public_html
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
814 chmod 755 ~/public_html ~/public_html/hgwebdir.cgi
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
815 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
816 With basic configuration out of the way, try to visit
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
817 \url{http://myhostname/~myuser/hgwebdir.cgi} in your browser. It
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
818 should display an empty list of repositories. If you get a blank
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
819 window or error message, try walking through the list of potential
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
820 problems in section~\ref{sec:collab:wtf}.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
821
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
822 The \sfilename{hgwebdir.cgi} script relies on an external
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
823 configuration file. By default, it searches for a file named
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
824 \sfilename{hgweb.config} in the same directory as itself. You'll need
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
825 to create this file, and make it world-readable. The format of the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
826 file is similar to a Windows ``ini'' file, as understood by Python's
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
827 \texttt{ConfigParser}~\cite{web:configparser} module.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
828
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
829 The easiest way to configure \sfilename{hgwebdir.cgi} is with a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
830 section named \texttt{collections}. This will automatically publish
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
831 \emph{every} repository under the directories you name. The section
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
832 should look like this:
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
833 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
834 [collections]
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
835 /my/root = /my/root
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
836 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
837 Mercurial interprets this by looking at the directory name on the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
838 \emph{right} hand side of the ``\texttt{=}'' sign; finding
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
839 repositories in that directory hierarchy; and using the text on the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
840 \emph{left} to strip off matching text from the names it will actually
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
841 list in the web interface. The remaining component of a path after
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
842 this stripping has occurred is called a ``virtual path''.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
843
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
844 Given the example above, if we have a repository whose local path is
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
845 \dirname{/my/root/this/repo}, the CGI script will strip the leading
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
846 \dirname{/my/root} from the name, and publish the repository with a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
847 virtual path of \dirname{this/repo}. If the base URL for our CGI
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
848 script is \url{http://myhostname/~myuser/hgwebdir.cgi}, the complete
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
849 URL for that repository will be
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
850 \url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
851
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
852 If we replace \dirname{/my/root} on the left hand side of this example
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
853 with \dirname{/my}, then \sfilename{hgwebdir.cgi} will only strip off
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
854 \dirname{/my} from the repository name, and will give us a virtual
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
855 path of \dirname{root/this/repo} instead of \dirname{this/repo}.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
856
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
857 The \sfilename{hgwebdir.cgi} script will recursively search each
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
858 directory listed in the \texttt{collections} section of its
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
859 configuration file, but it will \texttt{not} recurse into the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
860 repositories it finds.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
861
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
862 The \texttt{collections} mechanism makes it easy to publish many
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
863 repositories in a ``fire and forget'' manner. You only need to set up
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
864 the CGI script and configuration file one time. Afterwards, you can
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
865 publish or unpublish a repository at any time by simply moving it
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
866 into, or out of, the directory hierarchy in which you've configured
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
867 \sfilename{hgwebdir.cgi} to look.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
868
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
869 \subsubsection{Explicitly specifying which repositories to publish}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
870
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
871 In addition to the \texttt{collections} mechanism, the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
872 \sfilename{hgwebdir.cgi} script allows you to publish a specific list
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
873 of repositories. To do so, create a \texttt{paths} section, with
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
874 contents of the following form.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
875 \begin{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
876 [paths]
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
877 repo1 = /my/path/to/some/repo
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
878 repo2 = /some/path/to/another
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
879 \end{codesample2}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
880 In this case, the virtual path (the component that will appear in a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
881 URL) is on the left hand side of each definition, while the path to
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
882 the repository is on the right. Notice that there does not need to be
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
883 any relationship between the virtual path you choose and the location
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
884 of a repository in your filesystem.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
885
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
886 If you wish, you can use both the \texttt{collections} and
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
887 \texttt{paths} mechanisms simultaneously in a single configuration
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
888 file.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
889
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
890 \begin{note}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
891 If multiple repositories have the same virtual path,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
892 \sfilename{hgwebdir.cgi} will not report an error. Instead, it will
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
893 behave unpredictably.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
894 \end{note}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
895
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
896 \subsection{Downloading source archives}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
897
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
898 Mercurial's web interface lets users download an archive of any
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
899 revision. This archive will contain a snapshot of the working
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
900 directory as of that revision, but it will not contain a copy of the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
901 repository data.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
902
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
903 By default, this feature is not enabled. To enable it, you'll need to
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
904 add an \rcitem{web}{allow\_archive} item to the \rcsection{web}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
905 section of your \hgrc.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
906
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
907 \subsection{Web configuration options}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
908
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
909 Mercurial's web interfaces (the \hgcmd{serve} command, and the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
910 \sfilename{hgweb.cgi} and \sfilename{hgwebdir.cgi} scripts) have a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
911 number of configuration options that you can set. These belong in a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
912 section named \rcsection{web}.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
913 \begin{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
914 \item[\rcitem{web}{allow\_archive}] Determines which (if any) archive
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
915 download mechanisms Mercurial supports. If you enable this
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
916 feature, users of the web interface will be able to download an
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
917 archive of whatever revision of a repository they are viewing.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
918 To enable the archive feature, this item must take the form of a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
919 sequence of words drawn from the list below.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
920 \begin{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
921 \item[\texttt{bz2}] A \command{tar} archive, compressed using
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
922 \texttt{bzip2} compression. This has the best compression ratio,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
923 but uses the most CPU time on the server.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
924 \item[\texttt{gz}] A \command{tar} archive, compressed using
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
925 \texttt{gzip} compression.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
926 \item[\texttt{zip}] A \command{zip} archive, compressed using LZW
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
927 compression. This format has the worst compression ratio, but is
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
928 widely used in the Windows world.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
929 \end{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
930 If you provide an empty list, or don't have an
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
931 \rcitem{web}{allow\_archive} entry at all, this feature will be
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
932 disabled. Here is an example of how to enable all three supported
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
933 formats.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
934 \begin{codesample4}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
935 [web]
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
936 allow_archive = bz2 gz zip
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
937 \end{codesample4}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
938 \item[\rcitem{web}{allowpull}] Boolean. Determines whether the web
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
939 interface allows remote users to \hgcmd{pull} and \hgcmd{clone} this
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
940 repository over~HTTP. If set to \texttt{no} or \texttt{false}, only
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
941 the ``human-oriented'' portion of the web interface is available.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
942 \item[\rcitem{web}{contact}] String. A free-form (but preferably
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
943 brief) string identifying the person or group in charge of the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
944 repository. This often contains the name and email address of a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
945 person or mailing list. It often makes sense to place this entry in
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
946 a repository's own \sfilename{.hg/hgrc} file, but it can make sense
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
947 to use in a global \hgrc\ if every repository has a single
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
948 maintainer.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
949 \item[\rcitem{web}{maxchanges}] Integer. The default maximum number
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
950 of changesets to display in a single page of output.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
951 \item[\rcitem{web}{maxfiles}] Integer. The default maximum number
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
952 of modified files to display in a single page of output.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
953 \item[\rcitem{web}{stripes}] Integer. If the web interface displays
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
954 alternating ``stripes'' to make it easier to visually align rows
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
955 when you are looking at a table, this number controls the number of
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
956 rows in each stripe.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
957 \item[\rcitem{web}{style}] Controls the template Mercurial uses to
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
958 display the web interface. Mercurial ships with two web templates,
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
959 named \texttt{default} and \texttt{gitweb} (the latter is much more
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
960 visually attractive). You can also specify a custom template of
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
961 your own; see chapter~\ref{chap:template} for details. Here, you
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
962 can see how to enable the \texttt{gitweb} style.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
963 \begin{codesample4}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
964 [web]
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
965 style = gitweb
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
966 \end{codesample4}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
967 \item[\rcitem{web}{templates}] Path. The directory in which to search
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
968 for template files. By default, Mercurial searches in the directory
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
969 in which it was installed.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
970 \end{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
971 If you are using \sfilename{hgwebdir.cgi}, you can place a few
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
972 configuration items in a \rcsection{web} section of the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
973 \sfilename{hgweb.config} file instead of a \hgrc\ file, for
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
974 convenience. These items are \rcitem{web}{motd} and
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
975 \rcitem{web}{style}.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
976
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
977 \subsubsection{Options specific to an individual repository}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
978
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
979 A few \rcsection{web} configuration items ought to be placed in a
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
980 repository's local \sfilename{.hg/hgrc}, rather than a user's or
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
981 global \hgrc.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
982 \begin{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
983 \item[\rcitem{web}{description}] String. A free-form (but preferably
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
984 brief) string that describes the contents or purpose of the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
985 repository.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
986 \item[\rcitem{web}{name}] String. The name to use for the repository
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
987 in the web interface. This overrides the default name, which is the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
988 last component of the repository's path.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
989 \end{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
990
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
991 \subsubsection{Options specific to the \hgcmd{serve} command}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
992
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
993 Some of the items in the \rcsection{web} section of a \hgrc\ file are
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
994 only for use with the \hgcmd{serve} command.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
995 \begin{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
996 \item[\rcitem{web}{accesslog}] Path. The name of a file into which to
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
997 write an access log. By default, the \hgcmd{serve} command writes
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
998 this information to standard output, not to a file. Log entries are
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
999 written in the standard ``combined'' file format used by almost all
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1000 web servers.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1001 \item[\rcitem{web}{address}] String. The local address on which the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1002 server should listen for incoming connections. By default, the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1003 server listens on all addresses.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1004 \item[\rcitem{web}{errorlog}] Path. The name of a file into which to
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1005 write an error log. By default, the \hgcmd{serve} command writes this
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1006 information to standard error, not to a file.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1007 \item[\rcitem{web}{ipv6}] Boolean. Whether to use the IPv6 protocol.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1008 By default, IPv6 is not used.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1009 \item[\rcitem{web}{port}] Integer. The TCP~port number on which the
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1010 server should listen. The default port number used is~8000.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1011 \end{itemize}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1012
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1013 \subsubsection{Choosing the right \hgrc\ file to add \rcsection{web}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1014 items to}
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1015
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1016 It is important to remember that a web server like Apache or
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1017 \texttt{lighttpd} will run under a user~ID that is different to yours.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1018 CGI scripts run by your server, such as \sfilename{hgweb.cgi}, will
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1019 usually also run under that user~ID.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1020
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1021 If you add \rcsection{web} items to your own personal \hgrc\ file, CGI
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1022 scripts won't read that \hgrc\ file. Those settings will thus only
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1023 affect the behaviour of the \hgcmd{serve} command when you run it. To
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1024 cause CGI scripts to see your settings, either create a \hgrc\ file in
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1025 the home directory of the user ID that runs your web server, or add
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1026 those settings to a system-wide \hgrc\ file.
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1027
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1028
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1029 %%% Local Variables:
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1030 %%% mode: latex
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1031 %%% TeX-master: "00book"
b05e35d641e4 Copying the files from en to es and taking intro chapter
Igor TAmara <igor@tamarapatino.org>
parents: 432
diff changeset
1032 %%% End: