h1. Subversion

h2. Introducción

Subversión es un sistema de gestión de código fuente, lo que supone que:

• Un usuario que trabaja en diferente ordenadores en un mismo proyecto puede estar seguro de que sus archivos están actualizados siempre
• Varios usuarios trabajando juntos en un proyecto pueden estar seguros de que los cambios que hacen otros no son machacados por accidente
• Varios usuarios trabajando juntos pueden asegurarse de que todos sus archivos están actualizados
• Se puede ir atrás en el tiempo y recuperar una versión antigua de uno o múltiples ficheros

h2. Los primeros pasos

Asumiendo que se ha instalado subversion (apt-get install subversion) y solicitado la cuenta de subversion para trabajar en el código de un proyecto, para empezar necesitas estos tres datos (usaremos aquí datos de ejemplo):

• login de usuario= pepe
• contraseña= estomegusta
• url= http://desarrollo.educarex.es/svn/colegios/zeroconf-services

Lo primero que necesitas es hacer un checkout de la copia de trabajo del proyecto. Esto se hace mediante el comando:

svn checkout http://desarrollo.educarex.es/svn/colegios/zeroconf-services --username pepe --password estomegusta

Tu ordenador recuperará una copia del proyecto desde el servidor y la almacenará en tu ordenador en el directorio desde el que hayas ejecutado ese comando (esta copia se llama copia de trabajo y la operación de descargarla se llama checkout).
Si miras en los archivos descargados verás que hay un directorio llamado "trunk". En este directorio encontrarás todos los archivos que forman parte del proyecto y ya puedes empezar a trabajar con ellos. IMPORTANTE: Lo habitual es hacer el checkout una sóla vez por cada proyecto/persona/ordenador.

h3. Subversion desde Eclipse

Si se usa "Eclipse":www.eclipse.org para programar, no es necesario usar la consola, se puede manejar subversion desde el entorno integrado. "Aquí hay un tutorial para instalar el plugin necesario":http://daredled.blogspot.com/2009/08/howto-eclipse-y-subversion-en-ubuntu.html

Una vez instalado el plugin, se puede ir al menú File -> New ->Other -> SVN ->Project from SVN
Luego hay que usar la opción "Create a new repository location", y ahí rellenar los campos correspondientes a la url, usuario y contraseña.

h2. Forma habitual de trabajar con svn

Una vez que tienes la copia de trabajo, se entra en un ciclo habitual trabajando con los archivos:

• Update: para obtener los cambios que otros hayan hecho (o los que hayas hecho tu trabajando en otro ordenador)
• Editar: haces cambios en los archivos para escribir código, documentación, etc.
• Commit: Envias tus cambios al servidor.

Veamos más en profundidad estos tres pasos

h3. Update

Cuando otros hacen cambios y los suben al servidor, no se envían automáticamente a tu ordenador. Tu tienes que obtener los cambios desde el servidor y actualizar los archivos de tu copia de trabajo. Esto significa que pueden añadirse, modificarse o borrarse archivos durante el proceso de update, según lo que otros hayan hecho. Mi consejo es que actualices tu copia de trabajo siempre antes de empezar a editar los archivos, para trabajar siempre sobre los últimos cambios. Para actualizar tu copia de trabajo ejecutas el comando svn updatedentro del directorio que quieras actualizar.
Mientras subversion hace la actualización irá mostrando información de que archivos modifica/borra/añade y normalmente no hay nada más que hacer. Sin embargo, a veces hay un conflicto que tendrás que manejar. Más abajo explico como hacerlo.

h3. Editar

Puedes editar los archivos de tu código fuente con cualquier programa o editor de textos (Mi recomendación es usar geany para pequeños archivos y eclipse para proyectos más grandes, con los plugin de php, python, etc., según sea necesario).

h4. Commit

Después de editar los archivos es hora de enviar los cambios al servidor, para que otros puedan ver lo que has hecho. Te vas al directorio donde están los archivos y haces así:
svn commit -m "Aquí pongo algún mensaje explicativo" El texto puede ser cualquier cosa pero lo mejor es que sea algún comentario útil para que tus colegas sepan qué has hecho. Normalmente subversion devolverá algún mensaje sobre lo que ha hecho y dirá que ya está (vale, puedes tener conflictos aquí también... te lo explico después)

h2. Otros comandos

h3. Añadir archivos

Como es lógico, puedes añadir archivos al proyecto. Tan sólo crea el archivo y ponlo en donde quieras dentro de tu copia de trabajo, después ejecutas svn add ruta_al_archivo_nuevo Por ejemplo, si estás en el proyecto usbhome y añades el fichero Instrucciones.txt al directorio de documentación, tienes que ejecutar este comando para añadirlo al proyecto de subversion: svn add doc/Instrucciones.txt

Es importante que sepas que esto no envia los archivos al servidor, para eso debes hacer un commit como se explicó arriba.

h4. Borrar archivos

Si quieres borrar un archivo de un proyecto deberías dejar que subversion lo haga. Siempre debes tener en cuenta que el archivo se borrará de la versión actual del proyecto, pero que estará en el repositorio del servidor. Así si te das cuenta de que has borrado el archivo por error, puedes recuperarlo checking out una versión más antigua del proyecto. En fin, para borrar un archivo ejecutas el comando svn delete ruta_al_archivo Así, si quieres borrar el archivo que añadiste arriba, tendrías que ejecutar svn delete doc/Instrucciones.txt
Igual que antes, esto no le dice al servidor que borre el archivo de la versión actual del código. Para eso debes hacer un commit como antes.

h4. Mover o Renombrar archivos

Si queremos renombrar un fichero tan solo deberemos ejecutar la siguiente acción svn move nombre_inicial nombre_final. Como en las anteriores ocasiones, habrá que hacer un commit para que la acción se lleve a acabo.

h3. ¿Qué archivos has modificado tu?

Antes de hacer un commit con todos los archivos que has cambiado, añadido o borrado, es bueno estar seguro de que quieres mandar todo eso al servidor. A veces puede ser difícil recordar que has creado archivos y se te ha olvidado añadirlos al proyecto subversion,o simplemente no recuerdas cosas que has podido cambiar desde tu último commit. Para saber todo eso has de usar el comando status. Veamos con un ejemplo lo que ocurre al usarlo:

#ls
ph_intro.aux ph_intro.log ph_intro.pdf ph_intro.tex sigproc.bib

#svn status
? ph_intro.log
? ph_intro.aux
M ph_intro.tex

En la primera línea uso el comando ls para ver que archivos hay en este directorio, puedes ver que hay cinco archivos. Después ejecuto el comando status y subversion responde con tres líneas. El símbolo '?' quiere decir que este archivo no es parte del proyecto y el 'M' que mi copia de ph_intro.tex ha cambiado. Ahora puedo añadir los archivos ph_intro.log y ph_intro.aux con el comando 'add', pero como son archivos temporales no me molesto en añadirlos y directamente los puedo borrar. De todos modos debería hacer un commit para enviar los cambios que he hecho en el archivo ph_intro.tex y que los demás programadores puedan verlos.

h4. ¿Qué ha hecho otra gente?

Si quieres saber que cambios ha hecho otra gente a un archivo puedes usar el comando log svn log o svn log ruta_al_archivo
Por ejemplo:

svn log ph_intro.tex¶

---

r5 | jem | 2006-10-21 17:59:47 +0200 (Sat, 21 Oct 2006) | 1 line

Añadido texto de Pepe¶

r4 | mark | 2006-10-17 21:54:53 +0200 (Tue, 17 Oct 2006) | 1 line

Puestas nuevas categorías¶

r2 | jem | 2006-10-09 22:30:57 +0200 (Mon, 09 Oct 2006) | 1 line

Primer borrador¶

Aquí puedes ver que ph_intro.tex está actualmente en su quinta revisión, el último cambio lo hizo "jem" con el comentario "Añadido texto de Pepe". También se ve que cuando se hizo ese cambio, se estaba en la revisión 4, enviada por Mark unos cuatro días antes cuando puso nuevas categorías.

h4. ¿Y si subversion dice algo incorrecto?

Algunas veces subversion se queja de que algo está mal en tu copia local. Si eso te ocurre probablemente deberías hablar con alguien que esté trabajando contigo y conozca bien el uso de subversion (o mirar en el "libro de subversion":http://svnbook.red-bean.com/). Sin embargo, hay un comando que puedes intentar antes de pedir ayuda:
svn cleanup
Borrará algunos archivos temporales y a veces hace sentirse feliz otra vez a subversion.

h2. Conflictos

¿Qué ocurre si dos personas hacen cambios en el mismo archivo al mismo tiempo? Normalmente nada. Subversion vee que los dos habeis hecho algún cambio y coge los dos cambios y los mezcla en una nueva versión del documento. Como ejemplo, veamos este archivo de texto:

This is just some short example text to show
how suuversion works when it detects that several
users have changed the same file.
Este archivo ha sido enviado al servidor por el usuario A. El usuario B actualiza su copia de trabajo y ve que el archivo existe. B mira el archivo y ve que no está bien escrita la palabra subversion. B corrige el error y hace un commit del archivo. Al mismo tiempo el usuario A añade más texto al final del archivo y hace también su commit sin haber hecho antes un update (que le habría actualizado los cambios que hizo B). En resumen, que A envia este texto al servidor:
This is just some short example text to show
how suuversion works when it detects that several
users have changed the same file.
Subversion is actually a really useful tool for
anyone who uses a computer.
Mientras que B envia este otro texto:
This is just some short example text to show
how subversion works when it detects that several
users have changed the same file.
Ambos textos modifican el mismo número de versión del archivo, así que ¿cual debería guardar subversion? La respuesta es que ninguno de los dos. En lugar de eso subversion ve que los cambios no se solapan, lo que quiere decir que subversion los puede mezclar en una nueva versión:
This is just some short example text to show
how subversion works when it detects that several
users have changed the same file.
Subversion is actually a really useful tool for
anyone who uses a computer.
Esto es lo que suele ocurrir. No hay que hacer nada para asegurarse de que el documento contiene los últimos cambios. ¿Y qué ocurre si resulta que los cambios se solapan?. La respuesta es muy simple: subversion no hace nada, le deja la responsabilidad de resolver el conflicto a la persona que hizo la última operación de commit. (Si B hizo el commit 1 segundo después de A, B es el que tiene que arreglar el conflicto). Como esto nunca me ha ocurrido no voy a explicar como arreglarlo (Hay instrucciones para "arreglarlo aquí":http://svnbook.red-bean.com/nightly/en/svn.tour.cycle.html#svn.tour.cycle.resolve )

NOTA: Esta documentación es una traducción libre con algún añadido del texto de "Jan Erik Moström":http://www.mostrom.pp.se/notes/Tutorials/SVNMiniTutorial