Le dépôt constitue le cœur d'un système de gestion de versions ; c'est le lieu de stockage central des données gérées. Généralement, les informations y sont organisées sous la forme d'une arborescence de fichiers, c'est-à-dire une hiérarchie classique de fichiers et de répertoires. Un certain nombre de clients se connectent au dépôt, et parcourent ou modifient ces fichiers. En modifiant des données, un client rend ces informations disponibles aux autres clients ; en lisant des données, le client reçoit des informations des autres clients. La Figure 1.1, « Un authentique système client/serveur » illustre cela.

Figure 1.1. Un authentique système client/serveur

Quel est l'intérêt ? Jusque-là, cela ressemble à la définition d'un serveur de fichiers classique. En fait, le dépôt est bien une sorte de serveur de fichiers, mais d'un type particulier. Ce qui rend le dépôt spécial, c'est qu'il se souvient de toutes les versions de chacun des fichiers.

Quand un client parcourt le dépôt, il consulte généralement la dernière version de l'arborescence du système de fichiers. Mais, et c'est là l'intérêt d'un système de gestion de versions, le client est également capable de demander au dépôt les états antérieurs du système de fichiers. Par exemple, un client peut poser des questions concernant l'historique des données, comme « Que contenait ce répertoire mercredi dernier ? » ou « Quelle est la dernière personne qui a modifié ce fichier, et quels changements a-t-elle effectués ? ». C'est le genre de questions qui est au cœur de tout logiciel de gestion de versions.

La plus-value d'un système de gestion de versions provient de sa capacité à garder une trace de toutes les versions des fichiers et répertoires, mais les autres logiciels n'intègrent pas cette notion de « versions de fichiers et répertoires ». La plupart des logiciels ne savent manipuler qu'une seule version d'un type de fichier. Alors, comment l'utilisateur du système de gestion de versions interagit-il concrètement avec un dépôt abstrait — et souvent distant — plein de multiples versions des différents fichiers ? Comment son traitement de textes, son logiciel de présentation, son éditeur de code source ou de site web, ou n'importe quel autre logiciel peut-il avoir accès à ces fichiers suivis en versions ? La réponse se trouve dans ce que la gestion de versions appelle la copie de travail.

Une copie de travail est, littéralement, une copie locale d'une version particulière des données gérées en versions par l'utilisateur, sur laquelle il est libre de travailler. Les copies de travail^[5] sont vus par les autres logiciels comme n'importe quel autre répertoire rempli de fichiers, ainsi ces programmes n'ont pas besoin d'être « conscients » de la gestion de versions pour lire ou écrire des données dans ces fichiers. C'est le rôle du logiciel de gestion de versions de prendre en compte et communiquer les modifications du contenu de la copie de travail ou du dépôt.

Si la mission première d'un logiciel de gestion de versions est de tracer l'historique des différentes versions dans le temps des données numériques, une seconde mission concomitante dans n'importe quel gestionnaire de versions moderne consiste à permettre l'édition collaborative et le partage de ces données. Mais il existe différentes stratégies pour arriver à cette fin. Comprendre ces différentes stratégies est important à plusieurs titres. Tout d'abord, cela vous aidera à comparer et différencier les logiciels de gestion de versions existants, au cas où vous rencontriez d'autres logiciels similaires à Subversion. Ensuite, cela vous aidera également à utiliser plus efficacement Subversion, puisque Subversion lui-même autorise différentes façons de travailler.

Problématique du partage de fichiers

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 n'est présente dans la nouvelle version du fichier de Sally, car elle n'a 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

Modèle verrouiller-modifier-libérer

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 peut pas le verrouiller et ne peut donc faire aucun changement dessus. Tout ce qu'elle peut faire, c'est lire le fichier et 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 :

• Le verrouillage peut créer des problèmes d'administration. Parfois, Harry va verrouiller un fichier et oublier qu'il l'a fait. Pendant ce temps, Sally, qui est encore en train d'attendre pour éditer le fichier, est bloquée. Puis Harry part en vacances. Sally doit alors aller trouver un administrateur pour libérer le verrou de Harry. La situation finit par générer beaucoup de délais inutiles et de temps perdu.

• Le verrouillage peut créer une sérialisation inutile. Que se passe-t-il lorsque Harry veut éditer le début d'un fichier texte et que Sally veut simplement éditer la fin de ce même fichier ? Ces changements ne se chevauchent pas du tout. Ils pourraient aisément éditer le fichier simultanément et il n'y aurait pas beaucoup de dégâts, en supposant que les changements soient correctement fusionnés. Dans cette situation, il n'est pas nécessaire de les forcer à éditer le fichier chacun à leur tour.

• Le verrouillage peut créer un faux sentiment de sécurité. Supposons que Harry verrouille et édite le fichier A, alors qu'au même moment Sally verrouille et édite le fichier B. Que se passe-t-il si A et B dépendent l'un de l'autre et que les changements faits à chacun sont incompatibles d'un point de vue sémantique ? A et B ne fonctionnent soudainement plus ensemble. Le système de verrouillage a été incapable d'empêcher ce problème, bien qu'il ait d'une certaine manière instillé un faux sentiment de sécurité. Il est facile pour Harry et Sally d'imaginer qu'en verrouillant les fichiers, chacun commence une tâche isolée, sans danger et donc que ce n'est pas la peine de discuter à l'avance de leurs modifications incompatibles. Verrouiller devient souvent un substitut à une réelle communication.

Modèle copier-modifier-fusionner

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.

Le verrouillage est parfois nécessaire

Même si le modèle verrouiller-modifier-libérer est en général considéré comme pénalisant pour la collaboration, il y a quand même des cas où le verrouillage est approprié.

Le modèle copier-modifier-fusionner est basé sur l'hypothèse que les fichiers peuvent être fusionnés contextuellement, c'est-à-dire que la majorité des fichiers d'un dépôt sont des fichiers textes (comme le code source d'un programme). Mais pour les fichiers binaires, tels que des images ou du son, il est souvent impossible de fusionner les modifications en conflit. Dans ces cas-là, il est réellement nécessaire que les utilisateurs ne modifient le fichier qu'à tour de rôle. Sans accès sérialisé, quelqu'un finit par perdre son temps sur des modifications qui sont finalement rejetées.

Bien que Subversion soit avant tout un système copier-modifier-fusionner, il reconnaît toutefois la nécessité du verrouillage pour certains fichiers et fournit donc un mécanisme pour cela. Cette fonctionnalité est traitée plus tard dans ce livre, dans la section intitulée « Verrouillage ».

Subversion implémente le concept de dépôt comme tout autre logiciel de gestion de versions moderne. Contrairement à une copie de travail, un dépôt Subversion est une entité abstraite qui ne peut être manipulée pratiquement que par les bibliothèques et les propres outils de Subversion. Comme la plupart des interactions d'un utilisateur de Subversion se font par l'intermédiaire du client Subversion et qu'elles ont lieu dans le contexte de la copie de travail, ce livre traite en une grande partie de la copie de travail et des actions que l'on peut y appliquer. Pour les détails du dépôt, vous pouvez cependant vous référer au Chapitre 5, Administration d'un dépôt.

Avertissement

Dans Subversion, l'entité que possède chaque utilisateur du logiciel — le répertoire des fichiers suivis en versions ainsi que les métadonnées qui permettent au système de tracer les données et de communiquer avec le serveur — s'appelle la copie de travail. Bien que d'autres logiciels de gestion de versions utilisent le terme de « dépôt » pour l'entité côté client, c'est à la fois incorrect et une source fréquente de confusion d'utiliser ce terme dans ce sens là dans le contexte de Subversion. Les copies de travail sont abordées plus loin, dans la section intitulée « Copies de travail ».

Une opération svn commit propage (c'est-à-dire communique au serveur) les modifications d'un nombre quelconque de fichiers et de répertoires en une seule opération atomique. Par opération atomique, nous entendons que, soit toutes les modifications sont prises en compte par le dépôt, soit rien n'est pris en compte. Subversion essai d'être robuste dans ce concept d'atomicité, même en cas de plantage du programme, du système, de problèmes réseau ou d'actions de la part des autres utilisateurs.

Chaque fois que le dépôt accepte une propagation (c'est-à-dire une opération svn commit), il crée un nouvel état de l'arborescence du système de fichiers que l'on appelle révision. À Chaque révision est associé un entier naturel unique, immédiatement supérieur à l'entier associé à la révision précédente. La révision initiale d'un dépôt nouvellement créé à pour numéro 0 et n'est constituée que d'un répertoire racine vide.

La Figure 1.6, « L'évolution de l'arborescence au cours du temps » illustre une manière intéressante de se représenter le dépôt. Imaginez un tableau de numéros de révisions, commençant à zéro et s'étirant de la gauche vers la droite. À Chaque numéro de révision est suspendue une arborescence du système de fichiers, qui est une photo, un « instantané » (snapshot en anglais) du dépôt prise après une propagation.

Figure 1.6. L'évolution de l'arborescence au cours du temps

les logiciels côté client de Subversion utilisent des URL pour identifier les fichiers et répertoires suivis en versions dans les dépôts Subversion. Pour leur grande partie, ces URL utilisent la syntaxe standard, permettant de spécifier le nom du serveur et le numéro de port directement dans l'URL.

Les URL de dépôts Subversion ne se limitent pas au domaine http://. Comme Subversion permet à ses clients de dialoguer de différentes manières avec les dépôts, les URL utilisées pour se connecter diffèrent subtilement en fonction du protocole employé. La Tableau 1.1, « Les différents motifs d'URL pour l'accès aux dépôts » décrit la correspondance entre les différents motifs d'URL et les méthodes d'accès aux dépôts. Pour plus de détails sur les options du serveur Subversion, reportez-vous au Chapitre 6, Configuration du serveur.

La gestion des URL par Subversion possède quelques particularités qu'il convient de noter. Par exemple, les URL contenant la méthode d'accès file:// (utilisée pour les dépôts locaux) doivent spécifier, par convention, soit le nom de serveur localhost, soit pas de nom de serveur :

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 :

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 (\). Notez aussi que, 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 »).

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.

Il faut noter que le client Subversion encode automatiquement les URL en cas de besoin, exactement comme le fait un navigateur web. Par exemple, l'URL http://host/path with space/project/españa — qui contient à la fois des espaces et des caractères non ASCII— est automatiquement interprétée par Subversion comme si vous aviez fourni http://host/path%20with%20space/project/espa%C3%B1a. Si l'URL contient des espaces, prenez bien soin de les placer entre guillemets dans la ligne de commande afin que le shell traite le tout comme un unique argument du programme.

Il existe aussi une exception à la gestion des URL par Subversion qui s'applique à la gestion des chemins locaux dans beaucoup de contextes. Si le dernier élément de l'URL ou du chemin contient le signe arobase (@), vous devez utiliser une syntaxe particulière, décrite dans la section intitulée « Révisions pivots et révisions opérationnelles », afin que Subversion prenne proprement en compte l'adresse de cette ressource.

Dans Subversion 1.6, une nouvelle notation, dite syntaxe avec chapeau (^) a été introduite comme raccourci pour « l'URL du répertoire racine du dépôt ». Par exemple, vous pouvez utiliser ^tags/gros-sandwich pour désigner l'URL du répertoire /tags/gros-sandwich à la racine du dépôt. Une telle URL est appelée URL relative au dépôt. Remarquez que cette syntaxe d'URL ne fonctionne que si votre répertoire de travail est une copie de travail, le client texte interactif récupérant l'URL de la racine du dépôt dans les métadonnées de la copie de travail. Notez aussi que lorsque vous voulez faire référence précisément au répertoire racine du dépôt, vous devez utiliser ^/ (avec la barre oblique terminale) et non simplement ^. Les utilisateurs sous Windows ne doivent pas oublier que le caret est un caractère d'échappement pour ce système. En conséquence, vous devez utiliser un double caret ^^ si votre client Subversion tourne sur une machine Windows.

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 incorpore jamais les changements d'autres personnes ni ne rend 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). Remarquez que le dépôt central joue le rôle d'intermédiaire pour les changements de tout le monde dans Subversion ; les modifications ne passent pas directement d'une copie de travail à une autre copie de travail dans le processus classique.

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 copie de travail contient un sous-répertoire nommé .svn, aussi connu sous l'appellation de répertoire administratif de votre copie de travail. Les fichiers de ce répertoire administratif 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.

Note

Avant la version 1.7, Subversion plaçait un répertoire .svn dans chaque sous-répertoire géré en versions de la copie de travail. Subversion 1.7 utilise une approche complètement nouvelle pour stocker, suivre et travailler avec les métadonnées, et le changement le plus visible de cette approche est qu'il n'existe dans la copie de travail qu'un seul sous-répertoire .svn situé à la racine de la copie de travail.

Actions de base sur la copie de travail

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.7, « Système de fichiers du dépôt ».

Figure 1.7. 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  bouton.c entier.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 verra 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.

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 existante dont vous voulez suivre les changements dans votre dépôt Subversion. Par exemple :

$ svn import chemin/vers/mon/arborescence \
             http://svn.exemple.com/svn/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

Révision 1 propagée.
$

L'exemple précédent copie le contenu d'un dossier local mon-arborescence dans le dossier un/projet du dépôt. Notez que vous n'avez pas eu besoin de créer d'abord ce nouveau dossier, svn import le faisant pour vous. Immédiatement après la propagation, vous pouvez voir vos données dans le dépôt :

$ svn list http://svn.exemple.com/svn/depot/un/projet
machin.c
sous-repertoire/
truc.c
$

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.

On ne peut pas être plus flexible que Subversion pour l'organisation de vos données. Comme il ne fait que suivre en versions les fichiers et les dossiers et comme il n'attache aucune sémantique à ces objets, vous avez tout loisir de disposer les données dans votre dépôt comme bon vous semble. Malheureusement, la contrepartie de cette flexibilité est qu'il est facile de se retrouver perdu quand on essaye de parcourir différents dépôts Subversion, les schémas de stockage des données pouvant être très différents voire imprévisibles.

Pour pallier cette confusion possible, nous vous recommandons de suivre la convention suivante (établie il y a bien longtemps, avec l'éclosion du projet Subversion lui-même) qui consiste à nommer judicieusement quelques dossiers du dépôt Subversion en fonction des données qu'ils renferment. La plupart des projets possèdent « une ligne de développement principale » identifiable, autrement appelée tronc (trunk en anglais), des branches, qui sont des copies avec des variantes de la ligne de développement principale et des étiquettes (tags en anglais) qui sont des instantanés de la ligne de développement que l'on a nommés. En conséquence, nous recommandons premièrement que chaque projet dispose d'une racine de projet bien identifiée au sein du dépôt, un dossier sous lequel toutes les données du projet — et uniquement les données du projet — seront hébergées. Deuxièmement, nous recommandons que chaque racine de projet contienne un sous-dossier trunk pour la ligne de développement principale, un sous-dossier branches dans lequel les branches spécifiques (ou groupes de branches) seront créées et un sous-dossier tags dans lequel seront placés les instantanés (ou les groupes d'instantanés). Bien sûr, si un dépôt n'héberge qu'un seul projet, la racine du dépôt peut servir de racine du projet.

Voici quelques exemples :

$ svn list file:///var/svn/depot-projet-unique
trunk/
branches/
tags/
$ svn list file:///var/svn/depot-multiples-projets
projet-A/
projet-B/
$ svn list file:///var/svn/depot-multiples-projets/projet-A
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 dossiers racines d'un projet.

Subversion s'efforce de ne pas limiter le type de données que vous placez en suivi de versions. Le contenu des fichiers et les valeurs des propriétés sont stockés et transmis en tant que données binaires. la section intitulée « Type de contenu des fichiers » vous explique comment indiquer à Subversion que des opérations « textuelles » n'ont pas de sens pour un fichier particulier. Il existe toutefois quelques cas pour lesquels Subversion définit des limitations sur les informations qu'il stocke.

Subversion gère en interne certaines parties des données au format Unicode UTF-8, par exemple les noms de propriétés, les noms de chemins et les messages de trace. Cela ne veut toutefois pas dire que toutes vos interactions avec Subversion doivent faire intervenir l'UTF-8. En règle générale, les clients Subversion vont gérer de façon transparente les conversions entre l'UTF-8 et le système de codage utilisé par votre ordinateur, si cela a un sens de faire une telle conversion (ce qui est le cas pour les codages les plus courants utilisés de nos jours).

Dans les échanges WebDAV ainsi que dans des anciennes versions de certains fichiers de gestion interne de Subversion, les chemins sont utilisés en tant que valeurs d'attribut XML et les noms de propriétés en tant que noms de tags XML. Cela veut dire que les chemins ne peuvent contenir que des caractères XML (1.0) valides et que les noms de propriétés sont encore plus limités, ne pouvant contenir que des caractères ASCII. Subversion interdit également les caractères TAB (tabulation), CR et LF (caractères de fin de ligne) dans les noms de chemins pour empêcher les chemins d'être coupés en deux lors des comparaisons ou dans les sorties de commandes comme svn log ou svn status.

Bien que cela fasse beaucoup de choses à se rappeler, ces limitations sont rarement un problème en pratique. Tant que vos paramètres régionaux sont compatibles avec UTF-8 et que vous n'utilisez pas de caractères de contrôle dans les chemins, vous ne devriez pas avoir de problème pour communiquer avec Subversion. Le client texte interactif apporte un peu d'aide supplémentaire : afin de créer des versions « valides » pour un usage interne, il banalise automatiquement, si nécessaire, les caractères illégaux contenus dans les chemins d'URL que vous tapez.

Avertissement

Évidemment, au moment de choisir des noms de chemins valides, Subversion n'est pas l'unique facteur limitant. Les équipes qui travaillent avec plusieurs systèmes d'exploitation doivent aussi prendre en compte les limitations imposées par ces systèmes d'exploitation. Par exemple, Windows n'autorise pas l'utilisation de la virgule dans les noms de fichiers alors qu'un utilisateur de Linux peut très bien placer un tel fichier en suivi de versions, générant des données qui ne pourront plus être extraites sous Windows. De même, ajouter plusieurs fichiers dont les noms ne diffèrent que par la casse entraîne des problèmes pour les utilisateurs de systèmes de fichiers non sensibles à la casse. En conséquence, nous vous recommandons de bien prendre aussi en compte les limitations posées par les différents systèmes d'exploitation et systèmes de fichiers.

Si vous travaillez sur un projet donné qui est modifié par des copies de travail multiples, vous voudrez mettre à jour votre copie locale pour recevoir toutes les modifications qui ont pu être faites par les autres copies de travail depuis votre dernière mise à jour. Ce peut être des modifications que les autres membres de l'équipe de projet ont faites, ou simplement des modifications que vous avez faites vous-même sur un autre ordinateur. Afin de protéger vos données, Subversion ne vous autorise pas à publier des changements sur des fichiers ou des dossiers qui ne sont pas à jour. Il est donc toujours mieux d'avoir les dernières versions de tous les fichiers et dossiers des projets sur lesquels vous travaillez avant d'apporter vous-même des modifications.

Utilisez svn update pour synchroniser votre copie de travail avec la dernière version présente dans le dépôt :

$ svn update
Mise à jour de '.' :
U  truc.c
U  machin.c
Actualisé à la révision 2.
$

Dans cet exemple, il se trouve que quelqu'un a propagé 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é à côté 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 ou reportez-vous à svn update (up) dans Guide de référence de svn : le client texte interactif.

Vous pouvez à présent vous mettre au travail et apporter des modifications à votre copie de travail. Vous pouvez effectuer deux types de modifications : les modifications de fichiers et les modifications de dossiers. Vous n'avez pas à prévenir Subversion que vous voulez modifier un fichier ; faites vos modifications avec un éditeur de texte, un traitement de texte, un logiciel de dessin 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 aussi efficacement que les fichiers textes. Les modifications dans l'arborescence sont différentes ; cela comprend l'ajout et la suppression de fichiers, le renommage de fichiers ou de dossier ainsi que la copie ou le déplacement de fichiers ou dossiers vers un nouvel emplacement. Pour les modifications d'arborescence, les opérations de Subversion consistent à « marquer » la suppression, l'ajout, la copie ou le déplacement des fichiers et dossiers. Ces modifications prennent effet immédiatement sur votre copie de travail mais aucun ajout ou suppression n'interviendra 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, vous pouvez rédiger un commentaire de propagation, c'est-à-dire une description à l'attention des utilisateurs des changements propagés, ce commentaire étant conservé avec les données dans le dépôt. É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 la commande svn status et voir le détail de ces changements en utilisant svn diff.

Vue d'ensemble des changements effectués

Pour avoir une vue d'ensemble des changements que vous avez effectués, utilisez la commande svn status. C'est certainement la commande Subversion que vous utiliserez le plus.

Astuce

Parce que l'affichage produit par la commande cvs status était tellement verbeux et parce que la commande cvs update ne faisait pas qu'une mise à jour mais affichait également l'état des changements effectués localement, la plupart des utilisateurs de CVS ont appris à utiliser cvs update pour propager leurs modifications. Dans Subversion, les opérations de mise-à-jour et d'examen des changements sont complètement séparées. Reportez-vous à la section intitulée « Distinction entre les commandes status et update » pour plus de détails.

Si vous lancez svn status sans argument à la racine de votre copie de travail, Subversion détecte toutes les modifications effectuées sur les fichiers et sur l'arborescence.

$ svn status
?       gribouillage.c
A       bazar/pognon
A       bazar/pognon/nouveau.h
D       bazar/vieux.c
M       machin.c

Dans le format d'affichage par défaut, svn status affiche sept colonnes de caractères, suivis par plusieurs espaces, suivis par un nom de fichier ou de dossier. La première colonne indique le statut du fichier ou du dossier et/ou son contenu. Les codes les plus utilisés sont :

? élément

Le fichier, dossier ou lien symbolique élément n'est pas suivi en versions.

A élément

Le fichier, dossier ou lien symbolique élément est marqué pour ajout au dépôt.

C élément

Le fichier élément est dans un état de conflit. C'est-à-dire que des modifications ont eu lieu dans le dépôt depuis votre dernière mise à jour et ces modifications interfèrent avec les modifications que vous avez effectuées sur votre copie de travail (et la mise à jour n'a pas résolu ce conflit). Vous devez résoudre ce conflit avant de propager vos changements vers le dépôt.

D élément

Le fichier, dossier ou lien symbolique élément est marqué pour suppression (Deletion en anglais).

M élément

Le contenu du fichier élément a été modifié.

Si vous spécifiez un chemin à svn status, vous obtenez uniquement les informations relatives à ce chemin :

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

svn status possède aussi une option --verbose (-v) pour la rendre plus verbeuse : elle affiche alors le statut de tous les éléments de votre copie de travail, même ceux qui n'ont pas subi de modification :

 
$ svn status -v
M               44        23    sally     LISEZMOI
                44        30    sally     INSTALL
M               44        20    harry     machin.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/bitoniau.h
                44        36    harry     bazar/divers/tartempion.c

C'est la « version longue » de l'affichage de svn status. Les lettres de la première colonne ont la même signification que précédemment, mais la deuxième colonne indique le numéro de révision de travail de l'élément. Les troisième et quatrième colonnes indiquent le numéro de la révision dans laquelle a eu lieu le changement le plus récent et qui l'a effectué.

Aucune des commandes citées ci-dessus n'induit de connexion vers le dépôt : elles comparent les métadonnées de la zone administrative et les horodatages avec la copie de travail. Parfois, il peut être utile de voir quels éléments de la copie de travail ont été modifiés dans le dépôt depuis la dernière mise à jour de la copie de travail. À cette fin, svn status propose l'option --show-updates (-u) qui effectue une connexion au dépôt et ajoute les informations sur les éléments périmés :

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

Notez les deux astérisques : si vous lanciez la commande svn update, vous recevriez les changements relatifs à LISEZMOI et truite.c. Cela vous procure des informations particulièrement intéressantes, puisque l'un des éléments a fait l'objet de modifications de votre part (le fichier LISEZMOI) ; vous devez faire une mise à jour et récupérer les changements effectués sur LISEZMOI avant de propager les vôtres, sinon le dépôt rejettera votre propagation en la considérant comme périmée (le sujet est approfondi plus tard).

svn status peut afficher beaucoup plus d'informations sur les fichiers et dossiers de votre copie de travail que ce que nous venons de voir ici. Pour obtenir une description exhaustive de svn status et de ses modes d'affichage, lancez svn help status ou reportez-vous à svn status (stat, st) dans Guide de référence de svn : le client texte interactif.

$ svn diff
Index: truc.c
===================================================================
--- machin.c	(révision 3)
+++ machin.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/bitoniau.h	(révision 8)
+++ bazar/divers/bitoniau.h	(copie de travail)
+Voici un nouveau fichier pour
+écrire sur les petites choses.

$ svn diff > fichier-correctif
$

$ svn diff --diff-cmd /usr/bin/diff -x "-i" truc.c
…
$

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. Vous pourriez éditer à nouveau le fichier et défaire tous les changements. Vous pourriez essayer de trouver une copie du fichier tel qu'il était avant les changements et copier son contenu à la place de votre fichier modifié. Vous pourriez essayer d'appliquer les changements à l'envers en utilisant svn patch --reverse-diff ou depuis le système d'exploitation avec patch -R. Et il existe probablement encore d'autres méthodes.

Heureusement, avec Subversion annuler son travail et repartir de zéro ne nécessite pas autant d'acrobaties. Vous avez juste à utiliser la commande svn revert:

$ svn status LISEZMOI
M       LISEZMOI
$ svn revert LISEZMOI
'LISEZMOI' réinitialisé
$

Dans cet exemple, 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 d'administration. 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
$

Ou, si vous avez enlevé un fichier du suivi de versions par erreur :

$ svn status LISEZMOI

$ svn delete LISEZMOI
D       LISEZMOI
$ svn revert LISEZMOI
'LISEZMOI' réinitialisé
$ svn status LISEZMOI

$

La commande svn revert est le parachute des gens imparfaits. Elle peut vous faire gagner un temps et une énergie considérables que vous auriez dépensé autrement à faire des corrections manuelles, voire à récupérer une copie de travail vierge juste pour retrouver un environnement de travail propre.

Nous avons déjà vu que svn status -u est capable de prévoir les conflits, mais il reste à savoir gérer ces conflits. Des conflits peuvent survenir à chaque fois que vous voulez fusionner ou intégrer (dans le sens le plus général) des modifications en provenance du dépôt dans votre copie de travail. Vous savez désormais que la commande svn update génère ce type de situation ; la fonction essentielle de cette commande est de mettre à jour votre copie de travail en y intégrant toutes les modifications effectuées depuis votre dernière mise à jour. Comment Subversion vous rend-il compte de ces conflits et comment pouvez-vous les gérer ?

Supposons que vous lanciez svn update et que le résultat suivant apparaisse :

$ svn update
Mise à jour de '.' :
U  INSTALL
G  LISEZMOI
Conflit découvert dans 'machin.c'.
Sélectionner : (p) report, (df) diff complet, (e) édite, (m) fusion,
        (mc) my side of conflict, (tc) their side of conflict,
        (s) voir toutes les options:

Les codes U (qui veut dire « mis à jour », updated en anglais) et G (qui veut dire fusionné, merGed en anglais) 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 ne contenaient aucun changement local mais ont été mis à jour à partir de changements présents dans le dépôt. Le fichier marqué G avait subi des changements localement, mais les changements en provenance du dépôt ont pu être appliqués sans affecter les changements locaux.

Ce sont les quelques lignes suivantes qui sont intéressantes. D'abord, Subversion vous avertit que sa tentative pour fusionner les modifications en provenance du serveur dans le fichier local machin.c, il a détecté que certains changements interfèrent avec les vôtres quelqu'un a peut-être modifié la même ligne que vous. Quelle qu'en soit la raison, Subversion marque immédiatement le fichier comme étant dans un état de conflit. Ensuite, il vous demande ce que vous voulez faire pour résoudre ce conflit, vous proposant de choisir une action de manière interactive. Les options les plus utilisées sont affichées, mais vous pouvez voir toutes les options possibles en tapant s :

…
Sélectionner : (p) report, (df) diff complet, (e) édite, (m) fusion,
               (mc) my side of conflict, (tc) their side of conflict,
               (s) voir toutes les options:

  (e)  - change merged file in an editor  [edit]
  (df) - show all changes made to merged file
  (r)  - accept merged version of file

  (dc) - show all conflicts (ignoring merged version)
  (mc) - accept my version for all conflicts (same)  [mine-conflict]
  (tc) - accept their version for all conflicts (same)  [theirs-conflict]

  (mf) - accept my version of entire file (even non-conflicts)  [mine-full]
  (tf) - accept their version of entire file (same)  [theirs-full]

  (m)  - use internal merge tool to resolve conflict
  (l)  - launch external tool to resolve conflict  [launch]
  (p)  - mark the conflict to be resolved later  [postpone]
  (q)  - postpone all remaining conflicts
  (s)  - show this list (also 'h', '?')
Words in square brackets are the corresponding --accept option arguments.

Select: (p) postpone, (df) show diff, (e) edit file, (m) fusion,
        (mc) my side of conflict, (tc) their side of conflict,
        (s) show all options:

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, (m) fusion,
               (mc) my side of conflict, (tc) their side of conflict,
               (s) voir toutes les options:df
--- .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
…

Select: (p) postpone, (df) show diff, (e) edit file, (m) merge,
        (mc) my side of conflict, (tc) their side of conflict,
        (s) show all options: m
Merging 'Makefile'.
Conflicting section found during merge:
(1) their version (at line 24)                  |(2) your version (at line 24)
------------------------------------------------+------------------------------------------------
top_builddir = /truc                             |top_builddir = /machin
------------------------------------------------+------------------------------------------------
Select: (1) use their version, (2) use your version,
        (12) their version first, then yours,
        (21) your version first, then theirs,
        (e1) edit their version and use the result,
        (e2) edit your version and use the result,
        (eb) edit both versions and use the result,
        (p) postpone this conflicting section leaving conflict markers,
        (a) abort file merge and return to main menu:

$ svn update
Mise à jour de '.' :
Conflit découvert dans 'sandwich.txt'.
Select: (p) postpone, (df) show diff, (e) edit file, (m) merge,
        (mc) my side of conflict, (tc) their side of conflict,
        (s) show all options: p
C  sandwich.txt
Actualisé à la révision 2.
Résumé des conflits :
  Text conflicts: 1
$ 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 commentaire de propagation qui décrit ce changement. Votre commentaire est associé à la nouvelle révision que vous créez. Si votre commentaire est bref, vous pouvez le passer en ligne de commande en utilisant l'option --message (ou -m) :

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

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

$ svn commit -F commentaire_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 « Configuration générale ») pour que vous rédigiez le commentaire de propagation.

Astuce

Si, au moment où vous rédigez votre commentaire 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 commentaire, 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 ; 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        règles.txt
Transmission des données .
svn: E155011: Echec de la propagation (commit), détails :
svn: E155011: Fichier '/règles.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.

À ce moment là, 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.

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: règles.txt
===================================================================
--- règles.txt	(révision 3)
+++ règles.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 règles.txt
Index: règles.txt
===================================================================
--- règles.txt	(révision 3)
+++ règles.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 règles.txt
Index: règles.txt
===================================================================
--- règles.txt	(révision 2)
+++ règles.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 règles.txt
Index: règles.txt
===================================================================
--- règles.txt	(révision 2)
+++ règles.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/règles.txt
…
$

Pour connaître l'historique d'un fichier ou d'un dossier, utilisez la commande svn log. Elle affiche la liste des gens qui ont modifié le fichier ou le dossier 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 commentaire 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) :

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

$ svn log truc.c
…
$ svn log http://truc.com/svn/trunk/code/truc.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 dossier, svn log accepte également l'option --verbose (-v). Comme Subversion autorise les déplacements et les copies de dossiers 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/truc.c
   M /trunk/code/machin.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 commentaire de propagation. En combinaison avec --verbose, svn log n'affiche que les noms des fichiers qui ont changé.

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

Depuis Subversion 1.7, les utilisateurs du client texte interactif bénéficient du mode d'affichage spécial de svn log qui intègre un format similaire à celui produit par svn diff, que nous avons abordé précédemment. Si vous lancez svn log avec l'option --diff, Subversion ajoute, à chaque partie de l'historique d'une révision, une édition des différences au style diff. C'est très pratique pour visualiser à la fois les changements sémantiques, de haut niveau et les modifications ligne par ligne d'une révision.

À partir de Subversion 1.8, svn log reconnait les options --search et --search-and. Ces options vous permettent de filtrer la sortie de svn log en fonction du motif que vous fournissez. Lorsque vous utilisez ces options, le commentaire de propagation n'est affiché que si l'auteur, la date, le commentaire ou la liste des chemins modifiés correspond au motif fourni.

Grâce aux commandes svn cat et svn list, vous pouvez afficher des révisions variées des fichiers et dossiers 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 règles.txt
Être attentif envers les autres
Liberté = Glace au chocolat
Tout dans la modération
Mâcher la bouche ouverte
$

 
$ svn cat -r 2 règles.txt > règles.txt.v2
$

Affichage ligne par ligne des auteurs de modifications

La commande svn annotate ressemble beaucoup à la commande svn cat que nous venons d'aborder à la section précédente. Cette commande affiche aussi le contenu du fichier suivi en versions mais utilise un format en tableau. Chaque ligne, en plus du contenu du fichier, indique également le nom de l'utilisateur, le numéro de la révision et (optionnellement) l'horodatage de la révision dans laquelle la ligne a été modifiée pour la dernière fois.

Quand vous lui spécifiez comme argument un fichier de la copie de travail, svn annotate affiche par défaut les attributs du fichier correspondant à la version de la copie de travail.

$ svn annotate règles.txt
     1      harry Être attentif envers les autres
     3      sally Liberté = Responsabilité
     1      harry Tout dans la modération
     -          - Mâcher la bouche fermée
     -          - Écouter quand les autres parlent

Remarquez que, pour certaines lignes, il n'y a pas d'auteur indiqué. C'est parce que ces lignes ont été modifiées dans la copie de travail du fichier. De cette façon, svn annotate devient un outil supplémentaire pour visualiser quelles lignes du fichier vous avez modifiées. Vous pouvez utiliser le mot-clé BASE (voir la section intitulée « Mots-clés de révision ») pour visualiser la version non modifiée du fichier telle qu'elle est stockée dans votre copie de travail.

$ svn annotate règles.txt@BASE
     1      harry Être attentif envers les autres
     3      sally Liberté = Responsabilité
     1      harry Tout dans la modération
     1      harry Mâcher la bouche ouverte

L'option --verbose (-v) demande à svn annotate d'inclure également pour chaque ligne l'horodatage de la révision. Cela augmentant de manière significative la largeur de chaque ligne, nous nous passerons d'exemple pour cette option.

De même que pour svn cat, vous pouvez demander à svn annotate d'afficher les versions précédentes du fichier. C'est une astuce particulièrement utile lorsque, après avoir trouvé qui a modifié telle ligne dans le fichier, vous voulez savoir qui avait écrit la version précédente de cette ligne.

 
$ svn blame règles.txt -r 2
     1      harry Être attentif envers les autres
     1      harry Liberté = Glace au chocolat
     1      harry Tout dans la modération
     1      harry Mâcher la bouche ouverte

Au contraire de svn cat, le fonctionnement de svn annotate est fortement corrélé à la notion de « ligne » d'un fichier texte lisible par un humain. Ainsi, si vous essayez de lancer la commande sur un fichier que Subversion considère non lisible par un humain (en raison de sa propriété svn:mime-type, voir la section intitulée « Type de contenu des fichiers » pour les détails), vous obtiendrez un message d'erreur.

$ svn annotate images/logo.png 
Skipping binary file (use --force to treat as text): 'images/logo.png'
$

Comme l'indique le message d'erreur, vous pouvez spécifier l'option --force pour outrepasser la vérification et effectuer les annotations comme pour tout fichier contenant des lignes et lisible par un humain. Naturellement, si vous forcez Subversion à effectuer des annotations sur un fichier non textuel, vous obtiendrez ce à quoi vous devez vous attendre : un cafouillis incompréhensible.

$ svn annotate images/logo.png --force
     6      harry \211PNG
     6      harry ^Z
     6      harry
     7      harry \274\361\MI\300\365\353^X\300…

	Astuce
	En fonction de votre humeur du moment ou des raisons pour lesquelles vous lancez cette commande, vous vous retrouverez à taper svn blame … ou svn praise … au lieu de la forme canonique de la commande svn annotate. Pas de souci, les développeurs de Subversion l'ont anticipé et ces alias fonctionnent parfaitement.

Pour finir, comme pour beaucoup de commandes de Subversion qui interrogent les fichiers suivis en versions, svn annotate peut faire référence aux fichiers par leur URL dans le dépôt, ce qui permet un accès aux informations même sans disposer d'une copie de travail.

Contenu des dossiers suivis en versions

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

$ svn list http://svn.exemple.com/depot/projet
LISEZMOI
branches/
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.exemple.com/depot/projet
  23351 sally                 05 fev.,  13:26 ./
  20620 sally            1084 13 janv. 2006   LISEZMOI
  23339 harry                 02 sept., 01:40 branches/
  23198 harry                 23 janv., 17:17 tags/
  23351 sally                 27 fevr., 13:26 trunk/

Les colonnes vous indiquent la révision à laquelle le fichier ou le dossier 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 dossier local en cours, pas le dossier en cours de la copie de travail. Après tout, si vous voulez voir le contenu de votre dossier 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]

 
# met le dossier courant tel qu'il était à la révision 1729.
$ svn update -r 1729 
Mise à jour de '.' :
…
$

Astuce

Beaucoup de nouveaux utilisateurs de Subversion essaient d'utiliser la commande svn update comme dans cet exemple pour « annuler » des modifications propagées, mais cela ne fonctionne pas parce que vous ne pouvez pas propager des changements que vous avez obtenus en remontant le temps d'une copie de travail si le contenu des fichiers a changé dans des révisions plus récentes. Reportez-vous à la section intitulée « Résurrection des éléments effacés » pour une description de comment « annuler » une propagation.

Si vous préférez créer une nouvelle copie de travail complète à partir d'un instantané plus ancien, vous pouvez modifier l'appel classique à svn checkout. De même que pour svn update, vous pouvez passer l'option --revision (-r). Mais pour des raisons que nous explicitons dans la section intitulée « Révisions pivots et révisions opérationnelles », vous voudrez certainement spécifier la révision cible comme une partie de l'URL étendue suivant la syntaxe de Subversion.

 
# Extraie la branche principale à la révision 1729.
$ svn checkout http://svn.exemple.com/svn/depot/trunk@1729 trunk-1729
… 
# Extraie la branche principale actuelle telle qu'elle était
# à la révision 1729.
$ svn checkout http://svn.exemple.com/svn/depot/trunk -r 1729 trunk-1729
…
$

Enfin, si vous êtes en train de réaliser une version officielle et que vous voulez empaqueter vos fichiers et dossiers suivis en versions, vous pouvez utiliser la commande svn export pour créer une copie locale de tout ou partie de votre dépôt sans que la zone administrative .svn ne soit incluse. La syntaxe de base de cette sous-commande est identique à celle de svn checkout :

 
# Exporte la branche principale à partir de la dernière révision.
$ svn export http://svn.exemple.com/svn/depot/trunk trunk-export
… 
# Exporte la branche principale à partir de la révision 1729.
$ svn export http://svn.exemple.com/svn/depot/trunk@1729 trunk-1729
… 
# Exporte la branche principale actuelle, telle qu'elle était à la
# révision 1729.
$ svn export http://svn.example.com/svn/repo/trunk -r 1729 trunk-1729
…
$

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, en utilisant les commandes de votre système d'exploitation. Vous seriez cependant bien inspiré d'y jeter un œil avant, en lançant la commande svn status afin d'examiner tous les fichiers marqués d'un ? pour vous assurer qu'ils ne sont d'aucune importance.

Quand Subversion modifie votre copie de travail (ou toute information dans la zone administrative), 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 enlève son verrou et 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 (par exemple si le processus est tué ou si 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 vous informe des verrous posés dans la copie de travail, en affichant un L devant les éléments verrouillés :

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

$ svn cleanup
$ svn status
M      un-repertoire/truc.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 différents types de « verrous » pour des éclaircissements.

Prenons l'exemple d'un projet logiciel sur lequel vous travaillez et qui ressemble à ceci :

$ svn list -Rv svn://svn.exemple.com/trunk/
     13 harry                 06 sept., 10:34 ./
     13 harry              27 06 sept., 10:34 COPYING
     13 harry              41 06 sept., 10:32 Makefile
     13 harry              53 06 sept., 10:34 LISEZMOI
     13 harry                 06 sept., 10:32 code/
     13 harry              54 06 sept., 10:32 code/machin.c
     13 harry             130 06 sept., 10:32 code/truc.c
$

Plus tard, lors de la révision 14, votre collaborateur Harry renomme le fichier machin.c en bidule.c. Malheureusement, vous n'y prêtez pas attention toute de suite. Vous êtes occupé à réaliser un ensemble de modifications différent, dont certaines concernent machin.c :

$ svn diff
Index: code/truc.c
===================================================================
--- code/truc.c	(revision 13)
+++ code/truc.c	(copie de travail)
@@ -3,5 +3,5 @@
 int main(int argc, char *argv[])
 {
     printf("Je n'aime pas être baladé !\n%s", machin());
-    return 0;
+    return 1;
 }
Index: code/machin.c
===================================================================
--- code/machin.c	(revision 13)
+++ code/machin.c	(copie de travail)
@@ -1,4 +1,4 @@
 const char *machin(void)
 {
-    return "Moi non plus !\n";
+    return "Bah, moi j'aime bien être ballotté !\n";
 }
$

Vous commencez à réaliser que quelqu'un a modifié machin.c quand votre tentative de propagation échoue :

$ svn commit -m "Quelques petits changements."
Envoi          code/machin.c
Transmission des données .
svn: E155011: Échec de la propagation (commit), détails :
svn: E155011: Fichier '/home/svn/projet/code/machin.c' obsolète
svn: E160013: Fichier non trouvé : transaction '14-e', chemin '/code/machin.c'
$

À ce moment, vous devez lancer svn update.Non seulement votre copie de travail est mise à jour et vous pouvez voir les modifications effectuées par Harry, mais aussi l'arborescence est marquée comme étant en conflit afin que vous puissiez réellement mesurer ce qui a été modifié et résoudre le conflit proprement.

$ svn update 
Mise à jour de '.' :
   C  code/machin.c
A     code/bidule.c
U     Makefile
Actualisé à la révision 14.
Résumé des conflits :
  Arborescences en conflit : 1

Dans la sortie qu'elle produit, svn update indique un conflit d'arborescence en utilisant un C majuscule dans la quatrième colonne. svn status fournit plus de détails sur ce conflit :

$ svn status
M       code/truc.c
A  +  C code/machin.c
      >   local edit, incoming delete upon update
Résumé des conflits :
  Arborescences en conflit : 1
$

Notez que machin.c est automatiquement marqué pour ajout dans votre copie de travail, ce qui simplifie les choses si vous décidez de conserver le fichier.

Du fait qu'un déplacement dans Subversion est implémenté comme une copie suivie d'un effacement et que ces deux opérations ne peuvent pas être corrélées facilement lors d'une mise à jour, tout ce que Subversion peut vous dire c'est que la mise à jour va effacer le fichier sur lequel vous avez fait des modifications. L'effacement peut faire partie d'un déplacement ou n'être simplement qu'un effacement en tant que tel. Déterminer exactement quelle est la sémantique associée à cette modification dans le dépôt est important : vous devez savoir dans quelle mesure vos modifications s'intègrent dans l'évolution générale du projet. Lisez donc les commentaires de propagation, discutez avec vos collaborateurs, étudiez les lignes modifiées à l'aide de la visualisation « diff ». Bref, faites ce que vous avez à faire pour déterminer quelle est la conduite à tenir dans ce cas précis.

Ici, le commentaire de propagation de Harry vous donne toutes les informations utiles.

$ svn log -r14 ^/trunk
------------------------------------------------------------------------ 
r14 | harry | 2011-09-06 10:38:17 -0400 (dim. 06. sept. 2011) | 1 ligne
Chemins modifiés:
   M /Makefile
   D /code/machin.c
   A /code/bidule.c (de /code/machin.c:13)

J'ai renommé machin.c en bidule.c et modifié le Makefile en conséquence.
------------------------------------------------------------------------
$

svn info affiche les URL des éléments en conflit. L'URL de gauche indique la source locale du conflit alors que l'URL droite indique la source externe du conflit. Ces URL vous montrent où vous devez commencer à chercher les modifications qui génèrent le conflit dans l'historique du dépôt.

$ svn info code/machin.c
Chemin: code/machin.c
Nom: machin.c
URL: http://svn.exemple.com/svn/depot/trunk/code/machin.c
… 
Tree conflict: local edit, incoming delete upon update
  Source gauche: (fichier) ^/trunk/code/machin.c@4
  Source  droit: (aucun) ^/trunk/code/machin.c@5

$

On dit que machin.c est victime du conflit d'arborescence. Il ne peut pas être propagé tant que le conflit n'est pas résolu :

$ svn commit -m "Petites résolutions de problèmes"
svn: E155015: Échec de la propagation (commit), détails :
svn: E155015: Arrêt de la propagation : '/home/svn/projet/code/machin.c' demeure en conflit
$

Pour résoudre ce conflit, vous devez soit approuver soit rejeter le déplacement effectué par Harry.

Si vous approuvez le déplacement, votre machin.c est superflu. Vous pouvez alors l'effacer et marquer le conflit comme résolu. Mais attendez : vous avez effectué des modifications dans ce fichier ! Avant d'effacer machin.c, vous devez décider si les modifications que vous avez effectuées doivent être appliquées ailleurs, par exemple dans le nouveau fichier bidule.c, qui contient en effet tout l'ancien code de machin.c. Considérons que vos modifications doivent « suivre le mouvement ». Subversion n'est pas assez perfectionné pour faire ce travail à votre place^[10], vous devez donc faire ces modifications manuellement.

Dans notre exemple, vous pourriez manuellement refaire vos modifications sur machin.c assez facilement — ce n'était qu'un seul changement de ligne après tout. Cependant, ce n'est pas toujours le cas, c'est pourquoi nous allons voir une approche qui peut s'appliquer sur de plus gros changements. Nous commencerons par utiliser svn diff pour générer un fichier patch. Ensuite, nous allons modifier les entêtes de ce fichier patch pour pointer vers le nouveau nom de notre fichier déplacé. Finalement, nous appliquons à nouveau le fichier patch modifié sur la copie de travail.

 
$ svn diff code/machin.c > FICHIER_CORRECTIF
$ cat FICHIER_CORRECTIF
Index: code/machin.c
===================================================================
--- code/machin.c	(révision 14)
+++ code/machin.c	(copie de travail)
@@ -1,4 +1,4 @@
 const char *machin(void)
 {
-    return "Moi non plus!\n";
+    return "Bah, moi j'aime bien être ballotté !\n";
 }
$ ### Editer FICHIER_CORRECTIF pour pointer vers code/bidule.c au lieu de code/machin.c

$ cat FICHIER_CORRECTIF
Index: code/bidule.c
===================================================================
--- code/bidule.c	(révision 14)
+++ code/bidule.c	(copie de travail)
@@ -1,4 +1,4 @@
 const char *machin(void)
 {
-    return "Moi non plus!\n";
+    return "Bah, moi j'aime bien être ballotté !\n";
 }
$ svn patch FICHIER_CORRECTIF
U         code/bidule.c
$

Maintenant que les changements que vous aviez faits originellement sur machin.c ont été correctement reproduits dans bidule.c, vous pouvez effacer machin.c et résoudre le conflit en indiquant que vous choisissez la version de la copie de travail comme valide.

 
$ svn delete --force code/machin.c
D         code/machin.c
$ svn resolve --accept=working code/machin.c
Conflit sur 'code/machin.c' résolu
$ svn status
M       code/bidule.c
M       code/truc.c
$ svn diff
Index: code/truc.c
===================================================================
--- code/truc.c  (revision 14)
+++ code/truc.c  (working copy)
@@ -3,5 +3,5 @@
 int main(int argc, char *argv[])
 {
     printf("Je n'aime pas être baladé !\n%s", machin());
-    return 0;
+    return 1;
 }
Index: code/bidule.c
===================================================================
--- code/bidule.c  (revision 14)
+++ code/bidule.c  (working copy)
@@ -1,4 +1,4 @@
 const char *machin(void)
 {
-    return "Moi non plus!\n";
+    return "Bah, moi j'aime bien être ballotté !\n";
 }
$

Mais que se passe-t-il si vous n'êtes pas d'accord avec le déplacement ? Eh bien, dans ce cas, vous pouvez effacer bidule.c après vous être assuré que celui-ci ne contient pas de modification postérieure à son renommage que vous souhaiteriez conserver (n'oubliez pas non plus de revenir sur les modifications effectuées par Harry sur Makefile). Comme machin.c est déjà prévu d'être ajouté lors de la prochaine propagation, il n'y a rien de plus à faire et le conflit peut être marqué comme résolu :

$ svn delete --force code/bidule.c
D         code/bidule.c
$ svn resolve --accept=working code/machin.c
Conflit sur 'code/machin.c' résolu
$ svn status
M       code/truc.c
A  +    code/machin.c
D       code/bidule.c
M       Makefile
$ svn diff
Index: code/truc.c
===================================================================
--- code/truc.c	(revision 14)
+++ code/truc.c	(copie de travail)
@@ -3,5 +3,5 @@
 int main(int argc, char *argv[])
 {
     printf("Je n'aime pas être baladé !\n%s", machin());
-    return 0;
+    return 1;
 }
Index: code/machin.c
===================================================================
--- code/machin.c	(revision 14)
+++ code/machin.c	(copie de travail)
@@ -1,4 +1,4 @@
 const char *machin(void)
 {
-    return "Moi non plus!\n";
+    return "Bah, moi j'aime bien être ballotté !\n";
 }
Index: code/bidule.c
===================================================================
--- code/bidule.c	(revision 14)
+++ code/bidule.c	(copie de travail)
@@ -1,4 +0,0 @@
-const char *machin(void)
-{
-    return "Moi non plus!\n";
-}
Index: Makefile
===================================================================
--- Makefile	(revision 14)
+++ Makefile	(copie de travail)
@@ -1,2 +1,2 @@
 truc:
-	$(CC) -o $@ code/truc.c code/bidule.c
+	$(CC) -o $@ code/truc.c code/machin.c

Vous avez résolu votre premier conflit d'arborescence. Vous pouvez propager vos modifications et vous plaindre auprès de Harry à la pause café à propos de la surcharge de travail qu'il vous a infligée.

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 commentaire 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 dossier suivi en versions courant, les commentaires
# 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 :

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

	Note
	Gardez à l'esprit que la plupart des interpréteurs de commandes (shells) requièrent de mettre les dates qui contiennent des espaces entre guillemets ou « d'échapper » les espaces. Certains interpréteurs peuvent aussi poser problème avec les accolades si elles ne sont pas échappées. Consulter la documentation de votre interpréteur pour connaître les spécificités de votre environnement.

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

L'aptitude de Subversion à convertir correctement les horodatages de révisions en numéros de révision repose sur le fait que les horodatages de révisions sont ordonnées de manière croissante (plus le numéro est élevé, plus l'horodatage est récent). Mais l'horodatage d'une révision étant 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 modifiés et ne plus suivre la chronologie réelle. Aujourd'hui, cela n'affecte pas la plupart des opérations de Subversion (c'est le numéro de révision qui est l'identifiant primaire d'une révision). Mais si l'ordonnacement des horodatages 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. Combiner les historiques de plusieurs dépôts pour n'en former qu'un (tel que décrit dans la section intitulée « Migration des données d'un dépôt ») est la cause principale de ce type de situation.

À l'instar de Subversion, qui utilise les propriétés pour stocker des méta-données sur les fichiers, les dossiers 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 dossier. Ou, si vous voulez garder les mêmes noms de fichier, vous placez vos miniatures dans un dossier 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 dossier 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 « Utilisation des 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 dossier 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.

$ svn commit -m "Corrige la dernière régression connue." \
             --with-revprop "resultat-des-tests=tout ok"
Envoi         lib/crit_bits.c
Transmission des données .
Révision 912 propagée.
$

$ svn log --with-all-revprops --xml lib/crit_bits.c
<?xml version="1.0"?>
<log>
<logentry
   revision="912">
<author>harry</author>
<date>2011-07-29T14:47:41.169894Z</date>
<msg>Corrige la dernière régression connue.</msg>
<revprops>
<property
   name="resultat-des-tests">tout ok</property>
</revprops>
</logentry>
…
$

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 dossiers. 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 aussi utiliser des chiffres, des tirets (-) et des points (.) ^[13].

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 « Configuration générale ») 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 dossiers. 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 produit 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
  license

$

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 au client texte interactif 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 commentaire associé à la propagation d'une révision précédente ^[14]. Si le dossier 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 commentaires 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 dossiers 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 dossiers 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 dossiers 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
___________________________________________________________________
Added: copyright
## -0,0 +1 ##
+(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 « Vue d'ensemble des changements effectués »).

$ svn update calc
Mise à jour de 'calc' :
M  calc/Makefile.in 
Actualisé à la révision 143.
Conflit sur la propriété 'nombre_lignes' découvert sur 'calc/bouton.c'.
local add, incoming add upon update
Select: (p) postpone, (mf) my version, (tf) their version,
        (dc) display conflict, (e) edit property, (q) quit resolution,
        (h) help: p
Résumé des conflits :
  Property conflicts: 1
$

$ svn status calc
 C      calc/bouton.c
?       calc/bouton.c.prej
$ cat calc/bouton.c.prej
Tentative de modification de la propriété 'nombre_lignes' de '1267' à '1301'
mais la propriété a été modifiée localement de '1267' à '1256'.
$

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.

Subversion 1.7 améliore la situation sur deux points. D'abord, son affichage non standard des différences de propriétés est au moins traitable par machine — c'est une amélioration par rapport à l'affichage des propriétés des versions antérieures à la 1.7. Ensuite, Subversion 1.7 introduit la sous-commande svn patch, conçue spécifiquement pour prendre en charge les informations supplémentaires que génère la sortie de svn diff afin d'appliquer les changements à la copie de travail. Ainsi, pour ce qui nous concerne directement dans ce chapitre, les différences de propriétés indiquées dans les fichiers diff produits par svn diff de Subversion 1.7 ou ultérieur peuvent être appliqués automatiquement à une copie de travail par la commande svn patch. Pour plus d'informations concernant svn patch, référez-vous à svn patch dans Guide de référence de svn : le client texte interactif.

Note

Il existe une exception à l'indication des modifications de propriétés que rapporte la commande svn diff : les modifications à la propriété spéciale de Subversion svn:mergeinfo (cette propriété est utilisée pour garder trace des fusions qui ont été effectuées dans le dépôt) sont affichées d'une manière plus lisible pour les humains. C'est une facilité accordée à ceux qui doivent lire ces descriptions. Mais cela sert également à ce que les programmes qui appliquent les patchs (y compris svn patch) sautent ces descriptions en les traitant comme du bruit non significatif. Cela pourrait ressembler à un bogue, mais pas du tout car cette propriété a pour finalité d'être gérée uniquement par la sous-commmande svn merge. Pour plus d'information sur le suivi des fusions, regardez Chapitre 4, Gestion des branches.

Subversion 1.8 introduit le concept de propriétés héritées. Il n'y a rien de particulier concernant une propriété qui fait qu'on peut en hériter. En fait, on peut hériter de toutes les propriétés suivies en versions ! La principale différence entre les propriétés suivies en version avant Subversion 1.8 et après est que ces dernières proposent un mécanisme pour trouver les propriétés définies sur des chemins cibles parents même si ces parents ne se trouvent plus dans la copie de travail.

L'héritage de propriété se concrètise par l'intermédiaire de quelques commandes. D'abord, les sous-commandes svn proplist et svn propget peuvent retrouver toutes les propriétés de parents de chemins d'une URL ou d'une copie de travail en utilisant l'option --show-inherited-props. Vous pouvez vous représenter cette option comme étant l'opposé de l'option --recursive : au lieu de parcourir récursivement « vers le bas » les sous-dossiers de la cible, les sous-commandes avec l'option --show-inherited-props parcourrent « vers le haut » les dossiers parents de la cible. Les sous-commandes svnlook propget et svnlook proplist peuvent aussi utiliser l'option --show-inherited-props de la même manière.

Regardons un exemple pour mieux en comprendre le fonctinnement. La commande propget récursive ci-dessous appliquée à la racine de la copie de travail trouve la propriété svn:auto-props définie à la fois sur la cible et sur l'un de ses sous-dossiers site :

$ svn pg svn:auto-props --verbose -R .
Propriétés sur '.':
  svn:auto-props
    *.py = svn:eol-style=native
    *.c = svn:eol-style=native
    *.h = svn:eol-style=native

Propriétés sur 'site':
  svn:auto-props
    *.html = svn:eol-style=native

Si nous spécifions comme cible de la sous-commande le sous-dossier site et que nous utilisons l'option --show-inherited-props, nous trouvons que la propriété svn:auto-props est définie sur la cible et son parent. Les propriétés des parents sont affichées en tant que « héritées » :

$ svn pg svn:auto-props --verbose --show-inherited-props site
Propriétés héritées sur 'site'
de '.':
  svn:auto-props
    *.py = svn:eol-style=native
    *.c = svn:eol-style=native
    *.h = svn:eol-style=native

Propriétés sur 'site':
  svn:auto-props
    *.html = svn:eol-style=native

Dans les exemples précédents, la racine de la copie de travail correspond à la racine du dépôt, mais les propriétés peuvent aussi être héritées de l'extérieur de la copie de travail quand les racines ne coïncident pas. Réalisons une extraction du dossier site de l'exemple précédent et faisons-en la racine de notre copie de travail :

$ svn co http://svn.exemple.com/depot site-ct
A    site-ct/publication
A    site-ct/publication/ch2.html
A    site-ct/publication/actualités.html
A    site-ct/publication/ch3.html
A    site-ct/publication/faq.html
A    site-ct/publication/index.html
A    site-ct/publication/ch1.html
 U   site-ct
Révision 19 extraite.
$ cd site-ct

Maintenant, quand nous cherchons les propriétés héritées sur un chemin d'une copie de travail, nous pouvons constater qu'une propriété est héritée d'un parent de la copie de travail et une est héritée d'un parent du dépôt, c'est-à-dire à un emplacement « au-dessus » de la racine de la copie de travail :

$ svn pg svn:auto-props --verbose --show-inherited-props publication
Propriétés héritées sur 'publication',
de 'http://svn.exemple.com/depot':
  svn:auto-props
    *.py = svn:eol-style=native
    *.c = svn:eol-style=native
    *.h = svn:eol-style=native
Propriétés héritées sur 'publication',
de '.':
  svn:auto-props
    *.html = svn:eol-style=native

	Avertissement
	Vous ne pouvez hériter de propriétés des chemins dans des dépôts pour lesquels vous avez un droit en lecture — regardez la section intitulée « Authentification et contrôle d'accès intégrés » et la section intitulée « Contrôle d'accès ». Si vous n'avez pas de droit de lecture à un chemin parent alors tout se passe comme si le parent n'avait pas de propriété définie.

Comme indiqué précédemment, les commandes svnlook proplist et svnlook propget acceptent l'option --show-inherited-props, mais au lieu de travailler sur des copies de travail ou des URL, elles travaillent sur des chemins de dépôts :

$ svnlook pg repos svn:auto-props /site/publication --show-inherited-props -v
Propriétés héritées sur '/site/publish'
de '/':
  svn:auto-props
    *.py = svn:eol-style=native
    *.c = svn:eol-style=native
    *.h = svn:eol-style=native

Propriétés héritées sur '/site/publish'
de '/site':
  svn:auto-props
    *.html = svn:eol-style=native

Les propriétés héritées en amont de la racine d'une copie de travail sont mises en cache dans la zone administrative de la copie de travail au momemnt de l'extraction et des mises à jour de la copie de travail. Cela signifie que vous n'avez pas besoin d'accéder au dépôt pour visualiser les propriétés héritées. Cela permet aux sous-commandes Subversion qui n'accèdent tradionnellement pas au dépôt (par exemple svn add) de restées « déconnectées » tout en ayant accès aux propriétés héritées de chemins qui ne sont pas dans la copie de travail. Cependant, cela signifie aussi que les propriétés héritées en amont de la racine de la copie de travail peuvent avoir été modifiées depuis la dernière mise à jour, ce qui rend votre cache local obsolète. Donc, si vous avez absolument besoin des dernières valeurs de propriétés héritées, il est toujours préférable de d'abord mettre à jour votre copie de travail ou de requêter directement le dépôt.

Arrivé à ce point, vous devez vous dire : « pas mal, mais à quoi cela sert-il vraiment ? ». En tant que tel, l'héritage de propriété n'est pas très utile. Avant la version 1.8, toutes les propriétés svn:* que Subversion se réserve (et possiblement toutes les propriétés spécifiques définies par les utilisateurs) s'appliquaient seulement sur le chemin sur lequel elles étaient définies ou, au plus, sur les enfants directs des chemins^[15]. Les propriétés héritées sont un moyen utilisé par Subversion pour accomplir d'autres choses intéressantes, comme définir des propriétés automatiques avec svn:auto-props ou des bannissements sur tout le dépôt avec la propriété svn:global-ignores. Reportez-vous à la section intitulée « Configuration automatique des propriétés » et la section intitulée « Occultation des éléments non suivis en versions » pour plus d'informations sur ces propriétés spéciales et les manières de les utiliser.

Astuce

Aujourd'hui les propriétés héritables sont surtout utiles pour le fonctionnement de svn:auto-props et svn:global-ignores, mais cela ne signifie pas pour autant la fin de l'histoire. Les futures versions de Subversion intégreront d'autres fonctionnalités basées sur l'héritage de propriétés (un mécanisme pour définir des modèles de commentaires de propagation est le premier exemple qui nous vient à l'esprit). D'ici là, vous pouvez mettre en œuvre cette fonctionnalité comme bon vous semble. N'importe quelle métadonnées suivie en versions que vous voulez appliquer sur l'ensemble du dépôt (ou sur une grande partie de celui-ci) peut être stockée facilement dans une propriété à la racine du dépôt (ou sur le sous-arbre approprié). Nous sommes convaincu que des utilisateurs ou des administrateurs trouveront des utilisations à l'héritage de propriétés que nous n'avons jamais envisagées.

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 dossiers 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 » plus loin dans ce chapitre 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 des heuristiques pour déterminer le type MIME. En fonction de la façon dont il a été compilé, Subversion 1.7 peut utiliser des bibliothèques qui scrutent le contenu du fichier^[16] pour déterminer son type. En dernier recours, Subversion utilise sa propre heuristique très basique pour déterminer si le fichier contient des éléments non textuels. Si c'est le cas, Subversion attribue automatiquement la valeur propriété application/octet-stream (type MIME générique indiquant « une suite d'octets ») à la propriété svn:mime-type. 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).

Note

L'encodage UTF-16 est communément utilisé pour des fichiers dont le contenu sémantique est textuel par nature, mais cet encodage utilise beaucoup les octets en dehors de l'intervalle typique ASCII. Ainsi, Subversion aura tendance à classer de tels fichiers dans la catégorie binaire, au grand regret des utilisateurs qui souhaitent pouvoir effectuer des comparaisons et des fusions, de la substitution de mots-clés ou d'autres manipulations sur ces fichiers.

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 fichierde type *.cpp la propriété svn:eol-style avec la valeur native et la propriété svn:keywords avec la valeur Id. Reportez-vous à la section intitulée « Configuration générale » pour plus d'informations sur la configuration de cette fonction.

Bien que la configuration automatique de propriétés par la zone de configuration soit certainement très facile d'utilisation, les administrateurs de Subversion préféreront peut-être définir automatiquement, sur un serveur donné, un ensemble de propriétés pour tous les clients qui se connectent pour des extractions. Les clients Subversion 1.8 et plus récents possèdent cette fonctionnalité via la propriété héritable svn:auto-props.

La propriété svn:auto-props fonctionne comme la zone de configuration pour automatiquement définir des propriétés sur les fichiers lorsqu'ils sont ajoutés ou importés. La valeur de la propriété svn:auto-props doit être la même que celle de auto-props dans la zone de configuration (c'est-à-dire un nombre quelconque de paires clé-valeur au format MOTIF_FICHIER = NOM_PROPRIETE=VALEUR[;NOM_PROPRIETE=VALEUR ...]). Comme pour l'option de configuration auto-props, la propriété svn:auto-props peut être ignorée en spécifiant l'option --no-auto-props, mais contrairement à l'option de la zone de configuration, la propriété svn:auto-props n'est pas désactivée par l'option de la zone de configuration enable-auto-props définie à no.

Par exemple, considérons que vous avez extrait une copie de travail du tronc (trunk) et que avez besoin d'ajouter un nouveau fichier (nous supposons que les propriétés automatiques sont désactivées dans votre zone de configuration) :

$ svn st
?       calc/données.c

$ svn add calc/données.c
A         calc/données.c

$ svn proplist -v calc/données.c
Propriétés sur 'calc/données.c':
  svn:eol-style
    native

Vous notez qu'après avoir placé le fichier données.c sous suivi de versions, la propriété svn:eol-style a automatiquement été définie sur lui. Puisque nous avons supposé que l'option de la zone de configuration auto-props est désactivée, nous savons que la propriété svn:auto-props doit être définie sur un chemin parent de données.c. En utilisant la commande svn propget avec l'option --show-inherited-props, nous pouvons vérifier que c'est effectivement le cas :

$ svn propget svn:auto-props --show-inherited-props -v calc
Propriétés héritées sur 'calc'
de 'http://svn.exemple.com/depot':
  svn:auto-props
    *.py = svn:eol-style=native
    *.c = svn:eol-style=native
    *.h = svn:eol-style=native

Au contraire de la propriété svn:global-ignores et de la directive homologue de la zone de configuration global-ignores, qui se combinent, la propriété svn:auto-props prévaut sur l'option de la zone de configuration auto-props si elle définit une propriété automatique pour le même motif que la zone de configuration. Les propriétés automatiques héritées^[17] d'un chemin peuvent aussi prévaloir sur un motif identique hérité d'un chemin différent. L'ordre de priorité est défini comme suit :

Prenons un exemple. Supposons que nous avons ce contenu dans le fichier de configuration:

[miscellany]
enable-auto-props = yes
[auto-props]
*.py  = svn:eol-style=CR
*.c   = svn:eol-style=CR
*.h   = svn:eol-style=CR
*.cpp = svn:eol-style=CR

Vous voulez ajouter trois fichiers dans le dossier calc de votre copie de travail:

$ svn st
?       calc/données-binding.cpp
?       calc/données.c
?       calc/éditeur.py

Vérifions que svn:auto-props s'applique sur calc :

$ svn propget svn:auto-props -v --show-inherited-props calc
Propriétés héritées sur 'calc'
de 'http://svn.exemple.com/depot':
  svn:auto-props
    *.py = svn:eol-style=native
    *.c = svn:eol-style=native
    *.h = svn:eol-style=native

Propriétés héritées sur 'calc'
de '.':
  svn:auto-props
    *.py = svn:eol-style=native
    *.c = svn:keywords=Auteur Date Id Rev URL

Quand nous ajoutons ces trois fichiers, qu'attendons nous pour auto-props ? Nous ajoutons le trio au suivi de versions et nous vérifions :

$ svn add calc --force
A         calc/données-binding.cpp
A         calc/données.c
A         calc/éditeur.py

Le nom de fichier données-binding.cpp ne correspond qu'à un seul motif, *.cpp = svn:eol-style=CR dans la zone de configuration, donc la propriété svn:eol-style est évidemment définie à CR :

$ svn proplist -v calc/données-binding.cpp
Propriétés sur 'calc/données-binding.cpp':
  svn:eol-style
    CR

Le nom de fichier éditeur.py correspond à un seul motif dans la zone de configuration et à deux pour la propriété svn:auto-props mais, en raison de l'ordre de priorité défini auparavant, la propriété définie explicitement sur calc, *.py = svn:eol-style=native, est prioritaire. Donc la propriété svn:eol-style est définie à native: :

$ svn proplist -v calc/éditeur.py
Propriétés sur 'calc/éditeur.py':
  svn:eol-style
    native

Le nom de fichier données.c correspond à des motifs dans la zone de configuration et dans les propriétés héritées svn:auto-props. La propriété automatique svn:keywords n'est définie qu'une seule fois, sur calc, donc données.c possède automatiquement cette propriété. svn:auto-props sur calc ne définit pas de valeur pour svn:eol-style, donc le parent le plus proche http://svn.exemple.com/depot, définit la valeur :

$ svn proplist -v calc/données.c
Propriétés sur 'calc/données.c':
  svn:eol-style
    native
  svn:keywords
    Auteur Date Id Rev URL

Avertissement

L'application des priorités est uniquement valable pour des motifs identiques. Si un nom de fichier à ajouter ou importer correspond à plus d'un motif, alors il n'y a aucune garantie concernant le motif des propriétés automatiques qui est appliqué. Par exemple, disons que vous voulez ajouter le fichier truc.cpp dans le dossier machin. Supposons encore que la propriété svn:auto-props est définie sur machin avec la valeur : *.c* = svn:eol-style=native *.cpp = svn:eol-style=native;svn:keywords=Auteur Date Id Rev URL Comme truc.cpp correspond aux deux motifs,il n'est pas possible de savoir si la propriété svn:keywords sera définie sur truc.cpp quand on l'ajoutera.

Un dernier point sur svn:auto-props. Cette propriété (tout comme svn:global-ignores, voir la section intitulée « Occultation des éléments non suivis en versions ») ne constitue qu'une indication aux clients qui comprennent la signification de cette propriété. Les clients plus anciens ignorent ces propriétés, l'option --no-auto-props les laisse de côté, un utilisateur peut très bien modifier ou supprimer les propriétés automatiquement après qu'elles aient été définies ; il existe pléthore de moyens de passer outre les indications fournies par le contenu de svn:auto-props. Sachant cela, les administrateurs doivent toujours utiliser des procédures automatiques (hook scripts en anglais) pour valider la politique des propriétés qu'ils souhaitent mettre en place ; ils peuvent ainsi rejeter les propagations qui ne respectent pas les règles. Reportez-vous à la section intitulée « Mise en place des procédures automatiques » pour plus de détails sur les procédures automatiques du dépôt.

Dans cette section, nous allons brièvement aborder toutes les propriétés que Subversion réserve à son propre usage. Nous regardons les deux types de propriétés, celles associées à un fichier ou un dossier particulier suivi en versions et celles associées aux révisions

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.

De plus, puisque le fait d'afficher les différences et les modifications ligne par ligne est, c'est évident, dépendant de la signification que l'on accorde à une « ligne » du fichier considéré, les fichiers dont le type MIME n'est pas compatible avec du texte déclenchent par défaut des erreurs lorsqu'ils sont la cible de sous-commandes telles que svn diff et svn annotate. Cela peut s'avérer particulièrement frustrant pour les utilisateurs de fichiers XML dont la propriété svn:mime-type est définie avec une valeur comme application/xml qui n'est pas interprétée par Subversion comme lisible par un humain car relativement ambigüe. Heureusement, ces sous-commandes proposent l'option --force pour obliger Subversion à essayer d'opérer sur ces fichiers malgré leur apparente illisibilité pour un humain.

Avertissement

La propriété svn:mime-type, lorsqu'elle est définie avec une valeur qui n'indique pas de contenu textuel, peut entrainer des comportements inattendus avec les autres propriétés. Par exemple, comme la notion de fin de ligne (et donc de conversion de caractère de fin de ligne) n'a pas de sens pour un fichier binaire, Subversion vous empêche de définir la propriété svn:eol-style sur ces fichiers. Cela saute aux yeux lorsque 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.

Subversion fournit plusieurs mécanismes pour définir automatiquement la propriété svn:mime-type sur un fichier suivi en versions. Consultez la section intitulée « Configuration automatique des propriétés » pour en obtenir les détails.

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 ^[20]. 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 dossiers.

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 plates-formes 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 dossier 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êmes fichiers images 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: E175002: Échec de la propagation (commit), (détails):
svn: E175002: 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 à propager une modification sur ce 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 -u:

$ 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 est posé 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 ^/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 renvoie 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 /var/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 /var/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   machin.c
M    O          32   raisin.jpg
        *       72   truc.h
État par rapport à la révision     105
$ svn unlock raisin.jpg
svn: E195013: '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: warning: W160039: Unlock failed  on 'raisin.jpg' (403 Forbidden)
$ 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 : W160035: Path '/project/raisin.jpg' is already locked by
user 'harry' in filesystem '/var/svn/repos/db'
$ 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 
À la révision 105.
$ svn update
Updating '.':
  B  raisin.jpg 
À la révision 105.
$ 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 -u 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êchent de sauvegarder ses modifications dans le fichier. Cela lui rappelle 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 : W160035: Échec de la demande de verrou : '/projet/raisin.jpg'
is already locked by user 'harry' in filesystem '/var/svn/depot/db'

$ 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 ^[30].

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
A [correctifs-maths] entier.c
A [correctifs-maths] ops-math.c
$ 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
A [math-fixes] bouton.c
$ 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
D [correctifs-maths] bouton.c
$ svn changelist correctifs-graphiques bouton.c
A [correctifs-graphiques] bouton.c
$

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
D [correctifs-maths] bouton.c
A [correctifs-graphiques] bouton.c
$ 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 pourrait 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 bien 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 commit -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 .
D [correctifs-maths] entier.c
A [bogues-maths] entier.c
D [correctifs-maths] ops-math.c
A [bogues-maths] ops-math.c
$ svn changelist --remove --changelist bogues-maths --depth infinity .
D [bogues-maths] entier.c
D [bogues-maths] ops-math.c
$

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 la section intitulée « URL des dépôts Subversion »).

	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 réservées à l'usage de 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 afin de requérir une authentification. Parfois, les opérations de lecture sont autorisées aux utilisateurs anonymes alors que les opérations d'écriture nécessitent une authentification. Dans d'autres cas, à la fois les opérations de lecture et d'écriture requièrent une authentification. Les différentes options du serveur Subversion gèrent différents protocoles d'authentification mais, du point de vue de l'utilisateur, l'authentification se résume typiquement à un identifiant et un mot de passe. Les clients Subversion offrent différentes façon de gérer les éléments d'authentification de l'utilisateur, depuis la saisie interactive de l'identifiant et du mot de passe jusqu'à la mise en cache des éléments dans un conteneur chiffré ou non sur le disque.

Ici, le lecteur soucieux de sécurité va immédiatement bondir de son siège : « Mettre en cache des mots de passe sur le disque ? Quelle horreur ! Jamais ! ». Ne vous inquiétez pas outre mesure : ce n'est pas aussi terrible que ça en a l'air. Les paragraphes qui suivent vont détailler les différents types de cache pour les éléments d'authentification que Subversion utilise, les phases où il les utilise et comment désactiver cette fonctionnalité en totalité ou en partie.

Désactivation de la mise en cache des mots de passe

Quand vous effectuez une opération Subversion qui nécessite de vous authentifier, par défaut Subversion essaie de mettre en cache vos éléments d'authentification sur le disque sous une forme chiffrée. Sur certains systèmes, Subversion peut être incapable de chiffrer vos éléments d'authentification. Dans ce cas, Subversion vous demandera si vous voulez vraiment mettre en cache vos éléments d'authentification sur le disque sous forme claire :

$ svn checkout https://host.example.com:443/svn/private-repo
-----------------------------------------------------------------------
ATTENTION!  Your password for authentication realm:

   <https://host.example.com:443> Subversion Repository

can only be stored to disk unencrypted!  You are advised to configure
your system so that Subversion can store passwords encrypted, if
possible.  See the documentation for details.

You can avoid future appearances of this warning by setting the value
of the 'store-plaintext-passwords' option to either 'yes' or 'no' in
'/tmp/servers'.
-----------------------------------------------------------------------
Store password unencrypted (yes/no)?

Si vous voulez profiter de la facilité de ne pas avoir à entrer votre mot de passe à chaque nouvelle opération, vous pouvez répondre yes à cette invite. Si vous ne voulez pas stocker votre mot de passe en clair et que vous ne voulez pas que Subversion vous pose la question à chaque fois, vous pouvez désactiver la mise en cache en clair des mots de passe, soit de manière permanente, soit en fonction du serveur auquel vous vous connectez.

	Avertissement
	Au moment de faire votre choix concernant la mise en cache des mots de passe, vérifier la politique de sécurité relative à votre poste de travail. Beaucoup d'entreprises ont des règles strictes sur le stockage des mots de passe de leurs employés.

Pour désactiver de manière permanente la mise en cache des mots de passe en clair, ajouter la ligne store-plaintext-passwords = no à la section [global] du fichier de configuration servers de votre machine locale. Pour la désactiver uniquement pour un serveur particulier, utiliser la même directive dans la section appropriée du fichier de configuration servers (pour plus de détails, reportez-vous à la section intitulée « Options de configuration » dans Chapitre 7, Personnalisation de Subversion.)

Pour désactiver la mise en cache des mots de passe pour les opérations en ligne de commande, utilisez l'option --no-auth-cache. Pour désactiver la mise en cache de manière permanente, ajoutez l'option store-passwords = no dans le fichier de configuration Subversion de votre machine.

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

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

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

Un dernier mot sur l'authentification

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 :

1. D'abord, le client vérifie si l'utilisateur a spécifié explicitement des éléments d'authentification dans la ligne de commande (options --username et/ou --password). Si c'est le cas, le client essaie de s'authentifier auprès du serveur avec ces éléménts.

2. Si les éléments d'authentification ne sont pas passés en ligne de commande, ou si ceux qui ont été fournis ne sont pas valides, le client regarde dans la zone auth/ s'il trouve le nom, le port et le domaine du serveur pour voir si l'utilisateur a déjà les éléments d'authentification en cache. Si c'est le cas, il essaie d'utiliser ces éléments pour s'authentifier.

3. Finalement, si les mécanismes précédents ont abouti à des échecs d'authentification sur le serveur, le client se résout à demander les éléments à l'utilisateur (à moins qu'il ne lui ait été indiqué de ne pas le faire via l'option --non-interactive ou son équivalent spécifique au client).

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).

Le client texte interactif Subversion sait faire plusieurs opérations en utilisant des URL du dépôt et sans copie de travail afin d'effectuer des modifications simples. Certaines sont décrites ailleurs dans ce livre, mais nous vous en donnons la liste exhaustive ici.

Certainement la plus évidente des opérations à distance de type propagation est la comande svn import. Nous décrivons cette commande dans la section intitulée « Importation de fichiers et de dossiers » lorsque nous expliquons comment insérer facilement une arborescence complète de données non suivies en versions dans un dépôt Subversion afin de démarrer le processus de suivi de versions sur ces données.

Les commandes svn mkdir et svn delete, lorsqu'elle ciblent des URL, sont aussi des opérations de type propagation. Elles permettent respectivement à l'utilisateur de créer un ou plusieurs nouveaux dossiers suivis en versions ou supprimer (récursivement) un ou plusieurs fichiers ou dossiers suivis en versions, sans l'utilisation d'une copie de travail. Chaque fois que vous entrez une de ces commandes, le client communique avec le serveur de la même manière que s'il décrivait la propagation de l'ajout d'un dossier ou de la suppression d'un élément de la copie de travail. S'il n'y a pas de problème ou de conflit détecté par cette opération, le serveur propage les ajouts ou les suppressions dans une nouvelle révision unique.

Vous pouvez utiliser svn copy ou svn move avec deux URL (une URL source de la copie/déplacement et une URL destination) pour propager des copies ou des déplacements de fichiers ou dossiers directement dans le dépôt. Ces opérations s'avèrent être les plus coûteuses quand elles sont effectuées à l'intérieur d'une copie de travail alors qu'elles s'exécutent en temps constant lorsqu'elles sont effectuées à distance en utilisant des URL du dépôt. En fait, l'opération distante svn copy est communément utilisée pour créer des branches dans Subversion, comme nous le montrons dans la section intitulée « Création d'une branche ».

Comme pour la commande svn commit habituelle, vous pouvez spécifier un commentaire de propagation avec toutes ces commandes pour décrire les modifications que vous effectuez. Utilisez l'option --file (-F) ou --message (-m), sinon autorisez le client à vous inviter à lui fournir un commentaire de propagation.

Enfin, il y a plusieurs opérations relatives aux propriétés non suivies en versions que vous pouvez effectuer directement sur le dépôt. En fait, les propriétés de révisions sont quelques peu uniques dans ce contexte, puisqu'elles ne sont pas stockées dans les copies de travail et, par conséquent. doivent être modifiées sans toucher à la copie de travail. Reportez-vous à la section intitulée « Propriétés » pour une description détaillée de la façon de gérer les propriétés dans Subversion.

Un inconvénient de la propagation à distance par le client texte interactif est que vous êtes limité à une seule opération (réellement un type d'opération) par propagation. Par exemple, il est parfaitement naturel et possible de, disons, utiliser svn delete suivi de svn mkdir dans une copie de travail pour remplacer un répertoire suivi en versions existant avec un tout neuf. Lorsque vous propagez ces opérations, une seule nouvelle révision est créée dans le dépôt et cette révision comporte le remplacement complet de votre répertoire. Vous ne pouvez pas faire la même chose en opération à distance en utilisant le client texte interactif, tout en préservant l'unité de la transaction (svn delete URL créera une nouvelle révision qui supprime le répertoire et svn mkdir URL créera une deuxième révision qui recrée le répertoire).

Heureusement, Subversion fournit un utilitaire séparé qui a pour vocation de permettre aux utilisateurs d'enchaîner un ensemble d'opérations à distance et de les propager comme une modification atomique. Cet outil est svnmucc, pour Subversion Multiple URL Command Client (que l'on pourrait traduire par client Subversion pour les commandes avec de multiples URL) :

$ svnmucc --help
…Subversion multiple URL command client
usage: svnmucc ACTION...

  Perform one or more Subversion repository URL-based ACTIONs, committing
  the result as a (single) new revision.

Actions:
  cp REV SRC-URL DST-URL : copy SRC-URL@REV to DST-URL
  mkdir URL              : create new directory URL
  mv SRC-URL DST-URL     : move SRC-URL to DST-URL
  rm URL                 : delete URL
  put SRC-FILE URL       : add or modify file URL with contents copied from
                           SRC-FILE (use "-" to read from standard input)
  propset NAME VALUE URL : set property NAME on URL to VALUE
  propsetf NAME FILE URL : set property NAME on URL to value read from FILE
  propdel NAME URL       : delete property NAME from URL
…

svnmucc est inlus dans le code source du projet Subversion depuis de nombreuses années (en tant que commande mucc historiquement), mais c'est seulement à partir de Subversion 1.8 qu'il est devenu un membre à part entière de la panoplie des utilitaires en ligne de commande de Subversion.

L'utilitaire svnmucc peut effectuer toutes les manipulations que svn fait. Mais, au contraire de svn, svnmucc ne comporte pas de sous-commande. La syntaxe adoptée consiste à lui fournir une liste d'actions et d'opérandes dans une seule ligne de commande (ou depuis un fichier, via l'option --extra-args (-X)). Certaines actions autorisées par svnmucc singent le fonctionnement du client texte interactif. Vous aurez noté dans la sortie de la commande précédente que les cp, mkdir, mv et rm ressemblent bigrement aux commandes que nous avons citées dans la section intitulée « Opérations du client texte interactif à distance ». Mais souvenez-vous que la différence fondamentale réside dans le fait que vous pouvez enchaîner plusieurs actions dans une seule ligne de commande et que cela ne générera qu'une seule révision dans le dépôt.

Prenons l'exemple précédent qui consiste à simplement remplacer un répertoire à distance. En utilisant svnmucc, vous le feriez ainsi :

$ svnmucc rm http://svn.exemple.fr/projets/pour-jouer \
          mkdir http://svn.exemple.fr/projets/pour-jouer \
          -m "Remplace mon vieux projet pour-jouer par un tout neuf."
r22 propagée par harry le 2013-01-15T21:45:26.442865Z
$

Comme vous pouvez le constater, svnmucc a réalisé en une seule révision ce qui aurait nécessité deux révision pour svn (sans copie de travail à disposition).

	Avertissement
	Une autre différence entre svnmucc et svn réside dans le fait que le premier ne vous demandera pas d'entrer un commentaire de propagation si vous ne le fournissez pas via la ligne de commande. En lieu et place, il utilisera un message par défaut (ce qui est relativement inutile).

L'utilitaire svnmucc n'est pas simplement limité aux actions que svn ferait tout aussi bien. Il introduit des fonctionnalités supplémentaires que l'on ne trouve pas dans le client texte interactif. Par exemple, vous pouvez utiliser l'action put pour ajouter ou modifier un fichier dans le dépôt, en copiant le contenu d'un fichier présent sur votre machine locale ou depuis le flux de l'entrée standard. Cet outil permet aussi de manipuler les propriétés des fichiers et dossiers suivis en versions avec les actions propset, propsetf et propdel, explicitement ou en copiant les valeurs des propriétés à partir d'un fichier local. Ces actions ne sont pas possible depuis le client texte interactif à l'heure actuelle.

Il est temps de préciser la différence entre ce que peut faire svnmucc et ce qu'il est souhaitable qu'il fasse. Deux exemples viennent à l'esprit :

Comme vous travaillez sans copie de travail, il est impossible pour Subversion de détecter des conflits avant la propagation. Lors d'une utilisation classique de svn, les changements qui sont propagés vers le serveur sont comparés à une version de base déterminée du fichier ou du répertoire, afin de ne pas écraser par inadvertance des modifications concurrentes apportées par un autre membre de l'équipe. Le serveur connait la version du fichier que vous aviez avant vos modifications et il sait si d'autres gens ont changé ce fichier depuis la révision que vous détenez. Ce sont ces informations dont le serveur a besoin pour refuser votre propagation et qu'elle n'écrase pas les changements faits par quelqu'un d'autre ; il vous force alors à intégrer ces changements dans votre copie de travail et à reconsidérer vos propres modifications. Avec svnmucc, il n'y a pas de copie de travail, ce qui vous donne la possibilité de contourner ces sécurités et d'agir comme si l'état courant du dépot était celui qui vous sert de base de travail. Heureusement, il est évident pour vous qu'un tel pouvoir ne s'utilise pas à la légère.

Heureusement, svnmucc vous permet de poser un garde-fou lors de son utilisation. Afin d'offrir un mécanisme de sécurité comparable à l'utilisation d'une copie de travail, svnmucc propose l'option --revision (-r). Avec cette option, vous pouvez spécifier manuellement une révision de base pour les modifications que vous essayez de propager. Cette révision de base est idéalement la plus récente du dépôt dont vous ayez connaissance.

	Avertissement
	Nous encourageons fermement les utilisateurs à utiliser, et de manière appropriée, l'option --revision (-r) de svnmucc.

L'utilisation appropriée de svnmucc put démontre sans équivoque comment l'option --revision (-r) doit être invoquée. Considérons que Harry veuille modifier le fichier suivi en versions LISEZMOI sans s'embêter à rappatrier une copie de travail complète (nous supposons qu'il n'y a pas d'autre raison de disposer d'une copie de travail pour cette action, telles que le lancement de scripts avant de propager une révision pour vérifier qu'elle satisfait certains critères). Il doit en premier lieu décider avec quelle révision du fichier il va travailler. Typiquement, les utilisateurs souhaitent travailler avec la version la plus à jour d'un fichier. Ainsi, Harry effectue la requête relative à la révision de la dernière modification du fichier et modifie le contenu du fichier dans un fichier temporaire local :

$ svn info http://svn.exemple.com/projets/bac-à-sable/LISEZMOI
Chemin : LISEZMOI
URL : http://svn.exemple.com/projets/bac-à-sable/LISEZMOI
Relative URL : ^/bac-à-sable/LISEZMOI
Racine du dépôt : http://svn.example.com/projects
UUID du dépôt : 13f79535-47bb-0310-9956-ffa450edef68
Révision : 22
Type de nœud : fichier
Auteur de la dernière modification : sally
Révision de la dernière modification : 14
Date de la dernière modification : 2012-09-02 10:34:09 -0400 (dim. 02 sep. 2012)

$ svn cat -r 14 http://svn.exemple.com/projets/bac-à-sable/LISEZMOI \
      > LISEZMOI.tempo
$

Harry possède maintenant une copie du fichier LISEZMOI tel qu'il était lors de sa dernière modification. Il fait ses modifications dans cette copie du fichier. Naturellement, lorsqu'il a terminé, il veut propager ces modifications vers le dépôt.

Maintenant, si Harry utilise naïvement svnmucc put …, pour remplacer le contenu de LISEZMOI dans le dépôt par le contenu de son fichier local, il fait un abus de pouvoir avec svnmucc. Que se passe-t-il si, quelques microsecondes avant sa propagation, Sally a aussi modifié le fichier LISEZMOI ? Tout comme svn, svnmucc n'essaiera pas de fusionner sur le serveur les modifications de chacun pour les préserver. Non, svnmucc remplacera simplement la dernière version du fichier par la nouvelle qu'on lui donne. Harry n'en aura pas conscience, Sally sera furieuse.

$ svnmucc put LISEZMOI.tempo \
          http://svn.exemple.com/projets/bac-à-sable/LISEZMOI \
          -m "Modifié le fichier LISEZMOI."
r24 propagée par harry le 2013-01-21T16:21:23.100133Z
$
Message from sally@shell.example.com on pts/2 at 16:26 ...
Il faut qu'on se parle. Maintenant.
EOF

À la place, Harry doit rappeler la révision qu'il a utilisée comme base de travail à la commande svnmucc via l'option --revision (-r). Ainsi, le serveur pourra rejeter la propagation si, par malheur, Harry essaie de modifier un élément obsolète :

$ svnmucc -r 14 put LISEZMOI.tempo \
          http://svn.exemple.com/projets/bac-à-sable/LISEZMOI \
          -m "Modifié le fichier LISEZMOI."
svnmucc: E170004: Item '/bac-à-sable/LISEZMOI' est obsolète.
$

Comme toutes les autres options de svnmucc, l'option --revision (-r) est globale pour la commande, c'est-à-dire qu'elle s'applique à toutes les actions spécifiées dans la commande. Cela vous permet d'avoir les mêmes sortes de garde-fous que si vous aviez extrait une copie de travail du dépôt tout entier (et donc comme si vous travailliez sur une copie de travail uniformisée à la même révision), vous aviez effectué vos modifications sur cette copie de travail, puis vous aviez propagé toutes les modifications en même temps.

Comme vous pouvez le constater, svnmucc trouve bien sa place dans la boite à outils Subversion. Pour une référence complète des possibilités de cet outil, reportez-vous à Guide de référence de svnmucc : client texte Subversion pour URL multiples.