Control de versiones con Subversion

Todos los sistemas de control de versiones tienen que resolver un problema fundamental: ¿Cómo permitirá el sistema a los usuarios el compartir información, pero al mismo tiempo impedirá que se pisen los callos mutuamente de forma accidental? Es muy sencillo para los usuarios el sobreescribir accidentalmente los cambios de los demás en el repositorio.

Considere el escenario mostrado en Figura 2.2, “El problema a evitar”. Suponga que tenemos dos colaboradores, Juan y Carmen. Cada uno de ellos decide editar el mismo archivo del repositorio al mismo tiempo. Si Juan guarda sus cambios en el repositorio en primer lugar, es posible que (unos momentos más tarde) Carmen los sobreescriba accidentalmente con su propia versión del archivo. Si bien es cierto que la versión de Juan no se ha perdido para siempre (porque el sistema recuerda cada cambio), cualquier cambio que Juan haya hecho no estará presente en la versión más reciente de Carmen porque, para empezar, ella nunca vio los cambios de Juan. El trabajo de Juan sigue efectivamente perdido—o al menos ausente en la última versión del archivo—y probablemente por accidente. ¡Esta es definitivamente una situación que queremos evitar!

Figura 2.2. El problema a evitar

Muchos sistemas de control de versiones utilizan un modelo de bloqueo-modificación-desbloqueo para atacar este problema. En un sistema como éste, el repositorio sólo permite a una persona modificar un archivo al mismo tiempo. Juan debe “bloquear” primero el archivo para luego empezar a hacerle cambios. Bloquear un archivo se parece mucho a pedir prestado un libro de la biblioteca; si Juan ha bloqueado el archivo, entonces Carmen no puede hacerle cambios. Por consiguiente, si ella intenta bloquear el archivo, el repositorio rechazará la petición. Todo lo que puede hacer es leer el archivo y esperar a que Juan termine sus cambios y deshaga el bloqueo. Tras desbloquear Juan el archivo, Carmen puede aprovechar su turno bloqueando y editando el archivo. La figura Figura 2.3, “La solución bloqueo-modificación-desbloqueo” demuestra esta sencilla solución.

Figura 2.3. La solución bloqueo-modificación-desbloqueo

El problema con el modelo bloqueo-modificación-desbloqueo es que es un tanto restrictivo y a menudo se convierte en un obstáculo para los usuarios:

Subversion, CVS y otros sistemas de control de versiones utilizan un modelo del tipo copiar-modificar-mezclar como alternativa al bloqueo. En este modelo, el cliente de cada usuario se conecta al repositorio del proyecto y crea una copia de trabajo personal—una réplica local de los archivos y directorios del repositorio. Los usuarios pueden entonces trabajar en paralelo, modificando sus copias privadas. Finalmente, todas las copias privadas se combinan (o mezclan) en una nueva versión final. El sistema de control de versiones a menudo ayuda con la mezcla, pero en última instancia es un ser humano el responsable de hacer que ésto suceda correctamente.

He aquí un ejemplo. Digamos que Juan y Carmen crean sendas copias de trabajo del mismo proyecto, extraídas del repositorio. Ambos trabajan concurrentemente y hacen cambios a un mismo archivo A dentro de sus copias. Carmen guarda sus cambios en el repositorio primero. Cuando Juan intenta guardar sus cambios más tarde, el repositorio le informa de que su archivo A está desactualizado. En otras palabras, que el archivo A en el repositorio ha sufrido algún cambio desde que lo copió por última vez. Por tanto, Juan le pide a su cliente que mezcle cualquier cambio nuevo del repositorio con su copia de trabajo del archivo A. Es probable que los cambios de Carmen no se solapen con los suyos; así que una vez que tiene ambos juegos de cambios integrados, Juan guarda su copia de trabajo de nuevo en el repositorio. Las figuras Figura 2.4, “La solución copiar-modificar-mezclar” y Figura 2.5, “La solución copiar-modificar-mezclar (continuación)” muestran este proceso.

Figura 2.4. La solución copiar-modificar-mezclar

Figura 2.5. La solución copiar-modificar-mezclar (continuación)

¿Pero qué ocurre si los cambios de Carmen sí se solapan con los de Juan? ¿Entonces qué? Esta situación se conoce como conflicto y no suele suponer un gran problema. Cuando Juan le pide a su cliente que mezcle los últimos cambios del repositorio en su copia de trabajo, su copia del archivo A se marca de algún modo para indicar que está en estado de conflicto: Juan podrá ver ambos conjuntos de cambios conflictivos y escoger manualmente entre ellos. Observe que el programa no puede resolver automáticamente los conflictos; sólo los humanos son capaces de entender y tomar las decisiones inteligentes oportunas. Una vez que Juan ha resuelto manualmente los cambios solapados—posiblemente después de discutirlos con Carmen—ya podrá guardar con seguridad el archivo mezclado en el repositorio.

La solución copiar-modificar-mezclar puede sonar un tanto caótica, pero en la práctica funciona extremadamente bien. Los usuarios pueden trabajar en paralelo, sin tener que esperarse el uno al otro. Cuando trabajan en los mismos archivos, sucede que la mayoría de sus cambios concurrentes no se solapan en absoluto; los conflictos son poco frecuentes. El tiempo que toma resolver los conflictos es mucho menor que el tiempo perdido por un sistema de bloqueos.

Al final, todo desemboca en un factor crítico: la comunicación entre los usuarios. Cuando los usuarios se comunican pobremente, los conflictos tanto sintácticos como semánticos aumentan. Ningún sistema puede forzar a los usuarios a comunicarse perfectamente, y ningún sistema puede detectar conflictos semánticos. Por consiguiente, no tiene sentido dejarse adormecer por la falsa promesa de que un sistema de bloqueos evitará de algún modo los conflictos; en la práctica, el bloqueo parece inhibir la productividad más que otra cosa.

Ya ha leído acerca de las copias de trabajo; ahora demostraremos cómo las crea y las usa el cliente de Subversion.

Una copia de trabajo de Subversion es un árbol de directorios corriente de su sistema de archivos local, conteniendo una colección de archivos. Usted puede editar estos archivos del modo que prefiera y si se trata de archivos de código fuente, podrá compilar su programa a partir de ellos de la manera habitual. Su copia de trabajo es su área de trabajo privada: Subversion nunca incorporará los cambios de otra gente o pondrá a disposición de otros sus cambios hasta que usted le indique explícitamente que lo haga.

Tras hacer algunos cambios a los archivos en su copia de trabajo y verificar que funcionan correctamente, Subversion le proporciona comandos para “publicar” sus cambios al resto de personas que trabajan con usted en su proyecto (escribiendo en el repositorio). Si las demás personas publican sus propios cambios, Subversion le proporciona comandos para mezclar estos cambios en su directorio de trabajo (leyendo del repositorio).

Una copia de trabajo también contiene algunos archivos extra, creados y mantenidos por Subversion para ayudarle a ejecutar estos comandos. En particular, cada directorio de su copia de trabajo contiene un subdirectorio llamado .svn, también conocido como el directorio administrativo de la copia de trabajo. Los archivos en cada directorio administrativo ayudan a Subversion a reconocer qué archivos contienen cambios no publicados y qué archivos están desactualizados con respecto al trabajo hecho por los demás.

Un repositorio típico de Subversion contiene a menudo los archivos (o el código fuente) de varios proyectos; normalmente, cada proyecto es un subdirectorio en el árbol del sistema de archivos del repositorio. En esta disposición, la copia de trabajo de un usuario se corresponde habitualmente con un subárbol particular del repositorio.

Por ejemplo, suponga que usted tiene un repositorio que contiene dos proyectos de software, paint y calc. Cada proyecto reside en su propio subdirectorio dentro del directorio raíz, tal como se muestra en Figura 2.6, “El sistema de archivos del repositorio”.

Figura 2.6. El sistema de archivos del repositorio

Para conseguir una copia de trabajo, debe ejecutar primero un check out de algún subárbol del repositorio. (El término inglés “check out” puede sonar como si tuviera algo que ver con bloquear o reservar recursos, pero no es así; tan sólo crea una copia privada del proyecto para usted). Por ejemplo, si usted hace un check out de /calc, obtendrá una copia de trabajo como ésta:

$ svn checkout http://svn.example.com/repos/calc
A  calc
A  calc/Makefile
A  calc/integer.c
A  calc/button.c

$ ls -A calc
Makefile  integer.c  button.c  .svn/

La lista de letras A indica que Subversion está añadiendo una serie de elementos a su copia de trabajo. Usted ahora tiene una copia personal del directorio /calc del repositorio, con una entrada adicional—.svn—que contiene la información extra que Subversion necesita, tal y como se mencionó anteriormente.

$ svn checkout file:///ruta/a/repositorio
…
$ svn checkout file://localhost/ruta/a/repositorio
…

C:\> svn checkout file:///X:/ruta/a/repositorio
…
C:\> svn checkout "file:///X|/ruta/a/repositorio"
…

Suponga que hace cambios a button.c. Puesto que el directorio .svn recuerda la fecha de modificación del archivo y su contenido original, Subversion es capaz de darse cuenta de que el archivo ha cambiado. Sin embargo, Subversion no hará públicos sus cambios hasta que usted no le diga explícitamente que lo haga. El acto de publicar sus cambios es conocido comúnmente como consignar (o registrar) los cambios al repositorio.

Para publicar sus cambios a otros, usted puede utilizar el comando commit de Subversion:

$ svn commit button.c
Sending        button.c
Transmitting file data .
Committed revision 57.

Ahora sus cambios a button.c han sido consignados al repositorio; si otro usuario obtiene una copia de trabajo de /calc, podrá ver sus cambios en la última versión del archivo.

Suponga que tiene un colaborador, Carmen, quien obtuvo una copia de trabajo de /calc al mismo tiempo que usted. Cuando usted envía sus cambios sobre button.c, la copia de trabajo de Carmen se deja sin cambios; Subversion solo modifica las copias de trabajo a petición del usuario.

Para tener su proyecto actualizado, Carmen puede pedir a Subversion que proceda a actualizar su copia de trabajo, usando para ello el comando update de Subversion. Ésto incorporará los cambios hechos por usted en la copia de trabajo de Carmen, así como otros cambios consignados desde que ella hizo el check out.

$ pwd
/home/sally/calc

$ ls -A 
.svn/ Makefile integer.c button.c

$ svn update
U button.c

La salida del comando svn update indica que Subversion actualizó el contenido de button.c. Observe que Carmen no necesitó especificar qué archivos actualizar; Subversion usa la información del directorio .svn, junto con información adicional del repositorio, para decidir qué archivos necesitan una actualización.

Una operación svn commit puede publicar los cambios sobre cualquier número de ficheros y directorios como una única transacción atómica. En su copia privada, usted puede cambiar el contenido de los ficheros, crear, borrar, renombrar y copiar ficheros y directorios, y luego enviar el conjunto entero de cambios como si se tratara de una unidad.

En el repositorio, cada cambio es tratado como una transacción atómica: o bien se realizan todos los cambios, o no se realiza ninguno. Subversion trata de conservar esta atomicidad para hacer frente a posibles fallos del programa, fallos del sistema, problemas con la red, y otras acciones del usuario.

Cada vez que el repositorio acepta un envío, éste da lugar a un nuevo estado del árbol de ficheros llamado revisión. A cada revisión se le asigna un número natural único, una unidad mayor que el número de la revisión anterior. La revisión inicial de un repositorio recién creado se numera con el cero, y consiste únicamente en un directorio raíz vacío.

La Figura 2.7, “El repositorio” ilustra una manera interesante de ver el repositorio. Imagine un array de números de revisión, comenzando por el 0, que se extiende de izquierda a derecha. Cada número de revisión tiene un árbol de ficheros colgando debajo de él, y cada árbol es una “instantánea” del aspecto del repositorio tras cada envío.

Figura 2.7. El repositorio

Es importante observar que las copias de trabajo no siempre se corresponden con una revisión en particular del repositorio; pueden contener ficheros de varias revisiones diferentes. Por ejemplo, suponga que obtiene una copia de trabajo de un repositorio cuya revisión más reciente es la 4:

calc/Makefile:4
     integer.c:4
     button.c:4

Por el momento, esta copia de trabajo se corresponde exactamente con la revisión 4 del repositorio. Sin embargo, suponga que realiza un cambio a button.c y lo publica. Suponiendo que no se han realizado otros envíos, el suyo creará la revisión 5 del repositorio, y su copia de trabajo aparecerá ahora así:

calc/Makefile:4
     integer.c:4
     button.c:5

Suponga que, en este punto, Carmen envía un cambio a integer.c, creando la revisión 6. Si usted usa svn update para actualizar su copia de trabajo, ésta se verá ahora como:

calc/Makefile:6
     integer.c:6
     button.c:6

Los cambios de Carmen sobre integer.c aparecerán en su copia de trabajo y las modificaciones hechas por usted seguirán presentes en button.c. En este ejemplo, el texto de Makefile es idéntico en las revisiones 4, 5 y 6, aunque Subversion marcará su copia de trabajo de Makefile con la revisión 6 para indicar que ya está actualizada. Por lo tanto, después de hacer una actualización limpia en el directorio raíz de su copia de trabajo, ésta se corresponderá generalmente con una revisión del repositorio exactamente.

Para cada fichero de una copia de trabajo, Subversion registra dos datos esenciales en el área administrativa .svn/:

Con esta información, y comunicándose con el repositorio, Subversion puede conocer en cuál de los cuatro estados siguientes se encuentra el fichero de la copia de trabajo:

Todo ésto puede parecer un montón de cosas a tener en cuenta, pero el comando svn status le mostrará el estado de cualquier elemento de su copia de trabajo. Para obtener más información acerca de ese comando, vea “svn status”.

Por norma general, Subversion trata de ser tan flexible como sea posible. Un tipo especial de flexibilidad es la habilidad para tener dentro de una copia de trabajo números de revisión mixtos.

Para comenzar, puede que no esté completamente claro el por qué este tipo de flexibilidad se considera una característica y no un problema. Después de completar un envío al repositorio, los ficheros y directorios recién enviados se encuentran en una revisión de trabajo más reciente que el resto de la copia de trabajo. Parece un poco lioso. Tal como se mostró anteriormente, siempre se puede dejar una copia de trabajo en una única revisión de trabajo ejecutando svn update. ¿Por qué querría alguien deliberadamente tener una mezcla de revisiones de trabajo?

Suponiendo que su proyecto es lo suficientemente complejo, descubrirá que a veces es conveniente forzar la “desactualización” de ciertas partes de su copia de trabajo a una versión anterior; aprenderá cómo hacer ésto en el capítulo 3. Quizás quiera probar una versión anterior de un submódulo contenido en un subdirectorio, o tal vez quiera examinar una serie de versiones previas de un fichero en el contexto del último árbol.

Por mucho que usted haga uso de revisiones mixtas en su copia de trabajo, hay ciertas limitaciones asociadas a esta flexibilidad.

Primero, usted no puede publicar la eliminación de un fichero o directorio que no esté completamente actualizado. Si existe una versión más reciente en el repositorio, su intento de eliminación será rechazado para impedir que destruya accidentalmente cambios que aún no ha visto.

Segundo, usted no puede publicar los cambios en los metadatos de un directorio a menos que esté completamente actualizado. Aprenderá cómo adjuntar “propiedades” a elementos en el capítulo 6. Una revisión de trabajo de un directorio define un conjunto específico de entradas y propiedades, y por tanto enviar un cambio a una propiedad de un directorio desactualizado puede destruir las propiedades que no haya visto todavía.

Cuando usted crea un nuevo repositorio de Subversion, este comienza su vida en la revisión cero y cada envío sucesivo incrementa el número de revisión en uno. Después de completar su envío, el cliente de Subversion le informa del nuevo número de revisión:

$ svn commit --message "Corrected number of cheese slices."
Sending        sandwich.txt
Transmitting file data .
Committed revision 3.

Si en cualquier punto del futuro usted quiere referirse a esa revisión (veremos cómo y por qué podríamos querer hacer esto más adelante en este capítulo), puede referirse a ella como “3”.

El cliente de Subversion entiende una cantidad de palabras clave de la revisión. Estas palabras clave pueden ser usadas en vez del número entero como argumento a la opción --revision, y son resueltos como números específicos de revisión por Subversion:

Nota

Cada directorio en su copia de trabajo contiene un subdirectorio administrativo llamado .svn. Para todos los ficheros en un directorio, Subversion mantiene una copia de cada fichero en el área administrativa. Esta copia es una copia no modificada (ninguna expansión de palabra clave, ninguna traducción del fin de línea, nada de nada) del fichero tal como existió en la última revisión (llamada la revisión “BASE”) que usted actualizó a su copia de trabajo. Nos referimos a este fichero como copia prístina o versión basada en texto de su fichero, y siempre es una copia byte-a-byte exacta del fichero tal como existe en el repositorio.

	Nota
	PREV, BASE, y COMMITTED pueden ser usadas para referirse a rutas locales, pero no a URLs.

Aquí hay algunos ejemplos de palabras clave de revisión en acción. No se preocupe si los comandos no tienen sentido todavía; estaremos explicando estos comandos a medida que avancemos por el capítulo:

$ svn diff --revision PREV:COMMITTED foo.c
# shows the last change committed to foo.c

$ svn log --revision HEAD
# shows log message for the latest repository commit

$ svn diff --revision HEAD
# compares your working file (with local mods) to the latest version
# in the repository.

$ svn diff --revision BASE:HEAD foo.c
# compares your “pristine” foo.c (no local mods) with the 
# latest version in the repository

$ svn log --revision BASE:HEAD
# shows all commit logs since you last updated

$ svn update --revision PREV foo.c
# rewinds the last change on foo.c.
# (foo.c's working revision is decreased.)

Estas palabras clave le permiten realizar muchas operaciones comunes (y útiles) sin tener que buscar números específicos de revisión o recordar la revisión exacta de su copia de trabajo.

Dondequiera que usted especifique un número de revisión o palabra clave de revisión, usted también puede especificar una fecha dentro de llaves “{}”. ¡Puede incluso tener acceso a un rango de cambios en el repositorio usando fechas y revisiones juntas!

Aquí hay ejemplos de los formatos de fecha que admite Subversion. Recuerde usar comillas alrededor de cualquier fecha que contenga espacios.

$ svn checkout --revision {2002-02-17}
$ svn checkout --revision {15:30}
$ svn checkout --revision {15:30:00.200000}
$ svn checkout --revision {"2002-02-17 15:30"}
$ svn checkout --revision {"2002-02-17 15:30 +0230"}
$ svn checkout --revision {2002-02-17T15:30}
$ svn checkout --revision {2002-02-17T15:30Z}
$ svn checkout --revision {2002-02-17T15:30-04:00}
$ svn checkout --revision {20020217T1530}
$ svn checkout --revision {20020217T1530Z}
$ svn checkout --revision {20020217T1530-0500}
…

Cuando usted especifica una fecha como revisión, Subversion encuentra la revisión más reciente en el repositorio a esa fecha:

$ svn log --revision {2002-11-28}
------------------------------------------------------------------------
r12 | ira | 2002-11-27 12:31:51 -0600 (Wed, 27 Nov 2002) | 6 lines
…

También puede especificar un rango de fechas. Subversion encontrará todas las revisiones entre ambas fechas, inclusive:

$ svn log --revision {2002-11-20}:{2002-11-29}
…

Como señalamos, también puede mezclar fechas y revisiones:

$ svn log --revision {2002-11-20}:4040

Los usuarios deberían estar enterados de una sutileza que puede convertirse en un obstáculo al tratar con fechas en Subversion. Como la marca de tiempo de una revisión es guardada como una propiedad de la revisión— una propiedad sin versionar, modificable — las marcas de tiempo de las revisiones pueden cambiarse para representar una falsificación completa de la verdadera cronología, o incluso borrarla totalmente. Esto causará estragos en la conversión interna fecha-a-revisión que realiza Subversion.

Cuando se trabaja en un proyecto con un equipo, usted querrá actualizar su copia de trabajo local para recibir cualquier cambio hecho desde su última actualización por otros desarrolladores en el proyecto. Use svn update para poner a su copia de trabajo local en sincronía con la última revisión en el repositorio.

$ svn update
U  foo.c
U  bar.c
Updated to revision 2.

En este caso, alguien envió modificaciones a foo.c y bar.c desde la última vez que usted actualizó, y Subversion ha actualizado su copia de trabajo local para incluir estos cambios.

Vamos a examinar la salida de svn update un poco más. Cuando el servidor envía cambios a su copia de trabajo local, un código de letras es mostrado al lado de cada elemento para hacerle saber qué acciones realizó Subversion para actualizar su copia de trabajo local:

Ahora puede conseguir trabajar y hacer cambios en su copia de trabajo local. Generalmente es más conveniente decidir un cambio particular (o un conjunto de cambios) a hacer, por ejemplo escribir una nueva característica, corregir un fallo, etc. Los comandos de Subversion que puede usar aquí son svn add, svn delete, svn copy, y svn move. Sin embargo, si usted está simplemente corrigiendo los archivos que están ya en Subversion, puede no necesitar utilizar ninguno de estos comandos hasta que envíe los cambios. Cambios que puede hacer a su copia de trabajo local:

Para hacer cambios en los ficheros, use su editor de textos, procesador de textos, programa de gráficos , o cualquier herramienta que usaría normalmente. Subversion maneja ficheros binarios tan fácilmente como maneja archivos de texto—y tan eficientemente también.

Aquí hay una descripción de los cuatro subcomandos de Subversion que usted usará más a menudo para hacer cambios del árbol (cubriremos svn import y svn mkdir después.

Una vez que haya terminado de hacer cambios, necesita enviarlos al repositorio, pero antes de hacerlo, generalmente es buena idea echar un vistazo a lo que ha cambiado exactamente. Examinando sus cambios antes de que los envíe, puede hacer un mensaje de informe de cambios más exacto. También puede descubrir que ha cambiado inadvertidamente un fichero, y esto le da la posibilidad de invertir esos cambios antes de enviarlos. Además, esta es una buena oportunidad para revisar y escudriñar cambios antes de publicarlos. Usted puede ver exactamente qué cambios ha hecho usando svn status, svn diff, y svn revert. Generalmente usará los primeros dos comandos para descubrir qué ficheros han cambiado en su copia de trabajo local, y después quizá el tercero para invertir algunos (o todos) de esos cambios.

Subversion ha sido optimizado para ayudarle con esta tarea, y es capaz de hacer muchas cosas sin comunicarse con el repositorio. En particular, su copia de trabajo local contiene una copia “prístina” secreta almacenada de cada fichero de versión controlado dentro del área .svn. Debido a esto, Subversion puede rápidamente mostrarle cómo sus ficheros de trabajo han cambiado, o incluso permitirle deshacer sus cambios sin contactar con el repositorio.

$ svn status
  L    abc.c               # svn has a lock in its .svn directory for abc.c
M      bar.c               # the content in bar.c has local modifications
 M     baz.c               # baz.c has property but no content modifications
X      3rd_party           # this dir is part of an externals definition
?      foo.o               # svn doesn't manage foo.o
!      some_dir            # svn manages this, but it's either missing or incomplete
~      qux                 # versioned as dir, but is file, or vice versa
I      .screenrc           # this file is ignored
A  +   moved_dir           # added with history of where it came from
M  +   moved_dir/README    # added with history and has local modifications
D      stuff/fish.c        # this file is scheduled for deletion
A      stuff/loot/bloo.h   # this file is scheduled for addition
C      stuff/loot/lump.c   # this file has conflicts from an update
    S  stuff/squawk        # this file or dir has been switched to a branch
…

$ svn status stuff/fish.c
D      stuff/fish.c

$ svn status --verbose
M               44        23    sally     README
                44        30    sally     INSTALL
M               44        20    harry     bar.c
                44        18    ira       stuff
                44        35    harry     stuff/trout.c
D               44        19    ira       stuff/fish.c
                44        21    sally     stuff/things
A                0         ?     ?        stuff/things/bloo.h
                44        36    harry     stuff/things/gloo.c

$ svn status --show-updates --verbose
M      *        44        23    sally     README
M               44        20    harry     bar.c
       *        44        35    harry     stuff/trout.c
D               44        19    ira       stuff/fish.c
A                0         ?     ?        stuff/things/bloo.h
Status against revision:   46

$ svn diff
Index: bar.c
===================================================================
--- bar.c	(revision 3)
+++ bar.c	(working copy)
@@ -1,7 +1,12 @@
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include <stdio.h>

 int main(void) {
-  printf("Sixty-four slices of American Cheese...\n");
+  printf("Sixty-five slices of American Cheese...\n");
 return 0;
 }

Index: README
===================================================================
--- README	(revision 3)
+++ README	(working copy)
@@ -193,3 +193,4 @@ 
+Note to self:  pick up laundry.

Index: stuff/fish.c
===================================================================
--- stuff/fish.c	(revision 1)
+++ stuff/fish.c	(working copy)
-Welcome to the file known as 'fish'.
-Information on fish will be here soon.

Index: stuff/things/bloo.h
===================================================================
--- stuff/things/bloo.h	(revision 8)
+++ stuff/things/bloo.h	(working copy)
+Here is a new file to describe
+things about bloo.

$ svn diff > patchfile

svn revert

Ahora suponga que usted ve la salida del diff anterior, y se da cuenta que sus cambios a README son un error; quizás accidentalmente tecleó ese texto en el fichero equivocado en su editor

Esta es una oportunidad perfecta para usar svn revert.

$ svn revert README
Reverted 'README'

Subversion invierte el fichero a un estado pre-modificado reescribiéndolo con la copia “prístina” almacenada en el área .svn. Pero también observar que svn revert puede deshacer cualquier operación programada—por ejemplo, usted puede decidir que no quiere añadir un nuevo fichero después de todo:

$ svn status foo
?      foo

$ svn add foo
A         foo

$ svn revert foo
Reverted 'foo'

$ svn status foo
?      foo

	Nota
	svn revert ITEM tiene exactamente el mismo efecto que suprimiendo ITEM de su copia de trabajo local y después ejecutando svn update -r BASE ITEM. Sin embargo, si está revirtiendo un fichero, svn revert tiene una diferencia muy considerable—no tiene que comunicarse con el repositorio para reponer su fichero.

O quizás usted quito equivocadamente un fichero del control de versión:

$ svn status README 
       README

$ svn delete README 
D         README

$ svn revert README
Reverted 'README'

$ svn status README
       README

Ya hemos visto cómo svn status -u puede predecir conflictos. Suponga que ejecuta svn update y ocurren algunas cosas interesantes

$ svn update
U  INSTALL
G  README
C  bar.c
Updated to revision 46.

Los códigos U y G no son causa para la inquietud; esos ficheros absorbieron limpiamente los cambios del repositorio. Los ficheros marcados con una U no contienen cambios locales pero fueron actUalizados con cambios del repositorio. La G representa merGed, lo que significa que el fichero tenía para comenzar cambios locales, pero los cambios que venían del repositorio no se solaparon de ninguna manera.

Pero la C representa conflicto. Esto significa que los cambios del servidor se solapan con los suyos propios, y ahora tiene que elegir manualmente entre ellos.

Siempre que ocurra un conflicto, ocurren tres cosas para ayudarle a notar y resolver ese conflicto:

Por ejemplo, Sally hace cambios al fichero sandwich.txt en el repositorio. Harry acaba de cambiar el fichero en su copia de trabajo y lo ha enviado. Sally actualiza su copia de trabajo antes de enviarlo y recibe un conflicto:

$ svn update
C  sandwich.txt
Updated to revision 2.
$ ls -1
sandwich.txt
sandwich.txt.mine
sandwich.txt.r1
sandwich.txt.r2

En este punto, Subversion no le permitirá enviar el fichero sandwich.txt hasta que los tres ficheros temporales sean borrados.

$ svn commit --message "Add a few more things"
svn: Commit failed (details follow):
svn: Aborting commit: '/home/sally/svn-work/sandwich.txt' remains in conflict

Si obtiene un conflicto, necesita hacer una de tres cosas:

Una vez que usted haya resuelto el conflicto, necesita dejar que Subversion lo sepa ejecutando svn resolved. Esto borrará los tres ficheros temporales y Subversion no considerará por más tiempo que el fichero está en estado de conflicto.^[11]

$ svn resolved sandwich.txt
Resolved conflicted state of 'sandwich.txt'

$ cat sandwich.txt
Top piece of bread
Mayonnaise
Lettuce
Tomato
Provolone
<<<<<<< .mine
Salami
Mortadella
Prosciutto
=======
Sauerkraut
Grilled Chicken
>>>>>>> .r2
Creole Mustard
Bottom piece of bread

<<<<<<< .mine
Salami
Mortadella
Prosciutto
=======

=======
Sauerkraut
Grilled Chicken
>>>>>>> .r2

Top piece of bread
Mayonnaise
Lettuce
Tomato
Provolone
Salami
Mortadella
Prosciutto
Creole Mustard
Bottom piece of bread

$ svn resolved sandwich.txt
$ svn commit -m "Go ahead and use my sandwich, discarding Sally's edits."

$ svn update
C  sandwich.txt
Updated to revision 2.
$ ls sandwich.*
sandwich.txt  sandwich.txt.mine  sandwich.txt.r2  sandwich.txt.r1
$ cp sandwich.txt.r2 sandwich.txt
$ svn resolved sandwich.txt

$ svn revert sandwich.txt
Reverted 'sandwich.txt'
$ ls sandwich.*
sandwich.txt

Ahora usted está listo para enviar sus cambios. Observe que svn resolved, al contrario de la mayoría de los otros comandos que nos hemos ocupado en este capitulo, requiere un argumento. En cualquier caso, debe tener cuidado y solo ejecutar svn resolved cuando esté seguro que ha arreglado el conflicto en su fichero—una vez los ficheros temporales son borrados, Subversion le dejará enviar el fichero incluso si todavía tiene marcas de conflicto.

¡Finalmente! Su edición está terminada, ha fusionado todos los cambios del servidor, y está listo para enviar sus cambios al repositorio.

El comando svn commit envía todos sus cambios al repositorio. Cuando usted envía un cambio, necesita proveer un mensaje de registro, describiendo su cambio. Su mensaje de registro será adjuntado a la nueva revisión que ha creado. Si su mensaje de registro es breve, puede querer proveerlo en la línea de comando usando la opción --message (o -m):

$ svn commit --message "Corrected number of cheese slices."
Sending        sandwich.txt
Transmitting file data .
Committed revision 3.

Sin embargo, si ha estado componiendo su mensaje de registro mientras trabaja, puede querer decirle a Subversion que coja el mensaje de un fichero pasando el nombre de fichero con la opción --file :

$ svn commit --file logmsg 
Sending        sandwich
Transmitting file data .
Committed revision 4.

Si usted falla en especificar cualquiera de las opciones --message o --file, entonces Subversion lanzará automáticamente su editor favorito (según lo definido en la variable de entorno $EDITOR) para redactar un mensaje de registro.

	Sugerencia
	Si está en su editor escribiendo un mensaje de registro y decide que quiere cancelar su envío, usted puede quitar su editor sin guardar los cambios. Si ya ha guardado su mensaje de registro, simplemente borre el texto y salve otra vez. $ svn commit Waiting for Emacs...Done Log message unchanged or not specified a)bort, c)ontinue, e)dit a $

El repositorio no sabe ni cuida si sus cambios tienen algún sentido en su totalidad; solo comprueba para asegurarse que nadie haya cambiado cualquiera de los mismos ficheros que usted mientras usted no miraba. Si alguien ha hecho esto, el envío entero fallará con un mensaje informándole que uno o más de sus ficheros está fuera-de-fecha:

$ svn commit --message "Add another rule"
Sending        rules.txt
svn: Commit failed (details follow):
svn: Out of date: 'rules.txt' in transaction 'g'

En este punto, necesita ejecutar svn update, ocupándose con cualquier fusión o conflicto que resulte y procure enviarlo otra vez.

Eso cubre el ciclo básico de trabajo para usar Subversion. Hay muchas otras características en Subversion que usted puede usar para administrar su repositorio y copia de trabajo, pero puede pasar fácilmente usando solo los comandos que hemos visto hasta ahora en este capítulo.

Para descubrir información sobre la historia de un fichero o directorio, use el comando svn log. svn log le proporcionará un registro de quién hizo cambios a un fichero o directorio, en qué revisión cambió, la hora y fecha de esa revisión, y, si fue proporcionado, el mensaje de registro que acompañaba al envío.

$ svn log
------------------------------------------------------------------------
r3 | sally | Mon, 15 Jul 2002 18:03:46 -0500 | 1 line

Added include lines and corrected # of cheese slices.
------------------------------------------------------------------------
r2 | harry | Mon, 15 Jul 2002 17:47:57 -0500 | 1 line

Added main() methods.
------------------------------------------------------------------------
r1 | sally | Mon, 15 Jul 2002 17:40:08 -0500 | 1 line

Initial import
------------------------------------------------------------------------

Observe que los mensajes de registro son impresos en orden cronológico inverso por defecto. Si desea ver un rango diferente de revisiones en un orden particular, o solo una única revisión, pase la opción --revision (-r):

$ svn log --revision 5:19    # shows logs 5 through 19 in chronological order

$ svn log -r 19:5            # shows logs 5 through 19 in reverse order

$ svn log -r 8               # shows log for revision 8

También puede examinar el historial de registro de un único fichero o directorio. Por ejemplo:

$ svn log foo.c
…
$ svn log http://foo.com/svn/trunk/code/foo.c
…

Ésto mostrará los mensajes de registro solo para esas revisiones en las cuales el fichero de trabajo (o URL) cambió.

Si desea aún más información sobre un fichero o directorio, svn log también toma una opción --verbose (-v). Porque Subversion le permite mover y copiar ficheros y directorios, es importante poder seguir cambios de la ruta del fichero en el sistema de ficheros, así en modo detallado, svn log incluirá una lista de rutas de fichero cambiadas en una revisión en su salida:

$ svn log -r 8 -v
------------------------------------------------------------------------
r8 | sally | 2002-07-14 08:15:29 -0500 | 1 line
Changed paths:
M /trunk/code/foo.c
M /trunk/code/bar.h
A /trunk/code/doc/README

Frozzled the sub-space winch.

------------------------------------------------------------------------

$ svn log -r 2
------------------------------------------------------------------------
$

Ya hemos visto svn diff antes—éste muestra las diferencias de fichero en un formato unificado del diff; fue utilizado para mostrar las modificaciones locales hechas a nuestra copia de trabajo antes de enviarlas al repositorio.

De hecho, resulta que hay tres usos distintos para svn diff:

$ svn diff
Index: rules.txt
===================================================================
--- rules.txt	(revision 3)
+++ rules.txt	(working copy)
@@ -1,4 +1,5 @@
 Be kind to others
 Freedom = Responsibility
 Everything in moderation
-Chew with your mouth open
+Chew with your mouth closed
+Listen when others are speaking
$

$ svn diff --revision 3 rules.txt 
Index: rules.txt
===================================================================
--- rules.txt	(revision 3)
+++ rules.txt	(working copy)
@@ -1,4 +1,5 @@
 Be kind to others
 Freedom = Responsibility
 Everything in moderation
-Chew with your mouth open
+Chew with your mouth closed
+Listen when others are speaking
$

$ svn diff --revision 2:3 rules.txt 
Index: rules.txt
===================================================================
--- rules.txt	(revision 2)
+++ rules.txt	(revision 3)
@@ -1,4 +1,4 @@
 Be kind to others
-Freedom = Chocolate Ice Cream
+Freedom = Responsibility
 Everything in moderation
 Chew with your mouth closed 
$

$ svn diff --revision 4:5 http://svn.red-bean.com/repos/example/trunk/text/rules.txt
…
$

Si desea examinar una versión anterior de un fichero y no necesariamente las diferencias entre dos ficheros, puede usar svn cat:

$ svn cat --revision 2 rules.txt 
Be kind to others
Freedom = Chocolate Ice Cream
Everything in moderation
Chew with your mouth closed
$

También puede redireccionar la salida directamente a un fichero:

$ svn cat --revision 2 rules.txt > rules.txt.v2
$

Probablemente se esté preguntando por qué no usamos svn update --revision para actualizar el fichero a la revisión más antigua. Hay algunas razones por las que preferimos usar svn cat.

Primero, usted puede querer ver las diferencias entre dos revisiones de un fichero usando un programa diff externo (quizás uno gráfico, o quizás su fichero está en un formato que la salida de un diff unificado es absurdo). En este caso, necesitará coger una copia de la revisión antigua, redireccionarla a un fichero, y pasar este y el fichero de su copia de trabajo a su programa diff externo.

A veces es más fácil mirar una versión más antigua de un fichero en su totalidad en comparación con las diferencias entre esta y otra revisión.

El comando svn list le muestra qué ficheros están en un directorio de un repositorio sin realmente descargar los ficheros a su máquina local:

$ svn list http://svn.collab.net/repos/svn
README
branches/
clients/
tags/
trunk/

Si desea un listado más detallado, pase la opción --verbose (-v) para obtener una salida como esta.

$ svn list --verbose http://svn.collab.net/repos/svn
   2755 harry          1331 Jul 28 02:07 README
   2773 sally               Jul 29 15:07 branches/
   2769 sally               Jul 29 12:07 clients/
   2698 harry               Jul 24 18:07 tags/
   2785 sally               Jul 29 19:07 trunk/

Las columnas le dicen la revisión en la cual el fichero o directorio fue modificado por última vez, el usuario qué lo modificó, el tamaño si este es un fichero, la fecha de la última modificación, y el nombre del objeto.

Además de todos los comandos anteriores, usted puede usar svn update y svn checkout con la opción --revision para tomar una copia de trabajo entera “anterior en el tiempo” ^[13]:

$ svn checkout --revision 1729 # Checks out a new working copy at r1729
…
$ svn update --revision 1729 # Updates an existing working copy to r1729
…

Cuando Subversion modifica su copia de trabajo (o cualquier información en el interior de .svn), intenta hacerlo tan seguro como sea posible. Antes de cambiar cualquier cosa, escribe sus intenciones en un fichero de registro, ejecuta los comandos en el fichero de registro, entonces borra el fichero de registro (esto es similar en diseño a un sistema de ficheros transaccional). Si una operación de Subversion es interrumpida (si el proceso es matado, o si la máquina se cuelga, por ejemplo), los ficheros de registro permanecen en disco. Ejecutando de nuevo los ficheros de registro, Subversion puede completar la operación anteriormente empezada, y su copia de trabajo puede volver a estar en un estado consistente.

Y esto es exactamente lo que hace svn cleanup: busca en su copia de trabajo y ejecuta cualquier registro de sobra, eliminando bloqueos en el proceso. Si Subversion alguna vez le dice que alguna parte de su copia de trabajo está “bloqueada”, entonces éste es el comando que debería ejecutar. También, svn status mostrará una L al lado de los objetos bloqueados:

$ svn status
  L    somedir
M      somedir/foo.c 

$ svn cleanup
$ svn status
M      somedir/foo.c

El comando svn import es una manera rápida de copiar un árbol de ficheros sin versionar en el repositorio, creando directorios intermedios como sea necesario.

$ svnadmin create /usr/local/svn/newrepos
$ svn import mytree file:///usr/local/svn/newrepos/some/project
Adding         mytree/foo.c
Adding         mytree/bar.c
Adding         mytree/subdir
Adding         mytree/subdir/quux.h

Committed revision 1.

El ejemplo anterior copia el contenido del directorio mytree debajo del directorio some/project en el repositorio:

$ svn ls file:///usr/local/svn/newrepos/some/project
bar.c
foo.c
subdir/

Observe que después de que la importación esté acabada, el árbol original no se convierte en una copia de trabajo. Para empezar a trabajar, usted todavía necesita hacer svn checkout en una copia de trabajo fresca del árbol.

Crear una rama es muy simple—realice una copia del proyecto en el repositorio usando el comando svn copy. Subversion no sólo es capaz de copiar ficheros individuales, sino también directorios. En este caso, desea realizar una copia del directorio /calc/trunk. ¿Dónde debería colocar la nueva copia? Donde desee—es una cuestión de política de su proyecto. Digamos que su equipo tiene la política de crear ramas en el área de repositorio /calc/branches, y quiere nombrar la rama my-calc-branch. Entonces querrá crear un nuevo directorio /calc/branches/my-calc-branch, el cual comienza su vida como una copia de /calc/trunk.

Hay dos formas diferentes de realizar una copia. Le mostraremos primero el modo engorroso, para asegurarnos de que queda claro el concepto. Para comenzar, obtenga una copia local del directorio raíz del proyecto, /calc:

$ svn checkout http://svn.example.com/repos/calc bigwc
A  bigwc/trunk/
A  bigwc/trunk/Makefile
A  bigwc/trunk/integer.c
A  bigwc/trunk/button.c
A  bigwc/branches/
Checked out revision 340.

Realizar ahora una copia es cuestión de pasar dos rutas locales al comando svn copy:

$ cd bigwc
$ svn copy trunk branches/my-calc-branch
$ svn status
A  +   branches/my-calc-branch

En este caso, el comando svn copy copia recursivamente el directorio trunk en un nuevo directorio, branches/my-calc-branch. Tal y como puede ver por el comando svn status, el nuevo directorio está ahora a la espera de ser añadido al repositorio. Pero fíjese en el signo “+” tras la letra A. Esto indica que la adición pendiente es una copia de algo, no algo nuevo. Cuando envíe sus cambios al repositorio, Subversion creará /calc/branches/my-calc-branch en el repositorio como una copia de /calc/trunk, en lugar de reenviar todos los datos de su copia local de nuevo a través de la red:

$ svn commit -m "Creating a private branch of /calc/trunk."
Adding         branches/my-calc-branch
Committed revision 341.

Y ahora el método más sencillo para crear una rama, que deberíamos haberle explicado en primer lugar: svn copy es capaz de operar directamente sobre dos URLs.

$ svn copy http://svn.example.com/repos/calc/trunk \
           http://svn.example.com/repos/calc/branches/my-calc-branch \
      -m "Creating a private branch of /calc/trunk."

Committed revision 341.

Realmente no hay diferencia entre estos dos métodos. Ambos procedimientos crean un nuevo directorio en la revisión 341, y el nuevo directorio es una copia de /calc/trunk. Esto se puede ver en Figura 4.3, “Repositorio con nueva copia”. Note cómo el segundo método, no obstante, realiza los cambios en el repositorio inmediatamente. ^[14] Es un procedimiento más sencillo, porque no requiere obtener primero una gran copia local de todo el repositorio. De hecho, esta técnica ni si quiera requiere que tenga una copia local en absoluto.

Figura 4.3. Repositorio con nueva copia

Ahora que ha creado una rama del proyecto, puede obtener una nueva copia local para comenzar a usarla:

$ svn checkout http://svn.example.com/repos/calc/branches/my-calc-branch
A  my-calc-branch/Makefile
A  my-calc-branch/integer.c
A  my-calc-branch/button.c
Checked out revision 341.

No hay nada especial sobre esta copia local; simplemente refleja un directorio diferente del repositorio. Cuando envíe sus cambios, no obstante, Carmen nunca los verá cuando se actualice. Su copia local es de /calc/trunk. (Asegúrese de leer “Cambiando la copia local de trabajo” más adelante en este capítulo: el comando svn switch permite crear una copia local de una rama de modo diferente.)

Pretendamos que ha pasado una semana, y se realizan los siguientes cambios:

Ahora hay dos líneas independientes de desarrollo, mostradas en Figura 4.4, “Bifurcación de la historia de un fichero”, sobre el fichero integer.c.

Figura 4.4. Bifurcación de la historia de un fichero

Las cosas se ponen interesantes cuando mira el historial de cambios realizados a su copia de integer.c:

$ pwd
/home/usuario/my-calc-branch

$ svn log --verbose integer.c
------------------------------------------------------------------------
r343 | usuario | 2002-11-07 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines
Changed paths:
   M /calc/branches/my-calc-branch/integer.c

* integer.c:  frozzled the wazjub.

------------------------------------------------------------------------
r341 | usuario | 2002-11-03 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines
Changed paths:
   A /calc/branches/my-calc-branch (from /calc/trunk:340)

Creating a private branch of /calc/trunk.

------------------------------------------------------------------------
r303 | carmen | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  changed a docstring.

------------------------------------------------------------------------
r98 | carmen | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  adding this file to the project.

------------------------------------------------------------------------

Fíjese como Subversion sigue la historia de integer.c en su rama hacia atrás, traspasando incluso el punto donde el fichero fue copiado. Muestra la creación de la rama como un evento en la historia, porque integer.c fue copiado de forma implícita cuando realizó la copia de /calc/trunk/. Ahora mire qué es lo que ocurre cuando Carmen ejecuta el mismo comando sobre su copia del fichero:

$ pwd
/home/carmen/calc

$ svn log --verbose integer.c
------------------------------------------------------------------------
r344 | carmen | 2002-11-07 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  fix a bunch of spelling errors.

------------------------------------------------------------------------
r303 | carmen | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  changed a docstring.

------------------------------------------------------------------------
r98 | carmen | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines
Changed paths:
   M /calc/trunk/integer.c

* integer.c:  adding this file to the project.

------------------------------------------------------------------------

Carmen ve su propio cambio de la revisión 344, pero no el cambio realizado en la revisión 343. Desde el punto de vista de Subversion, estos dos cambios afectaron ficheros diferentes en distintos lugares del repositorio. No obstante, Subversion muestra que ambos ficheros comparten una historia común. Antes de que la rama fuese creada en la revisión 341, ambos eran el mismo fichero. Por esta razón tanto usted como Carmen ven los cambios realizados en las revisiones 303 y 98.

Hay dos lecciones importantes que debería recordar de esta sección.

El la sección anterior, mencionamos que tanto usted como Carmen han realizado cambios a integer.c en ramas diferentes. Si observa el informe de cambios de la revisión 344, puede ver que ella realizó algunas correcciones de ortografía. Sin duda, su copia del mismo fichero debe tener todavía los mismos errores de ortografía. Es probable que futuros cambios al fichero afectarán las mismas áreas que tienen estos errores ortográficos, lo que potencialmente generará conflictos cuando fusione su rama algún día. Es mejor, entonces, recibir ahora los cambios de Carmen, antes de que comience a trabajar de forma intensiva en el mismo sitio.

Es el momento de usar el comando svn merge. Este comando, descubrirá que es un primo cercano del comando svn diff (sobre el cual leímos en el tercer capítulo). Ambos comandos son capaces de comparar dos objetos cualquiera del repositorio y describir sus diferencias. Por ejemplo, puede preguntar a svn diff que le muestre el cambio exacto realizado por Carmen en la revisión 344:

$ svn diff -r 343:344 http://svn.example.com/repos/calc/trunk

Index: integer.c
===================================================================
--- integer.c	(revision 343)
+++ integer.c	(revision 344)
@@ -147,7 +147,7 @@
     case 6:  sprintf(info->operating_system, "HPFS (OS/2 or NT)"); break;
     case 7:  sprintf(info->operating_system, "Macintosh"); break;
     case 8:  sprintf(info->operating_system, "Z-System"); break;
-    case 9:  sprintf(info->operating_system, "CPM"); break;
+    case 9:  sprintf(info->operating_system, "CP/M"); break;
     case 10:  sprintf(info->operating_system, "TOPS-20"); break;
     case 11:  sprintf(info->operating_system, "NTFS (Windows NT)"); break;
     case 12:  sprintf(info->operating_system, "QDOS"); break;
@@ -164,7 +164,7 @@
     low = (unsigned short) read_byte(gzfile);  /* read LSB */
     high = (unsigned short) read_byte(gzfile); /* read MSB */
     high = high << 8;  /* interpret MSB correctly */
-    total = low + high; /* add them togethe for correct total */
+    total = low + high; /* add them together for correct total */
 
     info->extra_header = (unsigned char *) my_malloc(total);
     fread(info->extra_header, total, 1, gzfile);
@@ -241,7 +241,7 @@
      Store the offset with ftell() ! */
 
   if ((info->data_offset = ftell(gzfile))== -1) {
-    printf("error: ftell() retturned -1.\n");
+    printf("error: ftell() returned -1.\n");
     exit(1);
   }
 
@@ -249,7 +249,7 @@
   printf("I believe start of compressed data is %u\n", info->data_offset);
   #endif
   
-  /* Set postion eight bytes from the end of the file. */
+  /* Set position eight bytes from the end of the file. */
 
   if (fseek(gzfile, -8, SEEK_END)) {
     printf("error: fseek() returned non-zero\n");

El comando svn merge es casi exactamente idéntico. En lugar de mostrar las diferencias en su terminal, no obstante, las aplica directamente a su copia local como modificaciones locales:

$ svn merge -r 343:344 http://svn.example.com/repos/calc/trunk
U  integer.c

$ svn status
M  integer.c

La salida del comando svn merge muestra que su copia de integer.c fue parcheada. Ahora contiene el cambio de Carmen—el cambio ha sido “copiado” desde el tronco a su copia local de la rama privada, y existe ahora como una modificación local. En este punto, es tarea suya revisar la modificación local para asegurarse de que funciona correctamente.

En otra situación, es posible que las cosas no hayan ido tan bien, y que integer.c haya entrado en un estado de conflicto. Puede tener que resolver el conflicto usando el procedimiento estándar (vea el tercer capítulo), o si decide que la fusión fue una mala idea, simplemente dé se por vencido y use svn revert para revertir el cambio local.

Pero asumiendo que ha revisado el cambio fusionado, puede guardar sus cambios como es habitual con svn commit. En ese punto, el cambio ha sido fusionado en su rama del repositorio. En terminología de control de versiones, este acto de copiar cambios entre ramas se denomina portar cambios.

Cuando guarda su modificación local, asegúrese de que el mensaje de cambios indica que está portando un cambio específico de una rama a otra. Por ejemplo:

$ svn commit -m "integer.c: ported r344 (spelling fixes) from trunk."
Sending        integer.c
Transmitting file data .
Committed revision 360.

Tal y como verá en las siguientes secciones, es muy importante seguir esta “práctica recomendada”.

$ svn diff -r 343:344 http://svn.example.com/repos/calc/trunk > patchfile
$ patch -p0  < patchfile
Patching file integer.c using Plan A...
Hunk #1 succeeded at 147.
Hunk #2 succeeded at 164.
Hunk #3 succeeded at 241.
Hunk #4 succeeded at 249.
done

Aviso: aunque los comandos svn diff y svn merge son similares en concepto, tienen una diferente sintaxis en muchos casos. Asegúrese de leer en el capítulo 8 los detalles, o pregunte a svn help. Por ejemplo, svn merge requiere una ruta a una copia local como destino, es decir, un lugar donde debe aplicar los cambios del árbol. Si el destino no es especificado, asume que está intentando realizar una de las siguientes operaciones comunes:

Si está fusionando un directorio y no ha especificado una ruta destino, svn merge asume el primer caso mencionado e intenta aplicar los cambios en su directorio actual. Si está fusionando un fichero, y ese fichero (o un fichero con el mismo nombre) existe en su directorio actual de trabajo, svn merge asume el segundo caso mencionado e intenta aplicar los cambios al fichero local de mismo nombre.

Si quiere aplicar los cambios en otro lugar, tendrá que especificarlo. Por ejemplo, si todavía está en el directorio padre de su copia local, tendrá que especificar el directorio destino para recibir los cambios:

$ svn merge -r 343:344 http://svn.example.com/repos/calc/trunk my-calc-branch
U   my-calc-branch/integer.c

Para completar el ejemplo que hemos ido mostrando, nos moveremos hacia adelante en el tiempo. Suponga que han pasado varios días, y se han realizado muchos cambios tanto en el tronco como en su rama privada. Suponga que ya ha terminado de trabajar en su rama privada; la característica o corrección está finalmente completada, y ahora quiere fusionar todos los cambios de su rama en el tronco para que otros puedan disfrutarlos.

¿Cómo usamos svn merge en esta situación? Recuerde que este comando compara dos árboles, y aplica las diferencias en una copia local. Así que para recibir los cambios, necesita tener una copia local del tronco. Asumiremos que todavía tiene una copia original del tronco por alguna parte (completamente actualizada), o que recientemente ha obtenido una copia local fresca de /calc/trunk.

¿Pero qué dos árboles deberían ser comparados? A primera vista, la respuesta puede parecer obvia: simplemente compare el último árbol del tronco con el último árbol de su rama. ¡Pero cuidado—esta asunción es incorrecta, y ha confundido a muchos usuarios nuevos! Dado que svn merge funciona como svn diff, comparar el tronco y su rama no describirá meramente el conjunto de cambios realizados en su rama. Tal comparación muestra demasiados cambios: no solo mostraría la adición de los cambios en su rama, sino también el borrado de cambios en el tronco que nunca ocurrieron en su rama.

Para expresar únicamente los cambios que ocurrieron en su rama, necesita comparar el estado inicial de su rama con su estado final. Usando svn log en su rama, puede ver que ésta fue creada en la revisión 341. Y el estado final puede obtenerlo con la revisión HEAD. Esto significa que quiere comparar las revisiones 341 y HEAD del directorio de su rama, y aplicar esas diferencias a una copia local del tronco.

Sugerencia

Un buen método para encontrar la revisión en la cual fue creada una rama (la "base" de la misma) es usar la opción --stop-on-copy con svn log. El sub comando log normalmente muestra todo cambio realizado en la rama, incluyendo los de la copia a partir de la cual fue creada. Así que normalmente verá también la historia del tronco. La opción --stop-on-copy detendrá la salida del comando en cuanto svn log detecte que la rama fue copiada o renombrada. Así que en nuestro ejemplo continuo: $ svn log --verbose --stop-on-copy \ http://svn.example.com/repos/calc/branches/my-calc-branch … ------------------------------------------------------------------------ r341 | usuario | 2002-11-03 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines Changed paths: A /calc/branches/my-calc-branch (from /calc/trunk:340) $ Como esperábamos, el número final de revisión mostrado por este comando es la revisión en la cual my-calc-branch fue creado a raíz de una operación de copiado.

De nuevo, aquí está el procedimiento final de fusionado:

$ cd calc/trunk
$ svn update
At revision 405.

$ svn merge -r 341:HEAD http://svn.example.com/repos/calc/branches/my-calc-branch
U   integer.c
U   button.c
U   Makefile

$ svn status
M   integer.c
M   button.c
M   Makefile

# ...examine the diffs, compile, test, etc...

$ svn commit -m "Merged my-calc-branch changes r341:405 into the trunk."
Sending        integer.c
Sending        button.c
Sending        Makefile
Transmitting file data ...
Committed revision 406.

De nuevo, fíjese que el mensaje de cambios menciona de forma explícita el rango de cambios que fue fusionado en el tronco. Recuerde siempre hacer esto, porque es información crítica que necesitará más adelante.

Por ejemplo, suponga que decide continuar trabajando en su rama otra semana, para completar una mejora a una de las características originales o corregir un fallo. La revisión HEAD del repositorio es ahora 480, y está listo para realizar otra fusión desde su rama privada al tronco. Pero como se discutió en “Procedimientos ideales de fusionado”, no quiere fusionar los cambios que ya fueron fusionados; sólo quiere fusionar todo lo “nuevo” en su rama desde la última vez que fue fusionada. El truco es descubrir qué es lo nuevo.

El primer paso es ejecutar svn log en el tronco, y buscar un mensaje de cambios sobre la última vez que realizó una fusión desde su rama:

$ cd calc/trunk
$ svn log
…
------------------------------------------------------------------------
r406 | usuario | 2004-02-08 11:17:26 -0600 (Sun, 08 Feb 2004) | 1 line

Merged my-calc-branch changes r341:405 into the trunk.
------------------------------------------------------------------------
…

¡Ajá! Dado que todos los cambios que ocurrieron en la rama entre las revisiones 341 y 405 fueron fusionados con el tronco como la revisión 406, ahora sabe que sólo quiere fusionar los cambios de la rama posteriores a esto—comparando las revisiones 406 y HEAD.

$ cd calc/trunk
$ svn update
At revision 480.

# We notice that HEAD is currently 480, so we use it to do the merge:

$ svn merge -r 406:480 http://svn.example.com/repos/calc/branches/my-calc-branch
U   integer.c
U   button.c
U   Makefile

$ svn commit -m "Merged my-calc-branch changes r406:480 into the trunk."
Sending        integer.c
Sending        button.c
Sending        Makefile
Transmitting file data ...
Committed revision 481.

Ahora el tronco contiene la segunda oleada completa de cambios realizados en la rama. En este punto, puede o bien borrar su rama (discutiremos esto más adelante), o continuar trabajando en su rama y repetir este procedimiento en siguientes operaciones de fusionado.

Otro uso común de svn merge es deshacer un cambio que acaba de ser enviado al repositorio. Suponga que está trabajando felizmente en su copia local de /calc/trunk, y descubre que el cambio realizado hace tiempo en la revisión 303, que modificó integer.c, está completamente mal. Nunca debería haber llegado al repositorio. Puede usar svn merge para “deshacer” el cambio en su copia local, y entonces enviar las modificaciones locales al repositorio. Todo lo que necesita hacer es especificar la diferencia al revés:

$ svn merge -r 303:302 http://svn.example.com/repos/calc/trunk
U  integer.c

$ svn status
M  integer.c

$ svn diff
…
# verify that the change is removed
…

$ svn commit -m "Undoing change committed in r303."
Sending        integer.c
Transmitting file data .
Committed revision 350.

Una forma de pensar sobre las revisiones del repositorio es como un grupo de cambios (algunos sistemas de control de versiones los llaman changesets). Al usar el parámetro -r, puede pedirle a svn merge que aplique el changeset, o el rango completo de changesets sobre su copia local de trabajo. En nuestro caso para deshacer un cambio usamos svn merge para aplicar el changeset #303 a nuestra copia local al revés.

Tenga presente que deshacer un cambio de esta manera es como realizar cualquier otra operación svn merge, así que debería usar svn status y svn diff para confirmar que su trabajo está en el estado que usted desea, y entonces usar svn commit para enviar la versión final al repositorio. Tras el envío, este changeset particular ya no se verá reflejado en la revisión HEAD.

De nuevo puede estar preguntándose: vaya, eso no deshizo el cambio anterior, ¿verdad? El cambio todavía existe en la revisión 303. Si alguien obtiene una versión del proyecto calc entre las revisiones 303 y 349, seguirán viendo todavía el cambio malo, ¿verdad?

Si, en efecto. Cuando hablamos sobre “eliminar” un cambio, estamos hablando sobre eliminarlo de HEAD. El cambio original todavía existe en la historia del repositorio. En la mayoría de las situaciones, esto es suficiente. De todos modos la mayoría de las personas sólo están interesadas en seguir la versión HEAD de un proyecto. No obstante, hay casos especiales en los que realmente desearía destruir toda evidencia de un cambio. (Quizás alguien puso accidentalmente en el repositorio un documento confidencial.) Esto, tal y como verá, no es tan fácil porque Subversion fue diseñado deliberadamente para nunca perder información. Las revisiones son árboles inmutables que se construyen unos sobre otros. Eliminar una revisión de la historia podría causar un efecto dominó, creando caos en todas las revisiones siguientes y posiblemente invalidando todas las copias locales de trabajo. ^[16]

La mejor característica de los sistemas de control de versiones es que la información nunca se pierde. Incluso cuando borra un fichero o un directorio, puede haberse esfumado de la revisión HEAD, pero el objeto todavía existe en revisiones anteriores. Una de las preguntas más comunes realizadas por nuevos usuarios es, “¿Cómo puedo recuperar mi fichero o directorio antiguo?”

El primer paso es definir exactamentequé elemento está intentando resucitar. Aquí tiene una metáfora útil: puede pensar que todo objeto en el repositorio existe en una especie de sistema de coordenadas bidimensional. Las abscisas marcan una revisión particular del árbol, y las ordenadas una ruta de fichero dentro de ese árbol. Así que cualquier versión de su fichero o directorio puede definirse por un par específico de coordenadas.

Subversion no tiene un directorio Attic como CVS, ^[17] por lo que necesita usar el comando svn log para descubrir la pareja de coordenadas exactas que quiere resucitar. Una buena estrategia es ejecutar svn log --verbose en un directorio que solía contener el elemento borrado. La opción --verbose muestra una lista de todos los elementos modificados en cada revisión; todo lo que necesita hacer es encontrar la revisión en la cual borró el fichero o directorio. Puede hacer esto visualmente, o usando otra herramienta para examinar el informe de cambios (vía grep, o quizás con una búsqueda incremental en un editor.)

$ cd parent-dir
$ svn log --verbose
…
------------------------------------------------------------------------
r808 | jose | 2003-12-26 14:29:40 -0600 (Fri, 26 Dec 2003) | 3 lines
Changed paths:
   D /calc/trunk/real.c
   M /calc/trunk/integer.c

Added fast fourier transform functions to integer.c.
Removed real.c because code now in double.c.
…

En el ejemplo, estamos asumiendo que está buscando el fichero borrado real.c. Leyendo los informes de cambios del directorio padre, hemos encontrado que este fichero fue borrado en la revisión 808. Por lo tanto la última versión del fichero existió en la revisión inmediatamente anterior a esa. Conclusión: quiere resucitar la ruta /calc/trunk/real.c de la revisión 807.

Eso fue la parte difícil—la investigación. Ahora que sabe lo que quiere recuperar, tiene dos posibles opciones.

Una de las opciones es usar el comando svn merge para aplicar la revisión 808 “al revés”. (Ya hemos discutido cómo deshacer cambios, lea “Deshaciendo cambios”.) Esto tendría el efecto de reañadir real.c como modificación local. El fichero se programaría para ser añadido, y tras enviar los cambios, el fichero existiría de nuevo en HEAD.

No obstante, en este ejemplo particular, ésta probablemente no es la mejor estrategia. Aplicar al revés la revisión 808 no solamente programaría la adición de real.c, ya que el mensaje de cambios indica que también se desharían ciertos cambios a integer.c, cosa que no desea. Ciertamente, podría fusionar al revés la revisión 808 y entonces ejecutar svn revert sobre la modificación local de integer.c, pero esta técnica no es muy escalable. ¿Qué pasa si hay 90 ficheros modificados en la revisión 808?

Otra estrategia más precisa es usar svn copy en lugar de svn merge. Simplemente copie la “pareja de coordenadas” exactas de revisión y ruta del repositorio a su copia de trabajo local:

$ svn copy --revision 807 \
           http://svn.example.com/repos/calc/trunk/real.c ./real.c

$ svn status
A  +   real.c

$ svn commit -m "Resurrected real.c from revision 807, /calc/trunk/real.c."
Adding         real.c
Transmitting file data .
Committed revision 1390.

El símbolo de suma en la salida del comando indica que el elemento no sólo se ha programado para ser añadido, sino para ser añadido “con historia.” Subversion recuerda de dónde fue copiado. En el futuro, ejecutar svn log sobre este fichero recorrerá su historia hasta la resurrección y continuará también con la que tenía antes de la revisión 807. En otras palabras, este nuevo real.c no es realmente nuevo; es un descendiente directo del fichero original que fue borrado.

A pesar de que nuestro ejemplo muestra cómo resucitar un fichero, tenga en cuenta que esta misma técnica proporciona los mismos resultados al resucitar directorios borrados.

De nuevo, svn copy viene al rescate. Si desea crear una instantánea de /calc/trunk exactamente tal y como se ve en la revisión HEAD, haga una copia:

$ svn copy http://svn.example.com/repos/calc/trunk \
           http://svn.example.com/repos/calc/tags/release-1.0 \
      -m "Tagging the 1.0 release of the 'calc' project."

Committed revision 351.

Este ejemplo asume que ya existe un directorio /calc/tags. (Si no existe, vea svn mkdir). Tras finalizar la copia, el nuevo directorio lanzamiento-1.0 será para siempre una instantánea del aspecto que tenía la revisión HEAD del proyecto en el momento que realizó la copia. Por supuesto puede querer ser más preciso sobre qué revisión exacta copiar, en caso de que alguien realice un cambio al proyecto mientras no está observando. Así que si sabe que la revisión 350 de /calc/trunk es exactamente la instantánea que desea, puede especificarla pasando -r 350 al comando svn copy.

Pero espere un momento: ¿no es este procedimiento para crear etiquetas el mismo que usamos para crear una rama? Si, de hecho, así es. En Subversion no hay diferencia entre una etiqueta y una rama. Ambas son directorios ordinarios que son creados a partir de una copia. Igual que con las ramas, la única razón por la que un directorio copiado es una “etiqueta” es porque los humanos han decidido tratarlo de ese modo: mientras nadie envíe cambios usando ese directorio, seguirá siendo siempre una instantánea. Si la gente comienza a realizar cambios, se convierte en una rama.

Si está administrando un repositorio, hay dos formas de de gestionar etiquetas. La primera es “manos fuera”: según la política de su proyecto, decida dónde pondrá sus etiquetas, y asegúrese de que todos los usuarios saben cómo tratar los directorios que copian ahí. (En otras palabras, asegúrese de que no cambian nada en esos directorios.) La segunda forma es más paranoica: puede usar uno de los scripts de control de acceso proporcionados con Subversion para prevenir cualquier cosa que no sea la creación de nuevas copias en el área de etiquetado (Vea Capítulo 6, Configuración del servidor.) No obstante, el método paranoico normalmente no es necesario. Si un usuario envía un cambio accidentalmente al directorio de etiquetas, puede simplemente deshacer el cambio tal y como discutimos en la sección anterior. Después de todo, esto es control de versiones.

A veces quiere que su “instantánea” sea más complicada que un solo directorio de una revisión concreta.

Por ejemplo, pretendamos que su proyecto es mucho más grande que nuestro ejemplo calc: suponga que contiene un número de subdirectorios y muchos más ficheros. Realizando su trabajo, puede decidir que necesita crear una copia de trabajo local diseñada para contener características o correcciones de fallos específicas. Puede conseguir esto modificando ficheros o directorios de forma selectiva para que reflejen una revisión particular (usando svn update -r liberalmente), o cambiando ficheros y directorios a ramas particulares (haciendo uso de svn switch). Cuando ha finalizado, su copia local es un batiburrillo de ubicaciones del repositorio de diferentes versiones. Pero tras hacer unas pruebas, sabe que es la combinación precisa de datos que necesita.

Hora de tomar una instantánea. Copiar una URL en otra no funcionará esta vez. En este caso, quiere hacer una instantánea de la configuración exacta de su copia local y almacenarla en el repositorio. Afortunadamente, svn copy tiene en realidad cuatro usos diferentes (sobre los cuales puede leer en el noveno capítulo), incluyendo la habilidad para copiar el árbol de una copia local al repositorio:

$ ls
my-working-copy/

$ svn copy my-working-copy http://svn.example.com/repos/calc/tags/mytag

Committed revision 352.

Ahora existe un nuevo directorio en el repositorio, /calc/tags/mytag, el cual es una instantánea exacta de su copia local de trabajo—revisiones mezcladas, urls, y todo eso.

Otros usuarios han encontrado usos interesantes de esta característica. A veces hay situaciones en las que acaba de enviar al repositorio un grupo de cambios locales, y querría que los viese un colaborador. En lugar de ejecutar svn diff y enviar el fichero de parche (el cual no captura cambios en el árbol), puede usar en su lugar svn copy para “subir” su copia local a un área privada del repositorio. Entonces su colaborador puede o bien obtener una copia tal cual de su copia local, o bien usar svn merge para recibir sus cambios exactos.

Hay maneras estándar recomendadas para organizar un repositorio. La mayoría de las personas crean un directorio trunk que contendrá la “línea principal” de desarrollo, un directorio branches que contendrá copias de las ramas, y un directorio tags que contendrá copias de las etiquetas. Si un repositorio sólo almacena un proyecto, entonces la gente a menudo crea estos directorios en el directorio raíz:

/trunk
/branches
/tags

Si un repositorio contiene múltiples proyectos, los administradores normalmente indexan la estructura por proyecto (vea “Escogiendo el esquema de repositorio” para leer más sobre “raíces de proyecto”):

/paint/trunk
/paint/branches
/paint/tags
/calc/trunk
/calc/branches
/calc/tags

Por supuesto, es libre de ignorar estas estructuras comunes. Puede crear cualquier tipo de variación, lo que sea mejor para usted y su equipo. Recuerde que sea lo que sea lo que elija, no es una decisión final. Puede reorganizar su repositorio en cualquier momento. Dado que las ramas y etiquetas son directorios ordinarios, el comando svn move puede moverlos o renombrarlos como desee. Cambiar de una estructura a otra es una cuestión de ejecutar una serie de movimientos en el servidor; si no le gusta cómo se organizan las cosas en el repositorio, simplemente juegue un poco con los directorios.

Recuerde, no obstante, que aunque mover directorios puede ser fácil, necesita ser considerado con sus usuarios. Sus movimientos pueden desorientar a los usuarios que tengan copias locales de trabajo. Si un usuario tiene una copia local de un directorio particular del repositorio, su operación svn move quizás elimine la ruta de la última revisión. Cuando el usuario ejecute svn update, se le informará que su copia local usa una ruta que ya no existe, y el usuario se verá forzado a hacer svn switch a otra ubicación.

Otra buena característica del modelo de Subversion es que las ramas y las etiquetas pueden tener vidas infinitas, igual que cualquier otro elemento versionado. Por ejemplo, suponga que finalmente termina todo su trabajo en una rama personal del proyecto calc. Tras fusionar todos sus cambios de vuelta en /calc/trunk, ya no hace falta que el directorio de su rama privada permanezca visible:

$ svn delete http://svn.example.com/repos/calc/branches/my-calc-branch \
             -m "Removing obsolete branch of calc project."

Committed revision 375.

Y desapareció su rama. Por supuesto no ha desaparecido realmente: el directorio simplemente falta en la revisión HEAD, y ya no distrae a nadie más. Si usa svn checkout, svn switch, o svn list para examinar una revisión anterior, seguirá pudiendo ver su antigua rama.

Si navegar por su directorio borrado no es suficiente, siempre puede devolverle la vida. Resucitar datos es muy fácil en Subversion. Si hay un directorio (o fichero) borrado que querría volver a poner en HEAD, simplemente cópielo con svn copy -r de la revisión antigua:

$ svn copy -r 374 http://svn.example.com/repos/calc/branches/my-calc-branch \
                  http://svn.example.com/repos/calc/branches/my-calc-branch

Committed revision 376.

En nuestro ejemplo, su rama personal tuvo un periodo de actividad relativamente corto: puede haberla creado para corregir un fallo o implementar una nueva característica. Cuando su tarea está terminada, así lo está su rama. No obstante, en el desarrollo de software también es común tener dos ramas “principales” que viven en paralelo por largos periodos de tiempo. Por ejemplo, suponga que es el momento de hacer público el proyecto estable calc, y sabe que va a necesitar un par de meses corregir posibles fallos del mismo. No quiere que la gente añada nuevas características al proyecto, pero tampoco quiere decirle a los desarrolladores que dejen de programar. Así que crea una rama “estable” del software que no cambiará mucho:

$ svn copy http://svn.example.com/repos/calc/trunk \
         http://svn.example.com/repos/calc/branches/stable-1.0 \
         -m "Creating stable branch of calc project."

Committed revision 377.

Y ahora los desarrolladores son libres de continuar añadiendo características novísimas (o experimentales) a /calc/trunk, y usted puede declarar como política del proyecto que sólo las correcciones de fallos serán realizadas en /calc/branches/stable-1.0. Es decir, a medida que la gente continúa su trabajo en el tronco, un humano portará selectivamente las correcciones de fallos a la rama estable. Incluso después de haber lanzado la rama estable, probablemente continuará manteniéndola por un largo tiempo—es decir, tanto como desee continuar el soporte de esa versión para sus usuarios.

Hablando conceptualmente, un repositorio Subversion es una secuencia de árboles de directorios. Cada árbol es una fotografía de cómo eran los ficheros y directorios versionados en tu repositorio en un momento determinado. Estas fotografías son generadas como resultado de operaciones de programas cliente, y son llamadas revisiones.

Cada revisión nace como un árbol de transacciones. Cuando se envían cambios al repositorio, el programa cliente construye una transacción de Subversion que copia los cambios locales ( junto a cualquier cambio adicional que haya podido tener lugar desde el comienzo del proceso de envío de datos), y luego pide al repositorio que guarde ese árbol como la próxima fotografía en la secuencia. Si el envío de datos no da error, la transacción se convierte en una nueva revisión del árbol, y se le asigna un nuevo número de revisión. Si el envío de datos fallara por alguna razón, la transacción se destruye, y se le informa al cliente del error.

Las actualizaciones funcionan de una manera parecida. El Cliente prepara un árbol de transacción temporal que copia el estado de la copia de trabajo. El repositorio compara entonces ese árbol de transacción con el árbol de la revisión solicitada (normalmente la más reciente, o el árbol “más joven”), e informa al cliente acerca de qué cambios son necesario para convertir su copia local de trabajo en una réplica de ese árbol de revisión. Tras completarse la actualización, se borra la transacción temporal.

El uso de árboles de transacción es la única manera de hacer cambio permanentes en un repositorio de sistema de ficheros versionados. De todas maneras, es importante entender que el tiempo de vida de una transacción es completamente flexible. En el caso de actualizaciones, las transacciones con árboles temporales que se destruyen inmediatamente. En el caso de envíos al repositorio, las transacciones son transformadas en revisiones permanentes ( o borradas si el envío falla ). En el caso de un error, es posible que una transacción permanezca accidentalmente suelta en el repositorio ( sin que afecte en realidad a nada, pero ocupando espacio).

En teoría, un día los programas de flujo de trabajo completo deberán girar hacia un control más fino del tiempo de vida de la transacción. Es factible imaginar un sistema por el que cada transacción que se convierta en revisión permanezca en bastante después de que el cliente termine de describir sus cambios al repositorio. Esto permitiría que cada nuevo envío sea revisado por alguna otra persona, quizás un director o , que pueda elegir entre promoverla a una revisión, o cancelarla.

Las transacciones y las revisiones en el repositorio Subversion pueden tener propiedades adjuntas. Estas propiedades son relaciones genéricas clave-valor, y generalmente se usan para guardar información acerca del árbol al que están adjuntas. Los nombres y valores de estas propiedades se guardan en el sistema de ficheros del repositorio, junto con el resto de los datos de tu árbol.

Las propiedades de revisiones y transacciones son útiles para asociar información con un árbol que no está estrictamente relacionada con los ficheros y directorios de ese árbol—el tipo de información que no es gestiona por las copias de trabajo de cliente. Por ejemplo, cuando una nueva transacción de envío es creada en el repositorio, Subversion añade una propiedad a dicha transacción llamada svn:date— una marca de tiempo que representa el momento en que la transacción se creó. En el momento que el proceso de envío termina, el árbol también ha recibido una propiedad para guardar el nombre del usuario que es autor de la revisión (svn:author) y una propiedad para guardar el mensaje de informe de cambios adjunto a dicha revisión (svn:log).

Las propiedades de revisiones y transacciones son propiedades no versionada—cuando son modificadas, sus valores previos se descartan definitivamente. Así mismo, mientras los árboles de revisiones en sí son inmutables, las propiedades adjuntas de dichos árboles no lo son. Puedes añadir, borrar, y modificar propiedades de revisiones en cualquier momento más adelante. Si envías al repositorio una nueva revisión y más tarde te das cuenta de alguna información incorrecta o un error sintáctico en tu mensaje de log, puedes simplemente sustituir el valor de la propiedad svn:log con un nuevo y corregido mensaje de log.

Los datos almacenados dentro de repositorios Subversion, realmente se encuentran en una base de datos, más concretamente, un fichero de base de datos Berkeley. Durante la fase inicial de diseño de Subversion, los desarrolladores decidieron usar una base de datos Berkeley por una serie de razones, como su licencia open-source, soporte de transacciones, ser de confianza, funcionamiento, simplicidad de su API, soporte de hilos, cursores, y más.

La base de datos Berkeley tiene un soporte real de transacciones —probablemente es su característica más poderosa. Muchos procesos que acceden a sus repositorios Subversion no tienen que preocuparse por pisotear los datos de otros. El aislamiento provisto por el sistema de transacciones es tal que por cada operación dada, el código de repositorio Subversion tiene una vista estática de la base de datos—no una base de datos que está constantemente cambiando de la mano de algunos otros procesos—y puede tomar decisiones basándose en esa vista. Si dicha decisión está en conflicto con lo que otro proceso esté haciendo, la operación completa como si nunca hubiera sucedido, y Subversion reintenta la operación contra una nueva y actualizada ( y estática ) vista de la base de datos.

Otra gran característica de la base de datos Berkeley son las copias de seguridad en caliente— la habilidad para hacer una copia de seguridad del entorno de la base de datos sin que tenga que estar “”. Hablaremos sobre cómo hacer copias de seguridad de tu repositorio en “Copias de seguridad del repositorio”, pero los beneficios de ser capaz de hacer copias completas y funcionales de tus repositorios sin debería ser obvia.

La base de datos Berkeley también es un sistema de bases de datos de mucha confianza. Subversion utiliza las utilidades de registro de las bases de datos Berkeley, lo que significa que la base datos primero escribe una descripción de cualquier modificación que vaya a hacer en ficheros de registros, para luego hace la propia modificación. Esto es para asegurar que si algo fuese mal, el sistema de base de datos pueda retroceder a un checkpoint—una posición en los ficheros de registro que se sabe que no están corruptas—y repetir transacciones hasta que los datos estén en un estado usable. Ver “Gestionando el espacio de almacenamiento” si quieres más información acerca de los ficheros de registro de las bases de datos de Berkeley.

Pero toda rosa tiene su espina, así que tenemos que hablar sobre algunas conocidas limitaciones de la base de datos Berkeley. Primero, los entornos de base de datos Berkeley no son portables. No puedes copiar simplemente un repositorio Subversion que fue creado en un sistema Unix a un sistema Windows y esperar que funcione. A pesar de que la mayor parte del formato de base de datos Berkeley es independiente de la arquitectura, hay otros aspectos del entorno que no lo son. Segundo, Subversion usa la base de datos Berkeley de una manera que no puede funcionar en sistemas Windows 95/98—si necesita almacenar un repositorio en una máquina Windows, utilice Windows 2000 o Windows XP. Finalmente, no deberías mantener un repositorio Subversion en una unidad compartida por red. Mientras las bases de datos Berkeley prometen un comportamiento correcto en unidades compartidas por red que cumplan un grupo particular de especificaciones, casi ningún sistema de compartición conocido cumple con todas esas especificaciones.

Un gancho es un programa activado por algún evento del repositorio, como la creación de una nueva revisión o la modificación de una propiedad no versionada. A cada gancho se le da suficiente información para que sepa de qué evento se trata, cuál es su objetivo, y el nombre de usuario de la persona que disparó el evento. Dependiendo de la salida del gancho o de estado de su salida, el programa de enganche puede continuar la acción, pararla, o suspenderla de alguna manera.

El subdirectorio hooks se rellena, por defecto, con plantillas para varios ganchos de repositorio.

$ ls repos/hooks/
post-commit.tmpl          pre-revprop-change.tmpl
post-revprop-change.tmpl  start-commit.tmpl
pre-commit.tmpl           

Hay una plantilla por cada gancho que implementa el repositorio Subversion, y examinando los contenidos de dichas plantillas de scripts, puede ver qué disparador ejecuta cada script y qué datos se le pasan. También se encuentran en muchas de estas plantillas ejemplos de cómo debería usar dicho script, conjuntamente con otros programas provistos por Subversion, para realizar tareas comunes y útiles. Para instalar realmente un gancho funcional, sólo necesita colocar algún ejecutable o script en el directorio repos/hooks que pueda ser ejecutado con el nombre del gancho ( como start-commit o post-commit).

En plataformas Unix, esto significa proveer un script o programa (podría ser un shell script, un programa Python, un binario C compilado, o cualquier otra cosa) llamado exactamente igual que el nombre del gancho. Por supuesto, los ficheros de plantillas están presentes para algo más que sólo propósitos informativos—la manera más fácil de instalar un gancho en plataformas Unix es simplemente copiar el fichero de plantilla apropiado en un nuevo fichero sin la extensión .tmpl, personalizando los contenidos del gancho, y asegurándose de que el script sea ejecutable. Windows, sin embargo, usa extensiones de fichero para determinar si un programa es ejecutable o no, así que debería dar poner un programa cuyo nombre sea el nombre del gancho, y cuya extensión sea una de las extensiones especiales reconocidas por Windows como ficheros ejecutables, como .exe o .com para programas, y .bat para ficheros de scripts.

Actualmente hay cinco ganchos implementados por el repositorio Subversion:

Subversión tratará de ejecutar los ganchos como el mismo usuario que posee el proceso que está accediendo al repositorio Subversion. En la mayoría de los casos, el repositorio se accede a través del servidor HTTP Apache y mod_dav_svn, así que este usuario es el mismo que el usuario con el que se ejecuta Apache. Los mismos ganchos necesitarán ser configurados con permisos a nivel de sistema operativo que les permitan ser ejecutados por dicho usuario. Asimismo, esto significa que cualquier fichero o programas ( incluyendo el repositorio mismo ) al que acceda directa o indirectamente el gancho, será a través del mismo usuario. En otras palabras, esté alerta a problemas potenciales relacionados con permisos que impidan al gancho realizar las tareas para las cuales lo haya escrito.

Un entorno de base de datos Berkeley es una encapsulación de una o más bases de datos, ficheros de registro, ficheros regionales y ficheros de configuración. El entorno de base de datos Berkeley tiene su propio conjunto de valores de configuración por defecto para cosas como el número de bloqueos que se permite eliminar de una sola vez, o el tamaño máximo de los ficheros de registro , etc. El código del sistema de ficheros de Subversion elige además valores por defecto para algunas de las opciones de configuración de la base de datos Berkeley. De todas maneras, algunas veces su repositorio particular, con su colección única de datos y patrones de acceso, podría necesitar un grupo diferente de valores de configuración.

La gente de Sleepycat ( los programadores de la base de datos Berkeley ) entienden que bases de datos diferentes, tienen requerimientos específicos, de tal manera, que nos proveen de un mecanismo para sobreescribir en tiempo de ejecución, muchos de los valores de configuración del entorno Berkeley. Berkeley comprueba la presencia de un fichero denominado DB_CONFIG en cada directorio del entorno, y las opciones que encuentra en dicho fichero para usarlas en ese entorno Berkeley particular.

El fichero de configuración de Berkeley para su repositorio se encuentra en directorio del entorno db, en repos/db/DB_CONFIG. Subversion crea por sí mismo el fichero al mismo tiempo que el resto del repositorio. El fichero inicialmente contiene algunas opciones por defecto, así como enlaces a la documentación en línea de la base de datos Berkeley de tal manera que pueda saber qué significan dichas opciones. Por supuesto, es libre de añadir cualquiera de las opciones soportadas por la base de datos Berkeley a su fichero DB_CONFIG. Tan sólo tenga cuidado porque mientras Subversion no trata de leer o interpretar los contenidos del fichero, y no hace uso de sus opciones de configuración, tendrá que evitar cualquier cambio en la configuración que pueda causar que la base de datos Berkeley se comporte de una manera inesperada para el resto del código de Subversion. Por otra parte, los cambios hechos en DB_CONFIG no tendrán efecto hasta que vuelva a leer en entorno de la base de datos ( usando svnadmin recover).

Subversion provee un conjunto de utilidades para crear inspeccionar, modificar y reparar sus repositorio. Estudiemos más de cerca cada una de estas herramientas. Más tarde, examinaremos brevemente otras incluidas en la distribución de la base de datos Berkeley que añaden funcionalidades específicas al motor de base de datos de las que no disponen las herramientas propias de Subversion.

$ svnlook help
uso general. svnlook SUBCOMANDO RUTA_REPOS [PARAMS y OPCIONES ...]
Nota: todo subcomando que tome los parámetros '--revision' y '--transaction'
      actuará, si se lo invoca sin una de estas opciones, sobre la versión
      más reciente del repositorio.
Escriba "svn help <subcomando>" para ayuda en un subcomando específico.
…

$ svnlook info /path/to/repos
$ svnlook info /path/to/repos --revision 19

$ svnlook youngest /path/to/repos
19

$ svnlook info /path/to/repos
sally
2002-11-04 09:29:13 -0600 (Mon, 04 Nov 2002)
27
Added the usual
Greek tree.

$ svnlook tree /path/to/repos --show-ids
/ <0.0.1>
 A/ <2.0.1>
  B/ <4.0.1>
   lambda <5.0.1>
   E/ <6.0.1>
    alpha <7.0.1>
    beta <8.0.1>
   F/ <9.0.1>
  mu <3.0.1>
  C/ <a.0.1>
  D/ <b.0.1>
   gamma <c.0.1>
   G/ <d.0.1>
    pi <e.0.1>
    rho <f.0.1>
    tau <g.0.1>
   H/ <h.0.1>
    chi <i.0.1>
    omega <k.0.1>
    psi <j.0.1>
 iota <1.0.1>

$ svnadmin help
uso general: svnadmin SUBCOMANDO RUTA_REPOS  [PARAMS y OPCIONES ...]
Escriba "svnadmin help <subcomando>" para ayuda sobre un subcomando.

Subcomandos disponibles:
   create
   deltify
   dump
   help (?, h)
…

$ svndumpfilter help
uso general: svndumpfilter SUBCOMANDO [ARGS & OPCIONES ...]
Escriba "svndumpfilter help <subcommand>" para obtener información sobre un subcomando específico.

Subcomandos disponibles:
   exclude
   include
   help (?, h)

/
   calc/
      trunk/
      branches/
      tags/
   calendar/
      trunk/
      branches/
      tags/
   spreadsheet/
      trunk/
      branches/
      tags/

$ svnadmin dump /path/to/repos > repos-dumpfile
* Dumped revision 0.
* Dumped revision 1.
* Dumped revision 2.
* Dumped revision 3.
…
$

$ svndumpfilter include calc < repos-dumpfile > calc-dumpfile
…
$ svndumpfilter include calendar < repos-dumpfile > cal-dumpfile
…
$ svndumpfilter include spreadsheet < repos-dumpfile > ss-dumpfile
…
$

Node-path: calc
Node-action: add
Node-kind: dir
Content-length: 0

$ svnadmin create calc; svnadmin load calc < calc-dumpfile
<<< Started new transaction, based on original revision 1
     * adding path : Makefile ... done.
     * adding path : button.c ... done.
…
$ svnadmin create calendar; svnadmin load calendar < cal-dumpfile
<<< Started new transaction, based on original revision 1
     * adding path : Makefile ... done.
     * adding path : cal.c ... done.
…
$ svnadmin create spreadsheet; svnadmin load spreadsheet < ss-dumpfile
<<< Started new transaction, based on original revision 1
     * adding path : Makefile ... done.
     * adding path : ss.c ... done.
…
$

…
Node-path: spreadsheet/Makefile
…

$ svnshell.py /path/to/repos
<rev: 2 />$  help
Available commands:
  cat FILE     : dump the contents of FILE
  cd DIR       : change the current working directory to DIR
  exit         : exit the shell
  ls [PATH]    : list the contents of the current directory
  lstxns       : list the transactions available for browsing
  setrev REV   : set the current revision to browse
  settxn TXN   : set the current transaction to browse
  youngest     : list the youngest browsable revision number
<rev: 2 />$

<rev: 2 />$ ls
   REV   AUTHOR  NODE-REV-ID     SIZE         DATE NAME
----------------------------------------------------------------------------
     1    sally <     2.0.1>          Nov 15 11:50 A/
     2    harry <     1.0.2>       56 Nov 19 08:19 iota
<rev: 2 />$ cd A
<rev: 2 /A>$ ls
   REV   AUTHOR  NODE-REV-ID     SIZE         DATE NAME
----------------------------------------------------------------------------
     1    sally <     4.0.1>          Nov 15 11:50 B/
     1    sally <     a.0.1>          Nov 15 11:50 C/
     1    sally <     b.0.1>          Nov 15 11:50 D/
     1    sally <     3.0.1>       23 Nov 15 11:50 mu
<rev: 2 /A>$ cd D/G 
<rev: 2 /A/D/G>$ ls
   REV   AUTHOR  NODE-REV-ID     SIZE         DATE NAME
----------------------------------------------------------------------------
     1    sally <     e.0.1>       23 Nov 15 11:50 pi
     1    sally <     f.0.1>       24 Nov 15 11:50 rho
     1    sally <     g.0.1>       24 Nov 15 11:50 tau
<rev: 2 /A>$ cd ../..
<rev: 2 />$ cat iota
This is the file 'iota'.
Added this text in revision 2.

<rev: 2 />$ setrev 1; cat iota
This is the file 'iota'.

<rev: 1 />$ exit
$

En general su repositorio Subversion requerirá poca atención una vez lo haya configurado a su gusto. No obstante, hay ocasiones en las que podría necesitar la asistencia manual de un administrador. La utilidad svnadmin proporciona algunas funcionalidades provechosas para realizar tareas como

Quizás el subcomando de svnadmin más usado sea setlog. Cuando una transacción es guardada en el repositorio y ascendida a categoría de revisión, el mensaje del informe de cambios asociado con esa nueva revisión (y proporcionado por el usuario) se almacena como una propiedad no versionada adjunta a la propia revisión. En otras palabras, el repositorio sólo recuerda el último valor de la propiedad, y descarta valores anteriores.

A veces el usuario cometerá errores (ortográficos o quizás información equivocada) en sus informes de cambios. Si configura el repositorio (usando los ganchos pre-revprop-change y post-revprop-change; vea “Scripts de enganche”) para permitir modificaciones sobre el mensaje de informe de cambios de revisiones existentes, entonces el usuario puede “corregir” su informe remotamente usando el comando propset del programa svn (vea Capítulo 9, Referencia completa de Subversion). No obstante, debido al peligro potencial de perder información para siempre, los repositorios Subversion se configuran por defecto para impedir cambios a propiedades no versionadas—excepto para el administrador.

Si un informe de cambios necesita ser cambiado por un administrador, puede ejecutar svnadmin setlog. Éste comando modifica el mensaje de informe de cambios (la propiedad svn:log) de una revisión concreta de un repositorio, leyendo el nuevo valor del fichero proporcionado.

$ echo "Here is the new, correct log message" > newlog.txt
$ svnadmin setlog myrepos newlog.txt -r 388

El comando svnadmin setlog a secas sigue estando limitado por las mismas protecciones que impiden a los usuarios remotos modificar propiedades no versionadas—los ganchos pre- y post-revprop-change siguen ejecutándose, y por lo tanto debe configurar el repositorio para permitir cambios de esta naturaleza. Pero un administrador puede saltarse estas protecciones pasando el parámetro --bypass-hooks al comando svnadmin setlog.

	Aviso
	Recuerde, no obstante, que al ignorar los ganchos, probablemente esté evitando acciones como notificaciones automáticas por correo informando de cambios a propiedades, sistemas de copias de seguridad que siguen los cambios de propiedades sin versionar, etc, etc. En otras palabras, sea muy cuidadoso con lo que vaya a cambiar, y cómo lo cambia.

Otro uso habitual de svnadmin es comprobar que en el repositorio no hay transacciones pendientes—posiblemente muertas. En el caso de que una transacción falle, ésta normalmente se anula. Es decir, la propia transacción y cualquier dato asociado con ella (y sólo con ella) es eliminada del repositorio. No obstante, ocasionalmente ocurre un fallo de tal modo que la limpieza de la transacción no se llega a realizar nunca. Esto podría pasar por varias razones: quizás la operación del cliente fue terminada de manera poco elegante por el usuario, quizás ocurrió un fallo de red durante la operación, etc. En cualquier caso, estas transacciones muertas sólo molestan en el repositorio y consumen recursos.

Puede usar el comando lstxns de svnadmin's para obtener un listado de los nombres de las transacciones actuales de relevancia.

$ svnadmin lstxns myrepos
19
3a1
a45
$

Cada elemento del listado mostrado puede ser usado con svnlook (y su opción --transaction) para determinar quién creó la transacción, cuándo fue creada, qué tipos de cambios fueron realizados en la transacción—en otras palabras, si la transacción es o nó una candidata segura para ser eliminada. En caso de serlo, el nombre de la transacción puede ser usado con svnadmin rmtxns, que realizará la limpieza de la transacción. ¡De hecho, el subcomando rmtxns puede usar directamente como entrada la salida de lstxns!

$ svnadmin rmtxns myrepos `svnadmin lstxns myrepos`
$

Si usa estos subcomandos de éste modo, debería considerar desactivar temporalmente el acceso al repositorio por parte de sus clientes. Así, nadie podrá comenzar una transacción legítima antes de que comience con la limpieza. Lo que viene a continuación es un poco de shell-scripting que puede generar rápidamente la información sobre cada transacción pendiente de su repositorio:

#!/bin/sh

### Generate informational output for all outstanding transactions in
### a Subversion repository.

SVNADMIN=/usr/local/bin/svnadmin
SVNLOOK=/usr/local/bin/svnlook

REPOS="${1}"
if [ "x$REPOS" = x ] ; then
  echo "usage: $0 REPOS_PATH"
  exit
fi

for TXN in `${SVNADMIN} lstxns ${REPOS}`; do 
  echo "---[ Transaction ${TXN} ]-------------------------------------------"
  ${SVNLOOK} info "${REPOS}" --transaction "${TXN}"
done

Puede ejecutar el script anterior usando /ruta/a/txn-info.sh /ruta/al/repositorio. La salida es básicamente la concatenación de varios bloques de salida de svnlook info (vea “svnlook”), y tendrá el siguiente aspecto:

$ txn-info.sh myrepos
---[ Transaction 19 ]-------------------------------------------
sally
2001-09-04 11:57:19 -0500 (Tue, 04 Sep 2001)
0
---[ Transaction 3a1 ]-------------------------------------------
harry
2001-09-10 16:50:30 -0500 (Mon, 10 Sep 2001)
39
Trying to commit over a faulty network.
---[ Transaction a45 ]-------------------------------------------
sally
2001-09-12 11:09:28 -0500 (Wed, 12 Sep 2001)
0
$

Habitualmente, si descubre una transacción muerta que no tiene adjunto un informe de cambios, se trata del resultado de una operación fallida de actualización (o de estilo similar). Estas operaciones usan transacciones de Subversion internamente para emular el estado de una copia de trabajo local. Dado que éstas transacciones no tienen como propósito ser almacenadas, Subversion no requiere que tengan un mensaje de informe de cambios. Las transacciones que tienen informes de cambios son casi con total seguridad algún tipo de operación de almacenamiento fallida. Además, la fecha de una transacción puede proporcionar información interesante—por ejemplo, ¿qué probabilidades hay de que una operación que comenzase hace nueve meses todavía esté activa?

En resumen, no debe tomar a la ligera las decisión de limpieza de transacciones. Puede emplear varias fuentes de información—incluyendo los registros de acceso y errores de Apache, los registros de transacciones Subversion completadas con éxito, etc— durante la toma de decisiones. Finalmente, un administrador siempre puede comunicarse con el autor de una transacción aparentemente muerta (vía email, por ejemplo) para verificar que la transacción está, de hecho, en un estado zombi.

Mientras que el coste del almacenamiento ha caído de manera increíble durante los últimos años, el espacio en disco sigue siendo un motivo de preocupación válido para los administradores que buscan versionar grandes cantidades de datos. Cada byte adicional consumido por el repositorio en vivo es un byte que debe ser almacenado en una copia de seguridad, quizás múltiples veces como parte de una política de rotado periódico de copias de seguridad. Dado que el principal medio de almacenamiento de un repositorio de Subversion es un complejo sistema de bases de datos, es útil saber qué piezas deben permanecer en el servidor activo, cuáles deben ser almacenadas en una copia de seguridad, y cuáles pueden ser eliminadas.

Hasta hace poco, el mayor culpable en cuanto al uso de disco duro por parte de un repositorio de Subversion eran los fichero de registro que usaba la base de datos Berkeley para realizar sus pre-escrituras antes de modificar realmente los ficheros de la base de datos. Éstos ficheros capturan todas las acciones tomadas durante la ruta que modifica el estado de la base de datos— si los ficheros de la base de datos reflejan en cualquier momento un estado determinado, los ficheros de registro contienen todos los cambios entre diferentes estados. Como tales, pueden comenzar a acumularse rápidamente.

Afortunadamente, y comenzando con la versión 4.2 de la base de datos Berkeley, el entorno de la base de datos tiene la capacidad para borrar sus propios ficheros de registro obsoletos sin necesidad de procedimientos externos. Cualquier repositorio creado usando svnadmin, el cual se compila contra la versión 4.2 o superior de la base de datos Berkeley, será configurado automáticamente para borrar sus ficheros de registros. Si no quiere activar esta característica, simplemente pase la opción --bdb-log-keep al comando svnadmin create. Si olvida hacer esto, o cambia de opinión posteriormente, puede editar el fichero DB_CONFIG ubicado en el directorio db de su repositorio, comentar la línea que contiene la directiva set_flags DB_LOG_AUTOREMOVE, y entonces ejecutar svnadmin recover sobre su repositorio para forzar los cambios de configuración. Vea “Configuración de la base de datos Berkeley” para más información sobre la configuración de la base de datos.

Sin mecanismo de algún tipo que elimine los ficheros de registro, éstos se acumularán a medida que use el repositorio. Esto es en cierto sentido una característica del sistema de base de datos—debería ser capaz de recrear su base de datos por completo sin usar nada más que los ficheros de registro, así que éstos pueden ser útiles en recuperaciones de la base de datos tras una catástrofe. Pero habitualmente querrá archivar los ficheros de registro que la base de datos Berkeley ya no usa, y entonces eliminarlos del disco para conservar espacio. Use el comando svnadmin list-unused-dblogs para obtener un listado de los ficheros de registro no usados:

$ svnadmin list-unused-dblogs /path/to/repos
/path/to/repos/log.0000000031
/path/to/repos/log.0000000032
/path/to/repos/log.0000000033

$ svnadmin list-unused-dblogs /path/to/repos | xargs rm
## disk space reclaimed!

Para mantener el tamaño del repositorio tan pequeño como sea posible, Subversion usa la deltificación (o bien, “almacenamiento deltificado”) dentro del propio repositorio. La deltificación conlleva codificar la representación de un bloque de datos como una colección de diferencias contra otro bloque de datos. Si dos piezas son muy similares, la deltificación proporcionará ganancias de almacenamiento para los bloques deltificados—en lugar de tomar tanto espacio como el tamaño de los datos originales, tomará justo lo necesario para decir, “tengo casi el mismo aspecto de este otro bloque de datos de ahí, excepto por las siguientes diferencias.” De manera más específica, cada vez que una nueva versión de un fichero es enviada al repositorio, Subversion codifica la versión anterior (en realidad, varias versiones anteriores) como un delta contra la nueva versión. El resultado es que la mayor parte de los datos que suelen ocupar espacio—en concreto, los contenidos de los ficheros versionados—se almacenan con un tamaño mucho menor que la representación original completa (“fulltext”) de esos datos.

Nota

Dado que todos los datos del repositorio Subversion sujetos a la deltificación se almacenan en un único fichero de base de datos Berkeley, reducir el tamaño de los valores almacenados no reducirá necesariamente el tamaño de éste fichero. La base de datos Berkeley no obstante mantendrá un registro interno de áreas internas sin usar de la base de datos, y usará esas áreas primero antes de volver a redimensionar el tamaño del fichero de la base de datos. Así que aunque la deltificación no produce ganancias de espacio inmediatas, puede enlentecer drásticamente el crecimiento futuro de la base de datos.

Para poder proteger sus datos en el repositorio, el motor de la base de datos usa un mecanismo de bloqueo. Éste se asegura de que no hay porciones de la base de datos modificadas simultáneamente por múltiples clientes de la base de datos, y que cada proceso ve los datos en un estado correcto cuando éstos son leídos. Cuando un proceso necesita cambiar algo en la base de datos, primero comprueba la existencia de un bloqueo en los datos objetivo. Si los datos no están bloqueados, el proceso los bloquea, hace los cambios que desea realizar, y desbloquea los datos. Esto obliga a otros procesos a esperar hasta que se elimine el bloqueo antes de que se les permita continuar accediendo a esa sección de la base de datos.

A lo largo del uso de su repositorio Subversion, los errores fatales (como quedarse sin espacio en disco duro o sin memoria) o las interrupciones pueden evitar que un proceso tenga la oportunidad de eliminar los bloqueos que inició sobre la base de datos. El resultado es que el motor de la base de datos del sistema se “wedged”. Cuando esto ocurre, cualquier intento de acceso al repositorio se bloqueará de manera indefinida (dado que cada nuevo cliente estará esperando a que los bloqueos desaparezcan—lo cual no va a ocurrir).

Primero, si esto ocurre en su repositorio, no se preocupe. El sistema de ficheros de Subversion tiene la ventaja de usar transacciones, puntos de control y ficheros de registro pre-escritura para asegurarse de que sólo los eventos más catastróficos ^[22] pueden destruir de manera permanente el entorno de la base de datos. Un administrador de repositorio suficientemente paranoico estará haciendo copias de seguridad del repositorio en otra máquina separada de alguna manera, pero todavía no es el momento de llamarle para que realice la restauración de una cinta.

En segundo lugar, use la siguiente receta para intentar “unwedge” su repositorio:

Este procedimiento corrige casi todos los casos de bloqueos del repositorio. Asegúrese de ejecutar este comando como el usuario a quien le pertenece la base de datos y la gestiona, no basta con ser root. Parte del proceso de recuperación puede conllevar la regeneración de varios ficheros de bases de datos (por ejemplo, regiones de memoria compartidas). Al realizar la recuperación como root, éstos ficheros tendrán sus permisos, lo cual significa que incluso cuando recupere la conexión con el repositorio, los usuarios normales no serán capaces de acceder a él.

Si el procedimiento anterior, por alguna razón, no consigue desbloquear su repositorio, debería hacer dos cosas. En primer lugar, mueva su repositorio estropeado a otro lugar y recupere la última copia de seguridad que tenga del mismo. Entonces, envíe un correo electrónico a la lista de usuarios de Subversion (en <users@subversion.tigris.org>) describiendo su problema con todo detalle. Para los desarrolladores de Subversion mantener la integridad de los datos es una prioridad extremadamente alta.

Un sistema de ficheros de Subversion almacena sus datos repartidos por varias tablas de bases de datos de una forma generalmente comprensible (y sólo de interés) para los propios desarrolladores de Subversion. No obstante, pueden darse las circunstancias adecuadas que requieran que todos los datos, o un subconjunto de los mismos, sean recopilados en un fichero único, portable, y de formato simple. Subversion proporciona tal mecanismo implementado como la pareja de subcomandos de svnadmin: dump y load.

La razón más común para volcar y recargar un repositorio de Subversion es por cambios en el propio Subversion. A medida que Subversion madura, hay momentos en los que hace falta realizar cambios al esquema del motor de la base de datos que hacen a Subversion incompatible con versiones anteriores de su repositorio. La acción recomendada para actualizarse atravesando una de estas barreras de incompatiblidad es relativamente simple:

svnadmin dump generará en su salida un rango de revisiones del repositorio usando el formato propio de Subversion para volcar el sistema de ficheros. El volcado formateado será enviado al flujo estándar de salida, mientras que los mensajes informativos son enviados al flujo estándar de errores. Esto le permite redirigir el flujo de salida estándar a un fichero mientras observa el estado del volcado en su terminal. Por ejemplo:

$ svnlook youngest myrepos
26
$ svnadmin dump myrepos > dumpfile
* Dumped revision 0.
* Dumped revision 1.
* Dumped revision 2.
…
* Dumped revision 25.
* Dumped revision 26.

Al final del proceso tendrá un único fichero (dumpfile según el ejemplo anterior) que contendrá todos los datos almacenados en su repositorio en el rango de revisiones especificado. Tenga en cuenta que svnadmin dump lee los árboles de versiones del repositorio igual que cualquier otro proceso “lector” (por ejemplo, svn checkout). Así que es seguro ejecutar este comando en cualquier momento.

El otro subcomando de la pareja, svnadmin load, procesa el flujo estándar de entrada como un fichero de volcado de repositorio de Subversion, y reproduce de manera efectiva esas revisiones volcadas en el repositorio destino durante la operación. También proporciona mensajes informativos, esta vez usando el flujo de salida estándar:

$ svnadmin load newrepos < dumpfile
<<< Started new txn, based on original revision 1
     * adding path : A ... done.
     * adding path : A/B ... done.
     …
------- Committed new rev 1 (loaded from original rev 1) >>>

<<< Started new txn, based on original revision 2
     * editing path : A/mu ... done.
     * editing path : A/D/G/rho ... done.

------- Committed new rev 2 (loaded from original rev 2) >>>

…

<<< Started new txn, based on original revision 25
     * editing path : A/D/gamma ... done.

------- Committed new rev 25 (loaded from original rev 25) >>>

<<< Started new txn, based on original revision 26
     * adding path : A/Z/zeta ... done.
     * editing path : A/mu ... done.

------- Committed new rev 26 (loaded from original rev 26) >>>

Dado que svnadmin usa la los flujos estándar de entrada y salida para el volcado de repositorio y el proceso de carga, las personas que se sientan atrevidas pueden probar algo como ésto (quizás usando diferentes versiones de svnadmin en cada lado de la tubería):

$ svnadmin create newrepos
$ svnadmin dump myrepos | svnadmin load newrepos

Hemos mencionado anteriormente que svnadmin dump genera un rango de revisiones. Use la opción --revision para indicar que quiere volcar una revisión concreta, o un rango. Si omite esta opción, todas las revisiones existentes del repositorio serán volcadas.

$ svnadmin dump myrepos --revision 23 > rev-23.dumpfile
$ svnadmin dump myrepos --revision 100:200 > revs-100-200.dumpfile

A medida que Subversion vuelca cada revisión nueva, muestra la información justa para permitir a un cargador futuro recrear esa revisión basándose en la anterior. En otras palabras, para cualquier revisión dada en el fichero de volcado, sólo aparecerán los elementos que cambiaron en ella. La única excepción a esta regla es la primera revisión volcada por el comando svnadmin dump actual.

Por defecto, Subversion no expresará la primera revisión volcada como las meras diferencias aplicables sobre la revisión anterior. Para empezar, ¡es que no hay revisión anterior alguna en el fichero de volcado! Y en segundo lugar, Subversion no puede saber el estado del repositorio en el cual los datos volcados serán cargados (si este hecho llega a producirse). Para asegurarse de que la salida de cada ejecución de svnadmin dump es autosuficiente, la primera revisión volcada es por defecto una representación completa de cada directorio, fichero, y propiedad en esa revisión del repositorio.

No obstante, puede cambiar este comportamiento por defecto. Si añade la opción --incremental cuando vuelque su repositorio, svnadmin comparará la primera versión volcada del repositorio contra la revisión anterior del repositorio, igual que trata cualquier otra revisión volcada. Entonces mostrará la primera revisión exactamente igual que el resto de las revisiones del rango de volcado—mencionando únicamente los cambios ocurridos en esa revisión. El beneficio de esto es que puede crear varios ficheros de volcado menores que pueden ser cargados secuencialmente, en lugar de un único fichero grande, siguiendo estos pasos:

$ svnadmin dump myrepos --revision 0:1000 > dumpfile1
$ svnadmin dump myrepos --revision 1001:2000 --incremental > dumpfile2
$ svnadmin dump myrepos --revision 2001:3000 --incremental > dumpfile3

Estos ficheros de volcado podrían ser cargados en un nuevo repositorio usando la siguiente secuencia de comandos:

$ svnadmin load newrepos < dumpfile1
$ svnadmin load newrepos < dumpfile2

$ svnadmin load newrepos < dumpfile3

Otro truco interesante que puede realizar con la opción --incremental consiste en añadir a un fichero de volcado existente un nuevo rango de revisiones volcadas. Por ejemplo, digamos que tiene un gancho post-commit que simplemente añade el volcado del repositorio de la versión única que despertó la ejecución del gancho. O quizás tenga un script que se ejecute por las noches para añadir los datos del fichero de volcado de todas las revisiones que fueron añadidas al repositorio desde la última vez que fue ejecutado el script. Usados de este modo, los comandos svnadmin dump y load pueden ser valiosos aliados para realizar copias de seguridad de su repositorio a lo largo del tiempo en caso de un fallo de sistema o algún otro evento catastrófico.

El formato de volcado también puede ser usado para fusionar los contenidos de varios repositorios diferentes en uno único. Al usar la opción --parent-dir de svnadmin load, puede especificar un nuevo directorio virtual para el proceso de carga. Lo cual significa que si tiene ficheros de volcados para tres repositorios, digamos calc-dumpfile, cal-dumpfile, y ss-dumpfile, puede crear primero un nuevo repositorio para almacenarlos todos:

$ svnadmin create /path/to/projects
$

Entonces, cree nuevos directorios en el repositorio que encapsularán los contenidos de cada uno de los tres repositorios anteriores:

$ svn mkdir -m "Initial project roots" \
      file:///path/to/projects/calc \
      file:///path/to/projects/calendar \
      file:///path/to/projects/spreadsheet
Committed revision 1.
$ 

Por último, cargue los ficheros de volcado individuales en sus ubicaciones respectivas del nuevo repositorio:

$ svnadmin load /path/to/projects --parent-dir calc < calc-dumpfile
…
$ svnadmin load /path/to/projects --parent-dir calendar < cal-dumpfile
…
$ svnadmin load /path/to/projects --parent-dir spreadsheet < ss-dumpfile
…
$

Mencionaremos un último uso del formato de volcado de repositorio de Subversion—conversión desde un formato de almacenamiento diferente o sistema de control de versiones. Dado que el fichero de volcado es, en su mayor parte, legible por un humano, ^[23] debería ser relativamente sencillo describir un conjunto genérico de cambios—cada uno de ellos debería ser descrito como una nueva revisión—usando este formato de fichero. De hecho, la utilidad cvs2svn.py (vea “Convirtiendo un repositorio de CVS a Subversion”) usa el formato de volcado para representar el contenido de un repositorio CVS para que sus contenidos pueden ser trasladados a un repositorio Subversion.

A pesar de numerosos avances tecnológicos desde el nacimiento de la computadora moderna, hay una cosa que se entiende con cristalina claridad—a veces, las cosas van muy, pero que muy mal. Pérdidas de corriente, fallos de conectividad en la red, RAM corrupta y discos duros estropeados son un mero avance del mal que el Destino puede desatar sobre incluso el administrador más concienzudo. Y por lo tanto, llegamos a un tema muy importante—cómo hacer copias de seguridad de los datos de su repositorio.

En general hay dos tipos de métodos de copia de seguridad disponibles para los administradores de repositorios de Subversion—incrementales y completos. Hemos discutido en una sección anterior de este capítulo cómo usar svnadmin dump --incremental para realizar copias de seguridad incrementales (vea “Migrando un repositorio”). Esencialmente, la idea es realizar en un momento dado copias de seguridad de los cambios realizados desde la última vez que se hizo la copia de seguridad anterior.

Una copia de seguridad completa del repositorio es casi una copia literal del directorio que contiene todo el repositorio (lo cual incluye el entorno de la base de datos Berkeley). Ahora, a no ser que desactive temporalmente todo el acceso a su repositorio, ejecutar un simple copiado recursivo del directorio conlleva el riesgo de generar una copia de seguridad errónea, dado que alguien podría estar modificando la base de datos.

Afortunadamente, los documentos de la base de datos Berkeley de Sleepycat describen un orden concreto en el cual se pueden copiar los ficheros de la base de datos de tal modo que se garantice una copia de seguridad válida. Y aun mejor, usted no necesita implementar ese algoritmo por su cuenta, porque el equipo de desarrolladores de Subversion ya lo ha hecho. El script hot-backup.py que puede encontrar en el directorio tools/backup/ de la distribución de código fuente de Subversion. Usando como parámetros la ruta al repositorio y a la ubicación de la copia de seguridad, hot-backup.py—que realmente no es más que un envoltorio más inteligente sobre el comando svnadmin hotcopy— realizará los pasos necesarios para realizar una copia de seguridad en caliente del repositorio—sin necesitar en absoluto tener que impedir el acceso al mismo—y después borrará los ficheros de registro sin usar de Berkeley de su repositorio activo actual.

Incluso si también dispone de una copia de seguridad incremental, quizás quiera ejecutar también este programa de manera habitual. Por ejemplo, podría considerar añadir hot-backup.py a un programa de planificación (como por ejemplo cron en sistemas Unix). O, si prefiere soluciones de copias de seguridad con alta granularidad, podría hacer que su gancho post-commit llame hot-backup.py (vea “Scripts de enganche”), lo cual provocará una nueva copia de seguridad de su repositorio con cada nueva versión. Simplemente añada el script hooks/post-commit a su directorio activo del repositorio:

(cd /path/to/hook/scripts; ./hot-backup.py ${REPOS} /path/to/backups &)

La copia de seguridad resultante es un repositorio de Subversion completamente funcional, capaz de reemplazas su repositorio activo en caso de que algo vaya muy mal.

Ambos métodos de copias de seguridad son beneficiosos. La copia de seguridad completa es de lejos la más sencilla, la que siempre resultará ser una réplica de su repositorio perfectamente funcional. Le recordamos que esto significa que si algo malo le ocurre a su repositorio activo, puede recuperar su copia de seguridad con un simple copiado recursivo de directorios. Desafortunadamente, si está manteniendo múltiples copias de seguridad de su repositorio, estas copias completas acabarán ocupando la misma cantidad de espacio de disco que su repositorio activo.

Las copias de seguridad incrementales usando el formato de volcado del repositorio son excelentes para tener a mano si el esquema de la base de datos cambia entre sucesivas versiones del propio Subversion. Dado que para actualizar su repositorio al nuevo esquema es necesario que haga un volcado y carga completa del repositorio, es muy conveniente tener la mitad de ese proceso (la parte del volcado) realizada. Desafortunadamente, la creación—y recuperación—de copias de seguridad incrementales tarda mucho más, dado que cada revisión es reproducida en el fichero de volcado o el repositorio.

En ambos escenarios, los administradores del repositorio necesitan estar atentos a cómo las modificaciones de propiedades de revisión no versionadas afectan a sus copias de seguridad. Dado que estos cambios no generan por sí mismos nuevas revisiones, no activarán ganchos post-commit, y quizás ni siquiera los ganchos pre-revprop-change y post-revprop-change. ^[24] Y dado que puede cambiar las propiedades de revisión sin respetar su orden cronológico—puede cambiar cualquier propiedad de revisión en cualquier momento—una copia de seguridad incremental de las últimas pocas revisiones quizás no capture la modificación de una propiedad de revisión que fue incluida como parte de una copia de seguridad anterior.

Hablando de manera general, sólo los realmente paranoicos necesitarían hacer una copia de seguridad de su repositorio completo, digamos que, cada vez que se realiza un cambio. No obstante, asumiendo que un repositorio determinado tiene funcionando otros mecanismos de redundancia con relativa granularidad (como correos electrónicos por modificación), una copia de seguridad en caliente de la base de datos sería algo que un administrador de repositorio querría incluir como parte de una copia de seguridad de sistema nocturna. Para la mayoría de los repositorios, los correos archivados con cambios son suficiente fuente de redundancia, al menos para los últimos cambios. Pero son sus datos—protéjalos tanto como desee.

A menudo, la mejor estrategia para realizar copias de seguridad es aquella que diversifique. Puede aprovechar combinaciones de copias de seguridad completas e incrementales, y adicionalmente archivos de correo con los cambios. Los desarrolladores de Subversion, por ejemplo, realizan una copia de seguridad del repositorio de código fuente tras cada nueva revisión, y mantienen un archivo de todas las notificaciones por correo electrónico de cambios y modificaciones de propiedades. Su solución podría ser similar, pero debería estar orientada a las necesidades y ese delicado balance entre la conveniencia y la paranoia. Y aunque nada de todo esto le ayude a salvar su hardware del puño de hierro del Destino, ^[25] ciertamente debería ayudarle a recuperarse tras uno de esos momentos.

Aunque Subversion le permite desplazar los ficheros y directorios versionados sin pérdida de información de cualquier tipo, al hacerlo puede entorpecer el flujo de trabajo de aquellos quienes acceden al repositorio con frecuencia y esperan encontrar algunas cosas en ubicaciones determinadas. Intente asomarse un poco al futuro; planifique antes de poner sus datos bajo control de versiones. Al “organizar” el contenido de sus repositorios de una manera efectiva la primera vez, podrá evitar un montón de futuros dolores de cabeza.

Hay algunas cosas que deberá considerar al configurar repositorios con Subversion. Asumamos que como administrador de repositorio será responsable de dar soporte del sistema de control de versiones a varios proyectos. La primera decisión consiste en decidir si usará un único repositorio para múltiples proyectos, o le dará un repositorio a cada proyecto, o una mezcla de cambos.

Hay múltiples beneficios en el uso de un único repositorio para múltiples proyectos, siendo el más obvio evitar duplicar el trabajo de mantenimiento. Tener un único repositorio significa que sólo hay un conjunto de scripts de enganche, un elemento del que hacer rutinariamente copias de seguridad, un único volcado y recarga si Subversion lanza alguna nueva versión incompatible, y así con todo. Además, puede mover datos entre proyectos muy fácilmente, y sin perder ninguna información histórica de versionado.

Las desventajas de usar un único repositorio son que los diferentes proyectos pueden tener diferentes listas de correo que reciben notificaciones de los cambios realizados o diferentes requisitos de autenticación y autorización. Además, recuerde que Subversion usa números de revisión globales por repositorio. Hay gente a la que no le gusta el hecho de que incluso sin haber realizado cambios recientes en sus proyectos, el número de la revisión más reciente sigue subiendo porque otros proyectos siguen añadiendo revisiones de manera activa.

También puede diseñar una solución híbrida. Por ejemplo, los proyectos pueden ser agrupados en función de las relaciones que tengan entre ellos. Quizás tenga varios repositorios con un puñado de proyectos en cada uno. De ese modo, los proyectos más propensos a compartir sus datos pueden hacerlo de manera sencilla, y a medida que se añaden revisiones al repositorio, al menos los desarrolladores del mismo saben que están relacionadas remotamente con todo aquél que usa ese repositorio.

Tras decidir cómo desea organizar sus proyectos con respecto a los repositorios, probablemente querrá decidir las jerarquías de los directorios almacenados en ellos. Dado que Subversion usa copias de directorio normales para hacer ramas y etiquetas (vea Capítulo 4, Crear ramas y fusionarlas), la comunidad de Subversion recomienda que elija una ubicación en el repositorio para cada raíz de proyecto— el directorio “superior” que contiene todos los datos relacionados con el mismo—y cree tres nuevos subdirectorios en esa raíz: trunk, que sería el directorio bajo el cual se lleva el desarrollo principal del proyecto; branches, que sería el directorio que alojaría las diferentes ramas con nombre de la línea principal de desarrollo; tags, que es el directorio donde las ramas son creadas, y quizás destruidas, pero nunca modificadas.

Por ejemplo, su repositorio podría tener este aspecto:

/
   calc/
      trunk/
      tags/
      branches/
   calendar/
      trunk/
      tags/
      branches/
   spreadsheet/
      trunk/
      tags/
      branches/
   …

Tenga en cuenta que no importa dónde está la raíz de cada proyecto en su repositorio. Si sólo tiene un proyecto por repositorio, el lugar lógico para poner la raíz de cada proyecto es en la raíz del repositorio respectivo. Si tiene múltiples proyectos, quizás desee organizarlos en grupos dentro del repositorio, quizás ubicando proyectos con fines similares o código compartido en el mismo subdirectorio, o quizás simplemente prefiera agruparlos alfabéticamente. Tal esquema podría tener el siguiente aspecto:

/
   utils/
      calc/
         trunk/
         tags/
         branches/
      calendar/
         trunk/
         tags/
         branches/
      …
   office/
      spreadsheet/
         trunk/
         tags/
         branches/
      …

Despliegue su repositorio de la manera que crea más conveniente. Subversion no espera ni obliga un esquema de directorios concreto—a sus ojos, un directorio es un directorio es un directorio. Por último, debería elegir la organización del repositorio de manera que satisfaga las necesidades de aquellos que trabajen en los proyectos ahí alojados.

Tras decidir cómo organizar los proyectos de su repositorio, probablemente quiera poblarlo con ese esquema y los datos iniciales de los proyectos. Hay varios modos de hacer esto en Subversion. Podría usar el comando svn mkdir (vea Capítulo 9, Referencia completa de Subversion) para crear cada directorio en su esquema esquelético, uno tras otro. Una forma más rápida de realizar esta misma tarea es usar el comando svn import (vea “svn import”). Al crear el esquema en una ubicación temporal de su disco, puede importarlo por completo en un único cambio:

$ mkdir tmpdir
$ cd tmpdir
$ mkdir projectA
$ mkdir projectA/trunk
$ mkdir projectA/branches
$ mkdir projectA/tags
$ mkdir projectB
$ mkdir projectB/trunk
$ mkdir projectB/branches
$ mkdir projectB/tags
…
$ svn import . file:///path/to/repos --message 'Initial repository layout'
Adding         projectA
Adding         projectA/trunk
Adding         projectA/branches
Adding         projectA/tags
Adding         projectB
Adding         projectB/trunk
Adding         projectB/branches
Adding         projectB/tags
…
Committed revision 1.
$ cd ..
$ rm -rf tmpdir
$

Puede comprobar los resultados de la operación de importado ejecutando el comando svn list:

$ svn list --verbose file:///path/to/repos
      1 harry               May 08 21:48 projectA/
      1 harry               May 08 21:48 projectB/
…
$

Una vez tenga la estructura de su esquema en lugar, puede comenzar a importar los del proyecto en su repositorio, si es que tales datos existen. De nuevo, hay varios métodos para hacer esto. Puede usar el comando svn import. Podría obtener una copia de trabajo local de su reciente repositorio, mover y organizar los datos de su proyecto dentro, y usar los comandos svn add y svn commit. Pero una vez comenzamos a hablar de tales cosas, ya no estamos discutiendo la administración del repositorio. Si no está familiarizado con el programa cliente svn, vea Capítulo 3, Recorrido guiado.

El cliente Subversion insume la mayor parte de su tiempo manejando copias de trabajo. No obstante, cuando necesita información del repositorio efectúa una solicitud a través de la red, y el servidor responde apropiadamente. Los detalles del protocolo de red son ocultados por el usuario; el cliente intenta acceder a una URL, y dependiendo del esquema URL, utiliza un protocolo particular para contactar al servidor (ver URLs del repositorio). Los usuarios pueden ejecutar svn --version para ver que esquemas URL y protocolos que comprende el cliente.

Cuando el proceso del servidor recibe una solicitud del cliente, típicamente demanda que el cliente se identifique. Este solicita la autenticación al cliente , y el cliente responde proporcionando las credenciales al servidor. Una vez completado ésto, el servidor responde con la información que el cliente solicitó originalmente. Observe que este método se diferencia de sistemas como CVS, dónde el cliente por cuenta propia ofrece las credenciales (“de acceso al sistema”), antes de realizar una solicitud. En Subversion, el servidor “exige tomar” las credenciales a través de la negociación con el cliente en el momento apropiado, en lugar de que el cliente las “impulse”. Esto asegura operaciones más elegantes. Por ejemplo, si se configura un servidor para que permita acceso de lectura al repositorio a todo el mundo, nunca demandará a un cliente que se autentique cuando intente realizar un svn checkout.

Si la solicitud de red del cliente escribe datos nuevos en el repositorio (por ejemplo: svn commit), un nuevo árbol de revisión es creado. Si la solicitud del cliente fue autenticada, el nombre del usuario es guardado como valor de la propiedad svn:author en la nueva revisión (ver “Propiedades no versionadas”). Si el cliente no fue autenticado (en otras palabras, si el servidor nunca promulgó la autenticación), la propiedad svn:author de la revisión está en blanco.^[27]

Muchos servidores son configurados para requerir autenticación por cada solicitud que reciban. Esto puede convertirse en una gran molestia para los usuarios, quienes son forzados a escribir sus contraseñas una y otra vez.

Afortunadamente, el cliente Subversion ha remediado ésto: un sistema incorporado para ocultar las credenciales en el disco. Por defecto, en el momento en que el cliente se autentica satisfactoriamente con un servidor, éste guarda las credenciales en el área de configuración de ejecución privada del usuario— en ~/.subversion/auth/ en los sistemas tipo Unix o %APPDATA%/Subversion/auth/ en Windows. (El área de ejecución es cubierto con mayor detalle en “Área de configuración de parámetros de ejecución”.) Con éxito las credenciales son ocultadas en el disco, encerradas en una combinación de hostname, puerto y realm de autenticación.

Cuando el cliente recibe la solicitud para que se autentique, primero busca las credenciales apropiadas en el caché de disco; sino existen, o si las credenciales fallan en la autenticación, el cliente simplemente pregunta al usuario por la información.

Las personas que sufren de paranoia sobre asuntos de seguridad pueden estar pensando, “Contraseñas ocultas en el disco? Eso es terrible!” Pero por favor conserve la calma. Primero, el área de caché auth/ se encuentra protegida por permisos a fin de que sólo el usuario (dueño) puede leer la información que se encuentra en ella, evitando que otros puedan acceder. Si eso no es lo suficientemente seguro para usted, puede deshabilitar el caché de credenciales. Para lograrlo, sólo basta con un único comando, pasando la opción --no-auth-cache:

$ svn commit -F log_msg.txt --no-auth-cache
Authentication realm: <svn://host.example.com:3690> example realm
Username:  joe
Password for 'joe':

Adding         newfile
Transmitting file data .
Committed revision 2324.

# password was not cached, so a second commit still prompts us

$ svn rm newfile
$ svn commit -F new_msg.txt
Authentication realm: <svn://host.example.com:3690> example realm
Username:  joe
[...]

O, si usted desea deshabilitar el caché de credenciales en forma permanente, puede editar su archivo de configuración config (ubicado dentro del directorio auth/). Simplemente coloque no a store-auth-creds, y las credenciales no serán guardadas en el caché nunca más.

[auth]
store-auth-creds = no

Algunas veces los usuario desearán eliminar credenciales específicas del caché de disco. Para hacer ésto, necesitará navegar dentro del área auth/ y eliminar el archivo de caché apropiado en forma manual. Las credenciales son almacenadas en el área de caché en archivos individuales; si usted mira dentro de cada archivo, verá claves y valores. La clave svn:realmstreng describe el "realm" servidor particular con el que que el archivo es asociado:

$ ls ~/.subversion/auth/svn.simple/
5671adf2865e267db74f09ba6f872c28        
3893ed123b39500bca8a0b382839198e
5c3c22968347b390f349ff340196ed39

$ cat ~/.subversion/auth/svn.simple/5671adf2865e267db74f09ba6f872c28

K 8
username
V 3
joe
K 8
password
V 4
blah
K 15
svn:realmstring
V 45
<https://svn.domain.com:443> Joe's repository
END

Una vez que haya localizado el archivo de caché apropiado, sencillamente elimínelo.

Una última palabra acerca del comportamiento de autenticación del cliente: es necesaria una pequeña explicación respecto de las opciones --username y --pasword. Muchos sub-comandos del cliente aceptan estas opciones; sin embargo, es importante comprender que la utilización de las mismas no envía automáticamente las credenciales al servidor. Como se dijo anteriormente, el servidor “exige tomar” las credenciales del cliente cuando lo considera necesario; el cliente no puede “impulsarlas” a voluntad. Si un usuario y/o contraseña son pasados como opción, ellos serán presentados al servidor sólo si este así lo demanda. ^[28] Típicamente, estas opciones son utilizadas cuando:

Aquí hay un resumen final que describe como se comporta un cliente Subversion cuando recibe la demanda de autenticación:

Si el cliente se autentica correctamente a través de alguno de los métodos listados aquí arriba, éste intentará guardar en las credenciales en el caché de disco (a no ser que el usuario haya deshabilitado ese funcionamiento, como hemos mencionado anteriormente.)

Existen unas cuantas maneras diferentes de invocar el programa svnserve. Si se lo invoca sin argumentos, usted no verá nada más que un mensaje de ayuda. No obstante, si planea que inetd dispare el proceso, puede pasar la opción -i (--inetd):

$ svnserve -i
( success ( 1 2 ( ANONYMOUS ) ( edit-pipeline ) ) )

Cuando es invocado con la opción --inetd, svnserve intenta comunicarse con un cliente Subversion a través de stdin y stdout utilizando un protocolo personalizado. Este es un comportamiento estándar de los programas que son ejecutados a través de inetd. El IANA ha reservado el puerto 3690 para el protocolo Subversion, por lo tanto en un sistema tipo Unix usted puede agregar líneas a /etc/services como éstas (si es que no existen todavía):

svn           3690/tcp   # Subversion
svn           3690/udp   # Subversion

Y si su sistema utiliza un demonio inetd tipo Unix clásico, puede agregar esta línea a /etc/inetd.conf:

svn stream tcp nowait svnowner /usr/local/bin/svnserve svnserve -i

Asegúrese que “svnowner” es un usuario que posee permisos apropiados para acceder a su repositorio. Ahora, cuando una conexión cliente ingrese a su servidor en el puerto 3690, inetd disparará un proceso svnserve para servirlo.

Una segunda opción es ejecutar svnserve un proceso “demonio” independiente. Para esto, utilice la opción -d:

$ svnserve -d
$               # svnserve is now running, listening on port 3690

Cuando svnserve ejecute en modo demonio, usted puede utilizar las opciones --listen-port= y --listen-host= para personalizar el puerto y nombre exacto en el cual “escuchará”.

Aún queda una tercera forma de invocar a svnserve, y esa es en “modo túnel”, con la opción -t. Este modo supone que un programa de servicio remoto tal como RSH o SSH ha autenticado un cliente exitosamente y ahora está invocando un proceso privado svnserve como tal usuario. El programa svnserve se comporta normalmente (comunicándose a través de stdin y stdout), y asume que el tráfico está siendo redirigido automáticamente a través de algún tipo de túnel de vuelta al cliente. Cuando svnserve es invocado por un agente túnel como éste, está seguro que el usuario autenticado posee acceso total de lectura y escritura a los archivos de la base de datos del repositorio. (Ver Servidores y Permisos: Una Palabra de Advertencia.) Esencialmente es lo mismo que un usuario local accediendo al repositorio a través de las URLs file:///.

Una vez el programa svnserve se esté ejecutando, hace que cada repositorio en su sistema se encuentre disponibles a la red. Un cliente necesita especificar una ruta absoluta en la URL del repositorio. Por ejemplo, si un repositorio se encuentra ubicado en /usr/local/repositories/project1, el cliente accederá a través de svn://host.example.com/usr/local/repositories/project1 . Para incrementar la seguridad, usted puede pasar la opción -r a svnserve, que limita a exportar sólo los repositorios debajo de esa ruta:

$ svnserve -d -r /usr/local/repositories
…

En efecto, utilizando la opción -r modifica la ubicación que el programa tratará como raíz del espacio de sistema de archivos remoto. En consecuencia, los clientes utilizarán URLs que tengan la porción que le ha sido removida de la ruta, dejando URLs mucho más cortas (y mucho menos reveladoras):

$ svn checkout svn://host.example.com/project1
…

Cuando un cliente se conecta a un proceso svnserve, las siguientes cosas suceden:

En el momento de escribir estas líneas, el servidor sólo sabe cómo realizar la autenticación por CRAM-MD5 ^[29]. En esencia, el servidor envía unos pocos datos al cliente. El cliente usa el algoritmo hash MD5 para crear una huella digital de los datos y la palabra clave combinados, y envía la huella digital como respuesta. El servidor realiza el mismo cálculo con la palabra clave almacenada para verificar que el resultado es idéntico. En ningún momento el password real viaja a través de la red.

También es posible, por supuesto, que el cliente se autentifique externamente vía agente de túnel , como por ejemplo SSH. En este caso, el servidor simplemente examina el usuario bajo el cual se está ejecutando, y lo usa durante la autenticación.

Tal y como habrá imaginado, el fichero svnserve.conf es el mecanismo central de un repositorio para controlar las políticas de autenticación y autorización. El fichero sigue el mismo formato que otros ficheros de configuración (vea “Área de configuración de parámetros de ejecución”): los nombres de sección están enmarcados por corchetes ([ y ]), los comentarios comienzan con almohadillas (#), y cada sección contiene variables específicas que pueden ser modificadas (variable = valor). Démonos un paseo por este fichero para aprender a usarlas.

[general]
password-db = userfile
realm = example realm

[users]
harry = foopassword
sally = barpassword

[general]
password-db = userfile
realm = example realm

# anonymous users can only read the repository
anon-access = read

# authenticated users can both read and write
auth-access = write

[general]
password-db = userfile
realm = example realm

# anonymous users aren't allowed
anon-access = none

# authenticated users can both read and write
auth-access = write

La autenticación de serie de svnserve puede ser muy útil, porque evita tener que crear cuentas de sistema reales. Por otro lado, algunos administradores ya tienen entornos de autenticación SSH bien establecidos y funcionando. En estas situaciones, todos los usuarios del proyecto tienen cuentas en el sistema y la habilidad para conectarse con SSH a la máquina servidora.

Es fácil usar SSH junto con svnserve. El cliente simplemente usa el esquema de URL svn+ssh:// para conectar:

$ whoami
harry

$ svn list svn+ssh://host.example.com/repos/project
harry@host.example.com's password:  *****

foo
bar
baz
…

Lo que sucede en esta situación es que el cliente de Subversion invoca el proceso local ssh, conectándolo con host.example.com, autenticándose como el usuario juan, y entonces lanzando un proceso svnserve privado en la máquina remota, que se ejecuta como el usuario juan. El comando svnserve se invoca en modo túnel (-t) y todo el protocolo de red es canalizado a través “tunneled” de la conexión cifrada por ssh, el agente del túnel. svnserve se da cuenta de que se está ejecutando como el usuario juan, y si el cliente realiza cambios en el repositorio, el nombre de usuario autenticado será usado para atribuir la autoría de la nueva revisión.

Cuando se usa un túnel, la autorización es principalmente controlada por los permisos del sistema operativo a los ficheros de la base de datos del repositorio; es casi igual que si Juan estuviese accediendo al repositorio directamente vía URL file:///. Si necesita que múltiples usuarios del sistema accedan al repositorio directamente, podría ponerlos en un mismo grupo, y ajustar cuidadosamente sus umasks. (Asegúrese de haber leído “Ofrecer múltiples métodos de acceso al repositorio”.) Pero incluso en el caso de usar túneles, el fichero svnserve.conf todavía puede ser usado para bloquear el acceso, simplemente usando auth-access = read o auth-access = none.

Podría pensar que la historia del túnel por SSH acabaría aquí, pero no lo hace. Subversion le permite personalizar el comportamiento de los túneles en su fichero de configuración config (vea “Área de configuración de parámetros de ejecución”.) Por ejemplo, supongamos que desea usar RSH en lugar de SSH. En la sección [tunnels] de su fichero config, defina lo siguiente:

[tunnels]
rsh = rsh

Y ahora, usted puede usar esta nueva definición de túnel usando un esquema URL que concuerde con el nombre de su nueva variable: svn+rsh://host/path. Cuando use el nuevo esquema URL, el cliente Subversion estará ejecutando realmente el comando rsh host svnserve -t tras las cortinas. Si incluye un nombre de usuario en la URL (por ejemplo, svn+rsh://nombreusuario@host/path) el cliente también lo incluirá en su comando (rsh nombreusuario@host svnserve -t.) Pero puede definir nuevos esquemas de túneles mucho más elaborados que eso:

[tunnels]
joessh = $JOESSH /opt/alternate/ssh -p 29934

Este ejemplo muestra varias cosas. Primero, enseña cómo hacer que el cliente de Subversion lance un binario de túnel muy específico (uno ubicado en /opt/alternate/ssh) con opciones específicas. En este caso, acceder a la URL svn+joessh:// invocaría este particular binario de SSH con -p 29934 como parámetro—útil si desea que el programa de túnel se conecte a un puerto no estándar.

Segundo, enseña cómo definir una nueva variable de entorno personalizada que puede reemplazar el nombre de un programa de túnel. Modificar la variable de entorno SVN_SSH es un modo conveniente de reemplazar el agente de túneles SSH por defecto. Pero si necesita tener diferentes reemplazos para servidores diferentes, cada uno de ellos conectando quizás a un puerto diferente o usando un conjunto diferente de opciones, puede usar el mecanismo demostrado en este ejemplo. Ahora, si fuese a crear la variable de entorno JOESSH, su valor reemplazaría el valor completo de la variable del túnel—se ejecutaría $JOESSH en lugar de /opt/alternate/ssh -p 29934.

Para hacer disponible su repositorio por HTTP, básicamente necesita cuatro componentes disponibles en dos paquetes. Necesita el comando httpd de Apache 2.0, el módulo DAV mod_dav que viene con él, Subversion, y el módulo mod_dav_svn, que proporciona sistemas de ficheros, distribuido con Subversion. Una vez tenga todos estos componentes, el proceso para hacer disponible su repositorio es tan simple como:

Puede realizar los dos primeros pasos ya sea compilando httpd y Subversion a partir del código fuente, o instalando paquetes binarios precompilados en su sistema. Puede encontrar la información más actualizada sobre cómo compilar Subversion para su uso con el servidor HTTP Apache, al igual que cómo compilar y configurar Apache para este propósito, en el fichero INSTALL en el directorio raíz del código fuente de Subversion.

Una vez tenga todos los componentes necesarios instalados en su sistema, todo lo que queda por hacer es configurar Apache mediante su fichero httpd.conf. Ordene a Apache que cargue el módulo mod_dav_svn module usando la directiva LoadModule. La directiva debe preceder cualquier otro elemento de configuración relacionado con Subversion. Si su Apache fue instalado usando el esquema por defecto, su módulo mod_dav_svn debería haber sido instalado en el subdirectorio modules de la instalación (a menudo /usr/local/apache2). La directiva LoadModule tiene una sintaxis sencilla, relacionando el nombre de un módulo con la ubicación de una librería dinámica en disco: disk:

LoadModule dav_svn_module     modules/mod_dav_svn.so

Tenga en cuenta que si mod_dav fue compilado como un objeto compartido (en lugar de haber sido enlazado de manera estática con el binario httpd), necesitará también una línea LoadModule similar para él. Asegúrese de que aparece antes de la línea mod_dav_svn:

LoadModule dav_module         modules/mod_dav.so
LoadModule dav_svn_module     modules/mod_dav_svn.so

En un lugar posterior de su fichero de configuración, necesita indicarle a Apache dónde guardará su repositorio (o repositorios) de Subversion. La directiva Location sigue una notación tipo XML, comenzando con una etiqueta de apertura y terminando con una de cierre, con varias otras directivas de configuración en medio. El propósito de la directiva Location es indicar a Apache que debe realizar algo especial cuando tenga que procesar peticiones dirigidas a una URL determinada o a una hija suya. En el caso de Subversion, quiere que Apache simplemente le pase el control a la capa DAV de todas las URLs que apunten a recursos versionados. Puede ordenar a Apache que delegue el control de todas las URLs cuyas porciones de rutas (aquella parte de la URL que sigue el nombre del servidor y número de puerto opcional) empiecen con /repos/ a un proveedor DAV cuyo repositorio se encuentre en /ruta/absoluta/al/repositorio usando la siguiente sintaxis de httpd.conf:

<Location /repos>
  DAV svn
  SVNPath /ruta/absoluta/al/repositorio
</Location>

Si planea soportar múltiples repositorios de Subversion que residirán en el mismo directorio padre de su disco local, puede usar una directiva alternativa, la directiva SVNParentPath, para indicar ese directorio padre común. Por ejemplo, si sabe que creará múltiples repositorios Subversion en el directorio /usr/local/svn que sería accesible mediante URLs como http://my.server.com/svn/repos1, http://my.server.com/svn/repos2, y así en adelante, podría usar la sintaxis de configuración httpd.conf del siguiente ejemplo:

<Location /svn>
  DAV svn

  # any "/svn/foo" URL will map to a repository /usr/local/svn/foo
  SVNParentPath /usr/local/svn
</Location>

Usando la sintaxis anterior, Apache delegará el control de todas las URLs cuyas porciones comiencen con /svn/ al proveedor DAV de Subversion, quien asumirá que todos los elementos en el directorio especificado por la directiva SVNParentPath son en realidad repositorios de Subversion. Esta es una sintaxis particularmente conveniente, ya que a diferencia de la directiva SVNPath, no necesita reiniciar Apache para crear y hacer disponibles nuevos repositorios.

Asegúrese de que cuando defina su nuevo Location, no se solapa con otras ubicaciones exportadas. Por ejemplo, si su DocumentRoot principal es /www, no exporte ningún repositorio Subversion en <Location /www/repos>. En caso de recibir una petición para la URI /www/repos/foo.c, Apache no sabrá si tiene que buscar el fichero repos/foo.c en DocumentRoot, o si debe delegar en mod_dav_svn para que devuelva foo.c del repositorio Subversion.

ServerName svn.example.com

En este punto, debería considerar seriamente el tema de los permisos. Si ha estado ejecutando Apache durante algún tiempo como su servidor de web habitual, probablemente ya tenga una colección de contenido—páginas web, scripts y demás. Estos elementos ya han sido configurados con un conjunto de permisos que les permite funcionar con Apache, o de manera más apropiada, le permite a Apache funcionar con esos ficheros. Apache, cuando es usado como servidor de Subversion, también necesitará los permisos adecuados de lectura y escritura a su repositorio Subversion. (Vea Servidores y Permisos: Una Palabra de Advertencia.)

Tendrá que encontrar una configuración de permisos de sistema que satisfaga los requisitos de Subversion sin estropear instalaciones ya existentes de páginas web o scripts. Esto podría significar cambiar los permisos de su repositorio Subversion para que encajen con aquellos usados por otras elementos servidos por Apache, o podría significar usar las directivas User y Group del fichero httpd.conf para especificar que Apache debe ejecutarse con el usuario y grupo a quien pertenece su repositorio Subversion. No hay una única manera correcta de configurar sus permisos, y cada administrador tendrá diferentes razones para hacer las cosas a su manera. Sólo tenga presente que los problemas relacionados con los permisos son quizás el fallo más común cuando se configura un repositorio Subversion para ser usado con Apache.

En este punto, si ha configurado httpd.conf para que contenga algo como

<Location /svn>
  DAV svn
  SVNParentPath /usr/local/svn
</Location>

...entonces su repositorio es accesible al mundo de manera “anónima”. Hasta que configure algunas políticas de autenticación y autorización, los repositorios Subversion que haga disponibles con la directiva Location serán generalmente accesibles por cualquiera. En otras palabras,

$ ### First time: use -c to create the file
$ ### Use -m to use MD5 encryption of the password, which is more secure
$ htpasswd -cm /etc/svn-auth-file harry
New password: ***** 
Re-type new password: *****
Adding password for user harry
$ htpasswd /etc/svn-auth-file -m sally
New password: *******
Re-type new password: *******
Adding password for user sally
$

<Location /svn>
  DAV svn
  SVNParentPath /usr/local/svn
  AuthType Basic
  AuthName "Subversion repository"
  AuthUserFile /etc/svn-auth-file
</Location>

<Location /svn>
  DAV svn
  SVNParentPath /usr/local/svn
  AuthType Basic
  AuthName "Subversion repository"
  AuthUserFile /etc/svn-auth-file
  Require valid-user
</Location>

$ svn list https://host.example.com/repos/project

Error validating server certificate for 'https://home.example.com:443':
 - The certificate is not issued by a trusted authority. Use the
   fingerprint to validate the certificate manually!
Certificate information:
 - Hostname: host.example.com
 - Valid: from Jan 30 19:23:56 2004 GMT until Jan 30 19:23:56 2006 GMT
 - Issuer: CA, example.com, Sometown, California, US
 - Fingerprint: 7d:e1:a9:34:33:39:ba:6a:e9:a5:c4:22:98:7b:76:5c:92:a0:9c:7b

(R)eject, accept (t)emporarily or accept (p)ermanently?

[global]
ssl-authority-files = /path/to/CAcert1.pem;/path/to/CAcert2.pem

$ svn list https://host.example.com/repos/project

Authentication realm: https://host.example.com:443
Client certificate filename: /path/to/my/cert.p12
Passphrase for '/path/to/my/cert.p12':  ********
…

[groups]
examplehost = host.example.com

[examplehost]
ssl-client-cert-file = /path/to/my/cert.p12
ssl-client-cert-password = somepassword

En este punto, ya ha configurado la autenticación, pero no la autorización. Apache es capaz de cuestionar a los clientes y confirmar sus identidades, pero todavía no sabe cómo permitir o restringir el acceso a los clientes con esas identidades. Esta sección describe dos estrategias para controlar el acceso a sus repositorios.

<Location /svn>
  DAV svn
  SVNParentPath /usr/local/svn

  # how to authenticate a user
  AuthType Basic
  AuthName "Subversion repository"
  AuthUserFile /path/to/users/file
  
  # only authenticated users may access the repository
  Require valid-user
</Location>

<Location /svn>
  DAV svn
  SVNParentPath /usr/local/svn

  # how to authenticate a user
  AuthType Basic
  AuthName "Subversion repository"
  AuthUserFile /path/to/users/file

  # For any operations other than these, require an authenticated user.
  <LimitExcept GET PROPFIND OPTIONS REPORT>
    Require valid-user
  </LimitExcept>
</Location>

LoadModule dav_module         modules/mod_dav.so
LoadModule dav_svn_module     modules/mod_dav_svn.so
LoadModule authz_svn_module   modules/mod_authz_svn.so

            <Location /repos>
              DAV svn
              SVNParentPath /usr/local/svn

              # our access control policy
              AuthzSVNAccessFile /path/to/access/file                 
            </Location>
          

            <Location /repos>
              DAV svn
              SVNParentPath /usr/local/svn
            
              # our access control policy
              AuthzSVNAccessFile /path/to/access/file                 
            
              # only authenticated users may access the repository
              Require valid-user
            
              # how to authenticate a user
              AuthType Basic
              AuthName "Subversion repository"
              AuthUserFile /path/to/users/file                  
            </Location>
          

            <Location /repos>
              DAV svn
              SVNParentPath /usr/local/svn
            
              # our access control policy
              AuthzSVNAccessFile /path/to/access/file                 
            
              # try anonymous access first, resort to real 
              # authentication if necessary.
              Satisfy Any
              Require valid-user
            
              # how to authenticate a user
              AuthType Basic
              AuthName "Subversion repository"
              AuthUserFile /path/to/users/file                  
            </Location>
          

[calc:/branches/calc/bug-142]
harry = rw
sally = r

[calc:/branches/calc/bug-142]
harry = rw
sally = r

# give sally write access only to the 'testing' subdir
[calc:/branches/calc/bug-142/testing]
sally = rw

[calc:/branches/calc/bug-142]
harry = rw
sally = r

[calc:/branches/calc/bug-142/secret]
harry =

[/]
* = r

[groups]
calc-developers = harry, sally, joe
paint-developers = frank, sally, jane
everyone = harry, sally, joe, frank, sally, jane

[calc:/projects/calc]
@calc-developers = rw

[paint:/projects/paint]
@paint-developers = rw
jane = r 

Hemos cubierto la mayoría de las opciones de autenticación y autorización para Apache y mod_dav_svn. Pero Apache proporciona algunas otras características interesantes.

<Location /svn>
  DAV svn
  SVNParentPath /usr/local/svn
  SVNIndexXSLT "/svnindex.xsl"
  …
</Location>

La primera vez que el cliente de línea de comando svn es ejecutado, crea un área de configuración para el usuario. En sistemas tipo Unix, este área aparece como el directorio .subversion en el directorio home del usuario. En sistemas Win32, Subversion crea un directorio llamado Subversion, típicamente dentro del área Application Data del directorio de perfil del usuario (el cual, por cierto, suele ser un directorio oculto). No obstante, en esta plataforma la ubicación exacta difiere de sistema a sistema, y es dictada por el registro de Windows. ^[33] A lo largo del libro nos referiremos al área de configuración de cada usuario usando su nombre Unix, .subversion.

Además del área de configuración de cada usuario, Subversion también reconoce la existencia de un área de configuración global de sistema. Ésta le permite al administrador de sistema establecer valores por defecto para todos los usuarios en una máquina determinada. Tenga en cuenta que el área de configuración global de sistema por sí sola no dicta reglas obligatorias—los parámetros del área de configuración de cada usuario tienen prioridad a los globales, y los parámetros proporcionados en la línea de comando al programa svn tienen la palabra final sobre el comportamiento. En plataformas tipo Unix, el área de configuración global de sistema estará posiblemente en el directorio /etc/subversion; en máquinas Windows, se busca el directorio Subversion dentro de la ubicación común Application Data (de nuevo, especificada por el registro de Windows). A diferencia del caso específico de cada usuario, el programa svn no intentan crear un área de configuración global de sistema.

El área de configuración actualmente contiene tres ficheros—dos ficheros de configuración (config y servers), y un fichero README.txt que describe el formato INI. En el momento de su creación, los ficheros contienen los valores por defecto para cada una de las opciones soportadas por Subversion, en su mayoría con comentarios y agrupadas con descripciones textuales que indican cómo los valores de cada opción afectan al comportamiento de Subversion. Para cambiar un comportamiento dado, sólo necesita cargar el fichero de configuración adecuado en su editor de texto, y modificar el valor de la opción deseada. Si en algún momento desea recuperar los valores de configuración por defecto, puede simplemente borrar (o renombrar) su directorio de configuración y entonces ejecutar algún comando svn inocuo, como svn --version. Entonces se creará un nuevo directorio de configuración con el contenido por defecto.

El área de configuración de cada usuario también contiene una cache de datos de autenticación. El directorio auth agrupa un conjunto de subdirectorios que contienen trozos de información guardada usada por los varios métodos de autenticación soportados por Subversion. Este directorio es creado de tal manera que sólo su usuario tiene permiso para leer su contenido.

Además del área de configuración habitual basada en ficheros INI, los clientes de Subversion ejecutados en plataformas Windows también pueden usar el registro de Windows para almacenar datos de configuración. Los nombres de las opciones y sus valores son iguales que en los ficheros INI. La jerarquía “fichero/sección” también se mantiene, aunque especificada de una manera ligeramente diferente—en este esquema, los ficheros y las secciones son simples niveles del árbol del registro de claves.

Subversion busca valores de configuración global de sistema bajo la clave HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion. Por ejemplo, la opción global-ignores, que pertenece a la sección miscellany del fichero config, se encontraría en HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Config\Miscellany\global-ignores. Los valores de configuración de cada usuario debería poder encontrarlos en HKEY_CURRENT_USER\Software\Tigris.org\Subversion.

Las opciones de configuración almacenadas en el registro son procesadas antes que sus versiones en ficheros de texto, por lo que sus valores son sobreescritos por lo que contengan los ficheros de configuración. En otras palabras, en un sistema Windows, la prioridad de configuración sigue el siguiente orden:

Además, el registro de Windows no soporta el concepto de que algo esté “comentado”. No obstante, Subversion ignorará cualquier opción cuyo nombre comience con el carácter almohadilla (#). Esto le permite comentar de forma efectiva una opción de Subversion sin tener que borrar la clave completa del registro, obviamente simplificando el proceso de recuperación de esta opción.

El cliente de línea de comando svn nunca intenta modificar el registro de Windows, así que no intentará crear ahí ningún área de configuración por defecto. Puede crear las claves que necesita usando el programa REGEDIT. Alternativamente, puede crear un fichero .reg, y entonces hacer doble click sobre ese fichero desde una ventana de explorador, lo cual hará que los datos sean fusionados en su registro.

REGEDIT4

[HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Servers\groups]

[HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Servers\global]
"#http-proxy-host"=""
"#http-proxy-port"=""
"#http-proxy-username"=""
"#http-proxy-password"=""
"#http-proxy-exceptions"=""
"#http-timeout"="0"
"#http-compression"="yes"
"#neon-debug-mask"=""
"#ssl-authority-files"=""
"#ssl-trust-default-ca"=""
"#ssl-client-cert-file"=""
"#ssl-client-cert-password"=""

[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auth]
"#store-auth-creds"="no"

[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\helpers]
"#editor-cmd"="notepad"
"#diff-cmd"=""
"#diff3-cmd"=""
"#diff3-has-program-arg"=""

[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\miscellany]
"#global-ignores"="*.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#*"
"#log-encoding"=""
"#use-commit-times"=""
"#template-root"=""
"#enable-auto-props"=""

[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\tunnels]

[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auto-props]

El ejemplo anterior muestra el contenido de un fichero .reg que contiene algunas de las opciones de configuración más usadas y sus valores por defecto. Tenga en cuenta la presencia tanto de opciones globales de sistema (para opciones relacionadas con proxys) como opciones de cada usuario (programas de edición y almacenamiento de claves, entre otras). Fíjese también que todas las opciones están comentadas. Sólo tiene que eliminar el carácter almohadilla (#) del comienzo de cada nombre de opción, y poner los valores que desee.

En esta sección discutiremos las opciones específicas de parámetros de ejecución soportados actualmente por Subversion.

[groups]
beanie-babies = *.red-bean.com
collabnet = svn.collab.net

[beanie-babies]
…

[collabnet]
…

Las propiedades pueden ser adiciones muy útiles a copia de trabajo local. De hecho, Subversion usa para sí mismo propiedades para almacenar información especial, y como modo para indicar que puede ser necesario cierto procesamiento especial. Igualmente, puede usar propiedades para sus propósitos. Por supuesto, cualquier cosa que haga con propiedades puede ser realizada también usando ficheros versionados regulares, pero considere el siguiente ejemplo de uso de propiedades de Subversion.

Digamos que desea diseñar una página web que almacene muchas fotos digitales, y las muestra con descripciones y una marca de fecha. Ahora, su conjunto de fotos cambia constantemente, así que le gustaría tener la mayor parte posible de la web automatizada. Estas fotos pueden ser bastante grandes, así que como es habitual en páginas web de esta naturaleza, desea proporcionar miniaturas de las imágenes a los visitantes de su web. Puede hacer esto con ficheros tradicionales. Es decir, puede tener su imagen123.jpg y imagen123-miniatura.jpg uno al lado del otro en un directorio. O si prefiere tener los mismos nombres, puede tener las miniaturas en un directorio diferente, como miniaturas/imagen123.jpg. También puede almacenar sus descripciones y marcas de fechas del mismo modo, de nuevo separados del fichero original de la imagen. Pronto, su árbol de ficheros será un desorden, y crecerá en múltiplos con cada nueva foto que añada a la página web.

Ahora considere la misma situación usando las propiedades de ficheros de Subversion. Imagine tener un único fichero, imagen123.jpg, y varias propiedades anexas llamadas descripcion, marcadetiempo, e incluso miniatura. Ahora el directorio de su copia local de trabajo parece más fácil de gestionar—de hecho, parece que no hay más que ficheros de imágenes. Pero sus scripts automáticos están preparados. Saben que pueden usar svn (o incluso mejor, pueden usar un lenguaje de enlace con Subverion— vea “Usando lenguajes distintos de C y C++”) para extraer la información adicional que su página web necesita mostrar sin tener que leer un fichero índice o jugar manipulando las rutas de ficheros.

Cómo usar las propiedades de Subversion (si decide usarlas) está en sus manos. Tal y como hemos mencionados, Subversion usa las propiedades para sus propios fines, que discutiremos más tarde en este capítulo. Pero antes, veamos cómo manipular opciones usando el programa svn.

El comando svn tiene la libertad de añadir o modificar propiedades de ficheros y directorios de varias maneras. Para propiedades con valores cortos, legibles por humanos, quizás la forma más simple de añadir una nueva propiedad es especificar el nombre de la propiedad y su valor en la línea de comando con el subcomando propset.

$ svn propset copyright '(c) 2003 Red-Bean Software' calc/button.c
property 'copyright' set on 'calc/button.c'
$

Pero hemos estado alabando la flexibilidad que Subversion ofrece para los valores de sus propiedades. Y si está planeando tener un valor de propiedad textual multi línea, o incluso binario, probablemente no quiera proporcionarlo en la línea de comando. Así que el subcomando propset acepta el parámetro --file (-F) para especificar el nombre de un fichero que contiene el nuevo valor de una propiedad.

$ svn propset license -F /path/to/LICENSE calc/button.c
property 'license' set on 'calc/button.c'
$

Además del comando propset, el programa svn proporciona el comando propedit. Este comando usa el programa de edición configurado (vea “Config”) para añadir o modificar propiedades. Cuando ejecuta el comando, svn invoca su programa de edición sobre un fichero temporal que contiene el valor actual de la propiedad (o un fichero vacío, si está añadiendo una nueva propiedad). Entonces, simplemente modifique el valor en su programa de edición hasta que represente el nuevo valor que desea almacenar para la propiedad, guarde el fichero temporal, y salga del programa de edición. Si Subversion detecta que realmente ha modificado el fichero, aceptará esta versión como nuevo valor de la propiedad. Si sale de su programa de edición sin realizar cambios, la propiedad no será modificada.

$ svn propedit copyright calc/button.c  ### exit the editor without changes
No changes to property 'copyright' on 'calc/button.c'
$

Debemos advertirle de que al igual que con otros subcomandos de svn, aquellos relacionados con propiedades pueden actuar sobre varias rutas a la vez. Esto le permite modificar propiedades sobre un conjunto de ficheros con un único comando. Por ejemplo, podríamos haber hecho:

$ svn propset copyright '(c) 2002 Red-Bean Software' calc/*
property 'copyright' set on 'calc/Makefile'
property 'copyright' set on 'calc/button.c'
property 'copyright' set on 'calc/integer.c'
…
$

Todas estas adiciones y ediciones de propiedades no son realmente muy útiles si no puede recuperar fácilmente el valor almacenado en la propiedad. Así que el programasvn proporciona dos subcomandos para mostrar los nombres y valores de propiedades anexas a ficheros y directorios. El comando svn proplist mostrará un listado de los nombres de las propiedades que existen en una ruta. Una vez conozca el nombre de las propiedades de un nodo, puede solicitar sus valores individualmente usando svn propget. Este comando, dada una ruta (o grupo de rutas) y un nombre de propiedad, imprimirá el valor de la propiedad al flujo estándar de salida.

$ svn proplist calc/button.c
Properties on 'calc/button.c':
  copyright
  license
$ svn propget copyright calc/button.c
(c) 2003 Red-Bean Software

Incluso existe una variación del comando proplist que mostrará tanto el nombre de todas las propiedad como su valor command. Simplemente use la opción --verbose (-v).

$ svn proplist --verbose calc/button.c
Properties on 'calc/button.c':
  copyright : (c) 2003 Red-Bean Software
  license : ================================================================
Copyright (c) 2003 Red-Bean Software.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions 
are met:

1. Redistributions of source code must retain the above copyright
notice, this list of conditions, and the recipe for Fitz's famous
red-beans-and-rice.
…

El último subcomando que trata con propiedades es propdel. Dado que Subversion le permite almacenar propiedades con valores vacíos, no puede eliminar una propiedad usando propedit o propset. Por ejemplo, este comando no le proporcionará el efecto deseado:

$ svn propset license '' calc/button.c
property 'license' set on 'calc/button.c'
$ svn proplist --verbose calc/button.c
Properties on 'calc/button.c':
  copyright : (c) 2003 Red-Bean Software
  license : 
$

Debe usar el comando propdel para eliminar las propiedades por completo. La sintaxis es similar a la de otros comandos de propiedades:

$ svn propdel license calc/button.c
property 'license' deleted from ''.
$ svn proplist --verbose calc/button.c
Properties on 'calc/button.c':
  copyright : (c) 2003 Red-Bean Software
$

Ahora que está familiarizado con todos los subcomandos de svn relacionados con propiedades, veamos cómo las modificaciones de propiedades afectan al flujo de trabajo habitual de Subversion. Tal y como mencionamos anteriormente, las propiedades de ficheros y directorios están versionadas, igual que los contenidos de los ficheros. Como resultado, Subversion proporciona las mismas oportunidades de fusionar—ya sea de manera limpia o resolviendo conflictos—las modificaciones sobre propiedades de otra persona con las suyas.

$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop
property 'svn:log' set on repository revision '11'
$

Al igual que con los contenidos de sus ficheros, sus cambios sobre propiedades son modificaciones locales, únicamente convertidas en permanentes cuando las envía al repositorio con svn commit. También puede deshacer fácilmente sus cambios—el comando svn revert recuperará sus ficheros y directorios a su estado no modificado, contenido, propiedades, y todo lo demás. Además, puede recibir información interesante sobre el estado de las propiedades de sus ficheros y directorios usando los comandos svn status y svn diff.

$ svn status calc/button.c
 M     calc/button.c
$ svn diff calc/button.c
Property changes on: calc/button.c
___________________________________________________________________
Name: copyright
   + (c) 2003 Red-Bean Software

$

Fíjese cómo el subcomando status muestra una M en la segunda columna en lugar de la primera. Esto es porque hemos modificado propiedades de calc/button.c, pero no hemos modificado su contenido. De haber cambiado ambos, habríamos visto también una M en la primera columna (vea “svn status”).

% svn update calc
M  calc/Makefile.in
 C calc/button.c
Updated to revision 143.
$ 

$ svn status calc
 C     calc/button.c
?      calc/button.c.prej
$ cat calc/button.c.prej 
prop 'linecount': user set to '1256', but update set to '1301'.
$

Quizás también se haya dado cuenta del modo no estándar usado por Subversion para mostrar las diferencias entre propiedades. Todavía puede ejecutar svn diff y redirigir la salida para crear un fichero parche usable. El programa patch ignorará los parches de propiedades—como regla general, ignora cualquier ruido que no es capaz de entender. Esto significa desafortunadamente que para aplicar completamente un parche generado por svn diff, cualquier modificación de propiedades deberá ser aplicada a mano.

Como puede ver, la presencia de modificaciones de propiedades no tiene efectos significativos en el flujo de trabajo típico con Subversion. Sus patrones generales de actualizar su copia local, verificar el estado de sus ficheros y directorios, obtener informes sobre las modificaciones realizadas, y enviar éstas al repositorio son completamente inmunes a la presencia o ausencia de propiedades. El programa svn tiene algunos subcomandos adicionales para efectuar cambios de propiedades, pero esto es la única asimetría notable.

Subversion no tiene reglas particulares sobre propiedades—puede usarlas para cualquier fin. Subversion sólo le pide que no use nombres de propiedades que comiencen con el prefijo svn:. Ese es el espacio de nombres que reserva para uso propio. De hecho, Subversion define ciertas propiedades que tienen efectos mágicos sobre ficheros y directorios. En esta sección, desvelaremos el misterio, y describiremos cómo estas propiedades especiales pueden hacerle la vida un poco más fácil.

$ svn propset svn:ignore -F .cvsignore .
property 'svn:ignore' set on '.'
$

$ svn status calc
 M     calc/button.c
?      calc/calculator
?      calc/data.c
?      calc/debug_log
?      calc/debug_log.1
?      calc/debug_log.2.gz
?      calc/debug_log.3.gz

calculator
debug_log*

$ svn status
 M     calc
 M     calc/button.c
?      calc/data.c

$ svn status --no-ignore
 M     calc/button.c
I      calc/calculator
?      calc/data.c
I      calc/debug_log
I      calc/debug_log.1
I      calc/debug_log.2.gz
I      calc/debug_log.3.gz

Here is the latest report from the front lines.
$LastChangedDate$
$Rev$
Cumulus clouds are appearing more frequently as summer approaches.

$ svn propset svn:keywords "LastChangedDate Author" weather.txt
property 'svn:keywords' set on 'weather.txt'
$

Here is the latest report from the front lines.
$LastChangedDate: 2002-07-22 21:42:37 -0700 (Mon, 22 Jul 2002) $
$Rev$
Cumulus clouds are appearing more frequently as summer approaches.