Gestion de versions avec Subversion

Tous les logiciels de gestion de versions doivent résoudre le même problème fondamental : comment le logiciel va-t-il permettre aux utilisateurs de partager l'information, tout en les empêchant de se marcher mutuellement sur les pieds par accident ? Il est vraiment trop facile pour les utilisateurs d'écraser malencontreusement les changements effectués par d'autres dans le dépôt.

Observons le scénario décrit à la Figure 1.2, « La situation à éviter ». Supposons que nous ayons deux collaborateurs, Harry et Sally. Ils décident tous les deux d'éditer au même moment le même fichier dans le dépôt. Si Harry sauvegarde ses modifications dans le dépôt en premier, il est possible que, quelques instants plus tard, Sally les écrase avec sa propre version du fichier. Bien que la version de Harry ne soit pas perdue pour toujours, car le système se souvient de tous les changements, aucune des modifications effectuées par Harry ne sera présente dans la nouvelle version du fichier de Sally, car elle n'aura jamais vu les changements réalisés par Harry. De fait, le travail de Harry est perdu ou, du moins, perdu dans la version finale du fichier, et ceci probablement par accident. Il s'agit précisément d'une situation que nous voulons à tout prix éviter !

Figure 1.2. La situation à éviter

De nombreux logiciels de gestion de versions utilisent le modèle verrouiller-modifier-libérer pour résoudre le problème de plusieurs auteurs annihilant le travail des autres. Dans ce modèle, le dépôt ne permet qu'à une seule personne de modifier un fichier à un instant donné. Cette politique exclusive est gérée grâce à des verrous (« lock » en anglais). Harry doit « verrouiller » un fichier avant de commencer à le modifier. Si Harry a verrouillé un fichier, alors Sally ne pourra pas le verrouiller et ne pourra donc faire aucun changement dessus. Tout ce qu'elle pourra faire sera de lire le fichier et d'attendre que Harry ait fini ses changements puis libéré le verrou. Après que Harry ait libéré le fichier, Sally pourra à son tour le verrouiller et l'éditer. La Figure 1.3, « Modèle verrouiller-modifier-libérer » illustre cette solution très simple.

Figure 1.3. Modèle verrouiller-modifier-libérer

Le problème avec le modèle verrouiller-modifier-libérer est qu'il est relativement restrictif et devient souvent un barrage pour les utilisateurs :

Subversion, CVS et beaucoup d'autres logiciels de gestion de versions utilisent le modèle copier-modifier-fusionner comme alternative au verrouillage. Dans ce modèle, chaque utilisateur contacte le dépôt du projet via son client et crée une copie de travail personnelle, une sorte de version locale des fichiers et répertoires du dépôt. Les utilisateurs peuvent alors travailler, simultanément et indépendamment les uns des autres, et modifier leurs copies privées. Pour finir, les copies privées sont fusionnées au sein d'une nouvelle version finale. Le logiciel de gestion de versions fournit de l'aide afin de réaliser cette fusion, mais au final la responsabilité de s'assurer que tout se passe bien incombe à un être humain.

Voici un exemple. Supposons que Harry et Sally aient créé chacun des copies de travail du même projet, copiées à partir du dépôt. Ils travaillent simultanément et effectuent sur leur copie des modifications du même fichier A. Sally sauvegarde ses changements dans le dépôt en premier. Lorsque Harry essaie par la suite de sauvegarder ses modifications, le dépôt l'informe que son fichier A est périmé. En d'autres termes, le fichier A du dépôt a changé, d'une façon ou d'une autre, depuis la dernière fois qu'il l'avait copié. Harry demande donc à son client de fusionner tous les changements en provenance du dépôt dans sa copie de travail du fichier A. Il y a des chances que les modifications de Sally n'empiètent pas sur les siennes ; une fois qu'il a intégré les changements provenant des deux côtés, il sauvegarde sa copie de travail dans le dépôt. La Figure 1.4, « Modèle copier-modifier-fusionner » et la Figure 1.5, « Modèle copier-modifier-fusionner (suite) » illustrent ce processus.

Figure 1.4. Modèle copier-modifier-fusionner

Figure 1.5. Modèle copier-modifier-fusionner (suite)

Mais que se passe-t-il quand les modifications de Sally empiètent sur celles de Harry ? Que fait-on dans ce cas-là ? Cette situation est appelée un conflit et ne constitue pas, en général, un gros problème. Lorsque Harry demande à son logiciel client de fusionner les changements les plus récents du dépôt dans sa copie de travail, sa copie du fichier est en quelque sorte marquée comme étant dans un état de conflit : il a la possibilité de voir les deux ensembles de changements entrant en conflit et de choisir manuellement entre les deux. Notez bien qu'un logiciel ne peut pas résoudre automatiquement les conflits ; seuls les humains sont capables de comprendre et de faire les choix intelligents nécessaires. Une fois que Harry a manuellement résolu les modifications se chevauchant, par exemple après une discussion avec Sally, il peut sauvegarder le fichier fusionné en toute sécurité dans le dépôt.

Le modèle copier-modifier-fusionner peut sembler un peu chaotique mais, en pratique, il fonctionne de façon très fluide. Les utilisateurs peuvent travailler en parallèle, sans jamais devoir s'attendre les uns les autres. Lorsqu'ils travaillent sur les mêmes fichiers, il s'avère que la plupart des changements réalisés en parallèle ne se chevauchent pas du tout ; les conflits sont rares. Et le temps nécessaire à la résolution des conflits est en général bien inférieur au temps gaspillé par un système de verrouillage.

Au final, tout revient à un facteur critique : la communication entre les utilisateurs. Lorsque les utilisateurs communiquent mal, les conflits syntaxiques et sémantiques augmentent. Aucun système ne peut forcer les utilisateurs à communiquer parfaitement et aucun système ne peut détecter les conflits sémantiques. Il n'y a donc aucun intérêt à se laisser endormir par un faux sentiment de sécurité selon lequel un système de verrouillage permettrait d'éviter les conflits ; en pratique, le verrouillage semble limiter la productivité plus qu'aucun autre facteur.

Tout au long de ce livre, Subversion utilise des URL pour identifier des fichiers et des répertoires suivis en version au sein de dépôts Subversion. Pour la plupart, ces URL utilisent la syntaxe standard, permettant de spécifier les noms des serveurs et les numéros de port à l'intérieur même de l'URL :

$ svn checkout http://svn.exemple.com:9834/depot
…

Mais il existe quelques nuances dans la gestion des URL par Subversion qui doivent être notées. Par exemple, les URL ayant pour méthode d'accès file:// (utilisée pour les dépôts locaux) doivent posséder, en accord avec les conventions, soit un nom de serveur localhost , soit pas de nom de serveur du tout :

$ svn checkout file:///var/svn/depot
…
$ svn checkout file://localhost/var/svn/depot
…

D'autre part, les utilisateurs du procédé file:// sur les plateformes Windows doivent se servir d'une syntaxe qui est un « standard » officieux pour accéder à leurs dépôts se trouvant sur la même machine mais sur un disque différent du disque de travail habituel du client. Les deux syntaxes de chemin d'URL suivantes fonctionnent, X étant le disque sur lequel le dépôt se trouve :

C:\> svn checkout file:///X:/var/svn/depot
…
C:\> svn checkout "file:///X|/var/svn/depot"
…

Dans la seconde syntaxe, vous devez entourer l'URL de guillemets pour éviter que la barre verticale ne soit interprétée comme un symbole de redirection (un « pipe »). De plus, remarquez qu'une URL utilise des barres obliques (/) alors que la forme native (non-URL) d'un chemin sous Windows utilise des barres obliques inversées (\).

Note

Les URL Subversion file:// ne peuvent pas être utilisées dans un navigateur web classique de la même façon qu'une URL file:// habituelle. Lorsque vous essayez de visualiser une URL file:// dans un navigateur web classique, il lit et affiche le contenu du fichier situé à cet emplacement en interrogeant directement le système de fichiers. Cependant, les ressources de Subversion existent dans un système de fichier virtuel (cf. la section intitulée « Couche dépôt ») et votre navigateur ne comprend pas comment interagir avec ce système de fichiers.

Enfin, il faut noter que le client Subversion encode automatiquement les URL en cas de besoin, exactement comme le fait un navigateur web. Par exemple, si une URL contient un espace ou un caractère ASCII spécial, comme dans ce qui suit :

$ svn checkout "http://hote/chemin avec espace/projet/españa"

alors Subversion banalise les caractères spéciaux et se comporte comme si vous aviez tapé :

$ svn checkout http://hote/chemin%20avec%20espace/projet/espa%C3%B1a

Si l'URL contient des espaces, prenez bien soin de la placer entre guillemets, pour que votre shell traite le tout comme un unique argument du programme svn.

Vous avez déjà découvert ce que sont les copies de travail ; nous allons maintenant vous expliquer comment le client Subversion les crée et les utilise.

Une copie de travail Subversion est une arborescence classique de répertoires de votre système local, contenant un ensemble de fichiers. Vous pouvez éditer ces fichiers comme vous le voulez et, s'il s'agit de code source, vous pouvez compiler votre programme à partir de ceux-ci de la façon habituelle. Votre copie de travail est votre espace de travail personnel privé : Subversion n'y incorporera jamais les changements d'autres personnes ni ne rendra jamais disponibles vos propres changements à d'autres personnes tant que vous ne lui demanderez pas explicitement de le faire. Vous pouvez même avoir plusieurs copies de travail d'un même projet.

Après que vous ayez apporté quelques modifications aux fichiers de votre copie de travail et vérifié qu'elles fonctionnent correctement, Subversion vous fournit des commandes pour « publier » vos changements vers les autres personnes qui travaillent avec vous sur votre projet (en les transmettant au dépôt). Si d'autres personnes publient leurs propres modifications, Subversion vous fournit des commandes pour fusionner ces changements dans votre copie de travail (en les obtenant du dépôt).

Une copie de travail contient également quelques fichiers supplémentaires, créés et gérés par Subversion, pour l'aider à effectuer ces opérations. En particulier, chaque répertoire de votre copie de travail contient un sous-répertoire appelé .svn, aussi appelé répertoire administratif de votre copie de travail. Les fichiers de chacun de ces répertoires administratifs permettent à Subversion d'identifier quels fichiers contiennent des modifications non-publiées et quels fichiers sont périmés vis-à-vis du travail des autres personnes.

Un dépôt Subversion contient bien souvent les fichiers (ou code source) de plusieurs projets ; habituellement, chaque projet est un sous-répertoire de l'arborescence du système de fichiers du dépôt. Dans cette situation, la copie de travail d'un utilisateur correspond à une sous-arborescence particulière du dépôt.

Par exemple, supposons que votre dépôt contienne deux projets logiciels, paint et calc. Chaque projet réside dans son propre sous-répertoire racine, comme indiqué dans la Figure 1.6, « Système de fichiers du dépôt ».

Figure 1.6. Système de fichiers du dépôt

Pour obtenir une copie de travail, vous devez extraire une sous-arborescence du répertoire (le terme « extraire », « check out » en anglais, peut vous faire penser que cela a quelque chose à voir avec verrouiller ou réserver des ressources, mais ce n'est pas le cas ; cela crée simplement pour vous une copie privée du projet). Par exemple, si vous extrayez /calc, vous obtenez une copie de travail qui ressemble à ceci :

$ svn checkout http://svn.exemple.com/depot/calc
A    calc/Makefile
A    calc/entier.c
A    calc/bouton.c
Révision 56 extraite.

$ ls -A calc
Makefile  entier.c  bouton.c  .svn/

Les lettres A qui s'affichent dans la marge de gauche indiquent que Subversion est en train d'ajouter des éléments dans votre copie de travail. Vous avez désormais votre copie personnelle du répertoire /calc du dépôt, avec une entrée supplémentaire, .svn, qui contient des informations complémentaires nécessaires à Subversion, comme évoqué précédemment.

Supposons que vous fassiez des modifications à bouton.c. Comme le répertoire .svn se souvient de la date de modification et du contenu du fichier original, Subversion peut en déduire que vous avez modifié le fichier. Néanmoins, Subversion ne rend pas vos modifications publiques tant que vous ne lui dites pas de le faire. L'action de publication de vos modifications est plus communément appelée propagation (« commit » ou « check in » en anglais et, parfois, archivage ou livraison en français) des modifications au sein du dépôt.

Pour rendre publiques vos modifications, vous pouvez utiliser la commande Subversion svn commit :

$ svn commit bouton.c -m "Coquille corrigée dans bouton.c."
Ajout        bouton.c
Transmission des données .
Révision 57 propagée.

À présent, vos modifications de bouton.c ont été propagées au sein du dépôt, avec un commentaire décrivant ces changements (« vous avez corrigé une coquille »). Si un autre utilisateur extrait une copie de travail de /calc/, il va voir vos modifications dans la dernière version du fichier.

Supposons que vous ayez une collaboratrice, Sally, qui a extrait une copie de travail de /calc en même temps que vous. Lorsque vous propagez votre modification de bouton.c, la copie de travail de Sally reste inchangée ; Subversion ne modifie les copies de travail qu'à la demande des utilisateurs.

Pour mettre son projet à jour, Sally peut demander à Subversion de mettre à jour (« update » en anglais) sa copie de travail, en utilisant la commande svn update. Cela va intégrer vos modifications dans sa copie de travail, ainsi que celles qui ont été envoyées par d'autres personnes depuis qu'elle l'avait extraite.

$ pwd
/home/sally/calc

$ ls -A 
Makefile bouton.c entier.c .svn/ 

$ svn update
U    bouton.c
Actualisé à la révision 57.

En sortie, la commande svn update indique que Subversion a mis à jour le contenu de bouton.c. Remarquez que Sally n'a pas eu besoin de spécifier quels fichiers devaient être mis à jour ; Subversion utilise les informations contenues dans le répertoire .svn, ainsi que d'autres informations en provenance du dépôt, pour décider quels fichiers doivent être mis à jour.

Une opération svn commit publie les modifications d'un nombre quelconque de fichiers et de répertoires en une seule opération atomique. Dans votre copie de travail, vous pouvez modifier le contenu des fichiers : créer, supprimer, renommer et copier fichiers et répertoires ; puis propager un ensemble de modifications en une seule transaction atomique.

Par « transaction atomique », on entend simplement ceci : soit toutes les modifications sont propagées dans le dépôt, soit aucune ne l'est. Subversion tente de conserver cette atomicité aussi bien face à des « plantages » de programmes, de systèmes d'exploitation ou de réseau, que face aux actions des autres utilisateurs.

Chaque fois que le dépôt accepte une propagation, ceci crée un nouvel état de l'arborescence du système de fichiers, appelé révision. Un numéro unique est associé à chaque révision, correspondant au numéro de la révision précédente augmenté de 1. La révision initiale d'un dépôt fraîchement créé porte le numéro 0 et ne consiste en rien d'autre qu'un répertoire racine vide.

La Figure 1.7, « Le dépôt » offre une vue intéressante du dépôt. Imaginez un tableau de numéros de révisions, commençant à 0 et s'étirant de la gauche vers la droite. Chaque numéro de révision correspond à une arborescence de système de fichiers située en-dessous de lui et chaque arborescence est une photo, un « instantané » (« snapshot » en anglais) du dépôt prise après une propagation.

Figure 1.7. Le dépôt

Il est important de noter que les copies de travail ne correspondent pas toujours à une unique révision du dépôt ; elles peuvent contenir des fichiers provenant de plusieurs révisions différentes. Par exemple, supposons que vous extrayiez une copie de travail d'un dépôt dont la révision la plus récente est la numéro 4 :

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

À cet instant, le répertoire de travail correspond exactement à la révision 4 du dépôt. Néanmoins, supposons que vous modifiiez bouton.c et que vous propagiez cette modification. En supposant qu'aucune autre propagation n'a eu lieu, votre propagation crée la révision 5 du dépôt et votre copie de travail ressemble maintenant à ceci :

calc/Makefile:4
    entier.c:4
    bouton.c:5

Supposons maintenant qu'à ce moment précis, Sally propage une modification d'entier.c, créant la révision 6. Si vous utilisez svn update pour mettre à jour votre copie de travail, elle ressemble alors à ceci :

calc/Makefile:6
    entier.c:6
    bouton.c:6

Les modifications apportées par Sally à entier.c apparaissent dans votre copie de travail et vos modifications sont toujours présentes dans bouton.c. Dans cet exemple, le texte de Makefile est identique dans les révisions 4, 5 et 6 mais Subversion marque votre copie de travail de Makefile comme étant à la révision 6 pour indiquer qu'elle est à jour. Ainsi, quand vous effectuez une mise à jour au niveau de la racine de votre copie de travail, celle-ci correspond en général à une révision donnée du dépôt.

Pour chaque fichier d'un répertoire de travail, Subversion enregistre deux informations essentielles dans la zone administrative .svn/ :

À partir de ces informations, en dialoguant avec le dépôt, Subversion est capable de déterminer dans lequel des quatre états suivants se trouve un fichier de travail :

Tout ceci peut sembler compliqué à gérer mais la commande svn status vous indique dans quel état se trouve n'importe quel élément de votre copie de travail. Pour plus d'informations sur cette commande, référez-vous à la section intitulée « Avoir une vue d'ensemble des changements effectués ».

Un principe général de Subversion est d'être aussi flexible que possible. Un type particulier de flexibilité est la capacité d'avoir une copie de travail contenant des fichiers et des répertoires avec un mélange de différents numéros de révision. Malheureusement, cette flexibilité a tendance à embrouiller un certain nombre de nouveaux utilisateurs. Si l'exemple précédent contenant des révisions mixtes vous laisse perplexe, voici une amorce d'explication à la fois sur les raisons pour lesquelles cette fonctionnalité existe et sur la façon de l'utiliser.

La commande svn import est un moyen rapide de copier une arborescence non-suivie en versions dans le dépôt, créant des dossiers intermédiaires si nécessaire. svn import ne nécessite pas de copie de travail et vos fichiers sont immédiatement propagés dans le dépôt. Ce moyen est utilisé essentiellement quand vous avez une arborescence dont vous voulez suivre les changements dans votre dépôt Subversion. Par exemple :

$ svnadmin create /var/svn/nouveau-depot
$ svn import mon-arborescence file:///var/svn/nouveau-depot/un/projet \
             -m "Import initial"
Ajout         mon-arborescence/truc.c
Ajout         mon-arborescence/machin.c
Ajout         mon-arborescence/sous-repertoire
Ajout         mon-arborescence/sous-repertoire/bidule.h

L'exemple précédent copie le contenu du dossier mon-arborescence dans le dossier un/projet dans le dépôt :

$svn list file:///var/svn/nouveau-depot/un/projet
truc.c
machin.c
sous-repertoire/

Notez qu'après la fin de l'import, l'arborescence d'origine n'est pas transformée en copie de travail. Pour commencer à travailler, vous devez extraire grâce à svn checkout une copie de travail toute fraîche de l'arborescence.

Bien que Subversion vous permette d'organiser votre dépôt de la manière dont vous le voulez, nous vous recommandons de créer un dossier appelé trunk pour stocker la « ligne principale » du développement, un autre dossier branches qui contiendra les copies alternatives (ou branches) et un dossier tags pour les versions étiquetées. Par exemple :

$ svn list file:///var/svn/depot
/trunk
/branches
/tags

Vous en apprendrez plus sur les étiquettes et les branches dans le Chapitre 4, Gestion des branches. Pour plus de détails et pour voir comment gérer plusieurs projets, reportez-vous à la section intitulée « Agencement du dépôt », et à la section intitulée « Stratégies d'organisation d'un dépôt » pour en savoir plus sur les répertoires racines d'un projet.

Lorsque vous réalisez une opération Subversion qui nécessite une authentification, Subversion met par défaut en cache sur le disque vos éléments d'authentification. Il fait cela par commodité, pour que vous ne soyez pas obligé de ré-entrer constamment votre mot de passe pour les opérations suivantes. Si la mise en cache des mots de passe Subversion vous dérange^[4], vous pouvez désactiver la mise en cache de façon permanente ou au cas par cas.

Pour désactiver la mise en cache du mot de passe pour un appel donné d'une commande particulière, passez l'option --no-auth-cache sur la ligne de commande. Pour désactiver de façon permanente la mise en cache, vous pouvez ajouter la ligne store-passwords = no à votre fichier de configuration Subversion sur votre machine locale. Voir la section intitulée « Mise en cache des éléments d'authentification du client » pour plus de détails.

Puisque Subversion met en cache par défaut les éléments d'authentification (à la fois le nom d'utilisateur et le mot de passe), il se souvient commodément de qui vous étiez la dernière fois que vous avez modifié votre copie de travail. Mais parfois, cela n'aide pas, en particulier si vous travaillez sur une copie de travail partagée, comme par exemple un répertoire de configuration système, ou le répertoire racine des documents d'un serveur Web. Dans ce cas, il suffit de passer l'option --username à la ligne de commande et Subversion essaie alors de vous authentifier en tant que cet utilisateur, vous demandant votre mot de passe si nécessaire.

Si vous travaillez en équipe sur un projet donné, vous voulez mettre à jour votre copie locale pour recevoir toutes les modifications qui ont pu être faites par les autres développeurs du projet depuis votre dernière mise à jour. Utilisez svn update pour synchroniser votre copie de travail avec la dernière version présente dans le dépôt :

$ svn update
U  truc.c
U  machin.c
Actualisé à la révision 2.

Dans cet exemple, il se trouve que quelqu'un a apporté des modifications à truc.c ainsi qu'à machin.c depuis votre dernière mise à jour et Subversion vient de répercuter ces modifications dans votre copie de travail.

Lorsque le serveur envoie des modifications vers votre copie de travail via svn update, un code, sous forme de lettre, est affiché à coté de chaque élément pour vous permettre de savoir quelles actions Subversion a effectuées pour mettre votre copie de travail à jour. Pour en savoir plus sur le sens de ces lettres, exécutez svn help update.

Vous pouvez à présent vous mettre au travail et apporter des modifications à votre copie de travail. Il est plus commode, habituellement, de démarrer par une modification (ou un ensemble de modifications) précise, comme par exemple écrire une nouvelle fonctionnalité, corriger un bogue, etc. Les commandes Subversion dont vous vous servez pour cela sont svn add, svn delete, svn copy et svn mkdir. Cependant, si vous ne faites qu'éditer des fichiers qui sont déjà dans Subversion, vous n'avez besoin d'aucune de ces commandes jusqu'à ce que vous propagiez vos modifications.

Vous pouvez apporter deux types de modifications à votre copie de travail : des modifications de fichier et des modifications d'arborescence. Vous n'avez pas besoin de signaler à Subversion que vous allez modifier un fichier ; faites vos changements en utilisant votre éditeur de texte, un logiciel de traitement de texte, un logiciel de graphisme, ou n'importe quel autre outil que vous utilisez d'habitude. Subversion détecte automatiquement quels fichiers ont été modifiés et, en plus, il traite les fichiers binaires tout aussi facilement et tout aussi efficacement que les fichiers textes. Pour les modifications d'arborescence, vous pouvez demander à Subversion de « marquer » les fichiers et répertoires afin de programmer leur suppression, ajout, copie ou renommage. Bien que ces modifications soient immédiatement répercutées sur votre copie de travail, aucun ajout et aucune suppression ne sera répercuté sur le dépôt avant que vous ne les propagiez.

Voici un aperçu des cinq sous-commandes Subversion les plus utilisées pour faire des modifications sur l'arborescence :

Une fois vos modifications apportées, vous devez les intégrer au dépôt. Avant de le faire, il est souvent utile de jeter un coup d'œil sur ces modifications pour savoir exactement ce que vous avez changé. En examinant les modifications avant de les intégrer au dépôt, le commentaire associé à la propagation sera souvent plus pertinent. Éventuellement, vous verrez que vous avez modifié un fichier par inadvertance et cela vous donne une chance de revenir sur ces modifications avant de les propager au dépôt. En outre, c'est une bonne occasion de passer en revue et d'examiner les modifications avant de les publier. Vous pouvez obtenir une vue d'ensemble des modifications que vous avez faites en utilisant svn status et voir le détail de ces changements en utilisant svn diff.

Subversion a été optimisé pour vous aider dans cette tâche et il est capable de faire beaucoup de choses sans communiquer avec le dépôt. En particulier, votre copie de travail conserve, dans le répertoire .svn, la « copie » de l'original de chaque fichier suivi en versions. C'est pour ça que Subversion peut vous indiquer rapidement en quoi vos fichiers ont changé, ou même vous permettre d'annuler vos changements sans contacter le dépôt.

?       gribouillage.c         # le fichier n'est pas suivi en versions
A       bazar/pognon/machin.h  # le fichier sera Ajouté
C       bazar/pognon/tas.c     # le fichier entre en Conflit
                                 avec une mise à jour
D       bazar/poisson.c        # le fichier sera supprimé
                                 (Deletion en anglais)
M       truc.c                 # le contenu de truc.c a subi
                                 des Modifications

$ svn status bazar/poisson.c
D      bazar/poisson.c

$ svn status -v
M               44        23    sally     LISEZMOI
                44        30    sally     INSTALL
M               44        20    harry     truc.c
                44        18    ira       bazar
                44        35    harry     bazar/truite.c
D               44        19    ira       bazar/poisson.c
                44        21    sally     bazar/divers
A                0         ?     ?        bazar/divers/machin.h
                44        36    harry     bazar/divers/bidule.c

$ svn status -u -v
M      *        44        23    sally     LISEZMOI
M               44        20    harry     truc.c
       *        44        35    harry     bazar/truite.c
D               44        19    ira       bazar/poisson.c
A                0         ?     ?        bazar/divers/machin.h
État par rapport à la révision   46

$ svn diff
Index: truc.c
===================================================================
--- truc.c	(révision 3)
+++ truc.c	(copie de travail)
@@ -1,7 +1,12 @@
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include <stdio.h>
 int main(void) {
-  printf("Soixante-quatre tranches de fromage...\n");
+  printf("Soixante-cinq tranches de fromage...\n");
 return 0;
 }
Index: LISEZMOI
===================================================================
--- LISEZMOI	(révision 3)
+++ LISEZMOI	(copie de travail)
@@ -193,3 +193,4 @@
+Pense-bête : passer au pressing.
Index: bazar/poisson.c
===================================================================
--- bazar/poisson.c	(révision 1)
+++ bazar/poisson.c	(copie de travail)
-Bienvenue dans le fichier 'poisson'.
-Plus d'informations seront disponibles prochainement.
Index: bazar/divers/machin.h
==================================================================
--- bazar/divers/machin.h	(révision 8)
+++ bazar/divers/machin.h	(copie de travail)
+Voici un nouveau fichier pour
+écrire sur les machins.

$ svn diff > fichier-correctif

Supposons qu'en examinant la sortie de svn diff, vous vous rendiez compte que tous les changements effectués sur un fichier donné sont erronés. Peut-être auriez-vous dû laisser le fichier tel quel, ou bien peut-être qu'il serait plus facile de reprendre les changements depuis le début.

C'est l'occasion idéale pour utiliser svn revert :

$ svn revert LISEZMOI
'LISEZMOI' réinitialisé

Subversion ramène le fichier dans son état d'avant les modifications en le remplaçant par la copie de l'original stockée dans la zone .svn. Mais notez aussi que svn revert peut annuler n'importe quelle opération. Par exemple, vous pouvez décider que, après tout, vous ne voulez pas ajouter tel fichier :

$ svn status truc
?      truc

$ svn add truc
A         truc

$ svn revert truc
'truc' réinitialisé

$ svn status truc
?      truc

	Note
	svn revert element produit exactement le même effet qu'effacer element de votre copie de travail puis de lancer la commande svn update -r BASE element. Toutefois, si vous voulez revenir à une version antérieure d'un fichier, svn revert a un comportement notablement différent : il n'a pas besoin de contacter le dépôt pour restaurer le fichier.

Ou que vous avez peut-être effacé un fichier par mégarde :

$ svn status LISEZMOI

$ svn delete LISEZMOI
D         LISEZMOI

$ svn revert LISEZMOI
'LISEZMOI' réinitialisé

$ svn status LISEZMOI

Nous avons déjà vu que svn status -u est capable de prévoir les conflits. Supposons que vous lanciez svn update et que le résultat suivant apparaisse :

$ svn update
U  INSTALL
G  LISEZMOI
Conflit découvert dans 'machin.c'.
Sélectionner : (p) report, (df) diff complet, (e) édite,
        (h) aide pour plus d'options :

Les codes U et G ne doivent pas vous inquiéter, les fichiers correspondants ayant absorbé sans problème les modifications venant du dépôt. Les fichiers notés U (pour « Updated ») ne contenaient aucun changement local mais ont été mis à jour à partir de changements présents dans le dépôt. Le G (pour « merGed ») signifie fusionné, ce qui veut dire que le fichier avait subi des changements localement et que les changements en provenance du dépôt ont pu être appliqués sans affecter les changements locaux.

Mais les deux lignes suivantes font partie d'une fonctionnalité (apparue dans Subversion 1.5) appelée résolution interactive des conflits. Cela signifie que les changements du dépôt interfèrent avec les vôtres et que vous avez la possibilité de résoudre ce conflit. Les options les plus utilisées sont affichées, mais vous pouvez voir toutes les options possibles en tapant h :

…
(p)  report        - marquer ce conflit pour résolution ultérieure
(df) diff-complet  - montrer toutes les différences du fichier fusionné
(e)  édite         - résoudre manuellement le conflit avec un éditeur
(r)  résolu        - utiliser la version fusionnée
(mf) mien complet  - utiliser ma version (ignore les autres éditions)
(tf) autre complet - prendre la version du dépôt (perds mes éditions)
(l)  lance         - utiliser un outil externe pour résoudre le conflit
(h)  aide          - afficher cette liste

Regardons brièvement ce que recèle chaque option avant de les détailler :

Nous allons maintenant passer en revue chaque commande, en les classant par fonctionnalité.

…
Sélectionner : (p) report, (df) diff-complet, (e) édite,
        (h) aide pour plus d'options : d
--- .svn/text-base/sandwich.txt.svn-base      mar. 11 déc. 2007, 21:33:57
+++ .svn/tmp/tempfile.32.tmp     mar. 11 déc. 2007, 21:34:33
@@ -1 +1,5 @@
-Achète-moi un sandwich.
+<<<<<<< .mien
+Va chercher un hamburger.
+=======
+Apporte-moi un taco !
+>>>>>>> .r32
…

$ svn update
Conflit découvert dans 'sandwich.txt'.
Sélectionner : (p) report, (df) diff-complet, (e) édite,
        (h) aide pour plus d'options : d
C  sandwich.txt
Actualisé à la révision 2.
$ ls -1
sandwich.txt
sandwich.txt.mine
sandwich.txt.r1
sandwich.txt.r2

$ svn commit -m "Quelques petits ajouts"
svn: Échec de la propagation (commit), détails :
svn: Arrêt de la propagation : '/home/sally/travail-svn/sandwich.txt'
                               demeure en conflit

$ svn resolve --accept working sandwich.txt
Conflit sur 'sandwich.txt' résolu

$ cat sandwich.txt
Tranche de pain supérieure
Mayonnaise
Laitue
Tomate
Comté
<<<<<<< .mine
Saucisson
Mortadelle
Jambon
=======
Choucroute
Poulet rôti
>>>>>>> .r2
Moutarde
Tranche de pain inférieure

<<<<<<< .mine
Saucisson
Mortadelle
Jambon
=======

=======
Choucroute
Poulet rôti
>>>>>>> .r2

Tranche de pain supérieure
Mayonnaise
Laitue
Tomate
Comté
Saucisson
Mortadelle
Jambon
Moutarde
Tranche de pain inférieure

$ svn resolve --accept working sandwich.txt
Conflit sur 'sandwich.txt' résolu
$ svn commit -m "Va pour mon sandwich et au diable celui de Sally !"

$ svn update
Conflit découvert dans 'machin.c'.
Sélectionner : (p) report, (df) diff complet, (e) édite,
        (h) aide pour plus d'options :
C    sandwich.txt
Actualisé à la révision 2.
$ ls sandwich.*
sandwich.txt  sandwich.txt.mine  sandwich.txt.r2  sandwich.txt.r1
$ svn resolve --accept theirs-full sandwich.txt
Conflit sur 'sandwich.txt' résolu

$ svn revert sandwich.txt
'sandwich.txt' réinitialisé
$ ls sandwich.*
sandwich.txt

Enfin ! Vos modifications sont terminées, vous les avez fusionnées avec celles du serveur et vous êtes prêt à les propager vers le dépôt.

La commande svn commit envoie vos changements au dépôt. Quand vous propagez un changement, vous devez l'accompagner d'un message de propagation qui décrit ce changement. Votre message est associé à la nouvelle révision que vous créez. Si votre message est bref, vous pouvez le passer en ligne de commande en utilisant l'option --message (ou -m) :

$ svn commit -m "J'ai corrigé le nombre de tranches de fromage."
Envoi        sandwich.txt
Transmission des données .
Révision 3 propagée.

Cependant, si vous avez rédigé votre message au fur et à mesure, vous souhaitez sûrement indiquer à Subversion de récupérer le message dans un fichier en lui donnant le nom du fichier avec l'option --file (-F) :

$ svn commit -F message_de_propagation
Envoi        sandwich.txt
Transmission des données .
Révision 4 propagée.

Si vous ne spécifiez ni l'option --message ni l'option --file, Subversion lance automatiquement votre éditeur de texte favori (voir les détails de editor-cmd dans la section intitulée « Fichier config ») pour que vous rédigiez le message de propagation.

	Astuce
	Si, au moment où vous rédigez votre message de propagation, vous décidez d'annuler la propagation, vous n'avez qu'à quitter l'éditeur de texte sans sauvegarder les changements. Si vous avez déjà sauvegardé le message, effacez le texte, sauvegardez à nouveau puis choisissez d'annuler : $ svn commit Attente de Emacs...Fait Entrée du journal non modifié ou non précisé a)nnule, c)ontinue, e)dite a $

Le dépôt ne sait pas si vos changements ont un sens ou pas (d'ailleurs, il s'en fiche) ; il vérifie seulement que personne n'a modifié, pendant que vous aviez le dos tourné, un des fichiers que vous-même avez modifié. Si c'est le cas, la propagation toute entière échoue, affichant un message vous informant qu'un ou plusieurs de vos fichiers ne sont plus à jour :

$ svn commit -m "Ajout d'une autre règle"
Envoi        regles.txt
svn: Echec de la propagation (commit), détails :
svn: Fichier '/regles.txt' obsolète
…

Notez que le phrasé exact de ce message d'erreur dépend du protocole réseau et du serveur que vous utilisez, mais l'idée reste la même.

Maintenant, vous devez lancer svn update, traiter les fusions ou conflits qui apparaissent et retenter une propagation.

Nous en avons terminé avec le cycle d'utilisation de base de Subversion. Subversion offre beaucoup d'autres fonctionnalités pour gérer votre dépôt et votre copie de travail, mais l'utilisation quotidienne de Subversion ne requiert pratiquement que les commandes que nous venons de voir dans ce chapitre. Intéressons-nous quand même à quelques commandes supplémentaires utilisées relativement souvent.

Pour connaître l'historique d'un fichier ou d'un répertoire, utilisez la commande svn log. Elle affiche la liste des gens qui ont modifié le fichier ou le répertoire en question, le numéro de chaque révision où il a changé, l'heure et la date de cette révision et, s'il y en avait un, le message associé à la propagation :

$ svn log
------------------------------------------------------------------------
r3 | sally | 2008-05-15 23:09:28 -0500 (jeu. 15 Mai 2008) | 1 ligne

Ajout des lignes include et correction du nombre de tranches de fromage.
------------------------------------------------------------------------
r2 | harry | 2008-05-14 18:43:15 -0500 (mer. 14 Mai 2008) | 3 lignes

Ajout des méthodes main().
------------------------------------------------------------------------
r1 | sally | 2008-05-10 19:50:31 -0500 (sam. 10 Mai 2008) | 1 ligne

Import initial
------------------------------------------------------------------------

Notez que, par défaut, l'historique est affiché en ordre chronologique inverse. Si vous voulez afficher un intervalle de révisions donné dans un ordre particulier ou juste une seule révision, ajoutez l'option --revision (-r) :

$ svn log -r 5:19    # affiche l'historique a partir de la révision 5
                     # jusqu'à la révision 19 dans l'ordre chronologique

$ svn log -r 19:5    # affiche l'historique à partir de la révision 5
                     # jusqu'à la révision 19 dans l'ordre
                     # chronologique inverse

$ svn log -r 8       # affiche l'historique de la révision 8

Vous pouvez aussi afficher l'historique d'un fichier ou d'un répertoire particulier. Par exemple :

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

Ceci n'affiche le contenu de l'historique que pour les révisions dans lesquelles le fichier de travail (ou l'URL) a changé.

Si vous voulez obtenir plus d'informations sur un fichier ou un répertoire, svn log accepte également l'option --verbose (-v). Comme Subversion autorise les déplacements et les copies de répertoires et de fichiers, il est important de pouvoir tracer ces modifications de chemin dans le système de fichiers. Ainsi, en mode verbeux, svn log affiche la liste des déplacements au cours de la révision concernée :

$ svn log -r 8 -v
------------------------------------------------------------------------
r8 | sally | 2008-05-21 13:19:25 -0500 (mer. 21 Mai 2008) | 1 ligne
Chemins modifiés :
M /trunk/code/machin.c
M /trunk/code/bidule.h
A /trunk/code/doc/LISEZMOI

Machination du bidule.

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

svn log accepte aussi l'option --quiet (-q), qui permet de ne pas afficher le contenu du message de propagation. En combinaison avec --verbose, svn log n'affiche que les noms des fichiers qui ont changé.

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

Nous avons déjà vu la commande svn diff, qui affiche les différences entre fichiers au format diff unifié ; nous l'avons utilisée pour afficher les modifications locales effectuées sur notre copie de travail avant de les propager vers le dépôt.

En fait, il y a trois façons différentes d'utiliser svn diff :

$ svn diff
Index: regles.txt
===================================================================
--- regles.txt	(révision 3)
+++ regles.txt	(copie de travail)
@@ -1,4 +1,5 @@
 Être attentif envers les autres
 Liberté = Responsabilité
 Tout dans la modération
-Mâcher la bouche ouverte
+Mâcher la bouche fermée
+Écouter quand les autres parlent
$

$ svn diff -r 3 regles.txt
Index: regles.txt
===================================================================
--- regles.txt	(révision 3)
+++ regles.txt	(copie de travail)
@@ -1,4 +1,5 @@
 Être attentif envers les autres
 Liberté = Responsabilité
 Tout dans la modération
-Mâcher la bouche ouverte
+Mâcher la bouche fermée
+Écouter quand les autres parlent
$

$ svn diff -r 2:3 regles.txt
Index: regles.txt
===================================================================
--- regles.txt	(révision 2)
+++ regles.txt	(révision 3)
@@ -1,4 +1,4 @@
 Être attentif envers les autres
-Liberté = Glace Au Chocolat
+Liberté = Responsabilité
 Tout dans la modération
 Mâcher la bouche ouverte
$

$ svn diff -c 3 regles.txt
Index: regles.txt
===================================================================
--- regles.txt	(révision 2)
+++ regles.txt	(révision 3)
@@ -1,4 +1,4 @@
 Être attentif envers les autres
-Liberté = Glace Au Chocolat
+Liberté = Responsabilité
 Tout dans la modération
 Mâcher la bouche ouverte
$

$ svn diff -c 5 http://svn.exemple.com/depot/exemple/trunk/texte/regles.txt
…
$

Grâce aux commandes svn cat et svn list, vous pouvez afficher des révisions variées des fichiers et répertoires sans changer la révision de votre copie de travail. En fait, vous n'avez même pas besoin d'avoir une copie de travail pour les utiliser.

$ svn cat -r 2 regles.txt
Être attentif envers les autres
Liberté = Glace Au Chocolat
Tout dans la modération
Mâcher la bouche ouverte
$

$ svn cat -r 2 regles.txt > regles.txt.v2
$

svn list

La commande svn list liste les fichiers présents dans le dépôt sans pour autant les télécharger :

$ svn list http://svn.apache.org/repos/asf/subversion/
README
branches/
developer-resources/
mk.xiv/
site/
svn-logos/
tags/
trunk/

Si vous désirez une liste plus détaillée, passez l'option --verbose (-v) et vous obtenez alors quelque chose comme ceci :

$ svn list -v http://svn.apache.org/repos/asf/subversion/
 904709 hwright               30 janv., 03:06 ./
 880872 cmpilato         5362 16 nov., 18:49 README
 904644 danielsh              29 janv., 23:05 branches/
 861356 lgo                   27 août 2006 developer-resources/
 868798 brane                 02 janv. 2008 mk.xiv/
 904663 cmpilato              30 janv., 00:19 site/
 863801 anonymou              02 sept. 2002 svn-logos/
 901971 cmpilato              22 janv., 04:39 tags/
 904709 hwright               30 janv., 03:06 trunk/

Les colonnes vous indiquent la révision à laquelle le fichier ou le répertoire a été modifié pour la dernière fois, qui est l'auteur de ce changement, la taille du fichier si c'en est un, la date de dernière modification et le nom de l'élément.

	Avertissement
	La commande svn list sans argument prend pour cible l'URL du dépôt correspondant au répertoire local en cours, pas le répertoire en cours de la copie de travail. Après tout, si vous voulez voir le contenu de votre répertoire local, vous pouvez utiliser ls, tout simplement (ou l'équivalent sur votre système non-Unix).

En plus de toutes les commandes citées précédemment, vous pouvez utiliser svn update et svn checkout avec l'option --revision pour ramener une copie de travail complète « dans le passé » : ^[8]

$ svn checkout -r 1729 # extrait une nouvelle copie de travail
                       # à la révision r1729
…
$ svn update -r 1729 # met à jour une copie de travail existante
                     # à la révision r1729
…

Astuce

Beaucoup de nouveaux utilisateurs de Subversion essaient d'utiliser svn update comme dans l'exemple précédent pour annuler des changements propagés, mais ça ne marche pas, puisque vous ne pouvez pas propager des changements obtenus en ramenant à une vieille version une copie de travail, si les fichiers modifiés ont subi des modifications depuis. Voir la section intitulée « Résurrection des éléments effacés » pour une description de la manière d' « annuler » une propagation.

Enfin, si vous êtes en train de réaliser une version officielle et que vous voulez extraire vos fichiers de Subversion sans avoir ces satanés répertoires .svn, vous pouvez utiliser svn export pour créer une copie locale de tout ou partie de votre dépôt sans les répertoires .svn. De même que pour svn update et svn checkout, vous pouvez passer l'option --revision à svn export :

$ svn export http://svn.exemple.com/svn/depot1 # Exporte la dernière révision
…
$ svn export http://svn.exemple.com/svn/depot1 -r 1729
# Exporte la révision r1729
…

Subversion ne conserve sur le serveur aucune trace de l'état ni de l'existence des copies de travail, il n'y a donc aucun impact côté serveur si des copies de travail traînent un peu partout. De la même façon, pas besoin de prévenir le serveur quand vous effacez une copie de travail.

Si vous envisagez de réutiliser une copie de travail, ça ne pose aucun problème de la laisser sur le disque jusqu'à ce que vous soyez prêts à l'utiliser à nouveau et, le moment venu, il suffit de lancer svn update pour la mettre à jour et ainsi la rendre utilisable.

Cependant, si vous êtes certain de ne plus utiliser une copie de travail, vous pouvez la supprimer entièrement, mais vous seriez bien inspirés d'y jeter un œil au cas où des fichiers non-suivis en versions s'y trouveraient encore. Pour trouver ces fichiers, lancez svn status et examinez tous les fichiers marqués d'un ? pour vous assurer qu'ils ne sont d'aucune importance. Une fois cet examen terminé, vous pouvez supprimer votre copie de travail en toute sécurité.

Quand Subversion modifie votre copie de travail (ou toute information dans .svn), il essaie de le faire de la manière la plus sûre possible. Avant de modifier votre copie de travail, Subversion inscrit ses intentions dans un fichier de traces. Ensuite, il exécute les commandes du fichier de traces pour appliquer les modifications demandées, en plaçant un verrou sur la partie concernée de la copie de travail pendant cette opération (pour empêcher d'autres clients Subversion d'accéder à cette copie de travail au beau milieu des changements). Pour finir, Subversion supprime le fichier de traces. D'un point de vue architectural, c'est le même fonctionnement qu'un système de fichiers journalisé. Si une opération Subversion est interrompue (c'est-à-dire le processus est tué ou la machine plante), le fichier de traces reste sur le disque. En exécutant de nouveau le fichier de traces, Subversion peut terminer l'opération en cours et votre copie de travail retrouve un état cohérent.

C'est exactement ce que fait la commande svn cleanup : elle trouve et exécute les fichiers de traces restant dans votre copie de travail, en enlevant les verrous au passage. Si un beau jour Subversion vous indique qu'une partie de votre copie de travail est verrouillée (« locked » en anglais), c'est la commande qu'il faut lancer. Par ailleurs, svn status affiche un L devant les éléments verrouillés :

$ svn status
  L    un-repertoire
M      un-repertoire/machin.c

$ svn cleanup
$ svn status
M      un-repertoire/machin.c

Ne confondez pas ces verrous agissant sur la copie de travail avec les verrous ordinaires que les utilisateurs de Subversion créent quand ils utilisent le modèle de gestion de versions parallèles verrouiller-modifier-libérer ; voir l'encadré Les trois types de « verrous » pour des éclaircissements.

Le client Subversion accepte une grande variété de mots-clés de révision. En tant qu'argument de l'option --revision (-r) ces mots-clés peuvent être utilisés en lieu et place des numéros et sont remplacés par les numéros correspondants par Subversion :

Comme vous pouvez le deviner d'après leur description, les mots-clés de révision PREV, BASE et COMMITTED ne sont utilisés que pour faire référence à un chemin dans la copie de travail ; ils ne s'appliquent pas à des URL du dépôt. En revanche, HEAD peut être utilisé avec les deux types de chemin (local ou URL du dépôt).

Vous trouvez ci-dessous des exemples de l'utilisation de ces mots-clés :

$ svn diff -r PREV:COMMITTED machin.c
# affiche le dernier changement propagé concernant machin.c

$ svn log -r HEAD
# affiche le message associé à la dernière propagation dans le dépôt.

$ svn diff -r HEAD
# compare votre copie de travail (avec tous ses changements locaux)
# à la dernière version de l'arborescence correspondante du dépôt.

$ svn diff -r BASE:HEAD machin.c
# compare la version non modifiée localement de machin.c avec la dernière
# version de machin.c dans le dépôt.

$ svn log -r BASE:HEAD
# affiche, pour le répertoire suivi en versions courant, les messages
# de propagation depuis la dernière mise à jour (svn update).

$ svn update -r PREV machin.c
# revient une version en arrière pour le fichier machin.c. Ceci diminue
# de un la révision de la version de travail du fichier machin.c.

$ svn diff -r BASE:14 machin.c
# compare la version non modifiée localement de machin.c avec
# la version de ce fichier à la révision 14.

Les numéros de révision n'ont aucune signification en dehors du système de gestion de versions. Cependant, parfois, vous avez besoin d'associer une date réelle à un moment précis de l'historique des versions. À cette fin, l'option --revision (-r) accepte comme argument une date placée entre accolades ({ et }). Subversion accepte les dates et les heures aux formats définis dans le standard ISO-8601 ainsi que quelques autres formats. Voici quelques exemples (n'oubliez pas de mettre les dates qui contiennent des espaces entre guillemets) :

$ svn checkout -r {2006-02-17}
$ svn checkout -r {15:30}
$ svn checkout -r {15:30:00.200000}
$ svn checkout -r {"2006-02-17 15:30"}
$ svn checkout -r {"2006-02-17 15:30 +0230"}
$ svn checkout -r {2006-02-17T15:30}
$ svn checkout -r {2006-02-17T15:30Z}
$ svn checkout -r {2006-02-17T15:30-04:00}
$ svn checkout -r {20060217T1530}
$ svn checkout -r {20060217T1530Z}
$ svn checkout -r {20060217T1530-0500}
…

Quand vous spécifiez une date, Subversion convertit cette date vers le numéro de révision le plus récent du dépôt à la date spécifiée. Puis, il continue son travail avec ce numéro de révision :

$ svn log -r {2006-11-28}
------------------------------------------------------------------------
r12 | ira | 2006-11-27 12:31:51 -0600 (lun. 27 nov. 2006) | 6 lignes
…

Vous pouvez également utiliser des intervalles de dates. Subversion trouve alors les révisions incluses entre ces deux dates :

$ svn log -r {2006-11-20}:{2006-11-29}
…

Avertissement

Puisque l'horodatage d'une révision est stocké comme une propriété modifiable et non suivie en versions de la révision (reportez-vous à la section intitulée « Propriétés »), les horodatages peuvent être changés et ne pas refléter la chronologie réelle. Ils peuvent même être tous supprimés. Or la capacité de Subversion à convertir correctement les dates en numéros de révision dépend des horodatages de révisions et de leur ordonnancement correct dans le temps : à une révision antérieure correspond un horodatage antérieur. Si cet ordonnancement n'est pas maintenu, il y a de grandes chances que l'utilisation des dates pour spécifier des intervalles de révisions dans votre dépôt ne fournisse pas les résultats attendus.

À l'instar de Subversion, qui utilise les propriétés pour stocker des méta-données sur les fichiers, les répertoires et les révisions qu'il gère, vous pouvez faire une utilisation similaire des propriétés. Vous pouvez trouver utile d'avoir un endroit, près de vos données suivies en versions, pour stocker des méta-données relatives à vos données.

Imaginons que vous vouliez créer un site Web qui héberge beaucoup de photos et qui les affiche avec une légende et une date. D'accord, mais votre collection de photos change constamment, donc vous voulez automatiser le plus possible la gestion du site. Ces photos peuvent être relativement volumineuses et vous voulez pouvoir fournir des miniatures à vos visiteurs, comme c'est généralement le cas sur ce genre de site.

Certes, vous pouvez le faire en utilisant des fichiers traditionnels. C'est-à-dire que vous avez votre image123.jpg et une image123-thumbnail.jpg côte à côte dans un répertoire. Ou, si vous voulez garder les mêmes noms de fichier, vous placez vos miniatures dans un répertoire différent, comme thumbnails/image123.jpg. Vous pouvez également stocker vos légendes et dates de la même façon, séparées encore une fois du fichier image original. Mais le problème est que votre collection de fichiers s'agrandit de plusieurs fichiers à chaque nouvelle photo ajoutée au site.

Maintenant, considérons le même site Web conçu en utilisant les propriétés des fichiers fournies par Subversion. Imaginez un simple fichier image, image123.jpg, et un ensemble de propriétés relatives à ce fichier nommées légende, date et même miniature. À présent, le répertoire de votre copie de travail se gère beaucoup plus facilement ; en fait, vu du navigateur, il semble ne contenir que des images. Mais vos scripts d'automatisation vont plus loin : ils savent qu'ils peuvent utiliser les commandes svn (ou mieux, ils peuvent utiliser les connecteurs spécifiques au langage utilisé, voir la section intitulée « Utiliser les API ») pour extraire les informations dont votre site a besoin sans avoir à lire un fichier d'index ou à jouer avec des chemins de fichiers.

Note

Bien que Subversion n'impose que peu de restrictions sur les noms et les valeurs des propriétés, il n'a pas été conçu pour gérer de façon optimale des valeurs de propriétés de grande taille ou un grand nombre de propriétés sur un fichier ou un répertoire donné. Subversion garde souvent en mémoire en même temps tous les noms et valeurs de propriétés associés à un élément, ce qui peut engendrer des problèmes de performance lors de l'utilisation de très gros ensembles de propriétés.

On utilise également fréquemment des propriétés de révisions personnalisées. Une utilisation classique est d'avoir une propriété qui contient un identifiant en provenance d'un autre outil de gestion et de l'associer à une révision. Par exemple, l'outil de gestion est utilisé pour suivre les bogues et la révision corrige le bogue associé à l'identifiant. Il s'agit parfois aussi d'utiliser des noms plus conviviaux pour les révisions : il peut être difficile de se remémorer que la révision 1935 correspond à une révision qui a subi la totalité des tests, alors qu'une propriété resultat-des-tests avec la valeur tout ok est autrement plus utile.

Problème(s): IZ2376, IZ1919
Corrigé par:  sally

Corrige un méchant plantage dans la fonction machin bidule
…

La commande svn offre différentes possibilités pour ajouter ou modifier des propriétés sur les fichiers et les répertoires. Pour les propriétés avec des valeurs courtes, lisibles par un humain, la solution la plus simple est sûrement de spécifier le nom de la propriété et sa valeur en ligne de commande avec la sous-commande svn propset :

$ svn propset copyright '(c) 2006 Red-Bean Software' calc/bouton.c
Propriété 'copyright' définie sur 'calc/bouton.c'
$

Mais nous avons vanté la souplesse de Subversion pour spécifier les valeurs des propriétés. Ainsi, si vous envisagez d'avoir des valeurs de plusieurs lignes de texte, ou même une valeur binaire, la passer en ligne de commande ne vous convient pas. La sous-commande svn propset accepte donc l'option --file (-F) pour spécifier le nom d'un fichier qui contient la nouvelle valeur de la propriété.

$ svn propset licence -F /chemin/vers/LICENCE calc/bouton.c
Propriété 'licence' définie sur 'calc/bouton.c'
$

Il y a quelques restrictions sur les noms de propriétés. Un nom de propriété doit commencer par une lettre, le caractère deux points (:), ou le caractère souligné (_) ; ensuite, vous pouvez utiliser des chiffres, des tirets (-) et des points (.) ^[9].

En plus de la commande propset, svn dispose de la commande propedit. Cette commande utilise l'éditeur de texte pré-configuré (reportez-vous à la section intitulée « Fichier config ») pour ajouter ou modifier des propriétés. Quand vous exécutez la commande, svn lance votre éditeur de texte avec un fichier temporaire qui contient la valeur actuelle de la propriété (ou un contenu vierge si vous ajoutez une nouvelle propriété). Vous pouvez alors modifier la valeur dans l'éditeur de texte pour y placer votre nouvelle valeur, sauvegarder le fichier temporaire et quitter l'éditeur. Si Subversion détecte que la valeur a effectivement changé, il la prend en compte. Si vous quittez l'éditeur sans faire de changement, la propriété n'est pas modifiée :

$ svn propedit copyright calc/bouton.c  ### sortez de l'éditeur sans faire de modification
Pas de modification de la propriété 'copyright' sur 'calc/bouton.c'
$

Vous pouvez noter que, à l'instar des autres commandes svn, celles relatives aux propriétés fonctionnent aussi sur des chemins multiples. Vous pouvez ainsi modifier les propriétés d'un ensemble de fichiers en une seule commande. Par exemple, nous aurions pu taper :

$ svn propset copyright '(c) 2006 Red-Bean Software' calc/*
Propriété 'copyright' définie sur 'calc/Makefile'
Propriété 'copyright' définie sur 'calc/bouton.c'
Propriété 'copyright' définie sur 'calc/entier.c'
…
$

Toutes ces manipulations de propriétés ne seraient pas vraiment utiles si vous ne pouviez pas récupérer facilement la valeur d'une propriété. Subversion propose donc deux sous-commandes pour afficher les noms et les valeurs des propriétés associées aux fichiers et répertoires. La commande svn proplist fournit la liste des noms de propriétés qui existent dans un chemin. Une fois que vous connaissez les noms des propriétés d'un élément, vous pouvez obtenir les valeurs correspondantes avec la commande svn propget. Cette commande affiche sur la sortie standard la valeur de la propriété dont le nom et le chemin (ou l'ensemble des chemins) ont été passés en paramètres.

$ svn proplist calc/bouton.c
Propriétés sur 'calc/bouton.c':
  copyright
  licence
$ svn propget copyright calc/bouton.c
(c) 2006 Red-Bean Software
$

Il y a même une variante de la commande proplist qui liste à la fois le nom et la valeur de toutes les propriétés. Ajoutez simplement l'option --verbose (-v) à la commande :

$ svn proplist -v calc/bouton.c
Propriétés sur 'calc/bouton.c':
  copyright : (c) 2006 Red-Bean Software
  license : ================================================================
Copyright (c) 2006 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.
…

La dernière sous-commande relative aux propriétés est propdel. Puisque Subversion vous autorise à stocker des propriétés avec une valeur vide, vous ne pouvez pas supprimer une propriété en utilisant svn propedit ou svn propset. Par exemple, la commande suivante ne fournit pas le résultat escompté :

$ svn propset licence calc/bouton.c
Propriété 'licence' définie sur 'calc/bouton.c'
$ svn proplist -v calc/bouton.c
Propriétés sur 'calc/bouton.c':
  copyright : (c) 2006 Red-Bean Software
  licence :
$

Vous devez utiliser la sous-commande propdel pour supprimer complètement une propriété. La syntaxe est similaire aux autres commandes sur les propriétés :

$ svn propdel license calc/bouton.c
Propriété 'licence' supprimée de 'calc/bouton.c'.
$ svn proplist -v calc/bouton.c
Propriétés sur 'calc/bouton.c':
  copyright : (c) 2006 Red-Bean Software
$

Vous souvenez-vous des propriétés de révision non suivies en versions ? Vous pouvez les modifier elles-aussi en utilisant les mêmes sous-commandes svn que nous venons de décrire. Il suffit juste d'ajouter l'option --revprop à la ligne de commande et de spécifier la révision à laquelle s'applique la modification. Puisque les numéros de révisions s'appliquent à l'ensemble de l'arborescence, vous n'avez pas besoin d'indiquer un chemin pour ces commandes, du moment que vous êtes dans une copie de travail du dépôt contenant la révision dont vous voulez modifier la propriété. Autrement, vous pouvez simplement fournir n'importe quelle URL du dépôt en question (y compris l'URL racine). Par exemple, imaginons que vous vouliez remplacer le message associé à la propagation d'une révision précédente ^[10]. Si le répertoire actuel fait partie de votre copie de travail du dépôt, vous pouvez simplement lancer la commande svn propset sans spécifier de chemin :

$ svn propset svn:log '* bouton.c: Corrige un avertissement du compilateur.' -r11 --revprop
Nouvelle valeur définie pour la propriété 'svn:log' à la révision du dépôt '11'
$

Et même si vous n'avez pas extrait de copie de travail du dépôt, vous pouvez toujours modifier la propriété en indiquant l'URL racine du dépôt :

$ svn propset svn:log '* bouton.c: Corrige un avertissement du compilateur.' -r11 --revprop \
              http://svn.exemple.com/depot/projet
Nouvelle valeur définie pour la propriété 'svn:log' à la révision du dépôt '11'
$

Notez que le droit de modifier cette propriété non suivie en versions doit être explicitement ajouté par l'administrateur du dépôt (voir la section intitulée « Correction des messages de propagation »). En effet, la propriété n'étant pas suivie en versions, vous risquez une perte d'informations si vous la modifiez à tort et à travers. L'administrateur du dépôt peut mettre en place des protections contre ce type d'incident et, par défaut, la modification de propriétés non suivies en versions est désactivée.

Astuce

Dans la mesure du possible, il est recommandé d'utiliser svn propedit au lieu de svn propset. Bien que le résultat soit identique, la première permet de visualiser la valeur actuelle de la propriété que l'on veut modifier, ce qui aide à vérifier que l'on fait bien ce que l'on pense faire. C'est particulièrement vrai dans le cas des propriétés non suivies en versions. Il est aussi beaucoup plus facile de modifier un texte de plusieurs lignes dans un éditeur de texte qu'en ligne de commande.

Maintenant que vous êtes familier avec toutes les sous-commandes svn relatives aux propriétés, voyons comment la modification des propriétés change le cycle habituel d'utilisation de Subversion. Comme mentionné précédemment, les propriétés des fichiers et répertoires sont suivies en versions, à l'instar du contenu des fichiers. En conséquence, Subversion offre les mêmes possibilités pour fusionner (proprement ou quand apparaissent des conflits) vos modifications avec celles des autres collaborateurs.

De même que pour le contenu des fichiers, les modifications de propriétés sont locales. Elles ne deviennent permanentes que quand vous les propagez dans le dépôt via svn commit. Vos modifications sur les propriétés peuvent aussi être annulées facilement : la commande svn revert restaure vos fichiers et répertoires dans leur état d'avant les modifications, y compris pour les propriétés. Vous pouvez également obtenir des informations intéressantes sur l'état des propriétés de vos fichiers et répertoires en utilisant les commandes svn status et svn diff.

$ svn status calc/bouton.c
 M     calc/bouton.c
$ svn diff calc/bouton.c
Modification de propriétés sur calc/bouton.c
___________________________________________________________________
Ajouté: copyright
   + (c) 2006 Red-Bean Software

$

Remarquez que la sous-commande status place le M dans la deuxième colonne plutôt que dans la première. C'est parce que nous avons modifié les propriétés de calc/bouton.c, mais pas son contenu. Si nous avions changé les deux, nous aurions vu le M dans la première colonne également (reportez-vous à la section intitulée « Avoir une vue d'ensemble des changements effectués »).

% svn update calc
M  calc/Makefile.in
 C calc/bouton.c
À la révision 143.
$

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

Vous avez peut-être remarqué que Subversion affiche les différences au niveau des propriétés d'une manière non standard. Certes, vous pouvez toujours rediriger la sortie de svn diff pour créer un fichier correctif utilisable : le programme patch ignore ce qui concerne les propriétés (comme il ignore tout ce qu'il ne comprend pas). Malheureusement, cela signifie aussi que pour appliquer intégralement un correctif généré par svn diff, les modifications concernant les propriétés doivent être faites à la main.

Les propriétés constituent une fonctionnalité très puissante de Subversion et sont un élément central de nombreuses fonctionnalités de Subversion présentées ailleurs dans ce chapitre ainsi que dans les autres chapitres : comparaisons et fusions textuelles, substitution de mots-clés, transformation des retours à la ligne, etc. Mais pour profiter pleinement des propriétés, il faut les placer sur les répertoires et fichiers adéquats. Malheureusement, cette étape peut passer à la trappe dans le train-train quotidien, d'autant plus qu'oublier de configurer une propriété n'engendre généralement pas une erreur qui saute aux yeux (du moins comparativement à oublier d'ajouter un fichier dans la gestion de versions). Pour vous aider à placer vos propriétés au bon endroit, Subversion propose deux fonctionnalités simples mais néanmoins utiles.

Au moment d'introduire un fichier en suivi de versions à l'aide de la commande svn add ou svn import, Subversion essaie de vous aider en configurant automatiquement certaines propriétés communes des fichiers. D'abord, sur les systèmes d'exploitation dont le système de fichiers utilise un bit « exécutable », Subversion ajoute automatiquement la propriété svn:executable aux nouveaux fichiers, ajoutés ou importés, qui ont ce bit activé (voir la section intitulée « Fichiers exécutables ou non » pour plus de détails sur cette propriété).

Ensuite, Subversion essaie de déterminer le type MIME du fichier. Si vous avez configuré le paramètre mime-types-files, Subversion essaie de trouver un type MIME correspondant à l'extension du nom de fichier. Si un tel type MIME existe, il définit automatiquement la propriété svn:mime-type avec la valeur du type trouvé. S'il ne trouve pas de type MIME correspondant ou s'il n'existe pas de fichier définissant les correspondances, Subversion applique une heuristique très basique pour déterminer si le contenu du fichier est lisible par un humain. Si le résultat est négatif, Subversion ajoute automatiquement la propriété svn:mime-type à ce fichier avec la valeur application/octet-stream (type MIME générique indiquant « une suite d'octets »). Bien sûr, si Subversion se trompe ou si vous voulez indiquer un type plus précis (par exemple image/png ou application/x-shockwave-flash), vous pouvez toujours supprimer ou modifier cette propriété (pour d'avantage d'informations sur la gestion des types MIME par Subversion, reportez-vous à la section intitulée « Type de contenu des fichiers » plus loin dans ce chapitre).

Subversion fournit également, via sa zone de configuration (voir la section intitulée « Zone de configuration des exécutables »), une fonction de renseignement automatique des propriétés, plus flexible, qui vous permet de créer des associations entre, d'une part, des motifs de noms de fichiers et, d'autre part, des noms de propriétés / valeurs de propriétés. Là encore, ces associations modifient le comportement des commandes add et import, pouvant non seulement passer outre la décision prise par défaut d'attribution d'une propriété de type MIME mais pouvant aussi définir d'autres propriétés, qu'elles soient utilisées par Subversion ou personnalisées. Par exemple, vous pouvez créer une association qui, à chaque ajout d'un fichier JPEG (c'est-à-dire dont le nom est du type *.jpg), fixe la propriété svn:mime-type de ce fichier à la valeur image/jpeg. Ou alors affecte à tout fichier de type *.cpp la propriété svn:eol-style avec la valeur native et la propriété svn:keywords avec la valeur Id. L'affectation automatique de propriétés est sûrement l'outil de manipulation des propriétés le plus commode de tout Subversion. Reportez-vous à la section intitulée « Fichier config » pour plus d'informations sur la configuration de cette fonction.

Subversion fait partie des nombreuses applications qui reconnaissent et utilisent les types MIME (Multipurpose Internet Mail Extensions). Ainsi, la valeur de la propriété svn:mime-type permet, en plus de stocker le type de contenu d'un fichier, de changer le comportement de Subversion lui-même.

Par exemple, un avantage fourni par cette reconnaissance de type par Subversion est la possibilité de fusion contextuelle, ligne par ligne, des changements reçus lors d'une mise à jour. En revanche, pour les fichiers contenant autre chose que du texte, il n'y a souvent pas de concept de « ligne ». En conséquence, pour les fichiers suivis en versions dont la propriété svn:mime-type contient une valeur de type MIME non textuel (généralement un intitulé qui ne commence pas par text/, bien qu'il y ait des exceptions), Subversion ne tente pas de fusion contextuelle pendant la mise à jour. À la place, chaque fois que vous avez modifié localement un fichier binaire qui a été mis à jour sur le dépôt, Subversion ne touche pas à votre fichier mais crée deux nouveaux fichiers. Un fichier avec l'extension .oldrev qui contient la version du fichier à la révision BASE. Un autre fichier avec l'extension .newrev qui contient la version à jour du fichier. Ce comportement est dicté par la volonté d'éviter que l'utilisateur ne tente d'effectuer une fusion qui échouerait parce que les fichiers ne peuvent tout simplement pas être fusionnés.

Avertissement

La propriété svn:mime-type, si elle n'est pas correctement définie à une valeur qui indique un contenu non textuel, peut causer des comportements inattendus. Par exemple, comme la « fin de ligne » n'a pas de sens dans un fichier binaire, Subversion vous empêche de définir la propriété svn:eol-style sur ces fichiers. Cela saute aux yeux quand vous travaillez sur un seul fichier et que svn propset génère une erreur. C'est beaucoup moins évident si vous effectuez une opération récursive, où Subversion omet silencieusement les fichiers qu'il considère inappropriés pour une propriété donnée.

Depuis Subversion 1.5, les utilisateurs peuvent configurer un nouveau paramètre mime-types-file dans la zone de configuration qui identifie un fichier de correspondance des types MIME. Subversion consulte ce fichier pour déterminer le type MIME de tout nouveau fichier ajouté ou importé.

Par ailleurs, si la propriété svn:mime-type est définie, alors le greffon Apache pour Subversion utilise cette valeur pour renseigner le champ Content-type: de l'en-tête HTTP en réponse à une requête GET. Cela fournit au navigateur Web une indication très importante pour pouvoir afficher correctement le fichier, quand vous l'utilisez pour parcourir le contenu du dépôt Subversion.

Sur beaucoup de systèmes d'exploitation, la capacité de rendre un fichier exécutable dépend d'un bit dit « exécutable ». Habituellement, ce bit est désactivé par défaut et doit être explicitement activé par l'utilisateur pour chaque fichier concerné. Ce serait une perte de temps énorme d'avoir à se rappeler exactement quel fichier, parmi ceux que l'on vient d'extraire du dépôt, doit avoir le bit exécutable positionné et ensuite de devoir le faire manuellement. C'est pourquoi Subversion fournit la propriété svn:executable pour spécifier que le bit exécutable doit être activé pour le fichier concerné. Subversion s'occupe lui-même de cette tâche quand il rapatrie de tels fichiers dans la copie de travail locale.

Cette propriété n'a aucun effet sur les systèmes de fichiers qui ne possèdent pas le concept du bit exécutable, tels que FAT32 et NTFS ^[12]. Par ailleurs, bien qu'elle n'ait pas de valeurs définies, Subversion lui attribue la valeur * lorsqu'il active cette propriété. Enfin, cette propriété n'est valide que sur des fichiers, pas sur des répertoires.

Pour tout fichier suivi en versions, Subversion considère que le contenu est lisible par un humain sauf si la propriété svn:mime-type indique le contraire. En règle générale, Subversion utilise cette information pour déterminer s'il est possible d'effectuer une comparaison contextuelle pour ce fichier. Sinon, pour Subversion, les octets sont des octets.

Cela veut dire que par défaut, Subversion ne s'intéresse pas au type de caractère utilisé pour marquer les fins de lignes (« EOL » en anglais, pour « End Of Line »). Malheureusement, des conventions différentes sont utilisées suivant les systèmes d'exploitation pour indiquer une fin de ligne de texte dans un fichier. Par exemple, les logiciels sous Windows utilisent généralement une paire de caractères de contrôle ASCII : un retour chariot (CR, « carriage return ») suivi par un saut de ligne (LF, « line feed »). Les logiciels Unix, cependant, utilisent uniquement le caractère LF pour indiquer les fins de lignes.

Tous les programmes ne savent pas gérer les fichiers utilisant un marqueur de fin de ligne « exogène » au système d'exploitation sur lequel ils tournent. Ainsi, il n'est pas rare de voir les programmes Unix traiter le marqueur CR des fichiers Windows comme un caractère normal (en affichant à l'écran un ^M) et les programmes Windows combiner en une seule ligne immense un fichier Unix parce qu'ils n'y ont pas trouvé la combinaison retour chariot-passage à la ligne (CR-LF).

Cette incapacité de traiter correctement les marqueurs de fin de ligne d'autres plateformes peut être assez frustrante pour ceux qui partagent des fichiers entre différents systèmes d'exploitation. Prenons l'exemple d'un fichier de code source qui est édité par des développeurs à la fois sous Windows et sous Unix. Si tous les développeurs utilisent des outils qui se plient à la convention utilisée par le fichier, pas de problème.

Mais, en pratique, de nombreux outils largement utilisés soit ne parviennent pas à lire correctement un fichier utilisant une convention différente pour les fins de ligne, soit ils convertissent les fins de lignes au format local lors de la sauvegarde. Dans le premier cas, le développeur doit utiliser des outils externes (tels que dos2unix et son compagnon unix2dos) pour préparer le fichier avant l'édition. Dans le deuxième cas, pas besoin de préparation. Mais dans les deux cas, le fichier résultant diffère de l'original littéralement pour toutes les lignes ! Avant de propager ses changements, l'utilisateur a deux choix. Soit il utilise un utilitaire de conversion pour revenir à la même convention qu'avant l'édition. Soit il propage le fichier avec la nouvelle convention de fin de ligne.

Au final, les deux hypothèses conduisent à une perte de temps et des modifications inutiles sur les fichiers propagés. La perte de temps est déjà pénible. Mais si en plus la propagation change chaque ligne du fichier, trouver quelle ligne a effectivement changé devient non trivial. À quel endroit ce bogue a-t-il réellement été corrigé ? Dans quelle ligne y avait-il cette erreur de syntaxe ?

La solution à ce problème est la propriété svn:eol-style (eol pour "End Of Line"). Quand cette propriété possède une valeur valide, Subversion l'utilise pour déterminer quel traitement il doit appliquer pour que le fichier ne change pas de convention à chaque propagation provenant d'un système d'exploitation différent. Les valeurs valides sont :

Dans un dépôt Subversion, un verrou est une méta-donnée qui alloue à un utilisateur un accès exclusif en écriture sur un fichier. Cet utilisateur est appelé détenteur du verrou. Chaque verrou possède également un identifiant unique, en général une longue chaîne de caractères, appelé jeton de verrouillage. Le dépôt gère les verrous en assurant in fine leur création, leur application et leur suppression. Si une propagation tente de modifier ou effacer un fichier verrouillé (ou effacer un répertoire parent dudit fichier), le dépôt demande deux informations : que le client effectuant la propagation s'authentifie en tant que détenteur du verrou et que le jeton de verrouillage soit fourni lors de la procédure de propagation afin de montrer que le client sait bien quel verrou il utilise.

Pour illustrer la création d'un verrou, reprenons notre exemple de graphistes travaillant sur les même fichiers image binaires. Harry a décidé de changer cette image JPEG. Pour interdire aux autres collaborateurs d'effectuer des changements sur le fichier pendant qu'il le modifie (et pour les avertir qu'il va modifier ce fichier), il verrouille le fichier dans le dépôt en utilisant la commande svn lock :

$ svn lock banane.jpg -m "Édition du fichier pour la livraison de demain."
'banane.jpg' verrouillé par l'utilisateur 'harry'.
$

Il y a plusieurs points intéressants dans l'exemple ci-dessus : d'abord, notez que Harry utilise l'option --message (-m) de svn lock. Comme svn commit, la commande svn lock accepte des commentaires (soit via --message (-m), soit via --file (-F)) pour indiquer la raison du verrouillage du fichier. En revanche, contrairement à svn commit, svn lock n'exige pas automatiquement un message en lançant votre éditeur de texte préféré. Les commentaires de verrouillage sont optionnels, mais néanmoins recommandés pour faciliter la communication entre collaborateurs.

Ensuite, la tentative de verrouillage a réussi. Cela signifie que le fichier n'était pas préalablement verrouillé et que Harry disposait de la dernière version du fichier. Si la copie de travail de Harry avait été obsolète, le dépôt aurait refusé la demande, forçant Harry à effectuer une mise à jour (svn update) et à relancer ensuite la commande de verrouillage. La commande de verrouillage aurait également échoué si le fichier avait déjà été verrouillé par quelqu'un d'autre.

Comme vous pouvez le constater, la commande svn lock affiche la confirmation que le verrouillage a réussi. Dès lors, le verrouillage du fichier apparaît dans le résultat des commandes svn status et svn info :

$ svn status
     K banane.jpg

$ svn info banane.jpg
Chemin : banane.jpg
Nom : banane.jpg
URL : http://svn.exemple.com/depot/projet/banane.jpg
Racine du dépôt : http://svn.exemple.com/depot
UUID du dépôt : edb2f264-5ef2-0310-a47a-87b0ce17a8ec
Revision: 2198
Type de nœud : file
Tâche programmée : normale
Auteur de la dernière modification : frank
Révision de la dernière modification : 1950
Date de la dernière modification : 2006-03-15 12:43:04 -0600 (mer. 15 mars 2006)
Texte mis à jour : 2006-06-08 19:23:07 -0500 (jeu. 08 juin 2006)
Propriétés mis à jour : 2006-06-08 19:23:07 -0500 (jeu. 08 juin 2006)
Somme de contrôle: 3b110d3b10638f5d1f4fe0f436a5a2a5
Nom de verrou : opaquelocktoken:0c0f600b-88f9-0310-9e48-355b44d4a58e
Propriétaire du verrou : harry
Verrou créé : 2006-06-14 17:20:31 -0500 (mer. 14 juin 2006)
Commentaire du verrou (1 ligne):
Édition du fichier pour la livraison de demain.

$

Le fait que la commande svn info, qui ne contacte pas le dépôt quand elle porte sur un chemin d'une copie de travail, affiche bien le jeton de verrouillage, révèle une caractéristique importante des jetons de verrouillage : ils sont intégrés dans la copie de travail. La présence du jeton de verrouillage est primordiale. Il authorise la copie de travail à utiliser le verrou ultérieurement. Par ailleurs, la commande svn status affiche un K (raccourci pour « locKed » — « verrouillé » en anglais) avant le nom du fichier, indiquant que le jeton de verrouillage est présent.

Maintenant que Harry a verrouillé banane.jpg, Sally ne peut ni modifier ni effacer ce fichier :

$ svn delete banane.jpg
D         banane.jpg
$ svn commit -m "Suppression des fichiers inutiles."
Suppression    banane.jpg
svn: Échec de la propagation (commit), (détails):
svn: Suppression de
'/depot/projet/!svn/wrk/64bad3a9-96f9-0310-818a-df4224ddc35d/banane.jpg':
423 Verrouillé (http://svn.exemple.com)
$

Mais Harry, après avoir fait ses retouches sur sa belle banane jaune, peut propager ses changements sur le fichier. C'est parce qu'il s'authentifie en tant que détenteur du verrou et aussi parce que sa copie de travail possède le bon jeton de verrouillage :

$ svn status
M    K banane.jpg
$ svn commit -m "Rendu la banane plus jaune."
Envoi        banane.jpg
Transmission des données .
Révision 2201 propagée.
$ svn status
$

Notez qu'après que la propagation est terminée, svn status permet de voir que le jeton de verrouillage n'est plus présent dans la copie de travail. C'est le comportement normal de svn commit : elle recherche dans la copie de travail (ou dans une liste de cibles, si vous fournissez une telle liste) les modifications effectuées localement et elle envoie les jetons de verrouillage qu'elle trouve durant sa recherche au serveur, en tant que partie intégrante du processus de propagation. Après que la propagation a réussi, tous les verrous du dépôt qui ont été mentionnés sont libérés, même ceux pour lesquels les fichiers n'ont pas été propagés. Ce comportement a pour but de dissuader les utilisateurs d'être négligents avec leurs verrous ou de garder des verrous trop longtemps. Si Harry verrouille au hasard trente fichiers dans un répertoire nommé Images parce qu'il n'est pas sûr de savoir quels fichiers il doit modifier et qu'il ne modifie finalement que quatre fichiers, alors quand il lance la commande svn commit Images, la procédure libère les trente verrous.

Ce mode de fonctionnement (libérer automatiquement les verrous) peut être modifié avec l'option --no-unlock de svn commit. C'est utile quand vous voulez propager des changements mais que vous prévoyez d'effectuer des changements supplémentaires et que donc vous avez toujours besoin des verrous. Vous pouvez également en faire le fonctionnement par défaut en réglant l'option no-unlock dans la zone de configuration (voir la section intitulée « Zone de configuration des exécutables »).

Bien sûr, verrouiller un fichier n'oblige pas l'utilisateur à le modifier. Le verrou peut être libéré n'importe quand avec la commande svn unlock :

$ svn unlock banane.c
'banane.c' déverrouillé.

Quand une propagation échoue parce que quelqu'un d'autre a posé un verrou, il est facile de savoir pourquoi. La commande la plus simple est svn status --show-updates:

$ svn status -u
M              23   truc.c
M    O         32   raisin.jpg
       *       72   machin.h
État par rapport à la révision      105
$

Dans cet exemple, Sally peut voir que non seulement sa copie de travail de machin.h n'est plus à jour, mais aussi qu'un des deux fichiers qu'elle prévoie de propager est verrouillé dans le dépôt. La lettre O (« Others » — « autres » en anglais) indique qu'un verrou existe sur ce fichier et qu'il a été créé par quelqu'un d'autre. Si elle essayait de lancer svn commit, le verrou sur raisin.jpg l'en empêcherait. Sally est laissée dans l'expectative de savoir qui a posé le verrou, quand et pourquoi. Là encore, svn info trouve la réponse :

$ svn info http://svn.exemple.com/depot/projet/raisin.jpg
Chemin : raisin.jpg
Nom : raisin.jpg
URL: http://svn.exemple.com/depot/projet/raisin.jpg
UUID du dépôt : edb2f264-5ef2-0310-a47a-87b0ce17a8ec
Révision: 105
Type de nœud : file
Auteur de la dernière modification : sally
Révision de la dernière modification : 32
Texte mis à jour : 2006-01-25 12:43:04 -0600 (Sun, 25 Jan 2006)
Nom de verrou : opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
Propriétaire du verrou : harry
Verrou créé : 2006-02-16 13:29:18 -0500 (jeu. 16 févr. 2006)
Commentaire du verrou (1 ligne):
Besoin de faire une retouche rapide sur cette image.
$

De la même manière que svn info peut être utilisée pour examiner les objets de la copie de travail, elle peut être utilisée pour examiner les objets du dépôt. Si l'argument principal de svn info est un chemin de la copie de travail, alors toutes les informations stockées localement sont affichées ; toute mention d'un verrou signifie que la copie de travail détient un jeton de verrouillage (si le fichier est verrouillé par un autre utilisateur ou depuis une autre copie de travail, alors lancer svn info sur la copie de travail ne renvoit aucune information relative au verrou). Si l'argument principal de svn info est une URL, alors les informations affichées se rapportent à la dernière version de l'objet dans le dépôt et toute mention d'un verrou concerne le verrou en cours sur l'objet.

Ainsi, dans notre exemple, Sally peut voir que Harry a verrouillé le fichier le 16 février pour effectuer une « retouche rapide ». Comme nous sommes en juin, elle suspecte qu'il a probablement oublié le verrou. Elle pourrait téléphoner à Harry pour le lui signaler et lui demander de libérer le verrou. S'il n'est pas joignable, elle peut toujours essayer de forcer le verrou elle-même, ou demander à un administrateur de le faire.

Un verrou n'est pas quelque chose de sacré : dans la configuration par défaut de Subversion, les verrous peuvent être libérés non seulement par leur détenteur, mais aussi par n'importe qui d'autre. Quand quelqu'un d'autre que le détenteur d'un verrou le libère, nous appelons ça casser le verrou.

Avec un statut d'administrateur, il est facile de casser un verrou. Les programmes svnlook et svnadmin peuvent afficher et casser les verrous directement dans le dépôt (pour plus d'informations sur ces outils, reportez-vous à la section intitulée « Boîte à outils de l'administrateur »).

$ svnadmin lslocks /usr/local/svn/depot
Chemin : /projet2/images/banane.jpg
Chaîne UUID : opaquelocktoken:c32b4d88-e8fb-2310-abb3-153ff1236923
Propriétaire : frank
Créé : 2006-06-15 13:29:18 -0500 (jeu. 15 juin 2006)
Expire :
Commentaire (1 ligne):
J'améliore encore la couleur jaune.

Chemin : /projet/raisin.jpg
Chaîne UUID : opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
Propriétaire : harry
Créé : 2006-02-16 13:29:18 -0500 (jeu. 16 fév. 2006)
Expire :
Commentaire (1 ligne):
Besoin de faire une retouche rapide sur cette image.

$ svnadmin rmlocks /usr/local/svn/depot/projet/raisin.jpg
'/projet/raisin.jpg' déverrouillé
$

L'option la plus intéressante est celle qui permet aux utilisateurs de casser les verrous détenus par d'autres personnes à travers le réseau. Pour ce faire, Sally doit simplement ajouter l'option --force à la commande svn unlock :

$ svn status -u
M              23   truc.c
M    O         32   raisin.jpg
       *       72   machin.h
État par rapport à la révision     105
$ svn unlock raisin.jpg
svn: 'raisin.jpg' n'est pas verrouillé dans cette copie de travail
$ svn info raisin.jpg | grep URL
URL: http://svn.exemple.com/depot/projet/raisin.jpg
$ svn unlock http://svn.exemple.com/depot/projet/raisin.jpg
svn: Unlock request failed: 403 Forbidden (http://svn.exemple.com)
$ svn unlock --force http://svn.exemple.com/depot/projet/raisin.jpg
'raisin.jpg' déverrouillé.
$

Ainsi, la tentative initiale de Sally pour libérer le verrou a échoué parce qu'elle a lancé svn unlock directement sur le fichier de sa copie de travail, où aucun jeton de verrouillage n'était présent. Pour casser le verrou directement dans le dépôt, elle doit passer une URL à svn unlock. Son premier essai pour casser le verrou avec l'URL échoue car elle ne peut pas s'authentifier comme détentrice du verrou (et elle n'a pas non plus le jeton de verrouillage). Mais quand elle passe l'option --force, les pré-requis d'authentification et d'autorisation sont ignorés et le verrou est cassé.

Casser le verrou peut ne pas être suffisant. Dans l'exemple, Sally ne veut pas seulement casser le verrou oublié par Harry, mais également re-verrouiller le fichier pour son propre usage. Elle peut le faire en lançant svn unlock avec l'option --force puis svn lock à la suite, mais il existe une petite chance que quelqu'un d'autre verrouille le fichier entre les deux commandes. La meilleure solution est donc de voler le verrou, ce qui implique de casser et re-verrouiller le fichier en une seule opération atomique. Pour ce faire, Sally passe l'option --force à la commande svn lock :

$ svn lock raisin.jpg
svn: avertissement : Échec de la demande de verrou : 423 verrouillé (http://svn.exemple.com)
$ svn lock --force raisin.jpg
'raisin.jpg' verrouillé par l'utilisateur 'sally'.
$

Dans tous les cas, que le verrou soit cassé ou volé, Harry est bon pour une bonne surprise. La copie de travail de Harry contient toujours le jeton de verrouillage original, mais le verrou n'existe plus. Le jeton de verrouillage est dit défunt. Le verrou associé au jeton de verrouillage a été soit cassé (il n'existe plus dans le dépôt) soit volé (remplacé par un autre verrou). Quoi qu'il en soit, Harry peut voir ce qu'il en est en demandant à svn status de contacter le dépôt :

$ svn status
     K raisin.jpg
$ svn status -u
     B         32   raisin.jpg
$ svn update
  B  raisin.jpg
$ svn status
$

Si le verrou dans le dépôt a été cassé, alors svn status --show-updates affiche un B (pour « Broken » — « cassé » en anglais) à côté du fichier. Si un nouveau verrou existe en lieu et place de l'ancien, alors un T (pour « sTolen » — « volé » en anglais) est affiché. Finalement, svn update détecte les jetons de verrouillage défunts et les supprime de la copie de travail.

Nous avons vu comment svn lock et svn unlock peuvent être utilisés pour poser, libérer, casser ou voler des verrous. Cela résout le problème de la sérialisation des accès à un fichier. Mais qu'en est-il du problème plus vaste d'éviter les pertes de temps ?

Par exemple, supposons que Harry verrouille un fichier image et commence à l'éditer. Pendant ce temps, loin de là, Sally veut faire la même chose. Elle ne pense pas à faire un svn status --show-updates et n'a donc pas la moindre idée que Harry a déjà verrouillé le fichier. Elle passe des heures à modifier le fichier et quand elle tente de propager ses changements, elle découvre soit que le fichier est verrouillé, soit que son propre fichier n'était pas à jour. Quoi qu'il en soit, ses modifications ne peuvent pas être fusionnées avec celles de Harry. L'un des deux doit passer ses modifications par pertes et profits, un temps conséquent a été gaspillé.

La solution proposée par Subversion à ce problème est de fournir un mécanisme pour rappeler aux utilisateurs qu'un fichier devrait être verrouillé avant de faire des modifications. Ce mécanisme est mis en œuvre par une propriété spéciale : svn:needs-lock. Si cette propriété est associée à un fichier (quelle que soit sa valeur, qui n'est pas prise en compte), alors Subversion essaie d'utiliser les permissions du système de fichiers pour le placer en lecture seule — à moins, bien sûr, que l'utilisateur ait explicitement verrouillé le fichier. Quand un jeton de verrouillage est présent (indiquant que svn lock a été lancée), le fichier est placé en lecture-écriture. Quand le verrou est libéré, le fichier passe de nouveau en lecture seule.

La théorie est donc que si le fichier image a cette propriété définie, alors Sally remarquera tout de suite quelque chose d'étrange à l'ouverture du fichier : beaucoup d'applications avertissent l'utilisateur immédiatement quand un fichier en lecture seule est ouvert pour édition et pratiquement toutes l'empêcheront de sauvegarder ses modifications dans le fichier. Cela lui rappellera de verrouiller le fichier avant de l'éditer, découvrant ainsi le verrou pré-existant :

$ /usr/local/bin/gimp raisin.jpg
gimp: erreur: le fichier est en lecture seule !
$ ls -l raisin.jpg
-r--r--r--   1 sally   sally   215589 juin  8 19:23 raisin.jpg
$ svn lock raisin.jpg
svn: avertissement : Échec de la demande de verrou : 423 verrouillé (http://svn.exemple.com)
$ svn info http://svn.exemple.com/depot/projet/raisin.jpg | grep errou
Nom de verrou : opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
Propriétaire du verrou : harry
Verrou créé : 2006-06-08 07:29:18 -0500 (jeu. 08 juin 2006)
Commentaire de verrouillage (1 ligne):
J'effectue quelques retouches.  Je le verrouille pour deux heures.
$

	Astuce
	Les utilisateurs et les administrateurs sont tous encouragés à positionner la propriété svn:needs-lock sur les fichiers qui ne peuvent pas être contextuellement fusionnés. C'est la technique de base pour favoriser les bonnes habitudes de verrouillage et éviter les pertes de temps.

Notez que cette propriété est un outil de communication qui fonctionne indépendamment de la politique de verrouillage. Autrement dit, n'importe quel fichier peut être verrouillé, que cette propriété existe ou pas. Et réciproquement, l'existence de cette propriété ne rend pas obligatoire le verrouillage pour pouvoir propager des modifications.

Malheureusement, le système n'est pas parfait. Il est possible que, même si le fichier possède la propriété, l'avertissement de lecture seule ne marche pas. Quelquefois, les applications ne suivent pas les normes et « piratent » le fichier en lecture seule, autorisant sans rien dire l'utilisateur à modifier et sauvegarder le fichier. Subversion ne peut pas faire grand chose dans ce genre de cas : au final, rien ne remplace une bonne communication entre les membres d'une équipe ^[17].

Vous pouvez créer, modifier et supprimer des listes de modifications en utilisant la commande svn changelist. Plus précisément, vous pouvez utiliser cette commande pour activer ou désactiver l'association d'une liste de modifications avec un fichier donné de la copie de travail. La création d'une liste de modifications a lieu la première fois que vous étiquetez un fichier avec ce nom de liste ; elle n'est supprimée que quand vous effacez l'étiquette du dernier fichier qui la portait. Examinons un cas concret pour illustrer ces notions.

Harry est en train de corriger des bogues dans le module de logique mathématique de l'application « calculatrice ». Son travail l'amène à modifier deux fichiers :

$ svn status
M      entier.c
M      ops-math.c
$

En testant son correctif, Harry s'aperçoit que ses modifications lui indiquent qu'un bogue collatéral existe au sein de la logique de l'interface utilisateur, située dans le fichier bouton.c. Harry décide alors qu'il va aussi corriger ce bogue, dans une propagation séparée de ses propres correctifs mathématiques. Dans une copie de travail de petite taille, ne contenant qu'une poignée de fichiers, et pour juste quelques modifications logiques, Harry pourrait probablement gérer mentalement ces deux ensembles logiques de modifications sans le moindre problème. Mais aujourd'hui il a décidé qu'il allait utiliser les listes de modifications de Subversion, pour faire une faveur aux auteurs de ce livre.

Harry commence par créer une première liste de modifications et y associe les deux premiers fichiers qu'il a déjà modifié. Pour ce faire, il utilise la commande svn changelist afin d'associer le même nom arbitraire de liste de modifications aux deux fichiers :

$ svn changelist correctifs-maths entier.c ops-math.c
Le chemin 'entier.c' fait maintenant partie de la liste de changement 'correctifs-maths'.
Le chemin 'ops-math.c' fait maintenant partie de la liste de changement 'correctifs-maths'.
$ svn status

--- Liste de changements 'correctifs-maths' :
M      entier.c
M      ops-math.c
$

Comme vous pouvez le constater, le résultat de svn status reflète bien ce nouvel ensemble.

Harry se lance alors dans la correction du problème d'interface graphique collatéral. Puisqu'il sait quel fichier il va modifier, il associe également ce chemin à une liste de modifications. Mais malencontreusement Harry associe ce troisième fichier à la même liste de modifications que les deux premiers :

$ svn changelist correctifs-maths bouton.c
Le chemin 'bouton.c' fait maintenant partie de la liste de changement 'correctifs-maths'.
$ svn status

--- Liste de changements 'correctifs-maths' :
       bouton.c
M      entier.c
M      ops-math.c
$

Par chance, Harry prend conscience de son erreur. Deux options se présentent alors à lui. Il peut supprimer l'association de bouton.c avec la liste de modifications, puis lui associer un nouveau nom de liste de modifications :

$ svn changelist --remove bouton.c
Le chemin 'bouton.c' n'est plus associé à une liste de changements.
$ svn changelist correctifs-graphiques bouton.c
Le chemin 'bouton.c' fait maintenant partie de la liste de changement 'correctifs-graphiques'.
$

Ou alors il peut sauter l'étape de suppression et juste associer un nouveau nom de liste de modifications à bouton.c. Dans ce cas, Subversion signale à Harry que bouton.c va être supprimé de la première liste de modifications :

$ svn changelist correctifs-graphiques bouton.c
svn:  avertissement : Retrait de 'bouton.c' de la liste de changements (changelist) 'correctifs-maths'.
Le chemin 'bouton.c' fait maintenant partie de la liste de changement 'correctifs-graphiques'.
$ svn status

--- Liste de changements 'correctifs-graphiques' :
       bouton.c

--- Liste de changements 'correctifs-maths' :
M      entier.c
M      ops-maths.c
$

Harry dispose donc à présent de deux listes de modifications distinctes dans sa copie de travail et svn status présente ses résultats en les regroupant par liste de modifications. Notez que bien qu'Harry n'ait pas encore modifié bouton.c, celui-ci est quand même mentionné par svn status car une liste de modifications lui est associée. Les listes de modifications peuvent être associées, ou enlevées, aux fichiers à tout moment, indépendamment du fait que ces fichiers contiennent des modifications locales ou pas.

Harry règle maintenant le problème de l'interface graphique dans bouton.c.

$ svn status

--- Liste de changements 'correctifs-graphiques':
M      bouton.c

--- Liste de changements 'correctifs-maths':
M      entier.c
M      ops-math.c
$

Le regroupement visuel qu'Harry constate en sortie de svn status, comme indiqué précédemment, est intéressant d'un point de vue esthétique, mais pas vraiment utile. La commande status n'est qu'une des commandes qu'il est susceptible de lancer sur sa copie de travail. Heureusement, bon nombre des autres opérations de Subversion sont capables d'agir sur les listes de modifications grâce à l'option --changelist.

Quand l'option --changelist est présente, les commandes Subversion limitent leur champ d'action aux fichiers auxquels est associé le nom de liste de modifications donné. Si Harry veut voir quels changements il a effectué sur les fichiers de sa liste correctifs-maths, il peut lister explicitement les fichiers faisant partie de cette liste de modifications avec la commande svn diff.

$ svn diff entier.c ops-math.c
Index: entier.c
===================================================================
--- entier.c	(révision 1157)
+++ entier.c	(copie de travail)
…
Index: ops-math.c
===================================================================
--- ops-math.c	(révision 1157)
+++ ops-math.c	(copie de travail)
…
$

Cette méthode fonctionne correctement pour un petit nombre de fichiers, mais qu'en est-il si Harry a modifié une vingtaine ou une trentaine de fichiers ? Fournir la liste de tous ces fichiers serait assez pénible. Mais puisqu'il utilise les listes de modifications, Harry peut désormais éviter de lister explicitement tous les fichiers et ne donner à la place que le nom de la liste de modifications :

$ svn diff --changelist correctifs-maths

Index: entier.c
===================================================================
--- entier.c	(révision 1157)
+++ entier.c	(copie de travail)
…
Index: ops-math.c
===================================================================
--- ops-math.c	(révision 1157)
+++ ops-math.c	(copie de travail)
…
$

Et au moment de lancer la propagation, Harry peut à nouveau se servir de l'option --changelist pour limiter le rayon d'action de la propagation aux fichiers de sa liste de modifications. Par exemple, il peut propager ses changements concernant l'interface graphique en lançant :

$ svn ci -m "Corrigé un bug de l'interface graphique découvert en travaillant sur la logique mathématique." \
      --changelist correctifs-graphiques
Envoi        bouton.c
Transmission des données .
Révision 1158 propagée.
$

En fait, la commande svn commit accepte une deuxième option liée aux listes de modifications : --keep-changelists. Normalement, l'association des listes de modifications avec les fichiers est supprimée dès que ceux-ci ont été propagés. Mais si l'option --keep-changelists est ajoutée sur la ligne de commande, les fichiers propagés (qui ne sont donc plus dans l'état modifié) restent associés aux listes de modifications en question. Dans tous les cas, propager des fichiers faisant partie d'une liste de modification laisse les autres listes de modifications intactes.

$ svn status

--- Liste de changements 'correctifs-maths':
M      entier.c
M      ops-math.c
$

Note

L'option --changelist agit comme un filtre sur les cibles des commandes Subversion et n'ajoute jamais de cible à une opération. Par exemple, lors d'une opération de propagation lancée via svn commit /chemin/vers/rep, la cible est le répertoire /chemin/vers/rep et ses fils (avec une profondeur infinie). Si ensuite vous ajoutez une option spécifiant une liste de modifications à cette commande, seuls les fichiers se trouvant sous le chemin /chemin/vers/rep et associés à cette liste de modifications sont pris en compte en tant que cibles de la propagation ; ne sont pas inclus les fichiers situés ailleurs (tels ceux sous /chemin/vers/autre-rep), quelle que soit la liste de modifications à laquelle ils appartiennent, même s'il font partie de la même copie de travail que la ou les cibles de l'opération.

Même la commande svn changelist accepte l'option --changelist. Ceci vous permet de renommer ou supprimer facilement une liste de modifications :

$ svn changelist bogues-maths --changelist correctifs-maths --depth infinity .
svn: avertissement : Retrait de 'entier.c' de la liste de changements (changelist) 'correctifs-maths'.
Le chemin 'entier.c' fait maintenant partie de la liste de changement 'bogues-maths'.
svn: avertissement : Retrait de 'ops-math.c' de la liste de changements (changelist) 'correctifs-maths'.
Le chemin 'ops-math.c' fait maintenant partie de la liste de changement 'bogues-maths'.
$ svn changelist --remove --changelist bogues-maths --depth infinity .
Le chemin 'entier.c' n'est plus associé à une liste de changements.
Le chemin 'ops-math.c' n'est plus associé à une liste de changements.
$

Enfin, vous pouvez spécifier plusieurs instances de l'option --changelist dans une même ligne de commande. Ceci limite le champ d'action de votre opération aux fichiers faisant partie de toutes les listes de modifications spécifiées.

La fonctionnalité de listes de modifications de Subversion est un outil très pratique pour créer des groupes de fichiers au sein de la copie de travail, mais elle a cependant quelques limitations. Les listes de modifications sont des objets contenus à l'intérieur d'une copie de travail, ce qui signifie que les associations entre fichiers et listes de modifications ne peuvent pas être propagées vers le dépôt, ni partagées avec d'autres utilisateurs. Les listes de modifications ne peuvent être associées qu'à des fichiers, Subversion n'offre pas cette possibilité pour les répertoires. Enfin, vous pouvez avoir au plus un nom de liste de modifications associé à un fichier donné. C'est ici que l'analogie avec les articles de blogs et les services d'étiquetage de photos en ligne part en fumée. S'il vous faut associer un fichier à plusieurs listes de modifications, vous êtes coincé.

Le client Subversion passe la plupart de son temps à gérer des copies de travail. Cependant, quand il a besoin d'informations disponibles dans un dépôt distant, il envoie une requête sur le réseau et le serveur lui répond. Les détails du protocole réseau sont cachés à l'utilisateur : le client essaie d'accéder à une URL et, suivant le format de cette URL, utilise un protocole particulier pour contacter le serveur (voir URL du dépôt).

	Astuce
	Tapez svn --version pour voir quels types d'URL et de protocoles sont utilisables par votre client.

Quand le serveur reçoit une requête d'un client, il demande souvent au client de s'identifier. Il envoie un défi d'authentification vers le client et le client répond en fournissant les éléments d'authentification au serveur. Une fois cette authentification terminée, le serveur répond à la requête originale du client. Remarquez que ce fonctionnement est différent de celui de CVS où le client envoie systématiquement au préalable ses identifiants de connexion (procédure de « log in »), avant même de formuler la moindre requête. Dans Subversion, le serveur requiert explicitement l'authentification du client (par un défi d'authentification) au moment approprié, au lieu que ce soit le client qui s'authentifie a priori. Certaines opérations sont donc effectuées plus élégamment. Par exemple, si un serveur est configuré pour laisser tout le monde accéder au dépôt en lecture, alors le serveur n'envoie jamais de défi d'authentification quand un client tente un svn checkout.

Si une requête d'un client conduit à la création d'une nouvelle révision du dépôt (par exemple un svn commit), alors Subversion utilise le nom d'utilisateur fourni lors de la phase d'authentification comme auteur de la révision. C'est-à-dire que le nom d'utilisateur est stocké dans la propriété svn:author de la nouvelle révision (voir la section intitulée « Propriétés dans Subversion »). Si le client n'a pas été authentifié (en d'autres termes, si le serveur n'a jamais envoyé de défi d'authentification), alors la propriété svn:author de la révision est vide.

Beaucoup de serveurs sont configurés pour demander une authentification à chaque requête. Ce serait particulièrement pénible pour les utilisateurs s'ils devaient taper leur mot de passe à chaque fois. Heureusement, le client Subversion a une solution : la mise en cache sur le disque des éléments d'authentification. Par défaut, si le client en ligne de commande s'authentifie avec succès auprès d'un serveur, le client sauvegarde les éléments d'authentification dans une zone privée propre à l'utilisateur (~/.subversion/auth/ sur les systèmes de type Unix ou %APPDATA%/Subversion/auth/ sur Windows) ; voir la section intitulée « Zone de configuration des exécutables » pour plus de détails). Les éléments d'authentification sont mis en cache sur le disque, classés suivant une combinaison du nom, du port et du domaine d'authentification du serveur.

Quand le client reçoit un défi d'authentification, il regarde d'abord s'il dispose des éléments appropriés dans le cache disque de l'utilisateur. Si ce n'est pas le cas, ou si les éléments conduisent à un échec lors de la tentative d'authentification, le client demande alors (c'est son comportement par défaut) à l'utilisateur les informations nécessaires.

Ici, le lecteur soucieux de sécurité va immédiatement commencer à s'inquiéter : « Mettre en cache des mots de passe sur le disque ? Quelle horreur ! Jamais ! »

Les développeurs de Subversion reconnaissent le bien fondé du problème et c'est pourquoi Subversion est capable de fonctionner avec les différents mécanismes offerts par le système d'exploitation et l'environnement de travail pour minimiser les risques de fuites d'information. Voici ce que cela veut dire sur les plateformes les plus courantes :

Bien sûr, si vous êtes complètement paranoïaque, aucun de ces mécanismes n'est parfait. Ainsi, pour ceux qui sont prêts à sacrifier le confort d'utilisation au profit de la sécurité absolue, Subversion fournit de nombreuses façons de désactiver le système de cache d'authentification.

Pour désactiver le système de cache pour une seule commande, utilisez l'option --no-auth-cache :

$ svn commit -F log_msg.txt --no-auth-cache
Domaine d'authentification : <svn://hote.exemple.com:3690> exemple de domaine
Nom d'utilisateur :  paul
Mot de passe pour 'paul' :

Ajout         nouveau_fichier
Transmission des données .
Révision 2324 propagée.

# le mot de passe n'a pas été mis dans le cache, donc la deuxième propagation
# nous redemandera le mot de passe

$ svn delete nouveau_fichier
$ svn commit -F nouveau_msg.txt
Domaine d'authentification : <svn://hote.exemple.com:3690> exemple de domaine
Nom d'utilisateur :  paul
…

Autrement, si vous voulez désactiver la mise en cache des éléments d'authentification de manière permanente, vous pouvez éditer le fichier config de votre zone de configuration et mettre l'option store-auth-creds à no. La mise en cache des éléments d'authentification est alors désactivée pour toutes les commandes Subversion que vous effectuez sur cet ordinateur. Ceci peut être étendu à l'ensemble des utilisateurs de l'ordinateur en modifiant la configuration globale de Subversion (voir la section intitulée « Agencement de la zone de configuration »).

[auth]
store-auth-creds = no

Il arrive que les utilisateurs veuillent effacer certains mots de passe du cache disque. Pour ce faire, vous devez vous rendre dans la zone auth/ et effacer manuellement le fichier de cache approprié. Les éléments d'authentification sont mis en cache dans des fichiers individuels ; si vous affichez chaque fichier, vous voyez des clés et des valeurs. La clé svn:realmstring décrit le domaine du serveur auquel est associé le fichier :

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

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

K 8
username
V 3
paul
K 8
password
V 4
blah
K 15
svn:realmstring
V 45
<https://svn.domaine.com:443> Dépôt de Paul
END

Une fois le bon fichier trouvé, effacez-le.

Un dernier mot sur la façon dont svn gère l'authentification, avec un zoom sur les options --username et --password. Beaucoup de sous-commandes du client acceptent ces options, mais il est important de comprendre que l'utilisation de ces options n'envoie pas automatiquement les éléments d'authentification au serveur. Comme vu précédemment, le serveur demande explicitement l'authentification au client quand il estime que c'est nécessaire ; le client ne les envoie pas à sa convenance. Même si un nom d'utilisateur et/ou un mot de passe sont passés en option, ils ne sont envoyés au serveur que si celui-ci les demande. Ces options sont couramment utilisées pour s'authentifier sous un nom d'utilisateur différent de celui que Subversion aurait choisi par défaut (comme votre nom de compte système), ou quand on ne veut pas de commande interactive (par exemple, utilisation de la commande svn dans un script).

	Note
	Une erreur classique consiste à mal configurer un serveur de telle sorte qu'il n'envoie jamais de défi d'authentification. Quand les utilisateurs passent les options --username et --password, ils sont surpris de voir qu'elles ne sont jamais utilisées, c'est-à-dire que les nouvelles révisions semblent toujours avoir été propagées de façon anonyme !

En résumé, voici comment un client Subversion se comporte quand il reçoit un défi d'authentification :

Si le client réussit à s'authentifier par l'une ou l'autre de ces méthodes, il essaie de mettre en cache les éléments d'authentification sur le disque (à moins que cette fonctionnalité ne soit désactivée, comme indiqué auparavant).

Créer une branche est très simple : il s'agit juste de faire une copie du projet dans le dépôt avec la commande svn copy. Subversion est capable de copier non seulement de simples fichiers, mais aussi des dossiers entiers. Dans le cas présent, vous voulez faire une copie du dossier /calc/trunk. Où doit résider la nouvelle copie ? Là où vous le désirez, cette décision faisant partie de la gestion du projet. Supposons que votre équipe ait pour convention de créer les branches dans la zone /calc/branches du dépôt et que vous vouliez nommer votre branche ma-branche-calc. Vous créez alors un nouveau dossier, /calc/branches/ma-branche-calc, qui commence ainsi sa vie en tant que copie de /calc/trunk.

Vous avez peut-être déjà utilisé svn copy pour copier un fichier vers un autre à l'intérieur d'une copie de travail. Mais il peut aussi être utilisé pour effectuer une copie « distante » entièrement à l'intérieur du dépôt. Il suffit de copier une URL vers une autre :

$ svn copy http://svn.exemple.com/depot/calc/trunk \
           http://svn.exemple.com/depot/calc/branches/ma-branche-calc \
      -m "Création d'une branche privée à partir de /calc/trunk."

Révision 341 propagée.

Cette commande entraîne une opération quasi-instantanée dans le dépôt, créant un nouveau dossier à la révision 341. Ce nouveau dossier est une copie de /calc/trunk, comme l'illustre la Figure 4.3, « Dépôt avec nouvelle copie » ^[21]. Bien qu'il soit aussi possible de créer une branche en utilisant svn copy pour dupliquer un dossier à l'intérieur de la copie de travail, cette technique n'est pas recommandée. Elle peut s'avérer assez lente, en fait ! Copier un dossier côté client est une opération linéaire en terme de durée, puisque chaque fichier et chaque dossier doit être dupliqué sur le disque local. Copier un dossier sur le serveur, par contre, est une opération dont la durée est constante et c'est ainsi que la plupart des gens créent des branches.

Figure 4.3. Dépôt avec nouvelle copie

Maintenant que vous avez créé votre branche du projet, vous pouvez extraire une nouvelle copie de travail et commencer à l'utiliser :

$ svn checkout http://svn.exemple.com/depot/calc/branches/ma-branche-calc
A  ma-branche-calc/Makefile
A  ma-branche-calc/entier.c
A  ma-branche-calc/bouton.c
Révision 341 extraite.

Cette copie de travail n'a rien de spéciale ; elle correspond juste à un dossier différent du dépôt. Cependant, quand vous propagerez vos modifications, Sally ne les verra pas quand elle effectuera une mise à jour, car sa copie de travail correspond à calc/trunk (pensez bien à lire la section intitulée « Parcours des branches » plus loin dans ce chapitre : la commande svn switch est une méthode alternative pour créer une copie de travail d'une branche).

Imaginons qu'une semaine passe et que les propagations suivantes ont lieu :

À présent, deux lignes de développement indépendantes (voir la Figure 4.4, « Historique des branches d'un fichier ») existent pour entier.c.

Figure 4.4. Historique des branches d'un fichier

Les choses deviennent intéressantes quand on regarde l'historique des modifications apportées à votre copie de entier.c :

$ pwd
/home/utilisateur/ma-branche-calc

$ svn log -v entier.c
------------------------------------------------------------------------
r343 | utilisateur | 2002-11-07 15:27:56 -0600 (jeu. 07 nov. 2002) | 2 lignes
Chemins modifiés :
   M /calc/branches/ma-branche-calc/entier.c

* entier.c:  machiné le bidule.

------------------------------------------------------------------------
r341 | utilisateur | 2002-11-03 15:27:56 -0600 (jeu. 07 nov. 2002) | 2 lignes
Chemins modifiés :
   A /calc/branches/ma-branche-calc (from /calc/trunk:340)

Création d'une branche privée à partir de /calc/trunk.

------------------------------------------------------------------------
r303 | sally | 2002-10-29 21:14:35 -0600 (mar. 29 oct. 2002) | 2 lignes
Chemins modifiés :
   M /calc/trunk/entier.c

* entier.c:  modifié une docstring.

------------------------------------------------------------------------
r98 | sally | 2002-02-22 15:35:29 -0600 (ven. 22 fev. 2002) | 2 lignes
Chemins modifiés :
  A /calc/trunk/entier.c
* entier.c:  ajout du fichier dans ce projet.

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

Notez bien que Subversion reprend tout l'historique du entier.c de votre branche à travers le temps, remontant même au delà du point où il a été copié. Il liste la création d'une branche en tant qu'élément de l'historique, parce qu'entier.c a été copié implicitement lorsque calc/trunk tout entier a été copié. Maintenant regardez ce qui se passe quand Sally lance la même commande sur sa copie du fichier :

$ pwd
/home/sally/calc

$ svn log -v entier.c
------------------------------------------------------------------------
r344 | sally | 2002-11-07 15:27:56 -0600 (jeu. 07 nov. 2002) | 2 lignes
 Chemins modifiés :
    M /calc/trunk/entier.c

 * entier.c:  corrigé un ensemble de coquilles.

 ------------------------------------------------------------------------
 r303 | sally | 2002-10-29 21:14:35 -0600 (mar. 29 oct. 2002) | 2 lignes
 Chemins modifiés :
    M /calc/trunk/entier.c

 * entier.c:  modifié une docstring.

 ------------------------------------------------------------------------
 r98 | sally | 2002-02-22 15:35:29 -0600 (ven. 22 fev. 2002) | 2 lignes
 Chemins modifiés :
   A /calc/trunk/entier.c

* entier.c:  ajout du fichier dans ce projet.

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

Sally voit la modification due à sa propre révision 344, mais pas le changement que vous avez effectué dans la révision 343. Pour Subversion, ces deux propagations ont touché des fichiers différents dans des dossiers distincts. Néanmoins, Subversion indique bien que les deux fichiers partagent une histoire commune. Avant que la copie de branche n'ait été faite en révision 341, les fichiers ne faisaient qu'un. C'est pourquoi Sally et vous voyez tous les deux les modifications apportées en révisions 303 et 98.

Il y a deux leçons importantes à retenir de ce paragraphe. Premièrement, Subversion n'a pas de notion interne de branche — il sait seulement faire des copies. Quand vous copiez un dossier, le dossier qui en résulte n'est une « branche » que parce que vous le considérez comme tel. Vous aurez beau envisager ce dossier différemment ou le traiter différemment, pour Subversion c'est juste un dossier ordinaire auquel sont associées des informations extra-historiques.

Deuxièmement, à cause de ce mécanisme de copie, les branches de Subversion existent en tant que dossiers classiques du système de fichiers du dépôt. En cela, Subversion diffère des autres systèmes de gestion de versions, où les branches sont définies par l'ajout d'« étiquettes » extra-dimensionnelles à des groupes de fichiers. L'emplacement du dossier de votre branche importe peu à Subversion. La plupart des équipes ont pour convention de placer toutes les branches dans un dossier /branches, mais vous êtes libre d'inventer la convention qui vous plaît.

Avant que nous n'allions plus loin, nous devons vous avertir que les pages suivantes contiennent de nombreuses discussions portant sur les « modifications ». Beaucoup de gens ayant de l'expérience dans les systèmes de gestion de versions utilisent le terme « modifications » et le terme « ensemble de modifications » de façon interchangeable et nous allons donc clarifier ce que Subversion entend par ensemble de modifications.

Chacun semble avoir sa propre définition, variant légèrement, d'un ensemble de modifications, ou tout du moins a une attente différente quant à leur traitement par le système de gestion de versions. En ce qui nous concerne, disons qu'un ensemble de modifications n'est qu'un simple regroupement de modifications identifié par un nom unique. Les modifications peuvent inclure des changements textuels du contenu des fichiers, des modifications de l'arborescence ou des ajustements portant sur les méta-données. En langage plus courant, un ensemble de modifications n'est qu'un correctif avec un nom auquel vous pouvez vous référer.

Dans Subversion, un numéro de révision globale N désigne une arborescence dans le dépôt : c'est ce à quoi le dépôt ressemblait après la N-ième propagation. C'est aussi le nom d'un ensemble de modifications implicite : si vous comparez l'arborescence N avec l'arborescence N−1, vous pouvez en déduire exactement le correctif qui a été propagé. Pour cette raison, il est facile de se représenter une révision N non seulement comme une arborescence, mais aussi comme un ensemble de modifications. Si vous utilisez un système de gestion des incidents pour gérer vos bogues, vous pouvez utiliser les numéros de révision pour vous référer à des correctifs particuliers permettant de résoudre des bogues — par exemple, « cet incident a été corrigé par r9238 ». Quelqu'un peut alors lancer svn log -r 9238 pour obtenir le détail des modifications qui ont corrigé le bogue et lancer svn diff -c 9238 pour voir le correctif lui-même. De plus (comme nous le verrons bientôt), la commande svn merge de Subversion est capable d'utiliser les numéros de révision. Vous pouvez fusionner des listes de modifications spécifiques d'une branche à une autre en les nommant dans les paramètres de la fusion : donner comme argument -c 9238 à svn merge fusionne la liste de modifications r9238 avec votre copie de travail.

Continuons avec notre exemple précédent et imaginons qu'une semaine a passé depuis que vous avez commencé à travailler sur votre branche privée. Votre nouvelle fonctionnalité n'est pas encore terminée, mais en même temps vous savez que d'autres personnes de votre équipe ont continué à faire des modifications importantes sur le /trunk du projet. Vous avez intérêt à recopier ces modifications dans votre propre branche, juste pour vous assurer qu'elles se combinent bien avec vos propres modifications. En fait, c'est là une bonne pratique : synchroniser fréquemment votre branche avec la ligne de développement principale permet d'éviter les conflits « surprise » le jour où vous reversez vos modifications dans le tronc.

Subversion connaît l'historique de votre branche et sait à quel moment elle s'est séparée du tronc. Afin de récupérer les modifications du tronc les plus récentes et les plus importantes, assurez-vous en premier lieu que votre copie de travail est « propre », c'est-à-dire que svn status ne liste aucune modification locale. Puis lancez juste :

$ pwd
/home/user/ma-branche-calc

$ svn merge http://svn.exemple.com/depot/calc/trunk
--- Fusion de r345 à r356 dans '.':
U    bouton.c
U    entier.c

La syntaxe de base, svn merge URL, indique à Subversion qu'il doit fusionner toutes les modifications récentes depuis l'URL vers le répertoire de travail actuel (qui est bien souvent la racine de votre copie de travail). Après l'exécution de la commande de l'exemple précédent, la copie de travail de votre branche contient de nouvelles modifications locales, ces changements étant des duplications de toutes les modifications qui ont eu lieu sur le tronc depuis que vous avez créé votre branche :

$ svn status
 M     .
M      bouton.c
M      entier.c

Une fois rendu là, le plus sage est d'examiner attentivement les modifications avec svn diff et ensuite de compiler et de tester votre branche. Notez que le répertoire de travail actuel (« . ») a aussi été modifié ; svn diff indique que sa propriété svn:mergeinfo a été créée ou modifiée. Ceci est une méta-information importante liée à la fusion, à laquelle vous ne devriez pas toucher, puisqu'elle sera nécessaire aux futures commandes svn merge (nous en apprendrons plus sur cette métadonnée plus loin dans ce chapitre).

Après avoir effectué la fusion, vous aurez peut-être aussi besoin de résoudre des conflits (comme vous le faites pour svn update) ou éventuellement d'effectuer de petites modifications afin que les choses fonctionnent correctement (souvenez-vous, ce n'est pas parce qu'il n'y a pas de conflits syntaxiques qu'il n'y a pas de conflits sémantiques !). Si vous rencontrez de graves difficultés, vous pouvez toujours annuler les modifications locales en lançant svn revert . -R (qui annule toutes les modifications locales) et entamer avec vos collègues une longue discussion sur le thème « Qu'est-ce qui se passe ? ». Par contre, si les choses se passent bien, vous pouvez propager ces modifications dans le dépôt :

$ svn commit -m "Fusionné les dernières modifications de trunk avec ma-branche-calc"
Envoi          .
Envoi          bouton.c
Envoi          entier.c
Transmission des données ..
Révision 357 propagée.

À présent, votre branche privée est désormais « synchro » avec le tronc, vous pouvez donc vous détendre, sachant qu'en continuant votre travail en isolation, vous ne dériverez pas trop loin de ce que les autres font.

$ cd ma-branche-calc
$ svn diff -r 341:HEAD http://svn.exemple.com/depot/calc/tronc > fichierpatch
$ patch -p0 < fichierpatch
Patching file entier.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

Supposons qu'une autre semaine s'est écoulée. Vous avez propagé des modifications supplémentaires dans votre branche et vos camarades ont également continué à améliorer le tronc. Une fois encore, vous aimeriez répercuter les dernières modifications du tronc vers votre branche et ainsi être synchro. Lancez juste la même commande svn merge à nouveau !

$ svn merge http://svn.exemple.com/depot/calc/trunk
--- Fusion de r357 à r380 dans '.':
U    bouton.c
U    Makefile
A    LISEZMOI

Subversion sait quelles sont les modifications du tronc que vous avez déjà répercutées vers votre branche, il ne répercute donc que les modifications que vous n'avez pas encore. Une fois de plus, vous devrez compiler, tester et propager les modifications locales à votre branche.

Cependant, que se passe-t-il quand vous finissez enfin votre travail ? Votre nouvelle fonctionnalité est terminée et vous êtes prêt à fusionner les changements de votre branche avec le tronc (pour que votre équipe puisse bénéficier du fruit de votre travail). La procédure est simple. Premièrement, synchronisez à nouveau votre branche avec le tronc, comme vous le faites depuis le début :

$ svn merge http://svn.exemple.com/repos/calc/tronc
--- Fusion de r381 à r385 dans '.':
U    bouton.c
U    LISEZMOI

$ # compiler, tester, ...

$ svn commit -m "Fusion finale des modifications du tronc dans ma-branche-calc."
Envoi          .
Envoi          bouton.c
Envoi          LISEZMOI
Transmission des données ..
Révision 390 propagée.

À présent, utilisez svn merge pour répercuter les modifications de votre branche sur le tronc. Vous avez alors besoin d'une copie de travail de /trunk qui soit à jour. Vous pouvez vous la procurer soit en effectuant un svn checkout, soit en reprenant une vieille copie de travail du tronc, soit en utilisant svn switch (voir la section intitulée « Parcours des branches »). Quelle que soit la manière dont vous obtenez une copie de travail, souvenez-vous qu'une bonne méthode est d'effectuer la fusion dans une copie de travail qui n'a pas été modifiée localement et qui a été mise à jour récemment (en d'autres termes, qui n'est pas un mélange de révisions locales). Si votre copie de travail n'est pas « propre » comme expliqué à l'instant, vous risquez de rencontrer des problèmes facilement évitables liés à des conflits et svn merge renverra probablement une erreur en retour.

Une fois que vous avez une copie de travail propre du tronc, vous êtes prêt pour y fusionner votre branche :

$ pwd
/home/user/calc-tronc

$ svn update  # (s'assurer que la copie de travail est à jour)
À la révision 390.

$ svn merge --reintegrate http://svn.exemple.com/depot/calc/branches/ma-branche-calc
--- Fusionne toutes les modifications non fusionnées des URLs sources dans '.':
U    bouton.c
U    entier.c
U    Makefile
U   .

$ # compiler, tester, vérifier, ...

$ svn commit -m "Fusionner ma-branche-calc dans le tronc !"
Envoi          .
Envoi          bouton.c
Envoi          entier.c
Envoi          Makefile
Transmission des données ..
Révision 391 propagée.

Félicitations, votre branche a maintenant réintégré la ligne de développement principale. Notez bien l'utilisation de l'option --reintegrate à cette occasion. L'option est essentielle pour répercuter les modifications d'une branche sur sa ligne de développement d'origine, ne l'oubliez pas ! Elle est nécessaire car ce type de « réintégration » est un type de tâche différent de ce que vous avez fait jusqu'à présent. Précédemment, nous demandions à svn merge de faire la liste des modifications ayant eu lieu dans une ligne de développement (le tronc) et de les dupliquer vers une autre (votre branche). C'est assez simple à réaliser et à chaque fois Subversion sait reprendre là où il s'était arrêté. Dans nos exemples précédents, vous pouvez voir qu'il fusionne en premier les modifications 345:356 du tronc vers la branche ; ensuite il continue en fusionnant le groupe contigu immédiatement suivant, 356:380. Quand il effectue la synchronisation finale, il fusionne le groupe 380:385.

Cependant, lors de la réintégration d'une branche dans le tronc, la logique sous-jacente est assez différente. Votre branche dédiée est à présent un amoncellement de modifications provenant à la fois du tronc et de votre branche privée et il n'y a donc pas de groupe de révisions contigu à recopier. En spécifiant l'option --reintegrate, vous demandez explicitement à Subversion de ne recopier que les modifications spécifiques à votre branche (et en fait il le fait en comparant l'arborescence la plus récente du tronc avec l'arborescence la plus récente de la branche : la différence qui en résulte constitue exactement les modifications de votre branche !).

Votre branche privée ayant réintégré le tronc, vous voudrez peut-être la supprimer du dépôt :

$ svn delete http://svn.exemple.com/depot/calc/branches/ma-branche-calc \
      -m "Supprime ma-branche-calc."
Révision 392 propagée.

Mais attendez ! L'historique de votre branche ne possède-t-il pas une certaine valeur ? Et si un beau jour quelqu'un voulait auditer l'évolution de votre fonctionnalité et examiner toutes les modifications de votre branche ? Pas la peine de s'inquiéter. Souvenez-vous que même si votre branche n'est plus visible dans le dossier /branches, son existence demeure une partie immuable de l'historique du dépôt. Une simple commande svn log appliquée à l'URL /branches vous renverra l'historique complet de votre branche. Votre branche pourrait même ressusciter un jour ou l'autre, si vous le désirez (voir la section intitulée « Résurrection des éléments effacés »).

Dans Subversion 1.5, une fois que la fusion d'une branche vers le tronc a été faite avec l'option --reintegrate, la branche n'est plus utilisable. Elle ne peut absorber correctement de nouvelles modifications du tronc, ni être réintégrée à nouveau proprement dans le tronc. Pour cette raison, si vous voulez continuer à travailler sur la branche de votre fonctionnalité, nous vous recommandons de la détruire et de la recréer depuis le tronc :

$ svn delete http://svn.exemple.com/depot/calc/branches/ma-branche-calc \
      -m "Supprime ma-branche-calc."
Révision 392 propagée.

$ svn copy http://svn.exemple.com/depot/calc/trunk \
           http://svn.exemple.com/depot/calc/branches/nouvelle-branche
      -m "Crée une nouvelle branche a partir du tronc."
Révision 393 propagée.

$ cd ma-branche-calc

$ svn switch http://svn.exemple.com/depot/calc/branches/nouvelle-branche
À la révision 393.

La dernière commande de l'exemple précédent, svn switch, est une façon de mettre à jour une copie de travail existante afin qu'elle pointe vers un autre dossier du dépôt. Nous en parlerons plus en détail dans la section intitulée « Parcours des branches ».

Le mécanisme de base que Subversion utilise pour gérer les ensembles de modifications, c'est-à-dire quelles modifications ont été fusionnées dans quelles branches, est l'enregistrement de données dans les propriétés. Plus précisément, les informations de fusion sont conservées dans la propriété svn:mergeinfo qui est associée aux fichiers et aux dossiers (si les propriétés de Subversion ne vous sont pas familières, c'est le moment de lire la section intitulée « Propriétés »).

Vous pouvez examiner cette propriété comme n'importe quelle autre :

$ cd ma-branche-calc
$ svn propget svn:mergeinfo .
/trunk:341-390

Il est déconseillé de changer soi-même la valeur de cette propriété, à moins de savoir vraiment ce que vous faites. Cette propriété est manipulée automatiquement par Subversion à chaque fois que vous lancez svn merge. Sa valeur indique quelles modifications (pour un chemin donné) ont été recopiées dans le dossier en question. Dans le cas présent, le chemin est /trunk et le dossier qui a reçu les modifications spécifiées est /branches/ma-branche-calc.

Il existe également une sous-commande, svn mergeinfo, qui peut être utile pour voir non seulement quels ensembles de modifications un dossier a absorbés, mais aussi quels ensembles de modifications il est encore susceptible de recevoir. Ceci donne une sorte d'aperçu du prochain ensemble de modifications que svn merge recopiera vers votre branche.

$ cd ma-branche-calc

# Quelles modifications ont déjà été fusionnées du tronc vers la branche ?
$ svn mergeinfo http://svn.exemple.com/depot/calc/trunk
r341
r342
r343
…
r388
r389
r390

# Quelles modifications sont encore susceptibles d'être fusionnées du tronc vers la branche ?
$ svn mergeinfo http://svn.exemple.com/depot/calc/trunk --show-revs eligible
r391
r392
r393
r394
r395

La commande svn mergeinfo prend en paramètres une URL « source » (d'où les modifications viennent) et une URL « cible » optionnelle (vers laquelle les modifications sont fusionnées). Si aucune URL cible n'est fournie, elle suppose que le dossier actuel est la cible. Dans l'exemple précédent, puisque nous interrogeons la copie de travail de notre branche, la commande suppose que ce qui nous intéresse est de recevoir les modifications de l'URL spécifiée du tronc vers /branches/ma-branche-calc.

Une autre manière d'obtenir un aperçu plus précis d'une opération de fusion est d'utiliser l'option --dry-run :

$ svn merge http://svn.exemple.com/depot/calc/trunk --dry-run
U    entier.c

$ svn status
#  rien ne s'affiche, la copie de travail n'a pas changé.

L'option --dry-run n'effectue en fait pas de modification locale sur la copie de travail. Elle ne fait qu'indiquer les codes d'état qui seraient affichés par une vraie fusion. Ceci permet d'obtenir un « aperçu général » d'une fusion potentielle, pour les fois où svn diff renvoie trop de détails.

Astuce

Après avoir effectué une opération de fusion, mais avant d'en avoir propagé les résultats, vous pouvez utiliser svn diff --depth=empty /chemin/vers/la/cible/de/la/fusion pour visualiser uniquement les modifications apportées à la cible immédiate de votre fusion. Si la cible de la fusion est un dossier, seules les différences de propriétés sont alors affichées. C'est un moyen très pratique pour voir les modifications de la propriété svn:mergeinfo enregistrées par l'opération de fusion, qui vous rappellera ce que vous venez juste de fusionner.

Bien sûr, la meilleure façon d'avoir un aperçu d'une opération de fusion est tout simplement de la réaliser ! Souvenez-vous que lancer svn merge n'est pas une opération risquée en soi (à moins que vous ayez effectué des modifications locales dans votre copie de travail, mais nous avons déjà souligné que vous ne devriez pas faire de fusion dans un tel environnement). Si les résultats de la fusion ne vous plaisent pas, lancez juste svn revert . -R pour ôter les modifications de votre copie de travail et réessayez la commande avec des options différentes. La fusion n'est définitive qu'une fois que vous en avez propagé les résultats.

Astuce

Bien qu'il soit parfaitement légitime de lancer svn merge et svn revert à plusieurs reprises pour préparer la fusion, vous risquez de rencontrer quelques obstacles (facilement surmontables). Par exemple, si l'opération de fusion ajoute un nouveau fichier (ou plus exactement programme son ajout), svn revert ne supprime pas le fichier ; il va juste déprogrammer l'ajout. Vous vous retrouvez avec un fichier non suivi en versions. Si ensuite vous tentez à nouveau de lancer la fusion, il risque d'y avoir des conflits dus au fichier non suivi en versions resté « en travers du chemin ». La Solution ? Après avoir effectué un retour en arrière à l'aide de svn revert, pensez à nettoyer la copie de travail et supprimer les fichiers et dossiers non suivis en versions. Il faut que le résultat de svn status soit le plus propre possible, et dans l'idéal vide.

Un usage très répandu de svn merge est le retour en arrière sur une modification qui a déjà été propagée. Supposons que vous travaillez tranquillement sur une copie de travail de /calc/trunk et que vous découvrez tout à coup que la modification faite il y a longtemps lors de la révision 303, qui affectait entier.c, est complètement incorrecte. Elle n'aurait jamais du être propagée. Vous pouvez utiliser svn merge pour revenir en arrière sur cette modification dans votre copie de travail, puis propager la modification locale au dépôt. Il suffit juste de spécifier une différence inversée (en indiquant soit --revision 303:302, soit --change -303, les deux se valent).

$ svn merge -c -303 http://svn.exemple.com/depot/calc/trunk
--- Fusion inverse de r303 dans 'entier.c':
U    entier.c

$ svn status
 M     .
M      entier.c

$ svn diff
…
# vérifier que la modification est supprimée
…

$ svn commit -m "Retour en arrière sur la modification propagée en r303."
Envoi          entier.c
Transmission des données .
Révision 350 propagée.

Comme nous l'avons signalé précédemment, une façon de se représenter une révision du dépôt est de la considérer comme un ensemble de modifications spécifique. En utilisant l'option -r, vous pouvez demander à svn merge d'appliquer un ensemble de modifications, ou tout un groupe d'ensembles de modifications, à votre copie de travail. Dans le cas présent, pour revenir en arrière, nous demandons à svn merge d'appliquer dans le sens inverse l'ensemble de modifications nº303 à notre copie de travail.

Gardez à l'esprit que revenir en arrière sur une modification de cette façon est similaire à toute autre opération svn merge, vous devez donc ensuite utiliser svn status et svn diff pour vous assurer que votre travail est dans l'état que vous voulez, puis utiliser svn commit pour propager la version finale au dépôt. Après la propagation, cet ensemble de modifications particulier n'est plus présent dans la révision HEAD.

À nouveau vous vous dites : bon, ceci n'a pas vraiment annulé la propagation, n'est-ce pas ? La modification existe toujours en révision 303. Si quelqu'un extrait une version du projet calc entre les révisions 303 et 349, il verra toujours la mauvaise modification, non ?

Oui, c'est vrai. Quand nous parlons de « supprimer » une modification, il s'agit de la supprimer de la révision HEAD. La modification originale existe toujours dans l'historique du dépôt. Dans la plupart des situations, c'est suffisant. La plupart des gens ne s'intéressent d'ailleurs qu'à la révision HEAD du projet. Il y a des cas particuliers, cependant, où l'on voudra vraiment détruire toute preuve de la propagation (quelqu'un a peut-être accidentellement propagé un document confidentiel). Cela ne s'avère pas si facile, parce que Subversion a été conçu délibérément pour ne jamais perdre d'information. Les révisions sont des arborescences immuables qui sont empilées les unes par dessus les autres. Supprimer une révision de l'historique créerait un effet domino, engendrant le chaos dans les révisions ultérieures et invalidant potentiellement toutes les copies de travail ^[22].

Ce qu'il y a de formidable dans les systèmes de gestion de versions, c'est que les informations ne sont jamais perdues. Même si vous effacez un fichier ou un dossier, s'il disparaît bien de la révision HEAD, l'objet existe toujours dans les révisions précédentes. Une des questions les plus courantes que posent les nouveaux utilisateurs est : « Comment est-ce que je récupère mon ancien fichier ou dossier ? »

La première étape est de définir exactement quel élément vous essayez de ressusciter. Voici une métaphore utile : vous pouvez imaginer votre objet dans le dépôt comme existant dans une sorte de système à deux dimensions. La première coordonnée est une révision correspondant à une arborescence particulière ; la deuxième coordonnée est un chemin à l'intérieur de cette arborescence. Ainsi, toute version d'un fichier ou d'un dossier peut être définie par une paire de coordonnées qui lui est propre (souvenez-vous de la syntaxe des « piquets de révisions » : machin.c@224, mentionnée dans la section intitulée « Piquets de révisions et révisions opérationnelles »).

Tout d'abord, vous allez peut-être avoir besoin de svn log pour identifier précisément les coordonnées du fichier ou dossier que vous voulez ressusciter. À cette fin, une bonne stratégie est de lancer svn log --verbose dans un dossier qui contenait votre élément effacé. L'option --verbose (-v) renvoie la liste de tous les éléments modifiés par chaque révision ; il vous suffit alors de trouver la révision dans laquelle vous avez effacé le fichier ou le dossier en question. Vous pouvez accomplir cette recherche soit visuellement soit en utilisant un autre outil pour examiner le résultat de la commande svn log (via grep ou peut-être via une recherche incrémentale dans un éditeur).

$ cd dossier-parent
$ svn log -v
…
------------------------------------------------------------------------
r808 | paul | 2003-12-26 14:29:40 -0600 (ven. 26 déc 2003) | 3 lignes
Chemins modifiés :
   D /calc/trunk/reel.c
   M /calc/trunk/entier.c

Ajouté les fonctions des transformées de fourier dans entier.c.
Supprimé reel.c car code désormais dans double.c.
…

Dans l'exemple ci-dessus, nous supposons que vous recherchez un fichier effacé nommé reel.c. En examinant le journal du dossier parent, vous avez découvert que ce fichier a été effacé en révision 808. La dernière version du fichier à avoir existé était donc dans la révision précédant celle-ci. Conclusion : vous voulez ressusciter le chemin /calc/trunk/reel.c tel qu'il était en révision 807.

Voilà, c'était la partie difficile : la recherche. Maintenant que vous savez ce que vous voulez récupérer, deux options s'offrent à vous.

Une possibilité serait d'utiliser svn merge pour appliquer la révision 808 « à l'envers » (nous avons déjà parlé de comment revenir sur des modifications dans la section intitulée « Retour en arrière sur des modifications »). Ceci aurait pour effet de ré-ajouter reel.c en tant que modification locale. Le fichier serait alors programmé pour être ajouté et après la propagation le fichier existerait à nouveau dans HEAD.

Cependant, dans cet exemple particulier, ce n'est probablement pas la meilleure stratégie. Appliquer la révision 808 à l'envers programmerait non seulement l'ajout de reel.c, mais le message de propagation indique qu'il reviendrait aussi sur certaines modifications de entier.c, ce que vous ne voulez pas. Vous pourriez certainement fusionner à l'envers la révision 808 et ensuite revenir sur les modifications locales faites dans entier.c, mais cette technique fonctionne mal à plus grande échelle. Que dire, si 90 fichiers avaient été modifiés en révision 808 ?

Une seconde stratégie plus ciblée est de ne pas utiliser svn merge du tout, mais plutôt d'utiliser la commande svn copy. Copiez juste la révision et le chemin exacts (vos deux « coordonnées ») du dépôt vers votre copie de travail :

$ svn copy http://svn.exemple.com/depot/calc/trunk/reel.c@807 ./reel.c

$ svn status
A  +   reel.c

$ svn commit -m "Ressuscité reel.c à partir de la révision 807, /calc/trunk/reel.c."
Ajout         reel.c
Transmission des données .
Révision 1390 propagée.

Le symbole plus dans le résultat de la commande svn status indique que l'élément n'est pas simplement programmé pour ajout, mais programmé pour ajout « avec son historique ». Subversion se souviendra d'où il a été copié. Dans le futur, lancer svn log sur ce fichier parcourra tout son historique en passant par la résurrection du fichier ainsi que tout ce qui précédait la révision 807. En d'autres termes, ce nouveau reel.c n'est pas vraiment nouveau ; c'est un descendant direct du fichier original qui avait été effacé. En général c'est une bonne chose, dont l'utilité est avérée. Si cependant vous vouliez récupérer le fichier sans conserver de lien historique avec l'ancien fichier, la technique suivante fonctionnerait tout aussi bien :

$ svn cat http://svn.exemple.com/depot/calc/trunk/reel.c@807 > ./reel.c

$ svn add reel.c
A         reel.c

$ svn commit -m "Recréé reel.c à partir de la révision 807."
Ajout         reel.c
Transmission des données .
Révision 1390 propagée.

Bien que notre exemple ne porte que sur la résurrection d'un fichier, remarquez que ces mêmes techniques fonctionnent tout aussi bien pour ressusciter des dossiers effacés. Remarquez aussi que cette résurrection ne doit pas forcément avoir lieu dans votre copie de travail ; elle peut avoir lieu entièrement dans le dépôt :

$ svn copy http://svn.exemple.com/depot/calc/trunk/reel.c@807 \
           http://svn.exemple.com/depot/calc/trunk/ \
      -m "Ressuscite reel.c dans la révision 807."
Révision 1390 propagée.

$ svn update
A    reel.c
À la révision 1390.

De la même façon que le terme « ensemble de modifications » est utilisé couramment dans les systèmes de gestion de versions, le terme « sélectionner à la main » pourrait l'être aussi. Il désigne l'action de choisir une liste de modifications particulière au sein d'une branche et de la recopier dans une autre. Sélectionner à la main peut aussi faire référence à l'action de dupliquer un ensemble de modifications (pas nécessairement contiguës !) d'une branche vers une autre. Ceci est en opposition avec des scénarios de fusion plus courants, où l'ensemble de révisions contiguës « suivant » est dupliqué automatiquement.

Pourquoi voudrait-on ne recopier qu'une modification unique ? Cela arrive plus souvent qu'on ne croit. Par exemple, remontons le temps et imaginons que vous n'avez pas encore réintégré votre branche de développement privée dans le tronc. À la machine à café, vous apprenez par hasard que Sally a apporté une modification intéressante à entier.c dans le tronc. Vous reportant à l'historique des propagations du tronc, vous vous apercevez qu'elle a corrigé un bogue crucial en révision 355, qui impacte directement la fonctionnalité sur laquelle vous êtes en train de travailler. Vous n'êtes peut-être pas encore prêt à fusionner toutes les modifications du tronc dans votre branche, mais vous avez certainement besoin de ce correctif pour continuer votre travail.

$ svn diff -c 355 http://svn.exemple.com/depot/calc/trunk

Index: entier.c
===================================================================
--- entier.c	(revision 354)
+++ entier.c	(revision 355)
@@ -147,7 +147,7 @@
     case 6:  sprintf(info->operating_system, "HPFS (OS/2 ou 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, "CP/MM");
+    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;

De la même façon que vous avez utilisé svn diff dans l'exemple précédent pour examiner la révision 355, vous pouvez passer le même paramètre à svn merge :

$ svn merge -c 355 http://svn.exemple.com/depot/calc/trunk
U    entier.c

$ svn status
M      entier.c

Vous pouvez à présent lancer les procédures habituelles de tests, avant de propager cette modification à votre branche. Après la propagation, Subversion marque r355 comme ayant été fusionnée dans la branche, afin qu'une future fusion « magique » synchronisant votre branche avec le tronc sache qu'elle doit sauter r355 (fusionner une même modification dans une même branche aboutit presque toujours à un conflit !).

$ cd ma-branche-calc

$ svn propget svn:mergeinfo .
/trunk:341-349,355

# Remarquez que r355 n'est pas listée comme "éligible" à la fusion,
# parce qu'elle a déjà été fusionnée.
$ svn mergeinfo http://svn.exemple.com/depot/calc/trunk --show-revs eligible
r350
r351
r352
r353
r354
r356
r357
r358
r359
r360

$ svn merge http://svn.example.com/depot/calc/trunk
--- Fusion de r350 à r354 dans '.':
 U   .
U    entier.c
U    Makefile
--- Fusion de r356 à r360 dans '.':
 U   .
U    entier.c
U    bouton.c

Ce type d'utilisation de la copie (ou rétroportage) de correctifs d'une branche à une autre est peut-être la raison la plus répandue pour sélectionner à la main des modifications ; le cas se présente très souvent, par exemple lorsqu'une équipe gère une « branche de production » du logiciel (ce thème est développé dans la section intitulée « Branches de publication »).

Avertissement

Avez-vous remarqué la façon dont, dans le dernier exemple, le lancement de la fusion a eu pour effet l'application de deux ensembles distincts de fusions ? La commande svn merge a appliqué deux correctifs indépendants à votre copie de travail, afin de sauter l'ensemble de modifications 355, que votre branche contenait déjà. Il n'y a rien de mal en soi là-dedans, sauf que ça risque de rendre plus délicate la résolution des conflits. Si le premier groupe de modifications engendre des conflits, vous devrez les résoudre de façon interactive pour que la procédure de fusion puisse continuer et appliquer le deuxième groupe de modifications. Si vous remettez à plus tard un conflit lié à la première vague de modifications, la commande de fusion renverra au final un message d'erreur [23].

Avertissement : bien que svn diff et svn merge soient conceptuellement très similaires, leur syntaxe est différente dans de nombreux cas. Pour plus de détails, reportez-vous au Chapitre 9, Références complètes de Subversion ou consultez svn help. Par exemple, svn merge demande en entrée, en tant que cible, le chemin d'une copie de travail, c'est-à-dire un emplacement où il va appliquer le correctif généré. Si la cible n'est pas spécifiée, il suppose que vous essayez d'exécuter l'une des opérations suivantes :

Si vous fusionnez un dossier et que vous n'avez pas encore spécifié de cible, svn merge suppose qu'il est dans la première situation et essaie d'appliquer les modifications dans votre dossier en cours. Si vous fusionnez un fichier et que ce fichier (ou un fichier du même nom) existe dans votre dossier de travail en cours, svn merge suppose qu'il est dans la seconde situation et essaie d'appliquer les modifications au fichier local du même nom.

Nous venons de voir des exemples d'utilisation de la commande svn merge et nous allons bientôt en voir plusieurs autres. Si vous n'avez pas bien assimilé le le fonctionnement des fusions, rassurez-vous, vous n'êtes pas un cas isolé. De nombreux utilisateurs (en particulier ceux qui découvrent la gestion de versions) commencent par une phase de perplexité au sujet de la syntaxe de la commande, ainsi que quand et comment utiliser cette fonctionnalité. Mais, en fait, cette commande est bien plus simple que vous ne le pensez ! Il y a une technique très simple pour comprendre comment svn merge agit.

La raison principale de la confusion est le nom de la commande. Le terme « merge » indique en quelque sorte que les branches vont être combinées, ou qu'un mystérieux mélange des données va avoir lieu. Ce n'est pas le cas. Un nom plus approprié pour cette commande aurait pu être « comparer-et-appliquer », car c'est là tout ce qui se passe : deux arborescences sont comparées et les différences sont appliquées à une copie de travail.

Si vous utilisez svn merge pour effectuer de simples copies de modifications entre branches, elle fait généralement ce qu'il faut automatiquement. Par exemple, une commande telle que :

$ svn merge http://svn.exemple.com/depot/calc/une-branche

tente de dupliquer toutes les modifications faites dans une-branche vers votre répertoire de travail actuel, qui est sans doute une copie de travail partageant des liens historiques avec la branche. La commande est suffisamment intelligente pour ne copier que les modifications que votre copie de travail ne possède pas encore. Si vous répétez cette commande une fois par semaine, elle ne copie que les modifications « les plus récentes » qui ont eu lieu depuis la dernière fusion.

Si vous choisissez d'utiliser la commande svn merge dans sa version intégrale en lui fournissant les groupes de révisions spécifiques à copier, la commande prend trois paramètres :

Une fois ces trois paramètres fournis, les deux arborescences sont comparées et les différences sont appliquées à la copie de travail cible en tant que modifications locales. Une fois que la commande s'est terminée, le résultat est le même que si vous aviez édité les fichiers à la main ou lancé diverses commandes svn add ou svn delete vous-même. Si le résultat vous plaît, vous pouvez le propager. S'il ne vous plaît pas, vous pouvez toujours lancer svn revert pour revenir en arrière sur toutes les modifications.

La syntaxe de svn merge est assez flexible quant à la façon de spécifier les trois paramètres. Voici quelques exemples :

$ svn merge http://svn.exemple.com/depot/branche1@150 \
			 http://svn.exemple.com/depot/branche2@212 \
			 ma-copie-de-travail

$ svn merge -r 100:200 http://svn.exemple.com/depot/trunk ma-copie-de-travail

$ svn merge -r 100:200 http://svn.exemple.com/depot/trunk

La première syntaxe liste les trois arguments de façon explicite, spécifiant chaque arborescence sous la forme URL@REV et incluant la copie de travail cible. La deuxième syntaxe peut être utilisée comme raccourci pour les cas où vous comparez des révisions différentes de la même URL. La dernière syntaxe indique que le paramètre copie de travail est optionnel ; s'il est omis, elle utilise par défaut le répertoire en cours.

Si le premier exemple donne la syntaxe « complète » de svn merge, celle-ci doit être utilisée avec grande prudence ; elle peut en effet aboutir à des fusions qui n'enregistrent pas la moindre méta-donnée svn:mergeinfo. Le paragraphe suivant évoque ceci plus en détail.

Subversion essaye de générer des métadonnées de fusion dès qu'il le peut, afin de rendre plus intelligentes les invocations suivantes de svn merge. Néanmoins, il reste des situations où les données svn:mergeinfo ne sont ni créées ni modifiées. Pensez à être prudent avec les scénarios suivants :

Tout comme la commande svn update, svn merge applique les modifications à votre copie de travail. Elle est donc aussi susceptible de créer des conflits. Cependant, les conflits engendrés par svn merge sont parfois différents et ce paragraphe va expliquer ces différences.

Pour commencer, supposons que votre copie de travail n'a pas de modification locale en cours. Quand vous lancez svn update pour la mettre à jour à une révision particulière, les modifications envoyées par le serveur s'appliquent toujours « proprement » à votre copie de travail. Le serveur génère le delta en comparant deux arborescences : d'une part un instantané virtuel de votre copie de travail, d'autre part l'arborescence de la révision qui vous intéresse. Parce que la partie gauche de la comparaison est parfaitement égale à ce que vous avez déjà, il est garanti que le delta va convertir correctement votre copie de travail en l'arborescence de droite.

Mais svn merge ne dispose pas de telles garanties et peut être bien plus chaotique : l'utilisateur avancé peut demander au serveur de comparer n'importe quelle paire d'arborescences, même des arborescences n'ayant aucun rapport avec la copie de travail ! Cela laisse potentiellement beaucoup de place à l'erreur humaine. Les utilisateurs vont parfois comparer deux arborescences qui ne sont pas les bonnes, créant ainsi un delta qui ne s'appliquera pas proprement. svn merge fera de son mieux pour appliquer la plus grande partie possible du delta, mais ça risque d'être impossible pour certains morceaux. De la même façon que la commande Unix patch se plaint parfois de « morceaux ratés » (failed hunks), svn merge se plaint de « cibles manquantes omises » (skipped targets) :

$ svn merge -r 1288:1351 http://svn.exemple.com/depot/branche
U    truc.c
U    bidule.c
Cible manquante omise : 'baz.c'
U    blob.c
U    machin.h
Conflit découvert dans 'glorb.h'.
Sélectionner : (p) report, (df) diff complet, (e) édite,
        (h) aide pour plus d'options :

Dans l'exemple précédent, il est possible que baz.c existe dans les deux instantanés de la branche en question et que le delta résultant tente de modifier le contenu du fichier, mais que le fichier n'existe pas dans la copie de travail. Quoi qu'il en soit, le message « Cible manquante omise » signifie que l'utilisateur compare probablement les mauvaises arborescences ; c'est le signe classique d'une erreur de l'utilisateur. Quand ça arrive, il est facile de revenir en arrière de manière récursive sur toutes les modifications créées par la fusion (svn revert . --recursive), d'effacer tout fichier ou dossier non suivi en versions restant après le retour en arrière et de relancer svn merge avec des paramètres différents.

Remarquez également que l'exemple précédent indique un conflit sur glorb.h. Nous avons déjà mentionné que la copie de travail n'a pas de modifications locales en cours : comment peut-il donc y avoir conflit ? Encore une fois, parce que l'utilisateur peut utiliser svn merge pour définir et appliquer n'importe quel vieux delta à la copie de travail, ce delta risque de contenir des modifications textuelles qui ne s'appliquent pas proprement à un fichier de la copie de travail, même si ce fichier n'a pas de modifications locales en cours.

Une autre petite différence entre svn update et svn merge concerne les noms des fichiers textes créés quand un conflit a lieu. Dans la section intitulée « Résoudre les conflits (fusionner des modifications) », nous avons vu qu'une mise à jour génère des fichiers appelés nomdufichier.mine, nomdufichier.rOLDREV et nomdufichier.rNEWREV. Cependant, quand svn merge cause un conflit, il crée trois fichiers appelés nomdufichier.working, nomdufichier.left et nomdufichier.right. Dans ce cas, les termes « left » et « right » décrivent de quel côté de la double comparaison d'arborescences le fichier venait. Dans tous les cas, ces noms de fichiers différents vous aideront à distinguer les conflits résultant d'une mise à jour de ceux résultant d'une fusion.

Il peut parfois y avoir un ensemble de modifications particulier dont vous ne voulez pas qu'il soit fusionné automatiquement. Par exemple, peut–être que l'habitude dans votre équipe est d'effectuer tout nouveau travail de développement dans /trunk, mais d'être plus conservateur en ce qui concerne le rétroportage des modifications vers une branche stable que vous utilisez pour la publication. À l'extrême, vous pouvez sélectionner à la main des ensembles de modifications individuels du tronc à porter vers la branche : juste les changements qui sont suffisamment stables pour être acceptables. Peut-être que les choses ne sont pas aussi strictes après tout ; peut-être que la plupart du temps vous aimeriez juste laisser svn merge fusionner automatiquement la plupart des modifications du tronc vers la branche. Dans ce cas, il vous faudrait une façon de masquer quelques modifications particulières, c'est-à-dire d'empêcher qu'elles ne soient fusionnées automatiquement.

Dans Subversion 1.5, la seule manière de bloquer une liste de modifications est de faire croire au système que cette modification a déjà été fusionnée. Pour cela, il est possible de lancer la commande de fusion avec l'option --record-only :

$ cd ma-branche-calc

$ svn propget svn:mergeinfo .
/trunk:1680-3305

# Marquons l'ensemble de modifications r3328 comme déjà fusionné.
$ svn merge -c 3328 --record-only http://svn.exemple.com/depot/calc/tronc

$ svn status
M     .

$ svn propget svn:mergeinfo .
/trunk:1680-3305,3328

$ svn commit -m "Empêche r3328 d'être fusionnée vers la branche."
…

Cette technique fonctionne, mais elle est un petit peu dangereuse. Le problème principal est que nous ne faisons pas clairement la différence entre « J'ai déjà cette modification » et « Je n'ai pas cette modification ». En fait, nous mentons au système, en lui faisant croire que la modification a déjà été fusionnée. Ce qui transfère vers vous, l'utilisateur, la responsabilité de vous rappeler que la modification n'a en fait pas été fusionnée, qu'elle n'était tout simplement pas voulue. Il n'y a pas moyen de demander à Subversion la liste des « listes de modifications bloquées ». Si vous voulez en conserver la trace (afin de pouvoir les débloquer un jour), vous devrez les consigner dans un fichier texte quelque part, ou peut-être dans une propriété inventée de toutes pièces pour l'occasion. Dans Subversion 1.5, malheureusement, c'est la seule façon de gérer les révisions bloquées ; dans les versions futures il est prévu d'en améliorer l'interface.

Une des fonctionnalités principales de tout système de gestion de versions est de conserver la trace de qui a modifié quoi et quand ils l'ont fait. Les commandes svn log et svn blame sont les outils adaptés pour cela : quand on les applique à des fichiers individuels, ils renvoient non seulement l'historique des ensembles de modifications qui ont touché le fichier, mais aussi exactement quel utilisateur a écrit quelle ligne de code et quand il l'a fait.

Cependant, quand des modifications commencent à être copiées entre des branches, les choses commencent à se compliquer. Par exemple, si vous interrogiez svn log sur l'historique de votre branche fonctionnelle, il renverrait exactement toutes les révisions qui ont touché cette branche :

$ cd ma-branche-calc
$ svn log -q
------------------------------------------------------------------------
r390 | utilisateur | 2002-11-22 11:01:57 -0600 (ven. 22 nov. 2002) | 1 ligne
------------------------------------------------------------------------
r388 | utilisateur | 2002-11-21 05:20:00 -0600 (jeu. 21 nov. 2002) | 2 lignes
------------------------------------------------------------------------
r381 | utilisateur | 2002-11-20 15:07:06 -0600 (mer. 20 nov. 2002) | 2 lignes
------------------------------------------------------------------------
r359 | utilisateur | 2002-11-19 19:19:20 -0600 (mar. 19 nov. 2002) | 2 lignes
------------------------------------------------------------------------
r357 | utilisateur | 2002-11-15 14:29:52 -0600 (ven. 15 nov. 2002) | 2 lignes
------------------------------------------------------------------------
r343 | utilisateur | 2002-11-07 13:50:10 -0600 (jeu. 07 nov. 2002) | 2 lignes
------------------------------------------------------------------------
r341 | utilisateur | 2002-11-03 07:17:16 -0600 (dim. 03 nov. 2002) | 2 lignes
------------------------------------------------------------------------
r303 | sally | 2002-10-29 21:14:35 -0600 (mar. 29 oct. 2002) | 2 lignes
------------------------------------------------------------------------
r98 | sally | 2002-02-22 15:35:29 -0600 (ven. 22 fev. 2002) | 2 lignes
------------------------------------------------------------------------

Mais est-ce bien là une description adéquate de tous les changements qui ont eu lieu sur cette branche ? Ce qui manque ici, c'est le fait que les révisions 390, 381 et 357 résultaient en fait de fusions en provenance du tronc. Si vous regardez plus en détail l'historique d'une de ces révisions, vous ne verrez nulle part les multiples ensembles de modifications du tronc qui ont été reportés sur la branche :

$ svn log -v -r 390
------------------------------------------------------------------------
r390 | utilisateur | 2002-11-22 11:01:57 -0600 (ven. 22 nov. 2002) | 1 ligne
Chemins modifiés :
   M /branches/ma-branche-calc/bouton.c
   M /branches/ma-branche-calc/LISEZMOI

Fusion finale des modifications du tronc dans ma-branche-calc.

Il se trouve que nous savons que cette fusion vers la branche n'était qu'une fusion de modifications du tronc. Comment pouvons-nous également voir ces modifications du tronc ? La réponse est d'utiliser l'option --use-merge-history (-g). Cette option donne le détail des modifications « filles » qui faisaient partie de la fusion.

$ svn log -v -r 390 -g
------------------------------------------------------------------------
r390 | utilisateur | 2002-11-22 11:01:57 -0600 (ven. 22 nov. 2002) | 1 ligne
Chemins modifiés :
   M /branches/ma-branche-calc/bouton.c
   M /branches/ma-branche-calc/LISEZMOI

Fusion finale des modifications du tronc dans ma-branche-calc.
------------------------------------------------------------------------
r383 | sally | 2002-11-21 03:19:00 -0600 (jeu. 21 nov. 2002) | 2 lignes
Chemins modifiés :
   M /branches/ma-branche-calc/bouton.c
Fusion via: r390

Corrige l'erreur d'inversion graphique sur le bouton.
------------------------------------------------------------------------
r382 | sally | 2002-11-20 16:57:06 -0600 (mer. 20 nov. 2002) | 2 lignes
Chemins modifiés :
   M /branches/ma-branche-calc/LISEZMOI
Fusion via: r390

Documente mon dernier correctif dans LISEZMOI.

En forçant l'opération svn log à utiliser l'historique des fusions, nous obtenons non seulement la révision que nous avions demandé (r390), mais aussi les deux révisions qui l'accompagnaient — deux modifications du tronc faites par Sally. C'est une image bien plus complète de l'historique !

La commande svn blame accepte également l'option --use-merge-history (-g). Si cette option est omise, quelqu'un qui regarderait un relevé annoté ligne par ligne pour bouton.c risquerait d'avoir l'impression erronée que vous êtes responsable des lignes qui ont corrigé une certaine erreur :

$ svn blame bouton.c
…
   390    utilisateur  retval = inverse_func(button, path);
   390    utilisateur  return retval;
   390    utilisateur  }
…

Et bien qu'il soit vrai que vous avez propagé ces trois lignes lors de la révision 390, deux d'entre elles ont en fait été écrites par Sally auparavant, en révision 383 :

$ svn blame bouton.c -g
…
G    383    sally        retval = inverse_func(button, path);
G    383    sally        return retval;
     390    utilisateur  }
…

À présent, nous savons qui doit réellement être tenu responsable pour ces deux lignes de code !

Quand vous discutez avec un développeur Subversion, il est très possible qu'il fasse référence au terme d'ascendance. Ce mot est utilisé pour décrire la relation entre deux objets dans un dépôt : s'ils sont liés l'un à l'autre, un des objets est alors qualifié d'ancêtre de l'autre.

Par exemple, supposons que vous propagiez la révision 100 qui contient une modification d'un fichier truc.c. Dès lors, truc.c@99 est un « ancêtre » de truc.c@100. En revanche, supposons que vous propagiez la suppression de truc.c en révision 101 et ensuite l'ajout d'un nouveau fichier du même nom en révision 102. Dans ce cas, truc.c@99 et truc.c@102 pourraient sembler apparentés (ils ont le même chemin), mais en fait ce sont des objets complètement différents au sein du dépôt. Ils ne partagent aucun historique ou « ascendance ».

Nous abordons ce point pour mettre en évidence une différence importante entre svn diff et svn merge. La première commande ignore toute ascendance, tandis que la seconde y est particulièrement sensible. Par exemple, si vous demandez à svn diff de comparer les révisions 99 et 102 de truc.c, vous obtenez des différences basées sur les lignes ; la commande svn diff compare deux chemins à l'aveugle. Mais si vous demandez à svn merge de comparer les deux mêmes objets, il remarque qu'ils ne sont pas liés et essaie d'abord de supprimer l'ancien fichier, puis d'ajouter le nouveau fichier ; le résultat indique une suppression puis un ajout :

D    truc.c
A    truc.c

La plupart des fusions impliquent de comparer des arborescences qui ont une relation d'ascendance de l'une à l'autre ; c'est pourquoi svn merge a ce comportement par défaut. Cependant, à l'occasion, vous pourriez vouloir que la commande svn merge compare deux arborescences sans relation d'ascendance entre elles. Par exemple, vous avez peut-être importé deux arborescences de code source représentant des publications différentes de deux fournisseurs d'un projet logiciel (voir la section intitulée « Branches fournisseur »). Si vous demandez à svn merge de comparer les deux arborescences, vous verrez la première arborescence complètement supprimée, puis l'ajout de la seconde arborescence toute entière ! Dans ce genre de situations, vous attendez de svn merge qu'il effectue une comparaison basée sur les chemins uniquement, en ignorant toute relation entre les fichiers et les dossiers. Ajoutez l'option --ignore-ancestry à votre commande svn merge et elle se comportera comme svn diff (et inversement, l'option --notice-ancestry fera se comporter svn diff comme la commande svn merge).

Il arrive souvent qu'on veuille réorganiser le code source, en particulier dans les projets logiciels en Java. Les fichiers et les répertoires sont déplacés et renommés, causant souvent de grandes perturbations pour tous ceux qui travaillent sur le projet. Ceci semble être le cas idéal où utiliser une branche, n'est-ce pas ? Créer une branche, réorganiser les choses, et ensuite fusionner la branche vers le tronc, non ?

Hélas, ce scénario ne fonctionne pas si bien pour le moment et est même considéré comme l'une des faiblesses de Subversion. Le problème est que la commande svn update de Subversion n'est pas aussi robuste qu'elle le devrait, en particulier en ce qui concerne les opérations de copies et de déplacements.

Quand vous utilisez svn copy pour dupliquer un fichier, le dépôt se souvient d'où venait le nouveau fichier, mais il ne transmet pas cette information au client qui lance svn update ou svn merge. Au lieu de dire au client « Copie ce fichier que tu as déjà vers ce nouvel emplacement », il envoie un fichier entièrement nouveau. Ceci peut engendrer des problèmes, en particulier parce que le fonctionnement est le même pour les fichiers renommés. Un fait peu connu à propos de Subversion est qu'il lui manque de « vrais renommages » - la commande svn move n'est rien de plus que l'agrégation de svn copy et svn delete.

Par exemple, supposons que pendant que vous travaillez sur votre branche privée, vous renommez entier.c en tout.c. Ce faisant, vous avez en fait créé un nouveau fichier dans votre branche, qui est une copie du fichier original, et vous avez supprimé le fichier original. Pendant ce temps, dans le tronc, Sally a propagé des améliorations d'entier.c. C'est alors que vous décidez de fusionner votre branche vers le tronc :

$ cd calc/trunk

$ svn merge --reintegrate http://svn.exemple.com/depot/calc/branches/ma-branche-calc
--- Fusion des différences des URLs du dépôt vers '.' :
D   entier.c
A   tout.c
U   .

Ceci n'a pas l'air si mal à première vue, mais ce n'est probablement pas ce à quoi Sally ou vous vous attendiez. L'opération de fusion a supprimé la version la plus récente du fichier entier.c (celle qui contenait les dernières modifications de Sally) et a ajouté machinalement votre nouveau fichier tout.c, qui est une copie de l'ancien fichier entier.c. Le résultat final est que la fusion de votre « renommage » a supprimé de la dernière révision les modifications récentes de Sally !

Il ne s'agit pas d'une vraie perte de données. Les modifications de Sally font toujours partie de l'historique du dépôt, mais le déroulement exact des événements n'est peut-être pas immédiatement évident. La morale de l'histoire est que jusqu'à ce que Subversion ne s'améliore, vous devrez faire très attention aux fusions de copies et de renommages d'une branche à une autre.

Si vous venez de mettre à niveau votre serveur Subversion à la version 1.5 ou plus, il existe un risque significatif que les clients Subversion pré-1.5 sèment la pagaille dans votre suivi automatique des fusions. Pourquoi ? Quand un client Subversion pré-1.5 exécute svn merge, il ne modifie pas du tout la valeur de la propriété svn:mergeinfo. La propagation qui s'ensuit, bien qu'elle soit le résultat d'une fusion, n'envoie donc aucune indication au dépôt au sujet des modifications dupliquées — ces informations sont perdues. Par la suite, lorsque des clients « qui prennent en compte les fusions » tentent d'effectuer une fusion automatique, ils rencontreront probablement toutes sortes de conflits résultant des fusions répétées.

Si votre équipe et vous dépendez des fonctionnalités de suivi des fusions de Subversion, vous voudrez peut-être configurer votre dépôt pour qu'il empêche les anciens clients de propager des modifications. La méthode la plus simple est d'examiner le paramètre « capabilities » dans la procédure automatique de début de propagation. Si le client indique être capable de gérer les mergeinfo, la procédure automatique peut l'autoriser à commencer la propagation. Si le client n'indique pas en être capable, la procédure automatique doit lui refuser la propagation. Nous en apprendrons plus sur les procédures automatiques dans le chapitre suivant ; voir la section intitulée « Mise en place des procédures automatiques » et start-commit pour les détails.

En fin de compte, la fonctionnalité de suivi des fusions de Subversion possède une mécanique interne extrêmement complexe et la propriété svn:mergeinfo est la seule lorgnette dont l'utilisateur dispose pour observer cette mécanique. Parce que cette fonctionnalité est relativement nouvelle, un certain nombre de cas litigieux et de comportements potentiellement inattendus risquent d'être rencontrés.

Par exemple, mergeinfo sera parfois générée lors d'une simple commande svn copy ou svn move. Parfois mergeinfo apparaîtra sur des fichiers dont vous n'auriez pas imaginé qu'ils soient touchés par une opération. Parfois mergeinfo ne sera pas du tout générée, contrairement à ce que vous attendiez. De plus, la gestion de la métadonnée mergeinfo a tout un ensemble de taxonomies et de comportements qui lui sont associés, tels que des mergeinfo « explicites » par opposition à « implicites », des révisions « opérationnelles » par opposition à « non-opérationnelles », des mécanismes spécifiques d'« élision » de mergeinfo et même d'« héritage » de répertoires parents à sous-répertoires.

Nous avons choisi de ne pas couvrir en détail ces sujets dans ce livre pour plusieurs raisons. Premièrement, l'utilisateur moyen serait totalement submergé par le niveau de détail disponible. Deuxièmement, au fur et à mesure que Subversion s'améliore, nous estimons que l'utilisateur moyen ne devrait pas avoir à comprendre ces concepts ; en tant que détails d'implémentation agaçants, ils finiront par disparaître à l'arrière-plan. Malgré tout ce qui vient d'être dit, si vous appréciez ce genre de choses, vous en trouverez une formidable vue d'ensemble dans un article posté sur le site internet de Collabnet : http://www.collab.net/community/subversion/articles/merge-info.html.

Pour le moment, si vous voulez rester à l'écart des bogues et autres comportements inattendus des fusions automatiques, l'article de Collabnet recommande que vous vous en teniez simplement aux bonnes pratiques suivantes :

Une fois encore, svn copy vient à la rescousse. Si vous voulez créer un instantané de /calc/trunk identique à ce qu'il est dans la révision HEAD, faites-en une copie :

$ svn copy http://svn.exemple.com/depot/calc/trunk \
           http://svn.exemple.com/depot/calc/tags/version-1.0 \
      -m "Étiquetage de la version 1.0 du projet 'calc'."

Révision 902 propagée.

Cet exemple présuppose qu'un répertoire /calc/tags existe déjà (s'il n'existe pas, vous pouvez le créer en utilisant svn mkdir). Une fois la copie terminée, le nouveau dossier version-1.0 sera pour toujours un instantané du dossier /trunk tel qu'il était en révision HEAD au moment où vous avez effectué la copie. Bien sûr, vous voudriez peut-être être plus précis quant à quelle révision vous copiez, au cas où quelqu'un d'autre aurait propagé des modifications au projet pendant que vous regardiez ailleurs. Donc si vous savez que la révision 901 de /calc/trunk est exactement l'instantané que vous voulez, vous pouvez le spécifier en passant -r 901 à la commande svn copy.

Mais attendez un moment : cette procédure de création d'étiquette, n'est-ce pas la même procédure que nous avons utilisé pour créer une branche ? En fait, oui. Dans Subversion, il n'y pas de différence entre une étiquette et une branche. Toutes deux ne sont que des répertoires ordinaires qui sont créés par copie. Comme pour les branches, la seule raison qui fasse qu'un répertoire copié soit une « étiquette » est que les humains ont décidé de le traiter de cette façon : aussi longtemps que personne ne propage de modification à ce répertoire, il reste un instantané. Si les gens commencent à y propager des choses, il devient une branche.

Si vous administrez un dépôt, il y a deux approches possibles pour gérer les étiquettes. La première approche est une politique de « non-intervention » : en tant que convention définie pour le projet, vous décidez où vos étiquettes sont placées et vous vous assurez que tous les utilisateurs savent comment traiter les répertoires qu'ils copient (c'est-à-dire que vous vous assurez qu'ils savent qu'ils ne doivent rien y propager). La seconde approche est plus paranoïaque : vous pouvez utiliser un des contrôles d'accès fournis avec Subversion pour empêcher que quiconque ne puisse faire autre chose dans la zone des étiquettes que d'y créer de nouvelles copies (voir le Chapitre 6, Configuration du serveur). L'approche paranoïaque n'est cependant pas nécessaire, en général. Si un utilisateur propage accidentellement une modification à un répertoire d'étiquettes, vous pouvez simplement revenir en arrière sur cette modification comme expliqué dans le paragraphe précédent. C'est ça la gestion de versions, après tout !

Parfois vous voudrez peut-être que votre « instantané » soit plus compliqué qu'un simple répertoire à une unique révision donnée.

Par exemple, imaginons que votre projet est bien plus vaste que notre exemple calc : supposons qu'il contient un bon nombre de sous-répertoires et bien plus de fichiers encore. Au cours de votre travail, vous pouvez très bien décider que vous avez besoin de créer une copie de travail destinée à des fonctionnalités particulières et à des corrections de bogues. Pour cela vous pouvez antidater de manière sélective des fichiers ou dossiers à des révisions données (en utilisant généreusement svn update avec l'option -r), déporter des fichiers et des dossiers vers des branches particulières (au moyen de svn switch) ou même effectuer manuellement un tas de modifications locales. Quand vous en avez terminé, votre copie de travail est un vrai bazar, fait d'emplacements du dépôt à des révisions différentes. Mais après l'avoir testée, vous êtes alors certain que c'est l'exacte combinaison de données que vous vouliez étiqueter.

C'est alors le moment de prendre un cliché. Copier une URL vers une autre ne fonctionnera pas cette fois. Dans le cas présent, vous voulez prendre un cliché de l'arrangement exact de votre copie de travail et le placer dans le dépôt. Par chance, svn copy possède en fait quatre usages différents (au sujet desquels vous pouvez obtenir des informations au Chapitre 9, Références complètes de Subversion), dont la possibilité de copier une arborescence de travail vers le dépôt :

$ ls
ma-copie-de-travail/

$ svn copy ma-copie-de-travail \
           http://svn.exemple.com/depot/calc/tags/mon-etiquette \
           -m "Étiquette l'état de ma copie de travail existante."

Révision 940 propagée.

Désormais il y a un nouveau répertoire dans le dépôt, /calc/tags/mon-etiquette, qui est un instantané exact de votre copie de travail : révisions mixtes, URL, modifications locales et tout et tout…

D'autres utilisateurs ont trouvé des usages intéressants pour cette fonctionnalité. Il y a parfois des situations où votre copie de travail contient un paquet de modifications locales que vous aimeriez montrer à un collaborateur. Au lieu de lancer svn diff et d'envoyer un fichier patch (qui ne listera pas les modifications de répertoires, de liens symboliques ou de propriétés), vous pouvez utiliser svn copy pour « envoyer » votre copie de travail vers une zone privée du dépôt. Votre collaborateur peut ensuite soit extraire une copie carbone de votre copie de travail, soit utiliser svn merge pour recevoir exactement vos modifications.

Bien que ce soit une jolie méthode pour mettre à disposition un instantané rapide de votre copie de travail, remarquez que ce n'est pas une bonne manière de créer une branche initialement. La création de branche devrait être un évènement en soi, tandis que cette méthode combine la création d'une branche avec des modifications supplémentaires apportées aux fichiers, le tout au sein d'une seule révision. Ceci rend très difficile (à terme) d'identifier un unique numéro de révision en tant que point de création de la branche.

Il existe des méthodes standard recommandées pour structurer un dépôt. La plupart des gens créent un répertoire trunk pour la « ligne de développement principale » (le tronc), un répertoire branches qui contiendra les copies de branches et un répertoire tags qui contiendra les copies étiquetées. Si un dépôt ne comprend qu'un seul projet, les gens créent souvent les dossiers suivants à la racine :

/trunk
/branches
/tags

Si un dépôt contient plusieurs projets, les administrateurs indexent généralement la structure du dépôt par projet (voir la section intitulée « Stratégies d'organisation d'un dépôt » pour en savoir plus sur les « dossiers racine d'un projet ») :

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

Bien sûr, vous restez libre d'ignorer ces agencements courants. Vous pouvez créer toutes sortes de variantes, selon ce qui fonctionne le mieux pour vous ou pour votre équipe. Souvenez-vous que quel que soit votre choix, ce n'est pas un engagement définitif. Vous pouvez réorganiser votre dépôt à tout moment. Parce que les branches et les étiquettes sont des répertoires ordinaires, la commande svn move peut les déplacer ou les renommer selon vos désirs. Passer d'un agencement à un autre consiste juste à lancer une série d'opérations de déplacement côté serveur ; si vous n'aimez pas la façon dont les choses sont organisées dans le dépôt, modifiez juste leur agencement.

Souvenez-vous néanmoins que bien qu'il soit facile de déplacer des dossiers, vous devez aussi rester attentif à vos utilisateurs. Vos modifications sont susceptibles de déboussoler ceux qui ont des copies de travail existantes. Si un utilisateur a une copie de travail d'un répertoire donné du dépôt, votre opération svn move risque de supprimer ce chemin de la révision la plus récente. Lorsque par la suite l'utilisateur lancera svn update, il se verra annoncer que sa copie de travail représente un chemin qui n'existe plus et sera contraint d'effectuer un svn switch vers le nouvel emplacement.

Une autre fonctionnalité intéressante liée aux principes de fonctionnement de Subversion est que les branches et les étiquettes peuvent avoir des durées de vie limitées, tout comme n'importe quel autre élément suivi en versions. Par exemple, supposons que vous avez enfin terminé votre travail sur votre branche personnelle du projet calc. Après avoir fusionné toutes vos modifications vers /calc/trunk, le répertoire contenant votre branche privée n'a plus de raison d'exister :

$ svn delete http://svn.exemple.com/depot/calc/branches/ma-branche-calc \
             -m "Suppression d'une branche obsolète du projet calc."

Révision 375 propagée.

Et maintenant votre branche a disparu. Bien sûr, elle n'a pas vraiment disparu : le répertoire est juste absent de la révision HEAD, ne gênant plus personne. Si vous utilisez svn checkout, svn switch ou svn list pour examiner une révision plus ancienne, vous pourrez toujours voir votre vieille branche.

Si la navigation dans votre répertoire supprimé ne vous suffit pas, vous pouvez toujours le récupérer. Ressusciter des données est très facile dans Subversion. S'il y a un dossier (ou un fichier) supprimé que vous aimeriez faire réapparaître dans HEAD, utilisez simplement svn copy pour le copier depuis l'ancienne révision.

$ svn copy http://svn.exemple.com/depot/calc/branches/ma-branche-calc@374 \
           http://svn.exemple.com/depot/calc/branches/ma-branche-calc \
           -m "Restaure ma-branche-calc."

Révision 376 propagée.

Dans notre exemple, votre branche personnelle a eu une durée de vie relativement limitée : vous l'aviez peut-être créée pour corriger un bogue ou implémenter une nouvelle fonctionnalité. Quand votre tâche est finie, il en va de même pour la branche. Cependant, en développement logiciel, il est aussi courant d'avoir deux branches « principales » côte à côte pour de très longues périodes. Par exemple, supposons que le moment est venu de publier une version stable du projet calc pour le public. Vous savez qu'il faudra quelques mois pour éliminer les bogues du logiciel. Vous ne voulez pas que les gens ajoutent de nouvelles fonctionnalités au projet, mais vous ne voulez pas non plus dire à tous les développeurs d'arrêter de programmer. Donc à la place, vous créez une branche « stable » du logiciel qui ne changera pas beaucoup :

$ svn copy http://svn.exemple.com/depot/calc/trunk \
           http://svn.exemple.com/depot/calc/branches/stable-1.0 \
           -m "Création de la branche stable du projet calc."

Révision 377 propagée.

Dès lors les développeurs sont libres de continuer à ajouter des fonctionnalités de pointe (ou expérimentales) à /calc/trunk et vous pouvez poser comme convention pour le projet que seules les corrections de bogues seront propagées dans /calc/branches/stable-1.0. C'est-à-dire qu'au fur et à mesure que les gens continueront de travailler sur le tronc, quelqu'un reportera de façon sélective les corrections de bogues vers la branche stable. Même après que la branche stable aura été publiée, vous continuerez probablement à maintenir la branche pendant longtemps, c'est-à-dire pour aussi longtemps que vous continuerez à fournir aux clients un support sur cette version. Nous évoquons ceci plus en détails dans le prochain paragraphe.

En général un logiciel suit un cycle de vie classique, répétant les trois étapes suivantes en boucle : code, test, publication. Il y a deux problèmes avec ce processus. Premièrement, les développeurs doivent continuer à écrire de nouvelles fonctionnalités pendant que les équipes d'assurance qualité prennent le temps de tester des versions supposées stables du logiciel. Les nouveaux développements ne peuvent pas s'arrêter pendant que le logiciel est en cours de test. Deuxièmement, l'équipe doit presque toujours effectuer le support des versions anciennes et publiées du logiciel ; si un bogue est découvert dans le code le plus récent, il existe probablement aussi dans les versions qui ont été publiées et les clients voudront obtenir le correctif pour ce bogue sans avoir à attendre la publication d'une nouvelle version majeure.

C'est là où la gestion de versions peut s'avérer utile. La procédure standard ressemble à ceci :

Ce processus entier se répète au fur et à mesure que le logiciel gagne en maturité : quand le travail pour la version 2.0 est terminé, une nouvelle branche de publication 2.0 est créée, testée, étiquetée et finalement publiée. Au bout de quelques années, le dépôt finit par avoir un certain nombre de branches de publication en mode « maintenance » et un certain nombre d'étiquettes représentant les versions finales publiées.

Une branche fonctionnelle est la sorte de branche qui est l'exemple dominant dans ce chapitre (celle sur laquelle vous travailliez pendant que Sally continuait à travailler sur /trunk). C'est une branche temporaire créée pour travailler sur un changement complexe sans interférer avec la stabilité de /trunk. À la différence des branches de publication (dont le support doit parfois être prolongé très longtemps), les branches fonctionnelles naissent, sont utilisées pendant un temps, sont fusionnées vers le tronc et sont finalement supprimées. Elles ont une utilité limitée dans le temps.

Encore une fois, les stratégies varient énormément au sujet du moment approprié pour créer une branche fonctionnelle. Certains projets n'utilisent jamais de branche fonctionnelle : n'importe qui peut propager des modifications à /trunk. L'avantage de ce système est qu'il est simple : personne n'a besoin d'être formé aux branches ou aux fusions. L'inconvénient est que le code du tronc est souvent instable ou inutilisable. D'autres projets utilisent les branches à l'extrême : une modification n'est jamais propagée directement dans le tronc. Même les modifications les plus triviales sont faites au sein d'une branche à courte durée de vie, vérifiées attentivement, puis fusionnées vers le tronc. La branche est ensuite supprimée. Ce système garantit que le tronc restera exceptionnellement stable et utilisable à tout moment, mais aux dépens des coûts de gestion liés à cette procédure très lourde.

La plupart des projets choisissent une approche à mi-chemin entre les deux. Ils insistent généralement pour qu'à tout moment /trunk puisse être compilé et passe avec succès les tests de régression. Une branche fonctionnelle n'est nécessaire que quand une modification nécessite un grand nombre de propagations susceptibles de déstabiliser le tronc. Une bonne méthode empirique est de se poser la question suivante : si le développeur travaillait pendant plusieurs jours en isolation et ensuite propageait cette grosse modification en une seule fois (afin que /trunk ne soit jamais déstabilisé), est-ce que ce serait une modification trop grosse à vérifier ? Si la réponse à cette question est « oui », alors la modification devrait être développée sur une branche fonctionnelle. Au fur et à mesure que le développeur propage ses modifications incrémentales dans la branche, elles peuvent facilement être vérifiées par ses pairs.

Finalement, il reste la question de savoir quelle est la meilleure méthode pour garder une branche synchronisée avec le tronc au fur et à mesure que le travail avance. Comme nous l'avons mentionné précédemment, il est très risqué de travailler sur une branche pendant des semaines ou des mois ; le tronc continuera peut-être à recevoir des modifications, au point que les deux lignes de développement risquent de s'éloigner tellement l'une de l'autre qu'essayer de fusionner la branche vers le tronc devienne un cauchemar.

Le mieux pour éviter une telle situation est de fusionner régulièrement les modifications du tronc vers la branche. Faites-en une habitude : une fois par semaine, fusionnez les modifications du tronc de la semaine précédente vers la branche.

Le moment arrivera où vous serez prêt à fusionner la branche fonctionnelle « synchronisée » vers le tronc. Commencez donc par effectuer une dernière fusion des modifications les plus récentes du tronc vers la branche. Une fois que c'est fait, les dernières versions de la branche et du tronc sont absolument identiques, mises à part vos propres modifications sur la branche. Vous êtes alors en mesure de fusionner la branche vers le tronc avec l'option --reintegrate :

$ cd copie-de-travail-du-tronc

$ svn update
À la révision 1910.

$ svn merge --reintegrate http://svn.exemple.com/depot/calc/branches/ma-branche
--- Fusion des différences des URLs du dépôt vers '.':
U    reel.c
U    entier.c
A    nouveau-dossier
A    nouveau-dossier/nouveau-fichier
 U   .
…

Une autre façon de concevoir ce modèle est d'imaginer que votre synchronisation hebdomadaire du tronc vers la branche est analogue au lancement de svn update dans une copie de travail, tandis que l'étape finale de fusion est analogue au lancement de svn commit depuis une copie de travail. Après tout, une copie de travail n'est rien d'autre qu'une branche privée très superficielle : c'est une branche qui n'est capable de ne contenir qu'une modification à la fois.

La gestion des branches fournisseur fonctionne généralement de la façon suivante : vous créez d'abord un répertoire à la racine (par exemple /fournisseur) qui contiendra les branches fournisseur. Ensuite vous importez le code tierce dans un sous-dossier de ce dossier racine. Vous copiez ensuite ce sous-répertoire vers l'emplacement approprié de votre branche de développement principale (par exemple /trunk). Vous faites bien attention à toujours effectuer vos modifications locales dans la branche de développement principale. À chaque nouvelle version du code tierce, vous le déposez dans la branche fournisseur et en fusionnez les modifications vers /trunk, en résolvant les conflits qui apparaissent entre vos modifications locales et les modifications tierces.

Un exemple va rendre cet algorithme plus clair. Nous allons utiliser un scénario dans lequel votre équipe de développement crée un programme de calcul qui dépend d'une bibliothèque tierce d'arithmétique des nombres complexes, libcomplex. Nous commencerons par la création initiale de la branche fournisseur et l'import de la première livraison fournisseur. Nous appellerons notre dossier contenant la branche fournisseur libcomplex et nos livraisons fournisseur iront dans un sous-dossier de notre branche fournisseur appelé actuel. Et puisque svn import crée tous les dossiers parents intermédiaires dont il a besoin, nous pouvons en fait accomplir ces deux étapes en une seule commande :

$ svn import /chemin/vers/libcomplex-1.0 \
             http://svn.exemple.com/depot/fournisseur/libcomplex/actuel \
             -m 'import initial de la livraison fournisseur 1.0'
…

Nous avons désormais la version actuelle du code source de libcomplex dans /fournisseur/libcomplex/actuel. À présent, nous étiquetons cette version (voir la section intitulée « Étiquettes ») et ensuite nous la copions dans la branche de développement principale. Cette opération de copie crée un nouveau dossier appelé libcomplex au sein du répertoire de notre projet existant calc. C'est dans cette copie des données du fournisseur que nous ferons nos ajustements maison :

$ svn copy http://svn.exemple.com/depot/fournisseur/libcomplex/actuel  \
           http://svn.exemple.com/depot/fournisseur/libcomplex/1.0      \
           -m 'étiquetage de libcomplex-1.0'
…
$ svn copy http://svn.exemple.com/depot/fournisseur/libcomplex/1.0  \
           http://svn.exemple.com/depot/calc/libcomplex        \
           -m 'amène libcomplex-1.0 dans la branche principale'
…

Nous extrayons ensuite la branche principale de notre projet, qui inclut désormais une copie de la première livraison fournisseur, et nous nous mettons au travail pour personnaliser le code de libcomplex. Avant même d'en avoir pris conscience, notre version modifiée de libcomplex est complètement intégrée dans notre programme de calcul ^[26].

Quelques semaines plus tard, les développeurs de libcomplex publient une nouvelle version de leur bibliothèque, la version 1.1, qui contient des fonctionnalités dont nous avons besoin. Nous aimerions pouvoir utiliser cette nouvelle version, sans toutefois perdre les évolutions que nous avons apportées à la version existante. En gros, ce que nous voudrions faire c'est remplacer notre version actuelle de libcomplex, la 1.0, par une copie de libcomplex 1.1 et ensuite ré-appliquer les modifications que nous avions effectuées précédemment sur cette bibliothèque à la nouvelle version. Mais, en fait, nous allons aborder le problème sous un autre angle, en appliquant les changements apportés à libcomplex entre les versions 1.0 et 1.1 à notre copie modifiée de celle-ci.

Pour effectuer cette mise à niveau, nous allons extraire une copie de notre branche fournisseur et remplacer le code du répertoire actuel par le nouveau code source de libcomplex 1.1. Nous copions en fait littéralement de nouveaux fichiers par-dessus des fichiers existants, par exemple en extrayant le contenu de l'archive de libcomplex 1.1 à l'endroit où se trouvent nos fichiers et dossiers. L'objectif ici est d'aboutir à ce que notre répertoire actuel ne contienne que le code de libcomplex 1.1 et de s'assurer que la totalité de ce code est suivi en versions. Ah, et puis nous voulons faire ceci avec le moins possible de perturbations liées à l'historique de la gestion de versions.

Après avoir remplacé le code de la 1.0 par le code de la 1.1, svn status liste les fichiers ayant des modifications locales et peut-être aussi des fichiers non suivis en versions. Si nous avons fait ce que nous étions censés faire, les fichiers non suivis en versions sont uniquement de nouveaux fichiers introduits par la version 1.1 de libcomplex ; nous lançons donc svn add sur ces fichiers pour les inclure dans la gestion de versions. Si le code de la 1.1 ne contient plus certains fichiers qui étaient dans l'arborescence de la 1.0, il sera peut-être difficile de les repérer ; il vous faudrait comparer les deux arborescences avec un outil extérieur et ensuite faire un svn delete sur tous les fichiers présents en 1.0 mais pas en 1.1 (bien qu'il soit peut-être parfaitement acceptable de laisser traîner ces mêmes fichiers, inutilisés, dans l'ombre). Finalement, une fois que notre copie de travail de actuel ne contient plus que le code de libcomplex 1.1, nous pouvons propager les modifications que nous avons faites pour lui donner cet aspect.

Notre branche actuel contient désormais la nouvelle livraison fournisseur. Nous étiquetons donc la nouvelle version en 1.1 (de la même façon que nous avions précédemment étiqueté la livraison fournisseur de la version 1.0) et ensuite nous fusionnons les différences entre les étiquettes de la version précédente et de la nouvelle version vers notre branche de développement principale :

$ cd copies-de-travail/calc
$ svn merge http://svn.exemple.com/depot/fournisseur/libcomplex/1.0      \
            http://svn.exemple.com/depot/fournisseur/libcomplex/actuel  \
            libcomplex
… # résoudre tous les conflits entre leurs modifications et nos modifications
$ svn commit -m 'fusion de libcomplex-1.1 vers la branche principale'
…

Dans le cas le plus trivial, la nouvelle version de notre outil tierce ressemblerait à la version précédente, du point de vue des fichiers et dossiers. Aucun des fichiers sources de libcomplex n'aurait été effacé, renommé, ou déplacé ; la nouvelle version ne contiendrait que des modifications textuelles par rapport à la précédente. Dans l'idéal, nos modifications s'appliqueraient proprement à la nouvelle version de la bibliothèque, sans la moindre complication ou conflit.

Mais les choses ne sont pas toujours aussi simples et, en fait, il arrive assez fréquemment que des fichiers sources changent d'emplacement d'une version à l'autre d'un logiciel. Ceci complique la tâche de s'assurer que nos modifications sont toujours valides pour la nouvelle version du code, et les choses peuvent rapidement dégénérer, jusqu'au point où nous pouvons être forcés de reporter manuellement nos évolutions maison dans la nouvelle version. Une fois que Subversion connaît l'historique d'un fichier source donné, incluant tous ses emplacements précédents, la procédure pour incorporer la nouvelle version de la bibliothèque est assez simple. Mais c'est à nous qu'incombe la responsabilité d'indiquer à Subversion de quelle manière l'agencement des fichiers sources a changé d'une livraison fournisseur à une autre.

Les livraisons fournisseur comportant plus de quelques suppressions, ajouts et déplacements compliquent le processus de mise à niveau à chaque version successive des données tierces. Subversion fournit donc le script svn_load_dirs.pl pour faciliter ce processus. Ce script automatise les étapes importantes que nous avons mentionnées dans la procédure générale de gestion des branches fournisseurs afin de minimiser les erreurs. Vous êtes toujours responsable de l'utilisation des commandes svn merge pour fusionner les nouvelles versions des données tierces vers votre branche de développement principale, mais svn_load_dirs.pl peut vous aider à parvenir à cette étape plus rapidement et plus facilement.

En bref, svn_load_dirs.pl est une version améliorée de svn import qui possède plusieurs caractéristiques importantes :

svn_load_dirs.pl prend trois paramètres obligatoires. Le premier paramètre est l'URL du répertoire de base de Subversion à modifier. Ce paramètre est suivi par l'URL, relative au premier paramètre, dans laquelle la livraison fournisseur sera importée. Enfin, le troisième paramètre est le dossier local à importer. En utilisant notre exemple précédent, une exécution type de svn_load_dirs.pl donne :

$ svn_load_dirs.pl http://svn.exemple.com/depot/fournisseur/libcomplex \
                   actuel                                              \
                   /chemin/vers/libcomplex-1.1
…

Vous pouvez indiquer que vous aimeriez que svn_load_dirs.pl étiquette la nouvelle livraison fournisseur en passant l'option -t et en spécifiant un nom d'étiquette. Cette étiquette est aussi une URL relative au premier paramètre du programme.

$ svn_load_dirs.pl -t libcomplex-1.1                              \
                   http://svn.exemple.com/depot/fournisseur/libcomplex \
                   actuel                                        \
                   /chemin/vers/libcomplex-1.1
…

Lorsque vous lancez svn_load_dirs.pl, il examine le contenu de votre livraison fournisseur existante, actuel, et le compare à la nouvelle livraison fournisseur. Dans le cas le plus trivial, aucun fichier n'est présent dans une version sans l'être dans l'autre et le script effectue le nouvel import sans incident. Cependant, s'il y a des divergences dans l'agencement des fichiers entre les versions, svn_load_dirs.pl vous demande comment résoudre ces différences. Par exemple, vous avez l'opportunité d'indiquer au script que vous savez que le fichier math.c de la version 1.0 de libcomplex a été renommé en arithmetique.c dans libcomplex 1.1. Toutes les divergences qui ne sont pas liées à des renommages sont traitées comme des ajouts et des suppressions classiques.

Le script peut également prendre en compte un fichier de configuration séparé, permettant de spécifier des propriétés sur des fichiers et dossiers, correspondants à une expression régulière, qui vont être ajoutés au dépôt. Ce fichier de configuration est indiqué à svn_load_dirs.pl en utilisant l'option -p en ligne de commande. Chaque ligne du fichier de configuration est un ensemble de deux ou quatre valeurs délimitées par des espaces : une expression régulière du style Perl à laquelle comparer le chemin ajouté, un mot clé de contrôle (soit break soit cont) et ensuite, en option, un nom de propriété et une valeur.

\.png$              break   svn:mime-type   image/png
\.jpe?g$            break   svn:mime-type   image/jpeg
\.m3u$              cont    svn:mime-type   audio/x-mpegurl
\.m3u$              break   svn:eol-style   LF
.*                  break   svn:eol-style   native

Pour chaque chemin ajouté, les modifications de propriétés configurées dont l'expression régulière correspond au chemin sont appliquées dans l'ordre, sauf si le terme de contrôle est break (ce qui signifie qu'aucune autre modification de propriété ne doit être appliquée à ce chemin). Si le terme de contrôle est cont (abréviation de continuer), la comparaison continue avec la ligne suivante du fichier de configuration.

Toute espace faisant partie de l'expression régulière, du nom de la propriété ou de la valeur de la propriété doit être entourée d'apostrophes ou de guillemets. Vous pouvez banaliser les guillemets et apostrophes qui ne sont pas utilisés pour entourer une espace en les faisant précéder d'une barre oblique inversée (ou « antislash » : \). L'antislash ne banalise que les guillemets et apostrophes pendant le traitement du fichier de configuration, ce n'est donc pas la peine de protéger d'autres caractères au-delà de ce qui est nécessaire pour l'expression régulière.