Introduction à l'utilisation de Subversion

Remarque: Cette page est une vulgarisation. Elle a pour but de donner une vision simple, sinon simpliste du fonctionnement de Subversion. Elle est approximative, et contient sûrement des erreurs. Elle est basée sur ma compréhension du fonctionnement de Subversion. J'espère ne pas trop dire de bêtises, mais si vous en voyez des grosses, n'hésitez pas à me les signaler à l'aide des commentaires.

Attention: Cette article est en cours de rédaction

J'ai du publier cette article pour des raisons pratiques, il est incomplet et contient surement quelques erreurs.

ps: oui Régis, tu as une raison de vivre, tu fait une très bonne raison pratique XD.

Principe de fonctionnement

Subversion est un outil de gestion de versions. Il autorise plusieurs personnes à travailler de concert sur un même code source, et historise les différentes évolutions validées par ces développeurs. Subversion peut être séparés en deux éléments: Le dépôt et le client.

Le dépôt

Le dépôt est ce que l'on appelle parfois le "serveur" Subversion. Il contient votre code source et son historique. Un dépôt peut être accéder par plusieurs méthodes, suivant sa configuration:

• http:// ou https:// : Subversion est associé à un serveur HTTP (Apache). C'est la méthode la plus fréquente, car elle permet de voir le contenu du dépôt à l'aide d'un navigateur Web.
• ssh:// : Cette méthode est aussi rencontrée de temps en temps. Subversion est alors associé à un serveur SSH (Secure SHell). Bien qu'elle soit plus difficile à mettre en oeuvre, elle apporte une meilleure sécurité des données que le https, et évite d'avoir un serveur Web installé sur la machine du dépôt Subversion.
• svn:// : Subversion possède son propre protocole, qui peut être activé via un serveur. Personnellement, je déconseille cette méthode, bien que je ne saurais dire pourquoi :)

Le dépôt utilise une base de donnée Bekerley (BDB pour les intimes) pour stocker les différentes versions de votre code source. A l'aide de Subversion, vous pouvez:

• Voir d'anciennes versions de votre code source.
• Annuler des modifications pour revenir à une ancienne version fonctionnelle.
• "Tagguer" les versions stables de votre projet, c'est à dire enregistrer l'état de votre code pour une version de votre logiciel.
• Et bien d'autre chose.

Subversion utilise une mécanique de "révision" pour stocker les informations de versions de votre code. Une révision correspond à un ensemble de modifications validées par un "commit". A tout moment, vous pouvez obtenir les informations associées à une révision donnée.

Le client

Le client est un outil en ligne de commande : svn. Il vous permet de manipuler le contenu de votre copie de travail ainsi que celui du dépôt Subversion. C'est aussi lui qui gère la synchronisation entre votre copie de travail et le serveur Subversion. Cette page est une présentation rapide de l'utilisation du client Subversion.

Opérations courantes

Créer une copie de travail

Vous ne pouvez directement modifier le contenu d'un dépôt Subversion. Pour travailler sur un projet, vous devez créer une copie de travail du code source de ce projet. La copie de travail est l'endroit ou vous modifiez le code du projet. Une fois le code modifié et testé, vous pouvez ajouter vos modifications au dépôt Subversion à l'aide d'un commit.

Pour créer une copie de travail à partir d'un dépôt, il vous faut utiliser la commande "checkout" ou "co" pour faire court. Pour ce faire, récupérez l'URL du dépot et exécutez :

svn co http://svn.domaine.com/monLogiciel/trunk monLogiciel

Mettre à jour une copie de travail

Il est important de synchroniser votre copie de travail avec la version présente dans le dépôt. C'est particulièrement le cas si vous travaillez en équipe avec d'autre développeurs. Pour ce faire, placez-vous à la racine de votre copie de travail et exécutez :

svn update

Subversion récupère alors les modifications présentes dans le dépôts.

Remarque: La plupart des modifications sont fondue avec vos modifications, mais dans certains cas, un conflit peut apparaitre. Vous devez alors corriger manuellement les fichiers posant problèmes (les conflits sont en général affichés entre des <<<< et >>>>).

Ajouter un fichier au dépôt

Pour ajouter un nouveau fichier au dépôt, placez-vous dans votre copie de travail et exécutez (en remplacement la valeur en gras par le chemin vers le nouveau fichier):

svn add chemin/vers/le/fichier

Faire un ajout massif de fichiers au dépôt

Si vous tenez à ajouter tous les nouveaux fichiers du dossier où vous vous trouvez au dépôt, voici une commande qui fait tout le travail à votre place :

/usr/bin/svn status | /bin/grep '?' | /bin/sed -e 's/^\?[ ]*//' | /usr/bin/xargs -iFILE /usr/bin/svn add "FILE"

Remarque : Faites attention lorsque vous utilisez cette commande. Elle ajoute tous les nouveaux fichiers au dépôt, y compris les copies de sauvegarde de gedit et les fichiers temporaires de vim.

Supprimer un fichier du dépôt

Pour supprimer un fichier présent dans le dépôt, placez-vous dans votre copie de travail, et exécutez :

svn del chemin/vers/le/fichier

Renommer ou déplacez un fichier

Pour renommer ou déplacer un fichier présent dans le dépôt, placez-vous dans votre copie de travail, et exécutez :

svn mv chemin/vers/le/fichier chemin/vers/le/nouveau/nom_fichier

Poster vos modifications

Une fois que les modifications que vous avez effectués sont fonctionnelles, vous pouvez envoyer vos changement sur le dépôt. Pour se faire, placez-vous à la racine de votre copie de travail, et exécutez la commande :

svn commit -m "Mon résumé de mes changements"

Créer un Tag de version du logiciel

Une fois que vous estimez que le "tronc" (trunk) courant est stable, vous pouvez créer un tag pour une nouvelle version de votre logiciel. Généralement, cela se fait à chaque livraison au client. Pour ce faire, exécutez la commande :

svn cp http://svn.domaine.com/monLogiciel/trunk http://svn.domaine.com/monLogiciel/tags/numero.de.version

Une convention assez courante de numérotation de version est une numérotation à 3 chiffres : 1.2.3 ou :

• 1 est le numéro de version majeur. Il change lorsque le logiciel subit de grosse modifications de fond, et n'est plus compatible avec la version précédente.
• 2 est le numéro de version mineur. Il représente l'ajout de nouvelle fonctionnalités, ou la modification d'existantes, tout en restant compatible avec la version précédente du logiciel.
• 3 est le numéro de correctif. Il représente le nombre de mise à jour correctives appliquées sur le logiciel depuis la dernière version mineure.

Afficher la liste des modifications entre 2 révisions

La commande suivante:

svn diff -r 310:304 --summarize

Affiche la liste des fichiers modifiés entre la révision 304 et la révision 310.

Utilisation avancée de Subversion

Il est possible d'aller beaucoup plus loin avec Subversion, voici une sélection des options disponibles les plus pratiques.

Utiliser la substitution de mots clefs pour mettre à jour la documentation de vos fichiers

Subversion peut remplacer des mots clefs donnés dans un ou plusieurs fichiers lors du commit. C'est très pratique pour insérer dans les fichiers certaines informations. Les mots clefs suivants sont disponibles:

• $Date$ : La date du commit.
• $Revision$ : Le numéro de la révision où le fichier a été modifié pour la dernière fois.
• $Author$: Le nom de l'auteur de la modification.
• $HeadURL$ : L'URL de la dernière version du fichier dans le dépôt Subversion.
• $Id$ : Un résumé des mots-clefs ci-dessus.

Ajouter ces mots clefs à vos fichiers ne suffit pas. Il faut activer explicitement ce réglage. Pour un fichier donné cela se fait grâce à la ligne de commande:

svn propset svn:keywords "Date Author" mon-fichier.txt

Si vous souhaitez que certains mots clefs soient substituées dans tous les fichiers que vous ajoutez au dépôt, cela peut se configurer dans le fichier ${HOME}/subversion/config. Pour ce faire, votre fichier de configuration doit resembler à :

[miscellany]
enable-auto-props = yes

[auto-props]
*.php = svn:keywords="Id Author Date"

Pour allez plus loin: je vous recommande la lecture de la section Keyword Substitution de la documentation Subversion.

Ignorer certains fichiers dans une copie de travail

Il est possible d'ignorer certains fichiers (par exemple les fichiers .pyc). Pour cela, placez-vous à la racine de votre copie de travail, puis exécuter la commande:

svn --recursive propset svn:ignore "*.pyc" ./
svn commit -m "* set ignore on *.pyc"

Pour que cette configuration s'applique à l'ensemble de vos copies de travail, éditez le fichier de configuration ${HOME}/subversion/config et dé-commenter l'option global-ignores:

global-ignores = *.o *.lo *.la *.al .libs *.so *.so.[0-9]* *.a *.pyc *.pyo
   *.rej *~ #*# .#* .*.swp .DS_Store

Ignorer les changements survenant dans certains fichiers ou dossiers

Il est possible d'ignorer les changements sur certains fichiers NE FAISANT PAS PARTIE du dépôt (par exemple, le dossier cache, le dossier des logs, ou encore le dossier d'uploads). Pour ce faire, placez-vous dans le dossier contenant le contenu que vous souhaitez ignorer, et mettez à jour de façon à être sûr que vous utilisez la dernière révision :

svn update

Puis modifiez la propriété ignore pour le dossier courant :

svn propedit svn:ignore ./

Dans l'éditeur qui s'ouvre alors, saisissez la liste des fichiers de ce dossier que vous souhaitez ignorer :

databases.yml
propel.ini

Remarque : Pour ignorer tous les changements survenant dans ce dossier, il vous suffit de saisir un joker (l'étoile) :

*

Et sauvegardez. (S'il s'agit de nano : <Ctrl> + O, puis <Ctrl> + X)

Remarque : Les fichiers ignorés ne sont plus pris en compte par le dépôt Subversion. Je vous conseille de créer une copie de ces fichiers pour les conserver dans leur version orignale. Il suffit de leur ajouter l'extension ".orig" par exemple.

Vous pouvez maintenant poster cette modification :

svn commit

Utiliser un dépôt externe à votre logiciel

Il est parfois nécessaire d'utiliser un logiciel tierce, ou alors un code qui doit être commun à plusieurs projets. Afin que la mise à jour de ce code commun ne soit pas fastidieuse, il est possible de configurer Subversion pour que la mise à jour de votre copie de travail tienne compte du dépôt du code commun.

Pour ce faire, placez vous dans le dossier de votre copie de travail ou doit se placer le code source du logiciel tiers.

Ensuite, récupérez les sources du logiciel tierce à partir de son dépôt Subversion :

svn checkout http://svn.domaine.com/maBibliothequePHP/trunk/ maBibliothequePHP

Lancez ensuite la commande :

svn propedit svn:externals ./

Et tapez :

maBibliothequePHP http://svn.domaine.com/maBibliothequePHP/trunk/

Sauvegardez. (S'il s'agit de nano : <Ctrl> + O, puis <Ctrl> + X)

N'oubliez pas de poster ces modifications :

svn commit

Changer de branche

Si vous avez créé une branche, et que vous souhaitez que votre copie de travail pointe vers cette branche, placez vous dans le dossier de votre copie de travail, et utilisez cette commande :

svn switch http://svn.mon-projet.fr/projet/branches/1.x ./

Changer le dépôt d'une copie de travail

Si votre dépôt Subversion a changé de nom de domaine, il peut être utile de changer le dépôt d'une copie de travail plutôt que d'exécuter un nouveau check-out. Pour ce faire, il vous faut utiliser la commande svn switch avec l'option relocate:

svn switch --relocate svn://svn.ancien-domaine.com/svn/projet/trunk \
                      http://svn.nouveau-projet.fr/projet/trunk

Autres fonctionnalités

Subversion dispose d'une fonctionnalité de substitution automatique qui est utile pour intégrer dans les fichiers la date de dernier commit, ainsi que le numéro de révision. Pour en savoir plus à ce sujet, lisez la page sur les Revision Specifiers.

Pour aller plus loin

Pour aller plus loin, je vous conseille de lire les pages suivantes :

• la page Subversion de Wikipedia.
• la page Subversion sur le wiki du Binet Réseau (école polytechnique).
• Merci à Particletree pour Automatically Version Your CSS and JavaScript Files.