SVNBOOK Chap3 Properties
De Framalang Wiki.
Version du 24 mars 2009 à 14:48 par Sub Versif (Discuter | contributions)
Cette section fait partie du livre Version control with subversion
| Pseudo | Code | Rôle | Statut |
|---|---|---|---|
| Hotshot92 | Traduction | Fait | |
| SVF | 1ère Relecture | Fait | |
| Validation |
Sommaire |
Properties
Properties
Propriétés
We've already covered in detail how Subversion stores and retrieves various versions of files and directories in its repository. Whole chapters have been devoted to this most fundamental piece of functionality provided by the tool. And if the versioning support stopped there, Subversion would still be complete from a version control perspective.
But it doesn't stop there.
In addition to versioning your directories and files, Subversion provides interfaces for adding, modifying, and removing versioned metadata on each of your versioned directories and files. We refer to this metadata as properties, and they can be thought of as two-column tables that map property names to arbitrary values attached to each item in your working copy. Generally speaking, the names and values of the properties can be whatever you want them to be, with the constraint that the names must be human-readable text. And the best part about these properties is that they, too, are versioned, just like the textual contents of your files. You can modify, commit, and revert property changes as easily as you can file content changes. And the sending and receiving of property changes occurs as part of your typical commit and update operations—you don't have to change your basic processes to accommodate them.Nous avons vu en détail comment Subversion stocke et récupère les différentes versions des fichiers et répertoires 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.
Mais ce n'est pas tout.
En plus de gérer les versions de vos répertoires et de vos fichiers, Subversion fournit une interface pour ajouter, modifier et supprimer des méta-données gérées en version pour chacun de vos répertoires 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 doit être un texte lisible par un humain. Et l'atout principal de ces propriétés réside dans le fait qu'elles sont également suivies en version, 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 a lieu lors de vos propagations et mises à jour : vous n'avez pas à changer vos habitudes pour les utiliser.
NOTE
- Subversion has reserved the set of properties whose names begin with svn: as its own. While there are only a handful of such properties in use today, you should avoid creating custom properties for your own needs whose names begin with this prefix. Otherwise, you run the risk that a future release of Subversion will grow support for a feature or behavior driven by a property of the same name but with perhaps an entirely different interpretation.
- 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 devriez pas créer vos propres propriétés avec un nom commençant par ce préfixe. Sinon, vous courrez le risque qu'une future version de Subversion définisse une propriété ayant le même nom mais un usage tout autre.
Properties show up elsewhere in Subversion, too. Just as files and directories may have arbitrary property names and values attached to them, each revision as a whole may have arbitrary properties attached to it. The same constraints apply—human-readable names and anything-you-want binary values. The main difference is that revision properties are not versioned. In other words, if you change the value of, or delete, a revision property, there's no way within the scope of Subversion's functionality to recover the previous value.
Subversion has no particular policy regarding the use of properties. It asks only that you not use property names that begin with the prefix svn:. That's the namespace that it sets aside for its own use. And Subversion does, in fact, use properties, both the versioned and unversioned variety. Certain versioned properties have special meaning or effects when found on files and directories, or house a particular bit of information about the revisions on which they are found. Certain revision properties are automatically attached to revisions by Subversion's commit process, and carry information about the revision. Most of these properties are mentioned elsewhere in this or other chapters as part of the more general topics to which they are related. For an exhaustive list of Subversion's pre-defined properties, see the section called “Subversion properties”.
In this section, we will examine the utility—both to users of Subversion, and to Subversion itself—of property support. You'll learn about the property-related svn subcommands, and how property modifications affect your normal Subversion workflow.
Les propriétés sont aussi présentes ailleurs dans Subversion. De la même manière que pour les fichiers et répertoires, 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 version. 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 précise 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 version 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 répertoire, ou stockent des informations relatives à la révision à laquelle elles font référence. 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 "Propriétés de Subversion".
Dans cette section, nous examinerons 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.
Why Properties?
Why Properties?
Propriétés Subversion : pourquoi ?
Just as Subversion uses properties to store extra information about the files, directories, and revisions that it contains, you might also find properties to be of similar use. You might find it useful to have a place close to your versioned data to hang custom metadata about that data.
Say you wish to design a website that houses many digital photos, and displays them with captions and a datestamp. Now, your set of photos is constantly changing, so you'd like to have as much of this site automated as possible. These photos can be quite large, so as is common with sites of this nature, you want to provide smaller thumbnail images to your site visitors.
Now, you can get this functionality using traditional files. That is, you can have your image123.jpg and an image123-thumbnail.jpg side-by-side in a directory. Or if you want to keep the filenames the same, you might have your thumbnails in a different directory, like thumbnails/image123.jpg. You can also store your captions and datestamps in a similar fashion, again separated from the original image file. But the problem here is that your collection of files grows in multiples with each new photo added to the site.
Now consider the same website deployed in a way that makes use of Subversion's file properties. Imagine having a single image file, image123.jpg, and then properties set on that file named caption, datestamp, and even thumbnail. Now your working copy directory looks much more manageable—in fact, it looks to the casual browser like there are nothing but image files in it. But your automation scripts know better. They know that they can use svn (or better yet, they can use the Subversion language bindings—see the section called “Using the APIs”) to dig out the extra information that your site needs to display without having to read an index file or play path manipulation games.
A l'instar de Subversion, qui utilise les propriétés pour stocker des méta-données sur les fichiers, les répertoires et les révisions qu'il gère, vous pourriez faire une utilisation similaire des propriétés. Vous pourriez trouver utile d'avoir un endroit, près de vos données versionnées, 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. Soit, mais votre collection de photos change constamment, donc vous voudriez 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 sites.
Certes, vous pouvez le faire en utilisant des fichiers traditionnels. C'est-à-dire que vous aurez votre image123.jpg et une image123-thumbnail.jpg côte à côte dans un répertoire. Ou, si vous voulez garder les mêmes noms de fichier, vous placerez vos miniatures dans un répertoire différent, comme thumbnails/image123.jpg. Vous pouvez également stocker vos légendes et dates de la même façon, séparées encore une fois du fichier image original. Mais le problème est que votre collection de fichiers s'agrandit de plusieurs fichiers à chaque nouvelle photo ajoutée au site.
Maintenant, considérons le même site Web conçu en utilisant les propriétés des fichiers fournies par Subversion. Imaginez un simple fichier image, image123.jpg, et un ensemble de propriétés relatives à ce fichier nommées légende, date et même miniature. Maintenant, le répertoire de votre copie de travail se gère beaucoup plus facilement ; en fait, vu du navigateur, il semble ne contenir que des images. Mais vos scripts d'automatisation vont plus loin : ils savent qu'ils peuvent utiliser les commandes svn (ou mieux, ils peuvent utiliser les connecteurs spécifiques au langage utilisé, voir la section "Utiliser les API") pour extraire les informations dont votre site a besoin sans avoir à lire un fichier d'index ou à jouer avec des chemins de fichiers.
NOTE
- While Subversion places few restrictions on the names and values you use for properties, it has not been designed to optimally carry large property values or large sets of properties on a given file or directory. Subversion commonly holds all the property names and values associated with a single item in memory at the same time, which can cause detrimental performance or failed operations when extremely large property sets are used.
- Bien que Subversion n'impose que peu de restrictions sur les noms et les valeurs des propriétés, il n'a pas été conçu pour gérer de façon optimale des valeurs de propriétés de grande taille ou un grand nombre de propriétés sur un fichier ou un répertoire donné. Subversion garde souvent en mémoire en même temps tous les noms et valeurs de propriétés associés à un élément, ce qui peut engendrer des problèmes de performance lors de l'utilisation de très gros ensembles de propriétés.
Custom revision properties are also frequently used. One common such use is a property whose value contains an issue tracker ID with which the revision is associated, perhaps because the change made in that revision fixes a bug filed in the tracker issue with that ID. Other uses include hanging more friendly names on the revision—it might be hard to remember that revision 1935 was a fully tested revision. But if there's, say, a test-results property on that revision with a value all passing, that's meaningful information to have.
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. Ce peut aussi être l'utilisation de 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é qui stocke le résultat des tests avec la valeur "tout ok" est autrement plus utile.
NOTE
- For all their utility, Subversion properties—or, more accurately, the available interfaces to them—have a major shortcoming: while it is a simple matter to set a custom property, finding that property later is whole different ball of wax.
- Trying to locate a custom revision property generally involves performing a linear walk across all the revisions of the repository, asking of each revision, "Do you have the property I'm looking for?" Trying to find a custom versioned property is painful, too, and often involves a recursive svn propget across an entire working copy. In your situation, that might not be as bad as a linear walk across all revisions. But it certainly leaves much to be desired in terms of both performance and likelihood of success, especially if the scope of your search would require a working copy from the root of your repository.
- For this reason, you might choose—especially in the revision property use-case—to simply add your metadata to the revision's log message, using some policy-driven (and perhaps programmatically-enforced) formatting that is designed to be quickly parsed from the output of svn log. It is quite common to see in Subversion log messages the likes of:
Issue(s): IZ2376, IZ1919 Reviewed by: sally This fixes a nasty segfault in the wort frabbing process …
- But here again lies some misfortune. Subversion doesn't yet provide a log message templating mechanism, which would go a long way toward helping users be consistent with the formatting of their log-embedded revision metadata.
- Bien que très utiles, les propriétés Subversion, ou plus exactement les interfaces disponibles pour y accéder, ont une lacune majeure : alors qu'il est très simple de définir une propriété personnalisée, la retrouver plus tard est une toute autre affaire.
- Trouver une propriété de révision personnalisée implique généralement d'effectuer un parcours linéaire de toutes les révisions du dépôt, en demandant à chacune : "Avez-vous la propriété que je cherche ?" Trouver une propriété personnalisée suivie en version est également difficile, et implique souvent un appel récursif à svn propget sur toute une copie de travail. Dans votre situation, ce pourrait être moins pire que le parcours linéaire de toutes les révisions. Mais cela laisse certainement beaucoup à désirer en termes de performance et de probabilité de réussite, surtout si, pour votre recherche, il faut une copie de travail de la racine de votre dépôt.
- Pour cette raison, vous pourriez choisir, en particulier pour ce qui concerne les propriétés de révisions, de simplement ajouter les méta-données au message de propagation. Par exemple, utilisez une politique de formatage (idéalement appliquée automatiquement par un script) conçue pour être rapidement analysée à partir de la sortie de svn log. Ainsi, il est assez fréquent de voir dans Subversion des messages de propagation qui ressemblent à :
Problème(s): IZ2376, IZ1919 Corrigé par: sally Corrige un méchant plantage dans la fonction machin bidule …
- Mais hélas, cela ne résout pas tout. Subversion ne fournit pas encore de mécanisme pour gérer des modèles de messages associés aux propagations, ce qui aiderait pourtant beaucoup les utilisateurs à respecter le format des méta-données qu'ils placent dans les messages de révision.
Manipulating Properties
Manipulating Properties
Manipuler les propriétés
The svn command affords a few ways to add or modify file and directory properties. For properties with short, human-readable values, perhaps the simplest way to add a new property is to specify the property name and value on the command line of the propset subcommand.
$ svn propset copyright '(c) 2006 Red-Bean Software' calc/button.c property 'copyright' set on 'calc/button.c' $
But we've been touting the flexibility that Subversion offers for your property values. And if you are planning to have a multi-line textual, or even binary, property value, you probably do not want to supply that value on the command line. So the propset subcommand takes a --file (-F) option for specifying the name of a file which contains the new property value.
$ svn propset license -F /path/to/LICENSE calc/button.c property 'license' set on 'calc/button.c' $
There are some restrictions on the names you can use for properties. A property name must start with a letter, a colon (:), or an underscore (_); after that, you can also use digits, hyphens (-), and periods (.). [8]
La commande svn offre différentes possibilités pour ajouter ou modifier des propriétés sur les fichiers et les répertoires. Pour les propriétés avec des valeurs courtes, lisibles par un humain, la solution la plus simple est sûrement de spécifier le nom de la propriété et sa valeur en ligne de commande avec la sous-commande 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 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 license -F /path/to/LICENSE calc/bouton.c Propriété 'license' définie sur 'calc/bouton.c' $
Il y a quelques restrictions sur les noms de propriétés. Un nom de propriété doit commencer par une lettre, le caractère deux points (:) ou le caractère souligné (_) ; ensuite, vous pouvez utiliser des chiffres, des tirets (-) et des points (.) [8].
In addition to the propset command, the svn program supplies the propedit command. This command uses the configured editor program (see the section called “Config”) to add or modify properties. When you run the command, svn invokes your editor program on a temporary file that contains the current value of the property (or which is empty, if you are adding a new property). Then, you just modify that value in your editor program until it represents the new value you wish to store for the property, save the temporary file, and then exit the editor program. If Subversion detects that you've actually changed the existing value of the property, it will accept that as the new property value. If you exit your editor without making any changes, no property modification will occur:
$ svn propedit copyright calc/button.c ### exit the editor without changes No changes to property 'copyright' on 'calc/button.c' $
We should note that, as with other svn subcommands, those related to properties can act on multiple paths at once. This enables you to modify properties on whole sets of files with a single command. For example, we could have done:
$ svn propset copyright '(c) 2006 Red-Bean Software' calc/* property 'copyright' set on 'calc/Makefile' property 'copyright' set on 'calc/button.c' property 'copyright' set on 'calc/integer.c' … $
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 "Config") pour ajouter ou modifier des propriétés. Quand vous exécutez la commande, svn lance votre éditeur de texte avec un fichier temporaire qui contient la valeur actuelle de la propriété (ou un contenu vierge si vous ajoutez une nouvelle propriété). Vous pouvez alors modifier la valeur dans l'éditeur de texte pour y placer votre nouvelle valeur, sauvegarder le fichier temporaire et quitter l'éditeur. Si Subversion détecte que la valeur a effectivement changé, il la prend en compte. Si vous quittez l'éditeur sans faire de changement, la propriété ne sera 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' … $
All of this property adding and editing isn't really very useful if you can't easily get the stored property value. So the svn program supplies two subcommands for displaying the names and values of properties stored on files and directories. The svn proplist command will list the names of properties that exist on a path. Once you know the names of the properties on the node, you can request their values individually using svn propget. This command will, given a property name and a path (or set of paths), print the value of the property to the standard output stream.
$ svn proplist calc/button.c Properties on 'calc/button.c': copyright license $ svn propget copyright calc/button.c (c) 2006 Red-Bean Software $
There's even a variation of the proplist command that will list both the name and value of all of the properties. Simply supply the --verbose (-v) option.
$ svn proplist -v calc/button.c Properties on 'calc/button.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. … $
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 stockées des fichiers et répertoires. La commande svn proplist fournit la liste des noms de propriétés qui existent dans un chemin. Une fois que vous connaissez les noms des propriétés d'un élément, vous pouvez obtenir les valeurs correspondantes avec la commande svn propget. Cette commande affiche sur la sortie standard la valeur de la propriété dont le nom et le chemin (ou l'ensemble des chemins) ont été passés en paramètres.
$ svn proplist calc/bouton.c Propriétés sur 'calc/bouton.c': copyright license $ 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. … $
The last property-related subcommand is propdel. Since Subversion allows you to store properties with empty values, you can't remove a property altogether using propedit or propset. For example, this command will not yield the desired effect:
$ svn propset license calc/button.c property 'license' set on 'calc/button.c' $ svn proplist -v calc/button.c Properties on 'calc/button.c': copyright : (c) 2006 Red-Bean Software license : $
You need to use the propdel subcommand to delete properties altogether. The syntax is similar to the other property commands:
$ svn propdel license calc/button.c property 'license' deleted from 'calc/button.c'. $ svn proplist -v calc/button.c Properties on 'calc/button.c': copyright : (c) 2006 Red-Bean Software $
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 propedit ou propset. Par exemple, la commande suivante ne fournira pas le résultat escompté :
$ svn propset license calc/bouton.c Propriété 'license' 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 entièrement une propriété. La syntaxe est similaire aux autres commandes sur les propriétés :
$ svn propdel license calc/bouton.c Propriété 'license' 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 $
Remember those unversioned revision properties? You can modify those, too, using the same svn subcommands that we just described. Simply add the --revprop command-line parameter, and specify the revision whose property you wish to modify. Since revisions are global, you don't need to specify a target path to these property-related commands so long as you are positioned in a working copy of the repository whose revision property you wish to modify. Otherwise, you can simply provide the URL of any path in the repository of interest (including the repository's root URL). For example, you might want to replace the commit log message of an existing revision. [9] If your current working directory is part of a working copy of your repository, you can simply run the svn propset command with no target path:
$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop property 'svn:log' set on repository revision '11' $
But even if you haven't checked out a working copy from that repository, you can still affect the property change by providing the repository's root URL:
$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop \
http://svn.example.com/repos/project
property 'svn:log' set on repository revision '11'
$
Vous vous souvenez des propriétés de révision non suivies en version ? Vous pouvez les modifier elles-aussi en utilisant les mêmes sous-commandes svn que nous venons de décrire. Il suffit juste d'ajouter l'option --revprop à la ligne de commande et de spécifier la révision à laquelle s'applique la modification. Puisque les numéros de révisions s'appliquent à l'ensemble de l'arborescence, vous n'avez pas besoin d'indiquer un chemin pour ces commandes, du moment que vous êtes dans une copie de travail du dépôt contenant la révision dont vous voulez modifier la propriété. Autrement, vous pouvez simplement fournir n'importe quelle URL du dépôt en question (y compris l'URL racine). Par exemple, imaginons que vous vouliez remplacer le message associé à la propagation d'une révision précédente [9]. Si le répertoire actuel fait partie de votre copie de travail du dépôt, vous pouvez simplement lancer la commande svn propset sans spécifier de chemin :
$ svn propset svn:log '* bouton.c: Corrige un avertissement du compilateur.' -r11 --revprop Propriété 'svn:log' définie à 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
Propriété 'svn:log' définie à la révision du dépôt '11'
$
Note that the ability to modify these unversioned properties must be explicitly added by the repository administrator (see the section called “Commit Log Message Correction”). That's because the properties aren't versioned, so you run the risk of losing information if you aren't careful with your edits. The repository administrator can set up methods to protect against this loss, and by default, modification of unversioned properties is disabled.
Notez que le droit de modifier cette propriété non suivie en version doit être explicitement ajouté par l'administrateur du dépôt (voir la section "Correction d'un message de propagation"). En effet, la propriété n'étant pas suivie en version, vous risquez une perte d'informations si vous la modifiez à tort ou à 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 version est désactivée.
TIP
- Users should, where possible, use svn propedit instead of svn propset. While the end result of the commands is identical, the former will allow them to see the current value of the property they are about to change, which helps them to verify that they are, in fact, making the change they think they are making. This is especially true when modifying unversioned revision properties. Also, it is significantly easier to modify multiline property values in a text editor than at the command line.
- Dans la mesure du possible, il est recommandé d'utiliser svn propedit plutôt que svn propset. Bien que le résultat soit identique, svn propedit leur permet de visualiser la valeur actuelle de la propriété qu'ils veulent changer, ce qui les aide à vérifier qu'ils font bien ce qu'ils pensent faire. C'est particulièrement vrai dans le cas des propriétés non suivies en version. Il est aussi beaucoup plus facile de modifier un texte de plusieurs lignes dans un éditeur de texte qu'en ligne de commande.
Properties and the Subversion Workflow
Properties and the Subversion Workflow
Les propriétés et le cycle de travail Subversion
Now that you are familiar with all of the property-related svn subcommands, let's see how property modifications affect the usual Subversion workflow. As we mentioned earlier, file and directory properties are versioned, just like your file contents. As a result, Subversion provides the same opportunities for merging—cleanly or with conflicts—someone else's modifications into your own.
And as with file contents, your property changes are local modifications, only made permanent when you commit them to the repository with svn commit. Your property changes can be easily unmade, too—the svn revert command will restore your files and directories to their un-edited states—contents, properties, and all. Also, you can receive interesting information about the state of your file and directory properties by using the svn status and svn diff commands.
$ svn status calc/button.c
M calc/button.c
$ svn diff calc/button.c
Property changes on: calc/button.c
___________________________________________________________________
Name: copyright
+ (c) 2006 Red-Bean Software
$
Notice how the status subcommand displays M in the second column instead of the first. That is because we have modified the properties on calc/button.c, but not its textual contents. Had we changed both, we would have seen M in the first column, too (see the section called “See an overview of your changes”).
Maintenant que vous êtes familier avec toutes les sous-commandes svn relatives aux propriétés, voyons comment la modification des propriétés change le cycle habituel d'utilisation de Subversion. Comme mentionné précédemment, les propriétés des fichiers et répertoires sont gérées en version, à 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 restaurera vos fichiers et répertoires dans leur état d'avant les modifications, y compris pour les propriétés. Vous pouvez également obtenir des informations intéressantes sur l'état des propriétés de vos fichiers et répertoires en utilisant les commandes svn status et svn diff :
$ svn status calc/bouton.c
M calc/bouton.c
$ svn diff calc/bouton.c
Property changes on: calc/bouton.c
___________________________________________________________________
Name: copyright
+ (c) 2006 Red-Bean Software
$
Remarquez que la sous-commande status place le M dans la deuxième colonne plutôt que dans la première. C'est parce que nous avons modifié les propriétés de calc/bouton.c, mais pas son contenu. Si nous avions changé les deux, nous aurions vu le M dans la première colonne également (reportez-vous à la section "Avoir une vue globale des changements effectués”).
NOTE
- As with file contents, local property modifications can conflict with changes committed by someone else. If you update your working copy directory and receive property changes on a versioned object that clash with your own, Subversion will report that the object is in a conflicted state.
% svn update calc M calc/Makefile.in C calc/button.c Updated to revision 143. $
- Subversion will also create, in the same directory as the conflicted object, a file with a .prej extension which contains the details of the conflict. You should examine the contents of this file so you can decide how to resolve the conflict. Until the conflict is resolved, you will see a C in the second column of svn status output for that object, and attempts to commit your local modifications will fail.
$ svn status calc C calc/button.c ? calc/button.c.prej $ cat calc/button.c.prej prop 'linecount': user set to '1256', but update set to '1301'. $
- To resolve property conflicts, simply ensure that the conflicting properties contain the values that they should, and then use the svn resolve command to alert Subversion that you have manually resolved the problem.
- De la même manière que pour les contenus des fichiers, les modifications locales effectuées sur les propriétés peuvent entrer en conflit avec les changements effectués par d'autres collaborateurs. Si vous faites une mise à jour de votre copie de travail et que vous recevez un changement incompatible avec vos propres modifications d'une propriété d'un objet suivi en version, Subversion vous indiquera que l'objet est dans un état de conflit.
% svn update calc M calc/Makefile.in C calc/bouton.c Updated to revision 143. $
- Subversion créera également, dans le même répertoire que l'objet en conflit, un fichier avec l'extension .prej qui contiendra les détails du conflit. Vous devrez examiner le contenu de ce fichier pour décider comment résoudre le conflit. Tant que le conflit ne sera pas résolu, la sortie de svn status affichera un C dans la deuxième colonne pour cet objet, et vos tentatives de propagation échoueront.
$ svn status calc C calc/bouton.c ? calc/bouton.c.prej $ cat calc/bouton.c.prej prop 'nombre_lignes': user set to '1256', but update set to '1301'. $
- Pour résoudre les conflits sur les propriétés, assurez-vous simplement que les propriétés en question contiennent bien les valeurs qu'elle doivent contenir, puis utilisez la commande svn resolve pour indiquer à Subversion que vous avez résolu le problème manuellement.
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 re-diriger la sortie de svn diff pour créer un fichier patch utilisable : le programme patch ignorera 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 patch généré par svn diff, les modifications concernant les propriétés doivent être faites à la main.
Automatic Property Setting
Automatic Property Setting
Configurer des propriétés de façon automatique
Properties are a powerful feature of Subversion, acting as key components of many Subversion features discussed elsewhere in this and other chapters—textual diff and merge support, keyword substitution, newline translation, etc. But to get the full benefit of properties, they must be set on the right files and directories. Unfortunately, that step can be easily forgotten in the routine of things, especially since failing to set a property doesn't usually result in an obvious error (at least compared to, say, failing to add a file to version control). To help your properties get applied to the places that need them, Subversion provides a couple of simple but useful features.
Whenever you introduce a file to version control using the svn add or svn import commands, Subversion tries to assist by setting some common file properties automatically. First, on operating systems whose filesystems support an execute permission bit, Subversion will automatically set the svn:executable property on newly added or imported files whose execute bit is enabled. (See the section called “File Executability” for more about this property.) Secondly, it runs a very basic heuristic to determine if that file contains human-readable content. If not, Subversion will automatically set the svn:mime-type property on that file to application/octet-stream (the generic “this is a collection of bytes” MIME type). Of course, if Subversion guesses incorrectly, or if you wish to set the svn:mime-type property to something more precise—perhaps image/png or application/x-shockwave-flash—you can always remove or edit that property. (For more on Subversion's use of MIME types, see the section called “File Content Type”.)
Subversion also provides, via its runtime configuration system (see the section called “Runtime Configuration Area”), a more flexible automatic property setting feature which allows you to create mappings of filename patterns to property names and values. Once again, these mappings affect adds and imports, and can not only override the default MIME type decision made by Subversion during those operations, but can also set additional Subversion or custom properties, too. For example, you might create a mapping that says that any time you add JPEG files—ones whose names match the pattern *.jpg—Subversion should automatically set the svn:mime-type property on those files to image/jpeg. Or perhaps any files that match *.cpp should have svn:eol-style set to native, and svn:keywords set to Id. Automatic property support is perhaps the handiest property-related tool in the Subversion toolbox. See the section called “Config” for more about configuring that support.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 et dans les autres chapitres : comparaisons et fusions textuelles, substitution de mots-clés, transformation des retours à la ligne, etc... Mais pour profiter pleinement des propriétés, il faut les placer sur les répertoires et fichiers adéquats. Malheureusement, cette étape peut passer à la trappe dans le train-train quotidien, d'autant plus qu'oublier de configurer une propriété n'engendre généralement pas une erreur qui saute aux yeux (du moins comparativement à oublier d'ajouter un fichier dans la gestion de versions). Pour vous aider à placer vos propriétés au bon endroit, Subversion propose deux fonctionnalités simples mais utiles.
Au moment d'introduire un fichier en gestion 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 ajoutera automatiquement la propriété svn:executable aux nouveaux fichiers, ajoutés ou importés, qui ont ce bit activé (voir le paragraphe intitulé "Permission d'exécuter un fichier" pour plus de détails sur cette propriété). Ensuite, il lance une heuristique très basique pour déterminer si le contenu du fichier est lisible par un humain. Si le résultat est négatif, Subversion ajoute automatiquement la propriété svn:mime-type sur ce fichier avec la valeur application/octet-stream (type MIME générique indiquant "une suite d'octets"). Bien sûr, si Subversion se trompe, ou si vous voulez indiquer un type plus précis (par exemple image/png ou application/x-shockwave-flash), vous pouvez toujours supprimer ou modifier cette propriété. (Pour d'avantage d'informations sur la gestion des types MIME par Subversion, reportez vous à la section "Type de contenu des fichiers").
Subversion fournit également, via son système de zone de configuration (voir la section "Zone de configuration exécutable"), 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, tout fichier de type *.cpp se verra affecter la propriété svn:eol-style avec la valeur 'native' et la propriété svn:keywords la valeur Id. L'affectation automatique de propriétés est sûrement l'outil de manipulation des propriétés le plus commode de tout Subversion. Reportez-vous à la section "Config" pour plus d'informations sur la configuration de cette fonction.
