This text is a work in progress—highly subject to change—and may not accurately describe any released version of the Apache™ Subversion® software. Bookmarking or otherwise referring others to this page is probably not such a smart idea. Please visit http://www.svnbook.com/ for stable versions of this book.

Propriétés

Nous avons vu en détail comment Subversion stocke et récupère les différentes versions des fichiers et dossiers dans le dépôt. Des chapitres entiers ont décrit cette fonctionnalité fondamentale de l'outil. Et si la gestion de versions se limitait à ça, Subversion couvrirait déjà complètement les besoins attendus pour un système de gestion de versions.

Mais ce n'est pas tout.

En plus de gérer les versions de vos dossiers et de vos fichiers, Subversion fournit une interface pour ajouter, modifier et supprimer des méta-données suivies en versions pour chacun de vos dossiers et de vos fichiers. On appelle ces méta-données des propriétés. Elles peuvent être pensées comme des tableaux à deux colonnes, qui associent des noms de propriétés à des valeurs arbitraires, pour chaque élément de votre copie de travail. En termes simples, vous pouvez assigner n'importe quel nom et n'importe quelle valeur à vos propriétés, à la seule condition que le nom ne contiennent que des caractères ASCII. Et l'atout principal de ces propriétés réside dans le fait que ces propriétés sont également suivies en versions, tout comme le contenu textuel de vos fichiers. Vous pouvez modifier, propager et revenir en arrière sur les propriétés aussi facilement que sur le contenu des fichiers. L'envoi et la réception des changements concernant les propriétés intervient lors de vos propagations et mises à jour : vous n'avez pas à changer vos habitudes pour les utiliser.

[Note] Note

Subversion a réservé pour son propre usage les propriétés dont le nom commence par svn:. Bien qu'il n'y en ait seulement que quelques unes d'utilisées actuellement, vous ne devez pas créer vos propres propriétés avec un nom commençant par ce préfixe. Sinon, vous courez le risque qu'une future version de Subversion définisse une propriété ayant le même nom mais pour un usage tout autre.

Les propriétés sont aussi présentes ailleurs dans Subversion. De la même manière que pour les fichiers et dossiers, chaque révision en tant que telle peut avoir des propriétés arbitraires associées. Les mêmes contraintes s'appliquent : nom lisible par un humain et valeur arbitraire, éventuellement binaire. La différence principale est que les propriétés des révisions ne sont pas suivies en versions. Autrement dit, si vous changez la valeur ou si vous supprimez une propriété d'une révision, il n'y a pas moyen, en utilisant Subversion, de revenir à la valeur précédente.

Subversion ne fournit pas de recommandation particulière quant à l'utilisation des propriétés. Il demande seulement de ne pas utiliser de nom de propriété qui commence par le préfixe svn:. C'est l'espace de noms qu'il garde pour son propre usage. Et Subversion utilise bien lui-même les propriétés, suivies en versions ou pas. Certaines propriétés suivies en versions ont une signification particulière ou des effets particuliers quand elles font référence à un fichier ou à un dossier, ou stockent des informations relatives à la révision à laquelle elles sont rattachées. Certaines propriétés de révision sont automatiquement rattachées à une révision par la procédure de propagation et stockent des informations relatives à cette révision. La plupart de ces propriétés sont mentionnées ailleurs dans ce chapitre ou dans d'autres chapitres comme faisant partie de sujets plus généraux. Pour une liste exhaustive des propriétés pré-définies de Subversion, référez-vous à la section intitulée « Propriétés réservées à l'usage de Subversion ».

[Note] Note

Bien que Subversion crée automatiquement des propriétés à chaque révision (svn:date, svn:author, svn:log, etc.), il ne présage pas de leur existence par la suite et vous (ou les outils que vous utilisez) ne devriez pas non plus présager de leur existence dans vos interactions avec le dépôt. Les propriétés de révisions peuvent être effacées par programmation ou via le client (si les procédures automatiques l'autorisent) sans remettre en cause le bon fonctionnement de Subversion. En conséquence, lors de l'écriture de scripts qui opèrent sur les données du dépôt, veillez à ne pas considérer l'existence d'une propriété de révision comme acquis.

Dans cette section, nous examinons l'utilité des propriétés, à la fois pour l'utilisateur et pour Subversion lui-même. Vous apprendrez les sous-commandes svn relatives aux propriétés et comment la modification des propriétés change votre manière habituelle d'utiliser Subversion.

Utilisation des propriétés

À 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] 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.
$

Manipuler les propriétés

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

Les propriétés et le cycle de travail Subversion

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

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

Propriétés héritées

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

Configuration automatique des propriétés

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] 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 :

  • Une propriété automatique, pour un motif donné, définie par svn:auto-props prévaut sur la même propriété automatique pour un motif identique définie par auto-props dansla zone de configuration.

  • Si une propriété automatique, pour un motif donné, est héritée depuis plus d'un chemin parent par la propriété svn:auto-props, le chemin parent le plus près prévaut sur les chemins parents plus éloignés.

  • Une propriété automatique, pour un motif donné, définie par la propriété svn:auto-props explicitement appliquée à un chemin prévaut sur la même (ou les mêmes) propriétés automatiques pour un motif identique héritées de parents.

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

Propriétés réservées à l'usage de Subversion

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

Propriétés suivies en versions

Les propriétés suivies en versions que Subversion réserve à son propre usage sont les suivantes :

svn:auto-props

Si elle est définie sur un dossier, la valeur est un ensemble de définitions de propriétés qui s'appliquent à tous les fichiers sous le dossier. Voir la section intitulée « Configuration automatique des propriétés ».

svn:executable

Si elle est définie sur un fichier, le client rendra le fichier exécutable sur les copies de travail d'un système de type Unix. Voir la section intitulée « Fichiers exécutables ou non ».

svn:mime-type

Si elle est définie sur un fichier, la valeur indique le type MIME du fichier. Cela permet au client de décider si des fusions à partir des lignes sont pertinentes lors des mises à jour et cela peut aussi affecter le comportement des fichiers lorsqu'on les parcourt avec un navigateur web. Voir la section intitulée « Type de contenu des fichiers ».

svn:ignore

Si elle est définie sur un dossier, la valeur est une liste de motifs de noms de fichiers non suivis en versions que les sous-commandes svn status et autres ignoreront. Voir la section intitulée « Occultation des éléments non suivis en versions ».

svn:global-ignores

Si elle définie sur un dossier, la valeur est une liste de motifs de noms de fichiers non suivis en versions que les sous-commandes svn status et autres ignoreront. Au contraire de svn:ignore, les motifs s'appliquent à toute la sous-arborescence du dossier et pas seulement aux noms de fichiers qui sont fils directs du dossier. Voir la section intitulée « Occultation des éléments non suivis en versions ».

svn:keywords

Si elle est définie sur un fichier, la valeur indique au client comment remplacer des mots-clés particuliers à l'intérieur du fichier. Voir la section intitulée « Substitution de mots-clés ».

svn:eol-style

Si elle est définie sur fichier, la valeur indique au client comment les fins de ligne doivent être comprises dans la copie de travail et dans les exports d'arborescences. Voir la section intitulée « Caractères de fin de ligne » et svn export.

svn:externals

Si elle est définie sur un dossier, la valeur est une liste sur plusieurs lignes de chemins et d'URL que le client doit extraire. Voir la section intitulée « Définition de références externes ».

svn:special

Si elle est définie sur un ficiher, elle indique que ce fichier n'est pas ordinaire, mais est plutôt un lien symbolique ou autre objet spécial.[18]

svn:needs-lock

Si elle est définie sur un fichier, elle indique au client de placer le fichier en lecture seule dans la copie de travail, pour rappeler que ce fichier doit être verrouillé avant toute édition. Voir la section intitulée « Communication par l'intermédiaire des verrous ».

svn:mergeinfo

Utilisée par Subversion pour suivre les métadonnées liées aux fusions. Voir la section intitulée « Mergeinfo et aperçus » pour les détails  vous ne devriez jamais éditer cette propriété à moins de réellement savoir ce que vous faites.

Propriétés non suivies en versions

Les propriétés suivantes, toujours réservées par Subversion pour son propre usage, ne sont pas suivies en versions et s'appliquent aux révisions. La plupart d'entre elles apparaissent sur chaque révision dans le dépôt, stockant des informations importantes sur l'origine et la nature des modifications faites par cette révision.

svn:author

Si elle est définie, elle contient le nom de l'utilisateur authentifié qui a créé la révision. Si elle n'est pas définie, la révision a été propagée de manière anonyme.

svn:autoversioned

Si elle est définie, la révision a été créée par un mécanisme d'autoversionnage automatique. Voir la section intitulée « Gestion de versions automatique ».

svn:date

Contient l'horodatage UTC correspondant à la création de la révision, au format ISO 8601. La valeur provient de l'horloge du serveur, pas du client.

svn:log

Contient le commentaire de propagation relatif à la révision.

Certains outils connexes de la collection Subversion (svnrdump et svnsync) utilisent également les propriétés non suivies en version pour stocker des informations les concernant. Ces propriétés sont présentes uniquement sur la révision 0 des dépôts sur lesquels ces outils opèrent. Pour plus d'information sur svnrdump et svnsync, reportez-vous à Chapitre 5, Administration d'un dépôt. Les propriétés créées et gérées par ces outils sont les suivantes :

svn:rdump-lock

Utilisée pour mettre en œuvre un accès exclusif temporaire au dépôt par la commande svnrdump load. Cette propriété est généralement présente seulement quand une opération de ce type est en cours (ou quand une commande svnrdump a échoué à se déconnecter proprement du dépôt). Cette propriété n'a de sens que si elle est définie sur la révision 0.

svn:sync-currently-copying

Contient le numéro de révision du dépôt source qui est en train d'être recopié sur le dépôt cible par la commande svnsync. Cette propriété n'a de sens que si elle est définie sur la révision 0.

svn:sync-from-uuid

Contient l'UUID du dépôt dont le dépôt cible est un mirroir, créé par l'outil svnsync. Cette propriété n'a de sens que si elle est définie sur la révision 0.

svn:sync-from-url

Contient l'URL du dépôt dont le dépôt cible est un mirroir, créé par l'outil svnsync. Cette propriété n'a de sens que si elle est définie sur la révision 0.

svn:sync-last-merged-rev

Contient le numéro de révision du dépôt source qui a été dupliqué avec succès le plus récemment sur le dépôt cible. Cette propriété n'a de sens que si elle est définie sur la révision 0.

svn:sync-lock

Utilisée pour mettre en œuvre un accès exclusif temporaire au dépôt par la commande de duplication svnsync. Cette propriété est généralement présente seulement quand une opération de ce type est en cours (ou quand une commande svnsync a échoué à se déconnecter proprement du dépôt). Cette propriété n'a de sens que si elle est définie sur la révision 0.



[13] Pour ceux qui connaissent le XML, c'est à peu près le sous-ensemble ASCII pour la syntaxe du champ "Name" en XML.

[14] Corriger les fautes d'orthographe, les erreurs de grammaire et les informations simplement erronées au sein des commentaires de propagation est peut-être l'usage le plus courant de l'option --revprop.

[15] L'exception notable à cet état de fait est la propriété svn:mergeinfo qui est héritable, voir la section intitulée « Mergeinfo et aperçus »

[16] Actuellement, la bibliohèque utilisée est libmagic.

[17] Rappelez-vous que les utilisateurs ne peuvent hériter de propriétés pour lesquelles ils ont un droit en lecture. Donc si un administrateur définit la propriété svn:auto-props sur un chemin parent très ascendant (par exemple à la racine du dépôt), il doit s'assurer que tous les utilisateurs possèdent le droit de lecture sur ce chemin ou la configuration automatique de propriété voulue ne fonctionnera pas.

[18] Au moment de la rédaction de ce livre, les liens symboliques sont en fait les seuls objets « spéciaux » traités. Mais rien n'interdit qu'il y en ait d'autres dans des versions futures de Subversion.