SVNBOOK Chap3 Keyword Substitution
De Framalang Wiki.
Cette section fait partie du livre Version control with subversion
| Pseudo | Code | Rôle | Statut |
|---|---|---|---|
| Hotshot92 | Traduction | Fait | |
| SVF | 1ère Relecture | Fait | |
| Validation |
Keyword Substitution
Keyword Substitution
Substitution de mots-clés
Subversion has the ability to substitute keywords—pieces of useful, dynamic information about a versioned file—into the contents of the file itself. Keywords generally provide information about the last modification made to the file. Because this information changes each time the file changes, and more importantly, just after the file changes, it is a hassle for any process except the version control system to keep the data completely up-to-date. Left to human authors, the information would inevitably grow stale.
Subversion a la capacité de substituer des mots-clés dans les fichiers suivis en version par des informations dynamiques et utiles. Les mots-clés fournissent généralement des indications sur les dernières modifications faites au fichier. Comme ces informations changent à chaque fois que le fichier change, et plus spécifiquement, juste après que le fichier change, c'est compliqué pour tout processus, excepté pour le système de gestion de versions, de garder les données à jour. Sans outil automatique, adieu la pertinence de ces informations !
For example, say you have a document in which you would like to display the last date on which it was modified. You could burden every author of that document to, just before committing their changes, also tweak the part of the document that describes when it was last changed. But sooner or later, someone would forget to do that. Instead, simply ask Subversion to perform keyword substitution on the LastChangedDate keyword. You control where the keyword is inserted into your document by placing a keyword anchor at the desired location in the file. This anchor is just a string of text formatted as $KeywordName$.
Par exemple, prenons un document dans lequel vous voudriez afficher sa date de dernière modification. Vous pourriez charger chaque contributeur du document de renseigner le champ correspondant juste avant de propager ses changements. Mais un jour ou l'autre, quelqu'un oubliera de le faire. Demandez plutôt à Subversion de substituer le mot-clé LastChangedDate. Vous contrôlez où est inséré le mot-clé dans votre document en plaçant un signet à l'endroit voulu dans le fichier. Ce signet est juste une chaîne de caractères formatée comme $NomDuMotCle$.
All keywords are case-sensitive where they appear as anchors in files: you must use the correct capitalization in order for the keyword to be expanded. You should consider the value of the svn:keywords property to be case-sensitive too—certain keyword names will be recognized regardless of case, but this behavior is deprecated.
Tous les mots-clés sont sensibles à la casse des caractères quand ils apparaissent en tant que signets : vous devez placer les majuscules aux bons endroits pour que le mot-clé soit effectivement remplacé. Vous devriez aussi considérer que la valeur de la propriété svn:keywords est sensible à la casse ("case-sensitive") : certains mots-clés seront reconnus indépendamment de la casse, mais ce comportement est obsolète.
Subversion defines the list of keywords available for substitution. That list contains the following five keywords, some of which have aliases that you can also use:
Subversion définit la liste des mots-clés disponibles pour les substitutions. Cette liste contient les cinq mots-clés suivants (certains d'entre eux ont des alias que vous pouvez aussi utiliser) :
- Date
- This keyword describes the last time the file was known to have been changed in the repository, and is of the form $Date: 2006-07-22 21:42:37 -0700 (Sat, 22 Jul 2006) $. It may also be specified as LastChangedDate.
- Date
- Ce mot-clé indique la date du dernier changement connu dans le dépôt. Il est de la forme $Date: 2006-07-22 21:42:37 -0700 (Sat, 22 Jul 2006) $. Il peut également être spécifié en tant que LastChangedDate.
- Revision
- This keyword describes the last known revision in which this file changed in the repository, and looks something like $Revision: 144 $. It may also be specified as LastChangedRevision or Rev.
- Revision
- Ce mot-clé indique la dernière révision connue pour laquelle le fichier a changé dans le dépôt. Il fournit une réponse du type $Revision: 144 $. Il peut aussi être spécifié en tant que LastChangedRevision ou Rev.
- Author
- This keyword describes the last known user to change this file in the repository, and looks something like $Author: harry $. It may also be specified as LastChangedBy.
- Author
- ce mot-clé indique le dernier utilisateur qui a changé le fichier dans le dépôt et retourne une valeur du type $Author: harry $. Il peut être également spécifié en tant que LastChangedBy.
- HeadURL
- This keyword describes the full URL to the latest version of the file in the repository, and looks something like $HeadURL: http://svn.collab.net/repos/trunk/README $. It may be abbreviated as URL.
- HeadURL
- Ce mot-clé décrit l'URL complète de la dernière version du fichier dans le dépôt et ressemble à $HeadURL: http://svn.collab.net/depot/trunk/LISEZMOI $. On peut également utiliser l'abbréviation URL.
- Id
- This keyword is a compressed combination of the other keywords. Its substitution looks something like $Id: calc.c 148 2006-07-28 21:30:43Z sally $, and is interpreted to mean that the file calc.c was last changed in revision 148 on the evening of July 28, 2006 by the user sally.
- Id
- Ce mot-clé est une combinaison abrégée des autres mots-clés. Sa substitution donne quelque chose comme $Id: calc.c 148 2006-07-28 21:30:43Z sally $, que l'on interprète par "le fichier calc.c a été modifié en dernier par l'utilisateur sally lors de la révision 148 le 28 juillet 2006 au soir".
Une bonne partie des définitions qui précèdent utilisent la locution "dernière ... connue" ou quelque chose d'équivalent. Rappelez-vous que la substitution des mots-clés est une opération effectuée côté client et que votre client ne connaît pas les changements qui ont eu lieu dans le dépôt depuis votre dernière mise à jour. Si vous ne mettez jamais à jour de votre copie de travail locale, vos mots-clés resteront figés à la même valeur même si des changements ont lieu régulièrement dans le dépôt.
Pour indiquer à Subversion de substituer ou pas les mots-clés d'un fichier particulier, nous utilisons une fois de plus les commandes sur les propriétés. La propriété svn:keywords, quand elle est activée pour un fichier, contrôle quels mots-clés doivent être substitués dans ce fichier. Elle doit contenir une liste de mots-clés ou d'alias cités précédemment, séparés par des espaces.
For example, say you have a versioned file named weather.txt that looks like this:
Here is the latest report from the front lines. $LastChangedDate$ $Rev$ Cumulus clouds are appearing more frequently as summer approaches.
With no svn:keywords property set on that file, Subversion will do nothing special. Now, let's enable substitution of the LastChangedDate keyword.
$ svn propset svn:keywords "Date Author" weather.txt property 'svn:keywords' set on 'weather.txt' $
Par exemple, pour un fichier nommé meteo.txt qui ressemble à ça :
Voici les dernières prévisions de nos spécialistes : $LastChangedDate$ $Rev$ Les cumulus sont de plus en plus nombreux au fur et à mesure que l'été approche.
Sans la propriété svn:keywords activée sur ce fichier, Subversion ne fera rien de spécial. Maintenant, si nous activons les substitutions pour le mot-clé LastChangedDate :
$ svn propset svn:keywords "Date Author" meteo.txt property 'svn:keywords' set on 'meteo.txt' $
Now you have made a local property modification on the weather.txt file. You will see no changes to the file's contents (unless you made some of your own prior to setting the property). Notice that the file contained a keyword anchor for the Rev keyword, yet we did not include that keyword in the property value we set. Subversion will happily ignore requests to substitute keywords that are not present in the file, and will not substitute keywords that are not present in the svn:keywords property value.
Vous venez d'effectuer une modification locale des propriétés du fichier meteo.txt. Vous ne verrez aucun changement dans le contenu du fichier (à moins d'avoir fait des modifications avant d'activer la propriété). Notez que le fichier contenait un signet pour le mot-clé Rev et que nous n'avons pas inclus ce mot-clé dans la valeur de la propriété. Subversion ignorera simplement les requêtes de substitutions de mots-clés qui ne sont pas présents dans le fichier et ne substituera pas de mot-clé qui ne soit pas présent dans la valeur de la propriété svn:keywords.
Immediately after you commit this property change, Subversion will update your working file with the new substitute text. Instead of seeing your keyword anchor $LastChangedDate$, you'll see its substituted result. That result also contains the name of the keyword, and continues to be bounded by the dollar sign ($) characters. And as we predicted, the Rev keyword was not substituted because we didn't ask for it to be.
Immédiatement après avoir propagé ces modifications de propriété, Subversion mettra à jour votre copie de travail avec le nouveau texte substitué. Au lieu de voir votre signet $LastChangedDate$, vous verrez le résultat de la substitution. Ce résultat contient aussi le nom du mot-clé et est toujours entouré par des caractères dollar ($). Comme prévu, le mot-clé Rev n'a pas été substitué parce que nous n'avons pas demandé qu'il le soit.
Note also that we set the svn:keywords property to “Date Author” yet the keyword anchor used the alias $LastChangedDate$ and still expanded correctly.
Here is the latest report from the front lines. $LastChangedDate: 2006-07-22 21:42:37 -0700 (Sat, 22 Jul 2006) $ $Rev$ Cumulus clouds are appearing more frequently as summer approaches.
If someone else now commits a change to weather.txt, your copy of that file will continue to display the same substituted keyword value as before—until you update your working copy. At that time the keywords in your weather.txt file will be re-substituted with information that reflects the most recent known commit to that file.
Notez également que la substitution s'est bien passée alors que nous avons indiqué "Date Author" comme valeur de propriété svn:keywords et que le signet utilisait l'alias $LastChangedDate$.
Voici les dernières prévisions de nos spécialistes : $LastChangedDate: 2006-07-22 21:42:37 -0700 (Sat, 22 Jul 2006) $ $Rev$ Les cumulus sont de plus en plus nombreux au fur et à mesure que l'été approche.
Si quelqu'un d'autre propage une modification de meteo.txt, votre copie de ce fichier continuera à afficher la même valeur substituée de mot-clé, jusqu'à ce que vous mettiez à jour votre copie de travail. Aux mots-clés de meteo.txt seront alors à nouveau substitués les informations qui se rapportent à la plus récente propagation du fichier.
NOTE
- New users are often confused by how the $Rev$ keyword works. Since the repository has a single, globally increasing revision number, many people assume that it is this number which is reflected by the $Rev$ keyword's value. But $Rev$ expands to show the last revision in which the file changed, not the last revision to which it was updated. Understanding this clears the confusion, but frustration often remains—without the support of a Subversion keyword to do so, how can you automatically get the global revision number into your files?
- Les nouveaux utilisateurs sont parfois surpris par le fonctionnement du mot-clé $Rev$. Puisque le dépôt a un numéro de révision à la fois unique, global et croissant, beaucoup de gens pensent que c'est par ce numéro que sera remplacé le mot-clé $Rev$. Mais $Rev$ indique la dernière révision dans laquelle le fichier a changé, pas la révision de la dernière mise à jour. Le malentendu est ainsi dissipé, mais peut-être pas la frustration de ne pas avoir automatiquement le numéro global de la dernière révision dans vos fichiers, n'est-ce pas ?
- To do this, you need external processing. Subversion ships with a tool called svnversion which was designed for just this purpose. svnversion crawls your working copy and generates as output the revision(s) it finds. You can use this program, plus some additional tooling, to embed that revision information into your files. For more information on svnversion, see the section called “svnversion”.
- Pour l'obtenir, vous avez besoin d'un outil externe. Subversion est livré avec un outil appelé svnversion qui a été conçu spécifiquement pour cela. svnversion parcourt votre copie de travail et affiche toutes les révisions qu'il trouve. Vous pouvez utiliser ce programme, avec d'autres outils de traitement, pour insérer l'information de révision désirée dans vos fichiers. Pour davantage d'information sur svnversion, voir la section "svnversion".
Subversion 1.2 introduced a new variant of the keyword syntax which brought additional, useful—though perhaps atypical—functionality. You can now tell Subversion to maintain a fixed length (in terms of the number of bytes consumed) for the substituted keyword. By using a double-colon (::) after the keyword name, followed by a number of space characters, you define that fixed width. When Subversion goes to substitute your keyword for the keyword and its value, it will essentially replace only those space characters, leaving the overall width of the keyword field unchanged. If the substituted value is shorter than the defined field width, there will be extra padding characters (spaces) at the end of the substituted field; if it is too long, it is truncated with a special hash (#) character just before the final dollar sign terminator.
Subversion 1.2 introduisit une nouvelle variante pour la syntaxe des mots-clés. Cette syntaxe offre des fonctionnalités supplémentaires et utiles, bien que parfois atypiques. Vous pouvez désormais demander à Subversion de maintenir une longueur constante (en nombre d'octets consommés) pour les mots-clés substitués, longueur que vous définissez en utilisant la séquence double deux-points (::) après le nom du mot-clé, suivie du nombre de caractères espace ( ) voulus. Quand Subversion devra effectuer la substitution du mot-clé par le mot-clé et sa valeur, il ne remplacera que ces espaces, laissant la taille du champ inchangée. Si la valeur est plus courte que la largeur du champ, il restera des espaces pour combler la fin ; si la valeur est trop longue, elle sera tronquée avec le caractère dièse (#) juste avant le caractère dollar ($) final.
For example, say you have a document in which you have some section of tabular data reflecting the document's Subversion keywords. Using the original Subversion keyword substitution syntax, your file might look something like:
$Rev$: Revision of last commit $Author$: Author of last commit $Date$: Date of last commit
Par exemple, pour un document dans lequel vous avez une section avec les mots-clés Subversion dans un tableau. L'utilisation de la syntaxe originale de substitution de Subversion donnera quelque chose comme :
$Rev$: Numéro de révision de la dernière propagation $Author$: Auteur de la dernière propagation $Date$: Date de la dernière propagation
Now, that looks nice and tabular at the start of things. But when you then commit that file (with keyword substitution enabled, of course), you see:
$Rev: 12 $: Revision of last commit $Author: harry $: Author of last commit $Date: 2006-03-15 02:33:03 -0500 (Wed, 15 Mar 2006) $: Date of last commit
C'est joli et bien aligné au début. Mais quand vous allez propager ce fichier (avec la substitution des mots-clés activée, bien évidemment), vous obtiendrez :
$Rev: 12 $: Numéro de révision de la dernière propagation $Author: harry $: Auteur de la dernière propagation $Date: 2006-03-15 02:33:03 -0500 (Wed, 15 Mar 2006) $: Date de la dernière propagation
The result is not so beautiful. And you might be tempted to then adjust the file after the substitution so that it again looks tabular. But that only holds as long as the keyword values are the same width. If the last committed revision rolls into a new place value (say, from 99 to 100), or if another person with a longer username commits the file, stuff gets all crooked again. However, if you are using Subversion 1.2 or better, you can use the new fixed-length keyword syntax, define some field widths that seem sane, and now your file might look like this:
$Rev:: $: Revision of last commit $Author:: $: Author of last commit $Date:: $: Date of last commit
Le résultat n'est pas très heureux. Vous seriez alors tenté de modifier le fichier après la substitution pour que le contenu soit mieux aligné. Mais cette modification ne serait valable que tant que les valeurs des mots-clés gardent la même taille. Si le numéro de dernière révision change de valeur (par exemple de 99 à 100), ou si une autre personne avec un nom d'utilisateur plus long modifie le fichier, tout le travail d'alignement est à refaire. Cependant, si vous utilisez la version 1.2 (ou plus) de Subversion, vous pouvez utiliser la nouvelle syntaxe et définir des largeurs de champs adéquates et constantes. Votre fichier ressemblera alors à ceci :
$Rev:: $: Numéro de révision de la dernière propagation $Author:: $: Auteur de la dernière propagation $Date:: $: Date de la dernière propagation
You commit this change to your file. This time, Subversion notices the new fixed-length keyword syntax, and maintains the width of the fields as defined by the padding you placed between the double-colon and the trailing dollar sign. After substitution, the width of the fields is completely unchanged—the short values for Rev and Author are padded with spaces, and the long Date field is truncated by a hash character:
$Rev:: 13 $: Revision of last commit $Author:: harry $: Author of last commit $Date:: 2006-03-15 0#$: Date of last commit
Propagez ce fichier. Cette fois, Subversion prend en compte la syntaxe d'un champ de mot-clé à largeur fixe et maintient la largeur de ce champ comme indiqué entre le double deux-points et le signe dollar final. Après substitution, la largeur des champs n'a pas changé : les valeurs courtes comme Rev et Author sont comblées avec des espaces et le champ Date, trop long, est tronqué par un caractère dièse :
$Rev:: 13 $: Numéro de révision de la dernière propagation $Author:: harry $: Auteur de la dernière propagation $Date:: 2006-03-15 0#$: Date de la dernière propagation
The use of fixed-length keywords is especially handy when performing substitutions into complex file formats that themselves use fixed-length fields for data, or for which the stored size of a given data field is overbearingly difficult to modify from outside the format's native application (such as for Microsoft Office documents).
L'utilisation des mots-clés à longueur fixe est particulièrement efficace lors de substitutions dans des fichiers aux formats complexes, qui utilisent eux-mêmes des champs de données de longueur fixe ou qui stockent les données dans des champs dont la taille est particulièrement difficile à changer en dehors de l'application native elle-même (les documents Microsoft Office en sont un bon exemple).
WARNING
- Be aware that because the width of a keyword field is measured in bytes, the potential for corruption of multi-byte values exists. For example, a username which contains some multi-byte UTF-8 characters might suffer truncation in the middle of the string of bytes which make up one of those characters. The result will be a mere truncation when viewed at the byte level, but will likely appear as a string with an incorrect or garbled final character when viewed as UTF-8 text. It is conceivable that certain applications, when asked to load the file, would notice the broken UTF-8 text and deem the entire file corrupt, refusing to operate on the file altogether. So, when limiting keywords to a fixed size, choose a size that allows for this type of byte-wise expansion.
- Soyez conscient que, comme la taille d'un mot-clé est mesurée en octets, les valeurs utilisant des données codées sur plusieurs octets peuvent être corrompues. Par exemple, un nom d'utilisateur qui contient des caractères au format UTF-8 codés sur plusieurs octets risque d'être tronqué en plein milieu d'un de ces caractères multi-octets. Cette troncature est valide au niveau du traitement des octets mais résultera en une chaîne UTF-8 incorrecte en raison du caractère final tronqué. Il est ainsi possible que certaines applications, au moment de charger le fichier, remarquent que le texte UTF-8 est invalide, considèrent tout le fichier comme corrompu et refusent de travailler dessus. En conséquence, lorsque vous utilisez les mots-clés à longueur fixe, veillez à choisir une taille adaptée à des valeurs pouvant contenir des caractères éventuellement codés sur plusieurs octets.
