Subversion a la capacité de substituer des mots-clés dans les fichiers suivis en versions 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 !

Par exemple, prenons un document dont vous voulez afficher la date de dernière modification. Vous pouvez 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 ceci : $NomDuMotClé$.

Ajouter un signet dans votre fichier ne fait rien de particulier. Subversion n"essayera jamais de le substituer tant que vous ne lui demandez pas explicitement de le faire. Après tout, vous êtes peut-être en train de rédiger un document^[26] sur l'utilisation des mots-clés et vous ne voulez pas que Subversion substitue à vos beaux exemples de signets non substitués leur valeur réelle !.

Pour indiquer à Subversion que vous voulez substituer les mots-clés d'un fichier particulier, nous nous tournons une fois de plus vers les sous-commandes relatives aux propriétés. La propriété svn:keywords, quand elle est définie sur un fichier suivi en versions, 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 séparés par des espaces.

Par exemple, admettons que vous ayez un fichier suivi en versions nommé météo.txt qui ressemble à ceci :

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 définie sur ce fichier, Subversion ne fait rien de spécial. À présent, si nous activons les substitutions pour le mot-clé LastChangedDate :

$ svn propset svn:keywords "Date Author" météo.txt
Propriété 'svn:keywords' définie sur 'météo.txt'
$

Vous venez d'effectuer une modification locale des propriétés du fichier météo.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 ignore simplement les requêtes de substitutions de mots-clés qui ne sont pas présents dans le fichier et ne substitue pas de mot-clé qui ne soit pas présent dans la valeur de la propriété svn:keywords.

Immédiatement après avoir propagé cette modification de propriété, Subversion met à jour votre copie de travail avec le nouveau texte substitué. Au lieu de voir votre signet $LastChangedDate$, vous voyez 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.

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 (sam. 22 juil. 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 météo.txt, votre copie de ce fichier continue à 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 météo.txt sont alors à nouveau substituées les informations qui se rapportent à la plus récente propagation du fichier.

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 devez aussi considérer que la valeur de la propriété svn:keywords est sensible à la casse (case-sensitive en anglais) : certains mots-clés sont reconnus indépendamment de la casse, mais ce comportement est obsolète.

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

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 restent figés à la même valeur même si des changements ont lieu régulièrement dans le dépôt.

En complément de ces mots-clés et alias prédéfinis, Subversion 1.8 vous permet de définir et d'utiliser les mots-clés personnalisés. Pour définir un mot-clé personnalisé, ajoutez une jeton à la propriété svn:keywords avec la syntaxe suivante : MyMot-Clé=FORMAT. MyMot-Clé est le nom du mot-clé (celui que vous utiliserez dans le signet) et FORMAT est une chaine formatée dans laquelle l'information sera insérée lorsque le mot-clé sera substitué dans votre fichier.

La syntaxe de la chaine formatée utilisée pour les mots-clés personnalisés accepte les codes de substitution suivants :

Comme vous pouvez le constater, beaucoup de codes de format reprennent les informations disponibles dans les mots-clés prédéfinis. Mais bien ûr, les mots-clés personnalisés vous offrent plus de souplesse dans l'organisation de l'information. Par exemple, vous pouvez avoir envie d'avoir un mot-clé dans vos fichiers qui donne le chemin relatif dans le dépôt du fichier et la dernière révision qui le modifie, formattée à votre convenance pour une meilleure lisibilité. Pour ce faire, vous devez d'abord définir votre mot-clé personnalisé :

$ svn pset svn:keywords "CheminRev=%P,%_r%r" calc/bouton.c
Propriété 'svn:keywords' définie sur 'bouton.c'
$

Ensuite, vous devez éditer votre fichier pour ajouter le signet pour votre mot-clé, ce qui nous donne dans ce cas $CheminRev$. Après avoir propagé ces modifications, si vous regardez le contenu du fichier, vous constaterez que le mot-clé a été substitué conformément au résultat attendu : où le fichier contenait $CheminRev$, il contient maintenant $cheminRev: trunk/calc/bouton.c, r23 $.

	Note
	Subversion tronque automatiquement toute expansion de mot-clé qui dépasse 255 caractères de long. Les définitions de mots-clés dont le nom dépasse 255 caractères sont aussi ignorées.

Vous pouvez aussi demander à Subversion de conserver une longueur constante (en nombre d'octets consommés) pour la substitution d'un mot-clé. En utilisant la séquence double deux-points (::), suivi par le nombre de caractères désiré, vous définissez la largeur voulue. Quand Subversion substituera le mot-clé pour le mot-clé et sa valeur, il ne remplacera que les caractères espaces, laissant le reste du champ de mot-clé inchangé. Si la valeur de substitution est plus courte que la largeur définie, il y aura des caractères de remplissage à la fin du champ substitué ; si elle est trop longue, elle sera tronquée avec un caractère spécial « dièse » (#) juste avant le caractère dollar qui sert de délimiteur de fin.

Par exemple, supposons que vous ayez un document dans lequel vous avez un paragraphe avec des données tabulées qui représentent les mots-clés Subversion du document. Si vous utilisez la syntaxe originale Subversion pour la substitution des mots-clés, votre fichier ressemblera à :

$Rev$:     Révision de la dernière propagation
$Author$:  Auteur de la dernière propagation
$Date$:    Date de la dernière propagation

Tel quel, cela semble joli et bien aligné. Mais quand vous allez propager ce fichier (avec la substitution des mots-clés activée, bien évidemment), vous verrez :

$Rev: 12 $:     révision de la dernière propagation
$Author: harry $:  auteur de la dernière propagation
$Date: 2006-03-15 02:33:03 -0500 (mer. 15 Mar 2006) $:    date de la dernière propagation

Le résultat n'est pas très heureux. Vous êtes alors tenté d'ajuster le fichier après la substitution pour le remettre en forme. Mais cela ne fonctionne que tant que les substitutions de mots-clés gardent la même longueur. Si le numéro de la dernière révision propagée passe de 99 à 100 par exemple, ou si une autre personne avec un nom d'utilisateur plus long propage le fichier, tout le travail est à refaire. Cependant, si vous travaillez avec Subversion 1.2 ou plus récent, vous pouvez utiliser la nouvelle syntaxe des mots-clés à longueur fixe et spécifier la largeur adéquate de certains champs ; le fichier ressemble alors à ceci :

$Rev::               $:  révision de la dernière propagation
$Author::            $:  auteur de la dernière propagation
$Date::              $:  date de la dernière propagation

Propagez les modifications du fichier. Cette fois, Subversion prend en compte la nouvelle syntaxe des mots-clés à longueur fixe et conserve la largeur des champs telle que définie en complétant en tant que de besoin entre le double deux-points et le dollar de fin. Après substitution, la largeur des champs n'a pas changé : les valeurs courtes comme Rev et Author sont complétées avec des espaces et le champ Date, trop long, est tronqué par un caractère dièse :

$Rev:: 13            $:  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

L'utilisation de champs de mots-clés à longueur fixe est particulièrement utile lorsque vous faites des substitutions dans des fichiers dont le format est complexe et fait lui-même usage de champs à longueurs fixes ou lorsque la place disponible pour le stockage du champ de donnée est vraiment trop difficile à changer en dehors de l'application native elle-même. Bien sûr, dans le cas de fichiers binaires, vous devez toujours faire très attention à ce que les substitutions de mots-clés (à longueur fixe ou non) ne cassent pas l'intégrité du fichier. Bien que cela semble facile, cela peut être étonnament difficile pour la plupart des formats de fichiers binaires utilisés de nos jours et vous ne devez pas sous-estimer l'ampleur de cette tâche !

Avertissement

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ésulte 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.