Introduction Subversion

Julien Barnier 2 aot 2005

Introduction Subversion

Table des matires 1

1.1

Introduction
Objectifs de ce document

Ce document a pour objectif de servir daide-mmoire et de support de formation succinct au logiciel de contrle de versions Subversion 1 .

1.2

Quest-ce que Subversion ?

Subversion est un logiciel de gestion de sources et de contrle de versions. Ce type de programmes a plusieurs fonctions, notamment : garder un historique des direntes versions des chiers dun projet ; permettre le retour une version antrieure quelconque ; garder un historique des modications avec leur nature, leur date, leur auteur... ; permettre un accs souple ces chiers, en local ou via un rseau ; permettre des utilisateurs distincts et souvent distants de travailler ensemble sur les mmes chiers.

1.3

Pourquoi Subversion ?

Il existe un grand nombre de logiciels du mme type. Le plus connu dentre eux et le plus rpandu actuellement est sans doute CVS 2 , mais on peut aussi citer GNU Arch, Bitkeeper, Git, Superversion, etc. Des comparatifs point point peuvent tre trouvs aux adresses suivantes : http://zooko.com/revision_control_quick_ref.html http://better-scm.berlios.de/comparison/comparison.html On pourra justier rapidement le choix de Subversion par les arguments suivants : il est multiplateforme ; il sagit dun logiciel libre ; il fonctionne de manire centralise ; son utilisation et son administration sont plus faciles que CVS ; il supporte plusieurs modes daccs distants, dont SSH et WebDAV via Apache.

1.4

Conguration requise

Aucune conguration particulire nest ncessaire pour utiliser Subversion, il sut juste de se procurer un client qui permette de se connecter et de communiquer avec le dpt. A noter quil est trs facile dinstaller soi-mme un serveur Subversion en local sur sa machine si lon souhaite lutiliser de manire prive . Parmi les clients, on peut citer : la ligne de commande, un peu rustique mais qui permet de tout faire 3 ; TortoiseSVN (http://tortoisesvn.tigris.org/) (Windows)
1. http://subversion.tigris.org/ 2. http://www.cvshome.org/. Subversion est souvent cit comme le successeur ociel de CVS. 3. Pour utiliser la ligne de commande, il faut tlcharger et installer Subversion depuis le site ociel.

Introduction Subversion

RapidSVN (http://rapidsvn.tigris.org/), eSvn (http://esvn.umputun.com/) (multiplateforme) JSVN (http://jsvn.alternatecomputing.com/) (java, multiplateforme) Subclipse (http://subclipse.tigris.org/) (plugin pour Eclipse) AnkhSVN (http://ankhsvn.tigris.org/) (plugin pour Visual Studio .Net) psvn.el (http://xsteve.nit.at/prg/vc_svn/) (mode pour Emacs) etc, etc. Une liste complte de clients est disponible ladresse : http://subversion.tigris.org/links.html#clients Dans ce qui suit, nous illustrerons les points abords laide de la ligne de commande, mais les concepts sont les mmes pour les dirents clients.

2
2.1

Dnitions
Notions gnrales
dpt (repository)

2.1.1

Un dpt Subversion est lemplacement central o sont stockes toutes les donnes relatives aux projets grs. Le dpt est accd via une URL locale ou distante. Le dpt contient lhistorique des versions des chiers stocks, les logs enregistrs lors des modications, les dates et auteurs de ces modications, etc. Un dpt apparat de lextrieur comme un systme de chiers compos de rpertoires au sein desquels on peut naviguer, lire et crire selon les permissions accordes. 2.1.2 projets

Au sein dun dpt se trouvent un ou plusieurs projets. chaque projet correspond en gnral un rpertoire situ la racine du dpt et qui contient lui-mme les chiers et dossiers du projet proprement dit. Exemple darborescence :
(dpt)--+--/batchxsl--+--/trunk | | | +--/branches | | | +--/tags | +--/css-------+--/trunk | | | +--/branches | | | +--/tags | +--/test------+--/rep1 | +--/rep2

Introduction Subversion

2.1.3

copie de travail (working copy)

La copie de travail est un rpertoire situ en local sur le poste de lutilisateur et qui contient une copie dune rvision donne des chiers du dpt. Cest cette copie qui sert de base de travail et qui est modie en local avant dtre importe (sauvegarde) vers le dpt. 2.1.4 rvisions

Chaque modication faite au dpt constitue une rvision. Le numro de rvision commence 1 et augmente de 1 chaque opration. Sa valeur na aucune importance, mais cest un indicateur qui permet de revenir une version donne dun ou plusieurs chiers.

2.2
2.2.1

Oprations
checkout

Le checkout est lopration qui consiste rcuprer pour la premire fois les chiers dj existant au sein dun projet du dpt. Cette opration ne se fait en gnral quune fois par projet. Le rsultat est une copie de travail. 2.2.2 import

Limport est lopration inverse du checkout. Elle consiste placer dans le dpt des chiers locaux dj existants pour y crer un nouveau projet. Cette opration ne se fait en gnral quune fois par projet. 2.2.3 update

Lupdate consiste synchroniser la copie de travail locale avec le dpt en rcuprant la dernire version des chiers du dpt. Cest cette occasion que des conits de version peuvent apparatre. 2.2.4 commit

Un commit est lopration inverse dun update. Elle consiste mettre jour le dpt partir de la copie de travail locale. Une nouvelle rvision est alors cre. Un log (simple message texte contenant une description des modications eectues) doit tre saisi cette occasion. noter que pour quun commit soit possible, il faut que la copie de travail corresponde la dernire version du dpt (modications locales exceptes). Si ce nest pas le cas, il est ncessaire deectuer dabord un update et de rsoudre les conits ventuels avant de ressayer le commit.

Utilisation
Lutilisation de Subversion suit en gnral un cycle assez rptitif.

Introduction Subversion

3.1

Cration dun nouveau projet

La premire chose faire lors de la premire utilisation est de crer un nouveau projet. Deux cas de gure peuvent se prsenter : ou bien le projet existe dj au sein dun dpt et il sagit de rcuprer ce projet en local pour en faire une copie de travail, ou bien ce projet existe en local et doit tre import au sein du dpt. 3.1.1 Projet dj existant au sein dun dpt

Si le projet existe dj au sein du dpt, une seule commande sut pour eectuer un checkout et rcuprer la dernire version des chiers : il sagit de la commande svn co.
$ svn co https://cens-srv-dev1.ens-lsh.fr/svnrep/formationsvn . A credits.htm A index.htm Checked out revision 36.

La commande prcdente a eectu un checkout du projet formationsvn (situ dans un rpertoire racine du mme nom) dans le rpertoire courant. Le rsultat de la commande indique que deux chiers ont t rcuprs et que la dernire rvision est la rvision numro 36. 3.1.2 Import dun projet dj existant en local

Si le projet nexiste pas dans le dpt et quil faut le crer partir de chiers locaux, la commande utiliser est svn import. Cette opration nest en thorie eectue que par la personne charge de ladministration du dpt. Voir la documentation ocielle pour plus dinformations.

3.2

Rcupration de la dernire version du projet

Avant de travailler sur les chiers du projet, il faut sassurer que lon est bien synchronis avec le dpt, cest dire que la copie de travail correspond bien la dernire rvision en cours. Pour cela, il faut eectuer un update laide de la commande svn update :
$ svn update U index.htm Updated to revision 37.

La commande indique quun chier du rpertoire, vraisemblablement modi par quelquun dautre depuis notre dernier update, a t mis jour dans notre copie de travail.

3.3

Mise jour des modications dans le dpt

Une fois quon a modi des chiers, il faut basculer ces modications au sein du dpt pour quelles soient accessibles aux autres utilisateurs. Cette opration seectue laide de la commande svn commit :
$ svn commit -m "Ajout dune personne dans les credits" Sending credits.htm Transmitting file data . Committed revision 38.

Introduction Subversion

Toute opration de commit seectue en indiquant un message dcrivant les modications eectues (ici directement dans la ligne de commande). Il est possible deectuer cette opration sur un rpertoire entier, ou sur seulement un ou plusieurs chiers. Si des modications ont eu lieu par un autre utilisateur du dpt depuis le dernier update, un message derreur le signale. Il faut alors eectuer un nouvel update et rsoudre dventuels conits avant de relancer le commit.

3.4
3.4.1

Rcupration dune version antrieure dun chier

Rcupration de la dernire version

Lorsquon travaille sur un chier, il peut arriver que les modications eectues ne soient pas bonnes et quon souhaite retourner au chier tel quil tait lors du dernier update. La commande svn revert est faite pour a :
$ svn revert credits.htm Reverted credits.htm

Cette commande annule les modications eectues depuis le dernier update. noter que tout est eectu en local, et quun accs au dpt nest pas ncessaire. 3.4.2 Rcupration dune version antrieure du dpt

On peut aussi souhaiter revenir une version antrieure dun chier situ dans le dpt. Il faut alors utiliser svn update en prcisant le numro de la rvision et le ou les chiers :
$ svn update -r 36 credits.htm U credits.htm Updated to revision 36.

3.5

Gestion des chiers du dpt

Subversion propose un ensemble de commandes pour ajouter, supprimer ou renommer des chiers du dpt. 3.5.1 Ajout dun chier

Il faut utiliser svn add. A noter que lajout nest eectif quau prochain commit :
$ svn add liens.htm A liens.htm $ svn commit -m "Ajout du fichier de liens" Adding liens.htm Transmitting file data . Committed revision 39.

3.5.2

Suppression dun chier

Il faut utiliser svn delete :

Introduction Subversion

$ svn delete liens.htm D liens.htm $ svn commit -m "Suppression dun fichier" Deleting liens.htm Committed revision 40.

L aussi, la suppression nest eective quau commit suivant. 3.5.3 Renommer un chier

Il faut utiliser svn move :

$ svn move credits.htm merci.htm A merci.htm D credits.htm $ svn commit -m "Renommage dun fichier" Deleting credits.htm Adding merci.htm Committed revision 41.

3.6

Rsolution des conits

Les conits peuvent intervenir au moment dun update, lorsque des modications ont t faites la fois dans la copie de travail et dans le dpt. Par exemple, si vous ditez en local un chier pour lui rajouter une ligne, et quun autre utilisateur du dpt a commit entre temps une modication dirente sur le mme chier, votre commit va gnrer lerreur suivante :
$ svn commit Sending merci.htm svn: Commit failed (details follow): svn: Your file or directory merci.htm is probably out-of-date svn: The version resource does not correspond to the resource within the transaction. Either the requested version resource is out of date (needs to be updated), or the requested version resource is newer than the transaction root (restart the commit).

Il vous faut alors eectuer un update, ce qui va mettre en concurrence les deux versions du ou des chiers concerns. Deux cas de gure peuvent alors se prsenter. Dans le premier cas, le conit peut tre rsolu automatiquement par Subversion car les modications ne concernent pas les mmes parties du chier. Dans ce cas vous obtiendrez le message suivant :
$ svn update G merci.htm Updated to revision 42.

Il est quand mme conseill de vrier manuellement le rsultat de cette rsolution automatique . Dans le deuxime cas, les modications ne peuvent tre fusionnes automatiquement car elles concernent les mmes parties dun chier. Dans ce cas un conit est signal lors de lupdate :

Introduction Subversion

$ svn update C merci.htm Updated to revision 43.

Dans ce cas, deux nouveaux chiers font leur apparition dans votre copie de travail. Dans lexemple prcdent, on se retrouve avec : merci.htm.mine : copie du chier tel quil se trouvait dans votre copie de travail, en local, avant de faire lupdate. Cest la version que vous souhaitiez commiter avant de dtecter un conit ; merci.htm.r42 : version du chier pour la rvision 42, cest dire lors de votre dernier update. Cest la version qui a servi de base pour les deux utilisateurs du dpt qui ont travaill en parallle ; merci.htm.r43 : version du chier pour la revision 43, cest dire la version actuellement dans le dpt. Il sagit de la version modie par un autre utilisateur, commite avant votre update, et dont le contenu est lorigine du conit. merci.htm : il sagit dune version qui, en quelque sorte rsume les trois autres en faisant apparatre les dirences entre versions au sein dun seul chier. Ds lors, le travail consiste diter le chier merci.htm jusqu ce que le conit soit rsolu 4 . Une fois ce travail termin, on signale que le conit est rsolu laide de la commande svn resolved :
$ svn resolved merci.htm Resolved conflicted state of merci.htm

On peut alors eectuer le commit nal.

3.7

Tronc, branches, tags...

Les notions de tronc, de branches et de tags sont assez spciques aux logiciels de contrle de versions. Cest ce qui explique que les arborescences des rpertoires de projet contiennent souvent comme premier niveau de sous-rpertoires les dossiers trunk, branches et tags. En gnral, on dnit par tronc la version centrale du programme, le dveloppement principal ociel . Une branche est en gnral cre lorsquun dveloppement secondaire est mis en route, que ce soit pour ajouter une nouvelle fonctionnalit ou parce que certains dveloppeurs souhaitent essayer de prendre une autre direction pour certains aspects du dveloppement. Une branche peut, au bout dun certain temps, soit tre nouveau fusionne dans le tronc , soit disparatre, soit donner lieu un nouveau programme. La notion de tags correspond en partie celle de release, cest dire de marquage dune certaine rvision du projet comme composant une version du projet. Une fois que le dveloppement a atteint une certaine stabilit, on pourra par exemple crer un tag pour marquer la sortie de la version 1.0. Ceci permettra de revenir facilement cette version, indpendamment du numro de rvision sous-jacent correspondant.
4. Les clients graphiques proposent parfois des outils plus conviviaux pour rsoudre visuellement les conits de version. TortoiseSVN utilise le programme associ TortoiseMerge.

Introduction Subversion

Nous nentrerons pas dans le dtail de ces concepts et commandes ici, mais on peut juste citer que la cration de branches ou de tags ne sont en fait que des copies cres par la commande svn copy. La commande svn switch, elle, permet de faire passer la copie de travail dune branche une autre.

4
4.1

Outils
Aide intgre

Une aide est intgre linterface en ligne de commande. Pour obtenir de laide gnrale, et notamment la liste des commandes possibles, il sut de faire :
svn help

Pour obtenir de laide sur une commande particulire, utiliser :

svn help <nom de la commande>

4.2

Informations sur la copie de travail

Pour obtenir des informations sur la copie de travail en cours, on peut utiliser svn info :
$ svn info Path: . URL: https://cens-srv-dev1.ens-lsh.fr/svnrep/formationsvn Repository UUID: 090fa6ab-88f7-0310-b83e-cd111ae4905a Revision: 40 Node Kind: directory Schedule: normal Last Changed Author: jbarnier Last Changed Rev: 40 Last Changed Date: 2005-05-30 14:58:11 +0200 (lun, 30 mai 2005)

4.3

Voir lhistorique des modications dun chier ou projet

La commande svn log permet dacher lhistorique de toutes les modications dun chier donn en paramtre ou dun projet entier :
$ svn log index.htm -----------------------------------------------------------------------r37 | jbarnier | 2005-05-30 14:42:26 +0200 (lun, 30 mai 2005) | 2 lines Modification du titre de la page -----------------------------------------------------------------------r36 | jbarnier | 2005-05-30 14:34:05 +0200 (lun, 30 mai 2005) | 2 lines Ajout de deux fichiers de test. ------------------------------------------------------------------------

La commande svn blame permet dobtenir des informations sur un chier ligne par ligne, avec la rvision et lauteur correspondants :

Introduction Subversion

10

$ svn blame index.htm 36 jbarnier <html> 36 jbarnier <head></head> 36 jbarnier <body> 37 jbarnier <h1>Un bien beau titre, vraiment</h1> 36 jbarnier </body> 36 jbarnier </html>

4.4

Voir le statut de la copie de travail

La commande svn status permet davoir des informations sur ltat de la copie de travail depuis le dernier update :
$ svn status -v ? 40 41 40 40 jbarnier 41 jbarnier 37 jbarnier

credits.htm . merci.htm index.htm

4.5

Parcourir le dpt

La commande svn list permet dacher le contenu du dpt distance :

$ svn list https://cens-srv-dev1.ens-lsh.fr/svnrep/formationsvn index.htm merci.htm

4.6

Utiliser les proprits

Les proprits sont des attributs attachs un ou plusieurs chiers du dpt et qui permettent des comportements particuliers. Sans entrer dans le dtail, on ne citera que deux types de proprits. Tout dabord, la proprit svn :ignore permet de retirer explicitement certains chiers du contrle de version. Par exemple, si votre diteur de texte enregistre systmatiquement une copie de sauvegarde de vos chiers avec lextension .bak, il peut tre intressant de systmatiquement mettre de ct ces chiers en positionnant la proprit correspondante :
$ svn propset svn:ignore *.bak . property svn:ignore set on .

Une autre utilisation intressante concerne lutilisation de mots-cls. Ceux-ci sont des identiants insrs dans les chiers du projet et qui seront remplacs au moment du commit par des informations propres Subversion, comme le nom du chier, le numro de rvision, lauteur et la date de la dernire modication, etc. Par exemple, si vous insrez la chane $Id$ dans votre chier, celle-ci sera automatiquement remplace par un rsum de ces informations. Voici la valeur correspondant au chier source de ce document :
$Id: formation_svn.tex 135 2005-08-02 09:47:51Z julien $

Introduction Subversion

11

Pour que ces mots-cls fonctionnent, il faut positionner la proprit svn :keywords de manire adquate pour les chiers concerns :
$ svn propset svn:keywords "Id" index.htm property svn:keywords set on index.htm

5
5.1

Clients graphiques
Intrt dun client graphique

Les clients graphiques ne permettent pas de faire plus, mais proposent des interfaces plus labores que la ligne de commande. Ils permettent notamment de naviguer dans le dpt comme dans un explorateur de chiers, dacher les informations de manire plus structure, de garder un historique des logs saisis, etc. TortoiseSVN, par exemple, est un client particulirement bien intgr Windows, puisquil sajoute directement au menu contextuel de lexplorateur de chiers. Les commandes sont les mmes que celles dcrites dans ce document, mais elles sont lances par un menu et bncient dinterfaces graphiques plus conviviales.

Ressources
Site ociel de Subversion : http://subversion.tigris.org/ FAQ de Subversion : http://subversion.tigris.org/faq.html Documentation complte (en anglais) : http://svnbook.red-bean.com/ Un tutoriel en franais : http://toutprogrammer.com/print_19.html Documentation de TortoiseSVN (en anglais) : http://tortoisesvn.tigris.org/docs.html

propos de ce document

Ce document est publi sous licence Creative Commons Attribution. Vous pouvez voir une copie de cette licence ladresse http://creativecommons.org/licenses/by/2.5/. Copyright c 2005 Julien Barnier. Pour tout commentaire ou suggestion, nhsitez pas mcrire ladresse julien(at)nozav. org.