hgbook
view es/collab.tex @ 434:c847605eb2a9
translated a bit, will stop translating this file until I figure out how to translate the expression "case sensitivity"
| author | jerojasro@localhost |
|---|---|
| date | Mon Dec 01 20:56:29 2008 -0500 (2008-12-01) |
| parents | 35370f1551a7 |
| children | 0d6c97362064 |
line source
1 \chapter{Colaborar con otros}
2 \label{cha:collab}
4 Debido a su naturaleza descentralizada, Mercurial no impone política
5 alguna de cómo deben trabajar los grupos de personas. Sin embargo, si
6 usted es nuevo al control distribuido de versiones, es bueno tener
7 herramientas y ejemplos a la mano al pensar en posibles modelos de
8 flujo de trabajo.
10 \section{La interfaz web de Mercurial}
12 Mercurial tiene una poderosa interfaz web que provee bastantes
13 capacidades útiles.
15 Para uso interactivo, la interfaz le permite visualizar uno o varios
16 repositorios. Puede ver la historia de un repositorio, examinar cada
17 cambio(comentarios y diferencias), y ver los contenidos de cada
18 directorio y fichero.
20 Adicionalmente la interfaz provee feeds de RSS de los cambios de los
21 repositorios. Que le permite ``subscribirse''a un repositorio usando
22 su herramienta de lectura de feeds favorita, y ser notificado
23 automáticamente de la actividad en el repositorio tan pronto como
24 sucede. Me gusta mucho más este modelo que el estar suscrito a una
25 lista de correo a la cual se envían las notificaciones, dado que no
26 requiere configuración adicional de parte de quien sea que está
27 administrando el repositorio.
29 La interfaz web también permite clonar repositorios a los usuarios
30 remotos, jalar cambios, y (cuando el servidor está configurado para
31 permitirlo) publicar cambios en el mismo. El protocolo de tunneling
32 de Mercurial comprime datos agresivamente, de forma que trabaja
33 eficientemente incluso con conexiones de red con poco ancho de banda.
35 La forma más sencilla de iniciarse con la interfaz web es usar su
36 navegador para visitar un repositorio existente, como por ejemplo el
37 repositorio principal de Mercurial \url{http://www.selenic.com/repo/hg?style=gitweb}.
39 Si está interesado en proveer una interfaz web a sus propios
40 repositorios, Mercurial provee dos formas de hacerlo. La primera es
41 usando la orden \hgcmd{serve}, que está enfocada a servir ``de forma
42 liviana'' y por intervalos cortos. Para más detalles de cómo usar
43 esta orden vea la sección~\ref{sec:collab:serve} más adelante. Si
44 tiene un repositorio que desea hacer permanente, Mercurial tiene
45 soporte embebido del \command{ssh} para publicar cambios con seguridad
46 al repositorio central, como se documenta en la
47 sección~\ref{sec:collab:ssh}. Es muy usual que se publique una copia
48 de sólo lectura en el repositorio que está corriendo sobre HTTP usando
49 CGI, como en la sección~\ref{sec:collab:cgi}. Publicar sobre HTTP
50 satisface las necesidades de la gente que no tiene permisos de
51 publicación y de aquellos que quieren usar navegadores web para
52 visualizar la historia del repositorio.
54 \subsection{Trabajo con muchas ramas}
56 Los proyectos de cierta talla tienden naturlamente a progresar de
57 forma simultánea en varios frentes. En el caso del software, es común
58 que un proyecto tenga versiones periódicas oficiales. Una versión
59 puede entrar a ``modo mantenimiento'' por un tiempo después de su
60 primera publicación; las versiones de mantenimiento tienden a contener
61 solamente arreglos de fallos, pero no nuevas características. En
62 paralelo con las versiones de mantenimiento puede haber una o muchas
63 versiones futuras pueden estar en desarrollo. La gente usa normalmente
64 la palabra ``rama'' para referirse a una de las direcciones
65 ligeramente distintas en las cuales procede el desarrollo.
67 Mercurial está especialmente preparado para administrar un buen número
68 de ramas simultáneas pero no idénticas. Cada ``dirección de
69 desarrollo'' puede vivir en su propio repositorio central, y puede
70 mezclar los cambios de una a otra de acuerdo con las necesidades. Dado
71 que los repositorios son independientes, uno del otro, los cambios
72 inestables de una rama de desarrollo nunca afectarán una rama estable
73 a menos que alguien explícitamente mezcle los cambios.
75 A continuación un ejemplo de cómo podría hacerse esto en la
76 práctica. Digamos que tiene una ``rama principal'' en un servidor
77 central.
78 \interaction{branching.init}
79 Alguien lo clona, hace cambios locales, los prueba, y los publica allí
80 mismo.
82 Una vez que la rama principal alcanza una estado de versión se puede
83 usar la orden \hgcmd{tag} para dar un nombre permanente a la revisión.
84 \interaction{branching.tag}
85 Digamos que en la rama principal ocurre más desarrollo.
86 \interaction{branching.main}
87 Cuando se usa la etiqueta con que se identificó la versión, la gente
88 puede clonar el repositorio en cualquier momento en el futuro
89 empleando \hgcmd{update} para obtener una copia del directorio de
90 trabajo exacta como cuando se creó la etiqueta de la revisión que se
91 consignó.
92 \interaction{branching.update}
94 Adicionalmente, justo después de que la rama principal se etiquete,
95 alguien puede clonarla en el servidor a una nueva rama ``estable'',
96 también en el servidor.
97 \interaction{branching.clone}
99 Alguien que requiera hacer un cambio en la rama estable puede clonar
100 \emph{ese} repositorio, hacer sus cambios, consignar y publicarlos
101 posteriormente al inicial.
102 \interaction{branching.stable}
103 Puesto que los repositorios de Mercurial son independientes, y que
104 Mercurial no mueve los cambios de un lado a otro automáticamente, las
105 ramas estable y principal están \emph{aisladas} la una de la otra.
106 Los cambios que haga en la rama principal no ``se filtran'' a la rama
107 estable o vice versa.
109 Es usual que los arreglos de fallos de la rama estable deban hacerse
110 aparecer en la rama principal también. En lugar de reescribir el
111 arreglo del fallo en la rama principal, puede jalar y mezclar los
112 cambios de la rama estable a la principal, Mercurial traerá tales
113 arreglos por usted.
114 \interaction{branching.merge}
115 La rama principal contendtrá aún los cambios que no están en la
116 estable y contendrá además todos los arreglos de fallos de la rama
117 estable. La rama estable permanece incólume a tales cambios.
119 \subsection{Ramas de Características}
121 En proyectos grandes, una forma efectiva de administrar los cambios es
122 dividir el equipo en grupos más pequeños. Cada grupo tiene una rama
123 compartida, clonada de una rama ``principal'' que conforma el proyecto
124 completo. Aquellos que trabajan en ramas individuales típicamente
125 están aislados de los desarrollos de otras ramas.
127 \begin{figure}[ht]
128 \centering
129 \grafix{feature-branches}
130 \caption{Ramas de Características}
131 \label{fig:collab:feature-branches}
132 \end{figure}
134 Cuando una rama particular alcanza un estado deseado, alguien del
135 equipo de características jala y fusiona de la rama principal hacia
136 la rama de características y publica posteriormente a la rama principal.
138 \subsection{El tren de publicación}
140 Algunos proyectos se organizan al estilo``tren'': Una versión se
141 planifica para ser liberada cada cierto tiempo, y las características
142 que estén listas cuando ha llegado el momento ``tren'', se incorporan.
144 Este modelo tiene cierta similitud a las ramas de características. La
145 diferencia es que cuando una característica pierde el tren, alguien en
146 el equipo de características jala y fusiona los cambios que se fueron
147 en la versión liberada hacia la rama de característica, y el trabajo
148 continúa sobre lo fusionado para que la característica logre estar en
149 la próxima versión.
151 \subsection{El modelo del kernel linux}
153 El desarrollo del Kernel Linux tiene una estructura jerárquica
154 bastante horizontal, rodeada de una nube de caos aparente. Dado que la
155 mayoría de desarrolladores usan \command{git}, una herramienta distribuida
156 de control de versiones con capacidades similares a Mercurial, resulta
157 de utilidad describir la forma en que el trabajo fluye en tal
158 ambiente; si le gustan las ideas, la aproximación se traduce bien
159 entre Git y Mercurial.
161 En el centro de la comunidad está Linus Torvalds, el creador de Linux.
162 Él publica un único repositorio que es considerado el árbol
163 ``oficial'' actual por la comunidad completa de
164 desarrolladores. Cualquiera puede clonar el árbol de Linus, pero él es
165 muy selectivo acerca de los árboles de los cuales jala.
167 Linus tiene varios ``lugartenientes confiables''. Como regla, él jala
168 todos los cambios que ellos publican, en la mayoría de los casos sin
169 siquiera revisarlos. Algunos de sus lugartenientes generalmente
170 aceptan ser los ``mantenedores'', responsables de subsistemas
171 específicos dentro del kernel. Si un hacker cualquiera desea hacer un
172 cambio a un subsistema y busca que termine en el árbol de Linus, debe
173 encontrar quién es el mantenedor del subsistema y solicitarle que
174 tenga en cuenta su cambio. Si el mantenedor revisa los cambios y está
175 de acuerdo en tomarlos, estos pasarán al árbol de Linus de acuerdo a
176 lo expuesto.
178 Cada lugarteniente tiene su forma particular de revisar, aceptar y
179 publicar los cambios; y para decidir cuando hacerlos presentes a
180 Linus. Adicionalmente existen varias ramas conocidas que mucha gente
181 usa para propósitos distintos. Por ejemplo, pocas personas mantienen
182 repositorios ``estables'' de versiones anteriores del kernel, a los
183 cuales aplican arreglos de fallos críticos necesarios. Algunos
184 mantenedores publican varios árboles: uno para cambios
185 experimentales; uno para cambios que van a ofrecer al mantenedor
186 principal; y así sucesivamente. Otros publican un solo árbol.
188 Este modelo tiene dos características notables. La primera es que son
189 de ``jalar exclusivamente''. Usted debe solicitar, convencer o
190 incluso rogar a otro desarrollador para que tome sus cabmios, porque
191 casi no hay árboles en los cuales más de una persona pueda publicar, y
192 no hay forma de publicar cambios en un árbol que otra persona controla.
194 El segundo está basado en reputación y meritocracia. Si usted es un
195 desconocido, Linus probablemente ignorará sus cambios, sin siquiera
196 responderle. Pero un mantenedor de un subsistema probablemente los
197 revisara, y los acogerá en caso de que aprueben su criterio de
198 aplicabilidad. A medida que usted ofrezca ``mejores'' cambios a un
199 mantenedor, habrá más posibilidad de que se confíe en su juicio y se
200 acepten los cambios. Si usted es reconocido y matiene una rama
201 durante bastante tiempo para algo que Linus no ha aceptado, personas
202 con intereses similares pueden jalar sus cambios regularmente para
203 estar al día con su trabajo.
205 La reputación y meritocracia no necesariamente es transversal entre
206 ``personas'' de diferentes subsistemas. Si usted es respetado pero es
207 un hacker en almacenamiento y trata de arreglar un fallo de redes,
208 tal cambio puede recibir un nivel de escrutinio de un mantenedor de
209 redes comparable con el que se le haría a un completo extraño.
211 Personas que vienen de proyectos con un ordenamiento distinto, sienten
212 que el proceso comparativamente caótico del Kernel Linux es
213 completamente lunático. Es objeto de los caprichos individuales; la
214 gente desecha cambios cuando lo desean; y la fase de desarrollo es
215 alucinante. A pesar de eso Linux es una pieza de software exitosa y
216 bien reconocida.
218 \subsection{Solamente jalar frente a colaboración pública}
220 Una fuente perpetua de discusiones en la comunidad de código abierto
221 yace en el modelo de desarrollo en el cual la gente solamente jala
222 cambios de otros ``es mejor que'' uno en el cual muchas personas
223 pueden publicar cambios a un repositorio compartido.
225 Tícamente los partidarios del modelo de publicar usan las herramientas
226 que se apegan a este modelo. Si usted usa una herramienta
227 centralizada de control de versiones como Subversion, no hay forma de
228 elegir qué modelo va a usar: La herramienta le ofrece publicación
229 compartida, y si desea hacer cualquier otra cosa, va a tener que
230 aplicar una aproximación artificial (tal como aplicar parches a mano).
232 Una buena herramienta distribuida de control de versiones, tal como
233 Mercurial soportará los dos modelos. Usted y sus colaboradores
234 pueden estructurar cómo trabajarán juntos basados en sus propias
235 necesidades y preferencias, sin depender de las peripecias que la
236 herramienta les obligue a hacer.
238 \subsection{Cuando la colaboración encuentra la administración ramificada}
240 Una vez que usted y su equipo configurar algunos repositorios
241 compartidos y comienzan a propagar cambios entre sus repositorios
242 locales y compartidos, comenzará a encarar un reto relacionado, pero
243 un poco distinto: Administrar las direcciones en las cuales su equipo
244 puede moverse. A pesar de que está intimamente ligado acerca de cómo
245 interactúa su equipo, es lo suficientemente denso para ameritar un
246 tratamiento en el capítulo~\ref{chap:branch}.
248 \section{Aspectos técnicos de la colaboración}
250 Lo que resta del capítulo lo dedicamos a las cuestiones de servir
251 datos a sus colaboradores.
253 \section{Compartir informalmente con \hgcmd{serve}}
254 \label{sec:collab:serve}
256 La orden \hgcmd{serve} de Mercurial satisface de forma espectacular
257 las necesidades de un grupo pequeño, acoplado y de corto
258 tiempo. Se constituye en una demostración de cómo se siente usar los
259 comandos usando la red.
261 Ejecute \hgcmd{serve} dentro de un repositorio, y en pocos segundos
262 iniciará un servidor HTTP especializado; aceptará conexiones desde
263 cualquier cliente y servirá datos de este repositorio mientrs lo
264 mantenga funcionando. Todo el que sepa el URL del servidor que ha
265 iniciado, y que puede comunicarse con su computador por la red, puede
266 usar un navegador web o Mercurial para leer datos del repositorio. Un
267 URL para una instancia de \hgcmd{serve} ejecutándose en un portátil
268 debería lucir algo \Verb|http://my-laptop.local:8000/|.
270 La orden \hgcmd{serve} \emph{no} es un servidor web de propósito
271 general. Solamente puede hacer dos cosas:
272 \begin{itemize}
273 \item Permitir que se pueda visualizar la historia del repositorio que
274 está sirviendo desde navegadores web.
275 \item Hablar el protocolo de conexión de Mercurial para que puedan hacer
276 \hgcmd{clone} o \hgcmd{pull} (jalar) cambios de tal repositorio.
277 \end{itemize}
278 En particular, \hgcmd{serve} no permitirá que los usuarios remotos
279 puedan \emph{modificar} su repositorio. Es de tipo solo lectura.
281 Si está comenzando con Mercurial, no hay nada que le impida usar
282 \hgcmd{serve} para servir un repositorio en su propio computador, y
283 usar posteriormente órdenes como \hgcmd{clone}, \hgcmd{incoming}, para
284 comunicarse con el servidor como si el repositorio estuviera alojado
285 remotamente. Lo que además puede ayudarle a adecuarse rápidamente para
286 usar comandos en repositorios alojados en la red.
288 \subsection{Cuestiones adicionales para tener en cuenta}
290 Dado que permite lectura sin autenticación a todos sus clientes,
291 debería usar \hgcmd{serve} exclusivamente en ambientes en los cuáles
292 no tenga problema en que otros vean, o en los cuales tenga control
293 completo acerca de quien puede acceder a su red y jalar cambios de su
294 repositorio.
296 La orden \hgcmd{serve} no tiene conocimiento acerca de programas
297 cortafuegos que puedan estar instalados en su sistema o en su red. No
298 puede detectar o controlar sus cortafuegos. Si otras personas no
299 pueden acceder a su instancia \hgcmd{serve}, lo siguiente que debería hacer
300 (\emph{después} de asegurarse que tienen el URL correcto) es verificar
301 su configuración de cortafuegos.
303 De forma predeterminada, \hgcmd{serve} escucha conexiones entrantes en
304 el puerto~8000. Si otro proceso está escuchando en tal puerto, usted
305 podrá especificar un puerto distinto para escuchar con la opción
306 \hgopt{serve}{-p} .
308 Normalmente, cuando se inicia \hgcmd{serve}, no imprime nada, lo cual
309 puede ser desconcertante. Si desea confirmar que en efecto está
310 ejecutándose correctamente, y darse cuenta qué URL debería enviar a
311 sus colaboradores, inícielo con la opción \hggopt{-v}.
313 \section{Uso del protocolo Secure Shell (ssh)}
314 \label{sec:collab:ssh}
316 Usted puede publicar y jalar cambios en la red de forma segura usando
317 el protocolo Secure Shell (\texttt{ssh}). Para usarlo satisfactoriamente,
318 tendrá que hacer algo de configuración a nivel de cliente o el
319 servidor.
321 Si no está familizarizado con ssh, es un protocolo de red que le permite
322 comunicarse con seguridad con otro computador. Para usarlo con
323 Mercurial, estará estableciendo una o más cuentas de usuario en un
324 servidor de forma tal que los usuarios remotos puedan entrar y
325 ejecutar órdenes.
327 (Si ssh le \emph{es} familiar, encontrará probablemente elemental una
328 porción del material a continuación.)
330 \subsection{Cómo leer y escribir URLs de ssh}
332 Los URLs de ssh tienden a lucir de la siguiente forma:
333 \begin{codesample2}
334 ssh://bos@hg.serpentine.com:22/hg/hgbook
335 \end{codesample2}
336 \begin{enumerate}
337 \item La parte ``\texttt{ssh://}'' indica a Mercurial que use el
338 protocolo ssh.
339 \item El componente ``\texttt{bos@}'' indica el nombre del usuario que
340 está entrando al servidor. Puede omitirl si el usuario remoto
341 coincide con el usuario local.
342 \item ``\texttt{hg.serpentine.com}'' es el nombre del servidor al cual
343 se desea entrar.
344 \item El ``:22'' identifica el número del puerto en el servidor al cual
345 se conectará. El predeterminado es el~22, así que solamente
346 necesitará especificar esa porción si \emph{no} está usando el
347 puerto~22.
348 \item La última porción del URL es la ruta local al repositorio en el
349 servidor.
350 \end{enumerate}
352 El componente de la ruta del URL para ssh es una fuente de confusión,
353 puesto que no hay una forma estándar para que las herramientas puedan
354 interpretarlo. Algunos programas se comportan de manera distinta a
355 otros cuando manipulan estas rutas. No es la situación ideal, pero
356 es muy poco probable que vaya a cambiar. Por favor lea los párrafos
357 siguientes cuidadosamente.
359 Mercurial trata la ruta al repositorio en el servidor como relativo al
360 directorio chasa del usuario remoto. Por ejemplo, si el usuario
361 \texttt{foo} en el servidor tiene el directorio casa
362 \dirname{/home/foo},
363 entonces un URL ssh que contenga en su ruta a \dirname{bar}
364 \emph{realmente} se refiere al directorio \dirname{/home/foo/bar}.
366 Si desea especificar una ruta relativa a otro directorio de usuario,
367 puede usar una ruta que comience con un caracter tildado, seguido del
368 nombre del usuario(llamémosle \texttt{otrousuario}, así
369 \begin{codesample2}
370 ssh://server/~otrousuario/hg/repo
371 \end{codesample2}
373 Y si realmente desea especifica una ruta \emph{absoluta} en el
374 servidor, comience con el componente de la ruta con dos barras como
375 en el siguiente ejemplo:
376 \begin{codesample2}
377 ssh://server//absolute/path
378 \end{codesample2}
380 \subsection{Encontrar un cliente ssh para su sistema}
382 Casi todos los sistemas tipo Unix vienen con OpenSSH preinstalado. Si
383 usted está usando un sistema de estos, ejecute \Verb|which ssh| para
384 identificar dónde está instalada la orden \command{ssh} (usualmente
385 estará en \dirname{/usr/bin}). Si por casualidad no está presente,
386 vea la documentación de sus sistema para lograr instalarlo.
388 En Windows, tendrá que escoger primero un cliente adecuado para
389 descargarlo. Hay dos alternativas:
390 \begin{itemize}
391 \item El excelente paquete PuTTY~\cite{web:putty} de Simon Tatham, que
392 ofrece un suite completo de órdenes de cliente ssh.
393 \item Si tiene alta tolerancia al dolor, puede usar el porte de Cygwin
394 para OpenSSH.
395 \end{itemize}
396 En cualquier caso, tendrá que editar su fichero \hgini\ para indicarle
397 a Mercurial dónde encontrar la orden real del cliente. Por ejemplo, si
398 está usando PuTTY, tendrá que usar la orden \command{plink} como un
399 cliente de línea de órdenes.
400 \begin{codesample2}
401 [ui]
402 ssh = C:/ruta/a/plink.exe -ssh -i "C:/ruta/a/mi/llave/privada"
403 \end{codesample2}
405 \begin{note}
406 La ruta a \command{plink} no debería contener espacios o caracteres
407 en blanco, o Mercurial no podrá encontrarlo correctamente (por lo
408 tanto, probablemente no sería buena idea colocarlo en
409 \dirname{C:\\Program Files}
410 \end{note}
412 \subsection{Generar un par de llaves}
414 Para evitar la necesidad de teclera una clave de forma repetitiva cada
415 vez que necesita usar el cliente, recomiendo generar un par de llaves.
416 En un sistema tipo Unix, la orden \command{ssh-keygen} también se
417 comportará bien. En Windows, si está usando PuTTY, la orden
418 \command{puttygen} es la que necesitará.
420 Cuando genera un par de llaves, se aconseja \emph{comedidamente}
421 protegerlas con una frase de clave. (La única oportunidad en la cual
422 usted querría identificarse una única vez, es cuando está usando
423 el protocolo ssh para tareas automatizadas en una red segura.)
425 No basta con generar un par de llaves. Se requiere adicionar una llave
426 pública al conjunto de llaves autorizadas para todos los usuarios
427 remotos que se vayan a autenticar. Para aquellos servidores que usen
428 OpenSSH(la gran mayoría), significará añadir la llave pública a la
429 lista en el fichero llamado \sfilename{authorized\_keys} en su
430 directorio \sdirname{.ssh}.
432 En sistemas tipo Unix, su llave pública tendrá la extensión
433 \filename{.pub}. Si usa \command{puttygen} en Windows, puede
434 guardar la llave pública en un fichero de su elección, o pegarla desde
435 la ventana en la cual se despliega directamente en el fichero
436 \sfilename{authorized\_keys}.
438 \subsection{Uso de un agente de autenticación}
440 Un agente de autentitcación es un daemonio que almacena frases clave en
441 memoria(olvidará las frases clave si sale y vuelve a entrar). Un cliente
442 ssh notará si está corriendo, y solicitará una frase clave. Si no hay
443 un agente de autenticación corriendo, o el agente no almacena la frase
444 clave necesaria, tendrá que teclear su frase clave cada vez que
445 Mercurial intente comunicarse con un servidor para usted(p.e.~cada vez
446 que jale o publique cambios).
448 El problema de almacenar frases claves en un agente es que es posible
449 para un atacante bien preparado recuperar el texto plano de su frase
450 clave, en alguntos casos incluso si su sistema sea muy alternante.
451 Es su decisión si es un riesgo aceptable. Lo que si es seguro es que
452 evita reteclear.
454 En sistemas tipo Unix, el agente se llama \command{ssh-agent}, y
455 usualmente se ejecuta automáticamente cuando usted entra. Tendrá que
456 usar la orden \command{ssh-add} para añadir frases claves al agente. En
457 Windows, si está usando PuTTY, la orden \command{pageant} actúa como
458 el agente. Añade un ícono a su barra del sistema que le permitirá
459 almacenar frases clave.
461 \subsection{Configurar el lado del servidor apropiadamente}
463 Dado que puede ser dispendioso configurar ssh si usted es nuevo, hay
464 una variedad de cosas que podrían ir mal. Añada piense primero en
465 Mercurial y hay mucho más en qué pensar. La mayor parte de estos
466 problemas potenciales occuren en el lado del servidor, no en el cliente.
467 Las buenas noticias es que una vez tiene una configuración funcional,
468 usualmente continuará trabajando indefinidamente.
470 Antes de intentar que Mercurial hable con un servidor ssh, es mejor
471 asegurarse que puede usar la orden normal \command{ssh} o \command{putty}
472 para comunicarse con el servidor primero. Si tiene problemas usando
473 estas órdenes directamente, de seguro Mercurial no funcionará. Pero aún,
474 esconderá el problema subyacente. Cuando desee revisar un problema
475 relacionado con ssh y Mercurial, debería asegurarse primero que las
476 órdenes de ssh en el lado del cliente funcionan primero, \emph{antes}
477 de preocuparse por si existe un problema con Mercurial.
479 Lo primero para asegurar en el lado del servidor es que puede entrar
480 desde otra máquina. Si no puede entrar con \command{ssh} o
481 \command{putty}, el mensaje de error que obtenga le puede dar pistas
482 de qué ha ido mal. Los problemas más comunes son los siguientes:
483 \begin{itemize}
484 \item Si obitene un error de ``conexión rehusada'', es posible que no
485 haya un daemonio SSH corriendo en el servidor o que no pueda accederse
486 a él por configuraciones de cortafuegos.
487 \item Si obtiene un error de ``no hay ruta hasta el servidor'', puede
488 tener la dirección del servidor incorrecta o un cortafuegos con
489 bloqueo agresivo que no permitirá su existencia.
490 \item Si obtiene un mensaje de ``permiso denegado'', puede que haya
491 tecleado mal el usuario en el servidor, o que haya tecleado
492 incorrectamente la frase clave o la clave del usuario remoto.
493 \end{itemize}
494 En resumen, si tiene problemas al comunicarse con el daemonio ssh del
495 servidor, primero asegúrese de que está corriendo. En muchos sistemas
496 estará instalado, pero deshabilitado de forma predeterminada. Una vez
497 que haya hecho este paso tendrá que revisar si el cortafuegos del
498 servidor está configurado para recibir conexiones entrantes en el
499 puerto en el cual el daemonio de ssh está escuchando(usualmente el~22).
500 No trate de buscar otras posibilidades exóticas o configuraciones
501 erradas haste que haya revisado primero estas dos.
503 Si está usando un agente de autenticación en el lado del cliente para
504 almacenar las frase claves de sus contraseñas, debería poder entrar al
505 servidor sin necesidad de que se le solicite frases claves o
506 contraseñas. Si se le pregunta alguna, a continuación algunas
507 posibilidades:
508 \begin{itemize}
509 \item Puede haber olvidado usar \command{ssh-add} o
510 \command{pageant} para guardar la frase clave.
511 \item Puede haber almacenado una frase clave errónea para la llave.
512 \end{itemize}
513 Si se le solicita la clave del usuario remoto, hay otras posibilidades
514 que deben revisarse:
515 \begin{itemize}
516 \item O bien el directorio del usuario o su directorio \sdirname{.ssh}
517 tiene permisos excesivamente abiertos. Como resultado el daemonio
518 ssh no creerá o leerá su fichero \sfilename{authorized\_keys}.
519 Por ejemplo, un directorio casa o \sdirname{.ssh} causará aveces
520 este síntoma.
521 \item El fichero de usuario \sfilename{authorized\_keys} puede tener
522 un problema. Si alguien distinto al usuario es dueño o puede
523 escribir el archivo, el daemonio ssh no confiará o lo leerá.
524 \end{itemize}
526 En un mundo ideal, debería poder ejecutar la siguiente orden
527 exitósamente, y debería imprimir exactamente una línea de salida,
528 la fecha y hora actual.
529 \begin{codesample2}
530 ssh miservidor fecha
531 \end{codesample2}
533 Si en su servidor tiene guión que se ejecuta a la entrada e imprimie
534 letreros o cualquier otra cosa, incluso cuando se ejecutan órdenes no
535 interactivas como esta, debería arreglarlo antes de continuar, de
536 forma que solamente imprima algo si se ejecuta interactivamente. De
537 otra forma estos letreros al menos llenarán la salida de Mercurial.
538 incluso podrían causar problemas potenciales cuando se ejecuten
539 órdenes de forma remota. Mercurial intenta detectar e ignorar los
540 letreros en sesiones no interactivas de \command{ssh}, pero no es
541 a prueba de tontos. (Si edita sus guiones de entrada en el servidor,
542 la forma usual de ver si un guión de script se ejecuta en un shell
543 interactivo, es verificar el código de retorno de la orden
544 \Verb|tty -s|.)
546 Cuando verifique que el venerado ssh funciona en su servidor, el
547 paso siguiente es asegurar que Mercurial corre en el servidor. La
548 orden siguiente debería ejecutarse satisfactoriamente:
549 \begin{codesample2}
550 ssh miservidor hg version
551 \end{codesample2}
552 Si ve un mensaje de error en lugar de la salida usual de
553 \hgcmd{version}, será porque no ha instalado Mercurial en
554 \dirname{/usr/bin}. No se preocupe si este es el caso; no necesita
555 hacerlo. Pero debería revisar los posibles problemas presentados a
556 continuación:
557 \begin{itemize}
558 \item Está instalado Mercurial en el servidor? Se que suena trivial
559 pero es mejor revisar!
560 \item Tal vez la ruta de búsqueda de la interfaz de órdenes
561 (normalmente vía la variable de ambiente \envar{PATH}) simplemente
562 está mal configurada.
563 \item Puede ser que su variable de ambiente \envar{PATH} soalamente
564 apunte al lugar en el cual está el ejecutable \command{hg} si la
565 sesión de entrada es interactiva. Puede suceder si establece la
566 ruta en el guión de shell de entrada incorrecto. Consulte la
567 documentación de su línea de órdenes.
568 \item La variable de ambiente \envar{PYTHONPATH} puede requerir la
569 ruta a los módulos de Mercurial en Python. Puede que nisiquiera
570 está establecida; podría estar incorrecta; o puede ser que se
571 establezca únicamente cuando hay entradas interactivas.
572 \end{itemize}
574 Si puede ejecutar \hgcmd{version} sobre una conexión ssh,
575 felicitaciones! Ha logrado la interacción entre el cliente y el
576 servidor. Ahora debería poder acceder a los repositorios de
577 Mercurial que tiene el usuario en el servidor. Si tiene problemas
578 con Mercurial y ssh en este punto, intente usar la opción
579 \hggopt{--debug} para tener información más clara de lo que está
580 sucediendo.
582 \subsection{Compresión con ssh}
584 Mercurial no comprime datos cuando usa el protocolo ssh, dado que
585 el protocolo puede comprimir datos transparentemente. Pero el
586 comportamiento predeterminado del cliente ssh es \emph{no}
587 solicitar compresión.
589 Sobre cualquier red distinta a una LAN rápida(incluso con una red
590 inalámbrica), hacer uso de compresión puede mejorar el rendimiento
591 de las operaciones de Mercurial que involucren la red. Por ejemplo,
592 sobre WAN, alguien ha medido la compresión reduciendo la cantidad
593 de tiempo requerido para clonar un repositorio particularmente
594 grande de~51 minutos a~17 minutos.
596 Tanto \command{ssh} como \command{plink} aceptan la opción
597 \cmdopt{ssh}{-C} que activa la compresión. Puede editar fácilmente
598 su \hgrc\ para habilitar la compresión para todos los usos de
599 Mercurial sobre el protocolo ssh.
600 \begin{codesample2}
601 [ui]
602 ssh = ssh -C
603 \end{codesample2}
605 Si usa \command{ssh}, puede reconfigurarlo para que siempre use
606 compresión cuando se comunique con su servidor. Para hacerlo,
607 edite su fichero \sfilename{.ssh/config}(que puede no existir
608 aún), de la siguiente forma:
609 \begin{codesample2}
610 Host hg
611 Compression yes
612 HostName hg.ejemplo.com
613 \end{codesample2}
614 Que define un alias, \texttt{hg}. Cuando lo usa con la orden
615 \command{ssh} o con una URL de Mercurial con protocolo\texttt{ssh},
616 logrará que \command{ssh} se conecte a \texttt{hg.ejemplo.com}
617 con compresión. Que le dará un nombre más corto para teclear y
618 compresión, los cuales por derecho propio son buenos.
620 \section{Uso de CGI a través de HTTP}
621 \label{sec:collab:cgi}
623 Dependiendo de qué tan ambicioso sea, configurar la interfaz CGI
624 de Mercurial puede tomar desde unos minutos hasta varias horas.
626 Comenzaremos con el ejemplo más sencillo, y nos dirigiremos hacia
627 configuraciones más complejas. Incluso para el caso más básico
628 necesitará leer y modificar su configuración del servidor web.
630 \begin{note}
631 Configurar un servidor web es una actividad compleja, engorrosa y
632 altamente dependiente del sistema. De ninguna manera podremos
633 cubrir todos los casos posibles con los cuales pueda encontrarse.
634 Use su discresión y juicio respecto a las secciones siguientes.
635 Esté preparado para cometer muchas equivocaciones, y emplear
636 bastante tiempo leyendo sus bitácoras de error del servidor.
637 \end{note}
639 \subsection{Lista de chequeo de la configuración del servidor web}
641 Antes de continuar, tómese un tiempo para revisar ciertos aspectos de
642 la configuración de su sistema:
644 \begin{enumerate}
645 \item ¿Tiene un servidor web? Mac OS X viene con Apache, pero otros
646 sistemas pueden no tener un servidor web instalado.
647 \item Si tiene un servidor web instalado, ¿Está ejecutándose? En la
648 mayoría de sistemas, aunque esté presente, puede no estar habilitado
649 de forma predeterminada.
650 \item ¿u servidor está configurado para permitir ejecutar programas
651 CGI en el directorio donde planea hacerlo? Casi todos los
652 servidores de forma predeterminada explícitamente inhiben la
653 habilidad de ejecutar programas CGI.
654 \end{enumerate}
656 Si no tiene un servidor web instalado, y no tiene cierta experiencia
657 configurando Apache, debería considerar usar el servidor web
658 \texttt{lighttpd} en lugar de Apache. Apache tiene una reputación
659 bien ganada por su configuración barroca y confusa.
660 A pesar de que \texttt{lighttpd} tiene menos características que
661 Apache en ciertas áreas, las mismas no son relevantes para servir
662 repositorios de Mercurial. Definitivamente es mucho más sencillo
663 comenzar con \texttt{lighttpd} que con Apache.
665 \subsection{Configuración básica de CGI}
667 En sistemas tipo Unix es común que los usuarios tengan un subdirectorio
668 con un nombre como \dirname{public\_html} en su directorio personal,
669 desde el cual pueden servir páginas web. Un fichero llamado \filename{foo}
670 en este directorio será visible en una URL de la forma
671 \texttt{http://www.example.com/\~username/foo}.
673 Para comenzar, encuentre el guión \sfilename{hgweb.cgi} que debería
674 estar presente en su instalación de Mercurial. Si no puede
675 encontrarlo rápidamente una copia local en su sistema, puede
676 descargarlo del repositorio principal de Mercurial en
677 \url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}.
679 Tendrá que copiar este guión en su directorio \dirname{public\_html},
680 y asegurarse que sea ejecutable.
681 \begin{codesample2}
682 cp .../hgweb.cgi ~/public_html
683 chmod 755 ~/public_html/hgweb.cgi
684 \end{codesample2}
685 El argumento \texttt{755} de la orden \command{chmod} es un poco más
686 general que hacerlo ejecutable: Asegura que el guión sea ejecutable
687 por cualquiera, y que el ``grupo'' y los ``otros'' \emph{not} tengan
688 permiso de escritura. Si dejara los permisos de escritura abiertos,
689 , el subsistema \texttt{suexec} de Apache probablemente se negaría
690 a ejecutar el guión. De hecho, \texttt{suexec} también insiste en que
691 el \emph{directorio} en el cual reside el guión no tenga permiso de
692 escritura para otros.
693 \begin{codesample2}
694 chmod 755 ~/public_html
695 \end{codesample2}
697 \subsubsection{What could \emph{possibly} go wrong?}
698 \label{sec:collab:wtf}
700 Once you've copied the CGI script into place, go into a web browser,
701 and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi},
702 \emph{but} brace yourself for instant failure. There's a high
703 probability that trying to visit this URL will fail, and there are
704 many possible reasons for this. In fact, you're likely to stumble
705 over almost every one of the possible errors below, so please read
706 carefully. The following are all of the problems I ran into on a
707 system running Fedora~7, with a fresh installation of Apache, and a
708 user account that I created specially to perform this exercise.
710 Your web server may have per-user directories disabled. If you're
711 using Apache, search your config file for a \texttt{UserDir}
712 directive. If there's none present, per-user directories will be
713 disabled. If one exists, but its value is \texttt{disabled}, then
714 per-user directories will be disabled. Otherwise, the string after
715 \texttt{UserDir} gives the name of the subdirectory that Apache will
716 look in under your home directory, for example \dirname{public\_html}.
718 Your file access permissions may be too restrictive. The web server
719 must be able to traverse your home directory and directories under
720 your \dirname{public\_html} directory, and read files under the latter
721 too. Here's a quick recipe to help you to make your permissions more
722 appropriate.
723 \begin{codesample2}
724 chmod 755 ~
725 find ~/public_html -type d -print0 | xargs -0r chmod 755
726 find ~/public_html -type f -print0 | xargs -0r chmod 644
727 \end{codesample2}
729 The other possibility with permissions is that you might get a
730 completely empty window when you try to load the script. In this
731 case, it's likely that your access permissions are \emph{too
732 permissive}. Apache's \texttt{suexec} subsystem won't execute a
733 script that's group-~or world-writable, for example.
735 Your web server may be configured to disallow execution of CGI
736 programs in your per-user web directory. Here's Apache's
737 default per-user configuration from my Fedora system.
738 \begin{codesample2}
739 <Directory /home/*/public_html>
740 AllowOverride FileInfo AuthConfig Limit
741 Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
742 <Limit GET POST OPTIONS>
743 Order allow,deny
744 Allow from all
745 </Limit>
746 <LimitExcept GET POST OPTIONS>
747 Order deny,allow
748 Deny from all
749 </LimitExcept>
750 </Directory>
751 \end{codesample2}
752 If you find a similar-looking \texttt{Directory} group in your Apache
753 configuration, the directive to look at inside it is \texttt{Options}.
754 Add \texttt{ExecCGI} to the end of this list if it's missing, and
755 restart the web server.
757 If you find that Apache serves you the text of the CGI script instead
758 of executing it, you may need to either uncomment (if already present)
759 or add a directive like this.
760 \begin{codesample2}
761 AddHandler cgi-script .cgi
762 \end{codesample2}
764 The next possibility is that you might be served with a colourful
765 Python backtrace claiming that it can't import a
766 \texttt{mercurial}-related module. This is actually progress! The
767 server is now capable of executing your CGI script. This error is
768 only likely to occur if you're running a private installation of
769 Mercurial, instead of a system-wide version. Remember that the web
770 server runs the CGI program without any of the environment variables
771 that you take for granted in an interactive session. If this error
772 happens to you, edit your copy of \sfilename{hgweb.cgi} and follow the
773 directions inside it to correctly set your \envar{PYTHONPATH}
774 environment variable.
776 Finally, you are \emph{certain} to by served with another colourful
777 Python backtrace: this one will complain that it can't find
778 \dirname{/path/to/repository}. Edit your \sfilename{hgweb.cgi} script
779 and replace the \dirname{/path/to/repository} string with the complete
780 path to the repository you want to serve up.
782 At this point, when you try to reload the page, you should be
783 presented with a nice HTML view of your repository's history. Whew!
785 \subsubsection{Configuring lighttpd}
787 To be exhaustive in my experiments, I tried configuring the
788 increasingly popular \texttt{lighttpd} web server to serve the same
789 repository as I described with Apache above. I had already overcome
790 all of the problems I outlined with Apache, many of which are not
791 server-specific. As a result, I was fairly sure that my file and
792 directory permissions were good, and that my \sfilename{hgweb.cgi}
793 script was properly edited.
795 Once I had Apache running, getting \texttt{lighttpd} to serve the
796 repository was a snap (in other words, even if you're trying to use
797 \texttt{lighttpd}, you should read the Apache section). I first had
798 to edit the \texttt{mod\_access} section of its config file to enable
799 \texttt{mod\_cgi} and \texttt{mod\_userdir}, both of which were
800 disabled by default on my system. I then added a few lines to the end
801 of the config file, to configure these modules.
802 \begin{codesample2}
803 userdir.path = "public_html"
804 cgi.assign = ( ".cgi" => "" )
805 \end{codesample2}
806 With this done, \texttt{lighttpd} ran immediately for me. If I had
807 configured \texttt{lighttpd} before Apache, I'd almost certainly have
808 run into many of the same system-level configuration problems as I did
809 with Apache. However, I found \texttt{lighttpd} to be noticeably
810 easier to configure than Apache, even though I've used Apache for over
811 a decade, and this was my first exposure to \texttt{lighttpd}.
813 \subsection{Sharing multiple repositories with one CGI script}
815 The \sfilename{hgweb.cgi} script only lets you publish a single
816 repository, which is an annoying restriction. If you want to publish
817 more than one without wracking yourself with multiple copies of the
818 same script, each with different names, a better choice is to use the
819 \sfilename{hgwebdir.cgi} script.
821 The procedure to configure \sfilename{hgwebdir.cgi} is only a little
822 more involved than for \sfilename{hgweb.cgi}. First, you must obtain
823 a copy of the script. If you don't have one handy, you can download a
824 copy from the master Mercurial repository at
825 \url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}.
827 You'll need to copy this script into your \dirname{public\_html}
828 directory, and ensure that it's executable.
829 \begin{codesample2}
830 cp .../hgwebdir.cgi ~/public_html
831 chmod 755 ~/public_html ~/public_html/hgwebdir.cgi
832 \end{codesample2}
833 With basic configuration out of the way, try to visit
834 \url{http://myhostname/~myuser/hgwebdir.cgi} in your browser. It
835 should display an empty list of repositories. If you get a blank
836 window or error message, try walking through the list of potential
837 problems in section~\ref{sec:collab:wtf}.
839 The \sfilename{hgwebdir.cgi} script relies on an external
840 configuration file. By default, it searches for a file named
841 \sfilename{hgweb.config} in the same directory as itself. You'll need
842 to create this file, and make it world-readable. The format of the
843 file is similar to a Windows ``ini'' file, as understood by Python's
844 \texttt{ConfigParser}~\cite{web:configparser} module.
846 The easiest way to configure \sfilename{hgwebdir.cgi} is with a
847 section named \texttt{collections}. This will automatically publish
848 \emph{every} repository under the directories you name. The section
849 should look like this:
850 \begin{codesample2}
851 [collections]
852 /my/root = /my/root
853 \end{codesample2}
854 Mercurial interprets this by looking at the directory name on the
855 \emph{right} hand side of the ``\texttt{=}'' sign; finding
856 repositories in that directory hierarchy; and using the text on the
857 \emph{left} to strip off matching text from the names it will actually
858 list in the web interface. The remaining component of a path after
859 this stripping has occurred is called a ``virtual path''.
861 Given the example above, if we have a repository whose local path is
862 \dirname{/my/root/this/repo}, the CGI script will strip the leading
863 \dirname{/my/root} from the name, and publish the repository with a
864 virtual path of \dirname{this/repo}. If the base URL for our CGI
865 script is \url{http://myhostname/~myuser/hgwebdir.cgi}, the complete
866 URL for that repository will be
867 \url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}.
869 If we replace \dirname{/my/root} on the left hand side of this example
870 with \dirname{/my}, then \sfilename{hgwebdir.cgi} will only strip off
871 \dirname{/my} from the repository name, and will give us a virtual
872 path of \dirname{root/this/repo} instead of \dirname{this/repo}.
874 The \sfilename{hgwebdir.cgi} script will recursively search each
875 directory listed in the \texttt{collections} section of its
876 configuration file, but it will \texttt{not} recurse into the
877 repositories it finds.
879 The \texttt{collections} mechanism makes it easy to publish many
880 repositories in a ``fire and forget'' manner. You only need to set up
881 the CGI script and configuration file one time. Afterwards, you can
882 publish or unpublish a repository at any time by simply moving it
883 into, or out of, the directory hierarchy in which you've configured
884 \sfilename{hgwebdir.cgi} to look.
886 \subsubsection{Explicitly specifying which repositories to publish}
888 In addition to the \texttt{collections} mechanism, the
889 \sfilename{hgwebdir.cgi} script allows you to publish a specific list
890 of repositories. To do so, create a \texttt{paths} section, with
891 contents of the following form.
892 \begin{codesample2}
893 [paths]
894 repo1 = /my/path/to/some/repo
895 repo2 = /some/path/to/another
896 \end{codesample2}
897 In this case, the virtual path (the component that will appear in a
898 URL) is on the left hand side of each definition, while the path to
899 the repository is on the right. Notice that there does not need to be
900 any relationship between the virtual path you choose and the location
901 of a repository in your filesystem.
903 If you wish, you can use both the \texttt{collections} and
904 \texttt{paths} mechanisms simultaneously in a single configuration
905 file.
907 \begin{note}
908 If multiple repositories have the same virtual path,
909 \sfilename{hgwebdir.cgi} will not report an error. Instead, it will
910 behave unpredictably.
911 \end{note}
913 \subsection{Downloading source archives}
915 Mercurial's web interface lets users download an archive of any
916 revision. This archive will contain a snapshot of the working
917 directory as of that revision, but it will not contain a copy of the
918 repository data.
920 By default, this feature is not enabled. To enable it, you'll need to
921 add an \rcitem{web}{allow\_archive} item to the \rcsection{web}
922 section of your \hgrc.
924 \subsection{Web configuration options}
926 Mercurial's web interfaces (the \hgcmd{serve} command, and the
927 \sfilename{hgweb.cgi} and \sfilename{hgwebdir.cgi} scripts) have a
928 number of configuration options that you can set. These belong in a
929 section named \rcsection{web}.
930 \begin{itemize}
931 \item[\rcitem{web}{allow\_archive}] Determines which (if any) archive
932 download mechanisms Mercurial supports. If you enable this
933 feature, users of the web interface will be able to download an
934 archive of whatever revision of a repository they are viewing.
935 To enable the archive feature, this item must take the form of a
936 sequence of words drawn from the list below.
937 \begin{itemize}
938 \item[\texttt{bz2}] A \command{tar} archive, compressed using
939 \texttt{bzip2} compression. This has the best compression ratio,
940 but uses the most CPU time on the server.
941 \item[\texttt{gz}] A \command{tar} archive, compressed using
942 \texttt{gzip} compression.
943 \item[\texttt{zip}] A \command{zip} archive, compressed using LZW
944 compression. This format has the worst compression ratio, but is
945 widely used in the Windows world.
946 \end{itemize}
947 If you provide an empty list, or don't have an
948 \rcitem{web}{allow\_archive} entry at all, this feature will be
949 disabled. Here is an example of how to enable all three supported
950 formats.
951 \begin{codesample4}
952 [web]
953 allow_archive = bz2 gz zip
954 \end{codesample4}
955 \item[\rcitem{web}{allowpull}] Boolean. Determines whether the web
956 interface allows remote users to \hgcmd{pull} and \hgcmd{clone} this
957 repository over~HTTP. If set to \texttt{no} or \texttt{false}, only
958 the ``human-oriented'' portion of the web interface is available.
959 \item[\rcitem{web}{contact}] String. A free-form (but preferably
960 brief) string identifying the person or group in charge of the
961 repository. This often contains the name and email address of a
962 person or mailing list. It often makes sense to place this entry in
963 a repository's own \sfilename{.hg/hgrc} file, but it can make sense
964 to use in a global \hgrc\ if every repository has a single
965 maintainer.
966 \item[\rcitem{web}{maxchanges}] Integer. The default maximum number
967 of changesets to display in a single page of output.
968 \item[\rcitem{web}{maxfiles}] Integer. The default maximum number
969 of modified files to display in a single page of output.
970 \item[\rcitem{web}{stripes}] Integer. If the web interface displays
971 alternating ``stripes'' to make it easier to visually align rows
972 when you are looking at a table, this number controls the number of
973 rows in each stripe.
974 \item[\rcitem{web}{style}] Controls the template Mercurial uses to
975 display the web interface. Mercurial ships with two web templates,
976 named \texttt{default} and \texttt{gitweb} (the latter is much more
977 visually attractive). You can also specify a custom template of
978 your own; see chapter~\ref{chap:template} for details. Here, you
979 can see how to enable the \texttt{gitweb} style.
980 \begin{codesample4}
981 [web]
982 style = gitweb
983 \end{codesample4}
984 \item[\rcitem{web}{templates}] Path. The directory in which to search
985 for template files. By default, Mercurial searches in the directory
986 in which it was installed.
987 \end{itemize}
988 If you are using \sfilename{hgwebdir.cgi}, you can place a few
989 configuration items in a \rcsection{web} section of the
990 \sfilename{hgweb.config} file instead of a \hgrc\ file, for
991 convenience. These items are \rcitem{web}{motd} and
992 \rcitem{web}{style}.
994 \subsubsection{Options specific to an individual repository}
996 A few \rcsection{web} configuration items ought to be placed in a
997 repository's local \sfilename{.hg/hgrc}, rather than a user's or
998 global \hgrc.
999 \begin{itemize}
1000 \item[\rcitem{web}{description}] String. A free-form (but preferably
1001 brief) string that describes the contents or purpose of the
1002 repository.
1003 \item[\rcitem{web}{name}] String. The name to use for the repository
1004 in the web interface. This overrides the default name, which is the
1005 last component of the repository's path.
1006 \end{itemize}
1008 \subsubsection{Options specific to the \hgcmd{serve} command}
1010 Some of the items in the \rcsection{web} section of a \hgrc\ file are
1011 only for use with the \hgcmd{serve} command.
1012 \begin{itemize}
1013 \item[\rcitem{web}{accesslog}] Path. The name of a file into which to
1014 write an access log. By default, the \hgcmd{serve} command writes
1015 this information to standard output, not to a file. Log entries are
1016 written in the standard ``combined'' file format used by almost all
1017 web servers.
1018 \item[\rcitem{web}{address}] String. The local address on which the
1019 server should listen for incoming connections. By default, the
1020 server listens on all addresses.
1021 \item[\rcitem{web}{errorlog}] Path. The name of a file into which to
1022 write an error log. By default, the \hgcmd{serve} command writes this
1023 information to standard error, not to a file.
1024 \item[\rcitem{web}{ipv6}] Boolean. Whether to use the IPv6 protocol.
1025 By default, IPv6 is not used.
1026 \item[\rcitem{web}{port}] Integer. The TCP~port number on which the
1027 server should listen. The default port number used is~8000.
1028 \end{itemize}
1030 \subsubsection{Choosing the right \hgrc\ file to add \rcsection{web}
1031 items to}
1033 It is important to remember that a web server like Apache or
1034 \texttt{lighttpd} will run under a user~ID that is different to yours.
1035 CGI scripts run by your server, such as \sfilename{hgweb.cgi}, will
1036 usually also run under that user~ID.
1038 If you add \rcsection{web} items to your own personal \hgrc\ file, CGI
1039 scripts won't read that \hgrc\ file. Those settings will thus only
1040 affect the behaviour of the \hgcmd{serve} command when you run it. To
1041 cause CGI scripts to see your settings, either create a \hgrc\ file in
1042 the home directory of the user ID that runs your web server, or add
1043 those settings to a system-wide \hgrc\ file.
1046 %%% Local Variables:
1047 %%% mode: latex
1048 %%% TeX-master: "00book"
1049 %%% End: