Svn Howto

Attention ! Le site april a été migré sous Drupal en octobre 2008. Cette page n'est donc plus d'actualité pour la gestion du site web et est conservée pour raison historique

SVN-HOWTO

Benoît Sibaud <bsibaud AT april.org> basé sur le CVS-HOWTO du 30 septembre 1999 de Benjamin Drieu <bdrieu@april.org>

Ce document est une tentative d'explication de l'utilisation de l'outil Subversion/SVN dans le cadre du web d'APRIL. Il est tiré de nos expériences avec SVN, mais si vous avez des précisions à adapter à ce sujet, il serait intéressant de nous les communiquer. Notez de plus que ce fichier N'EST PAS un guide exhaustif de SVN, et qu'il n'a pas la prétention de vous l'apprendre en détail. C'est au plus un tutorial qui servira à guider vos premiers pas et à vous apprendre les commandes utiles pour contribuer aux projets d'APRIL (en particulier, consultez les autres howto).

1. Qu'est-ce que SVN ?

SVN est un système de gestion d'accès concurrents à un ensemble de fichiers. Dans la pratique, on utilise SVN pour synchroniser les accès par plusieurs utilisateurs à une arborescence donnée. De plus, SVN permet de gérer les versions successives de l'arborescence.

Ce qui en fait un outil idéal pour le travail collaboratif :

• • • • plusieurs personnes peuvent modifier le contenu d'un fichier au même moment, sans que l'une n'écrase le travail de l'autre. Dans ce cas, les modifications de l'un seront ajoutées aux modifications de l'autre ;
      • les modifications d'une personne sont archivées, ce qui permet de revenir à une version antérieure sans problème
      • les modifications sont stockées sous la forme de différence par rapport à la version précédente. Ce qui permet de revenir à une époque ancienne du développement, et de créer une branche parallèle au développement actuel. Dans le futur, ces deux branches pourront se rejoindre en appliquant leurs différences mutuelles à un fichier de référence.

SVN stocke les versions successives des fichiers qu'on lui soumet dans un dépôt (« repository »). Il s'agit d'une arborescence de fichiers qui contient des fichiers administratifs (qui définissent par exemple les modules des arborescences soumises à SVN), ainsi que toutes les projets abrités par le dépôt.

Vous n'utilisez pas le dépôt sur le serveur, mais une copie locale.

2. Comment ça marche ?

Très simplement. SVN utilise basiquement deux opérations :

• • • • le checkout
      • le commit

Lorsque vous exécutez SVN, vous spécifiez en premier argument l'opération à effectuer, et ensuite le ou les arguments éventuels de chaque opération.

2.1 checkout

Le checkout est l'opération qui consiste à extraire les fichiers à partir du dépôt. SVN extrait par défaut la dernière version du fichier. Si plusieurs branches de développement sont en cours ou que vous voulez une version plus ancienne, vous devez le spécifier à SVN (voir la page man de svn(1) pour plus de détails).

Vous devez spécifier en argument le ou les fichiers ou répertoire que vous voulez extraire. Par exemple :

$ svn checkout htdocs/actions/ldd/index.wml

Notez que l'utilisation de checkout est récursive. Ainsi, effectuer un checkout sur le répertoire htdocs sera catastrophique pour vous puisque vous allez télécharger L'ENSEMBLE du site web d'APRIL (disons... un peu plus d'un gigaoctet).

Si tout se passe bien, SVN fournit une sortie qui ressemble à :

U htdocs/actions/ldd/index.wml

et crée un répertoire htdocs/actions/ldd contenant le fichier index.wml ainsi qu'un répertoire .svn (qui contient des fichiers administratifs, et qu'il convient d'ignorer, MAIS PAS D'EFFACER). Vous pouvez maintenant travailler sur le fichier index.wml.

2.2 commit

Le commit est l'opération inverse. Le but du jeu est de mettre à jour sur le dépôt des fichiers que vous avez modifié. La commande est incantatoire :

$ svn commit htdocs/actions/ldd/index.wml

SVN demande ensuite de rentrer des informations sur la nature des modifications effectuées (afin d'archiver leur trace dans un format facilement compréhensible par des humains). Par défaut, SVN exécute la commande « vi », mais cette commande peut être modifiée au besoin en affectant le nom d'un éditeur de textes quelconque à la variable $EDITOR (par exemple emacs).

Enregistrez le texte de vos descriptions que vous venez de saisir (sous vi, ESC :x), et ensuite SVN mettra à jour vos modifications dans le dépôt. Notez que si vous mettez à jour plusieurs fichiers en même temps, SVN vous demandera certainement plusieurs descriptions pour vos modifications (vous pouvez mettre les mêmes).

Si votre description tient en quelques mots, vous pouvez vous passer de l'étape emacs/vi en mettant votre texte sur la ligne de commande, en utilisant l'option -m

$ svn commit -m "Ajout du mois de mai" htdocs/actions/ldd/index.wml

3.1 add

svn add permet d'insérer un ou plusieurs fichiers ou répertoires dans le dépôt. Cette procédure n'a besoin d'être effectuée qu'une bonne fois pour toute. De plus, vous avez besoin d'effectuer un svn commit sur les fichiers que vous rajoutez afin que leur ajout dans le dépôt soit effectif. Notez que cette commande est par défaut récursive (sinon il faut utiliser l'option -N) :

svn add htdocs/tralala.wml

ne marchera pas! A la place, il vous faut passer dans le bon répertoire, puis faire le add:

$ cd htdocs
$ svn add tralala.wml

3.2 remove

svn remove permet de supprimer des fichiers du dépôt. Encore une fois, il est nécessaire d'effectuer un commit afin que leur suppression soit effective dans le dépôt. La commande supprime aussi le fichier en local.

5.1. Emplacement du dépôt

Il y a trois dépôts SVN sur le serveur, dans les répertoires /var/lib/svn/web (site web public), /var/lib/svn/admins (partie admins) et /var/lib/svn/ca (partie CA). L'accès aux deux derniers est limité à un petit nombre d'utilisateurs.

Pour récupérer les dépôts en local, il faut disposer d'un accès SSH sur le serveur (ici avec le compte votre_login) et il faut utiliser :

$ svn checkout svn+ssh://votre_login@april.org/var/lib/svn/web/trunk/htdocs

Et si vous y êtes autorisé :

$ svn checkout svn+ssh://votre_login@april.org/var/lib/svn/admins/trunk/htdocs
$ svn checkout svn+ssh://votre_login@april.org/var/lib/svn/ca/trunk/htdocs

Vous êtes maintenant prêt à travailler.

5.2 WML et SVN

Nous utilisons WML pour la mise en page de nos documents HTML (voir le howto-wml) pour plus de documentation à ce sujet. Le principe de WML est qu'il faut compiler un document WML (langage de macro) en HTML.

Pour effectuer cette manipulation, nous utilisons un script qui est exécuté régulièrement, compile et met à jour les fichiers du site.

5.3 La liste webmasters

La liste webmasters@april.org est la liste de diffusion d'APRIL qui traite des évolutions actuelles ou futures du web de l'association. Pour vous y inscrire, envoyez un courriel à majordomo@april.org avec dans le corps du message "subscribe webmasters". Si vous avez besoin d'utiliser SVN pour effectuer des mises à jour sur le site et qu'une erreur vous en empêche, si vous êtes bloqué ou si vous ne savez pas comment exécuter une opération précise, n'hésitez pas à envoyer un courriel dans cette liste pour obtenir de l'aide.