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 : $NomDuMotCle$.

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

Ajouter des signets dans votre fichier ne fait rien de spécial. Subversion n'essaie jamais d'effectuer la substitution dans votre fichier tant que vous ne le lui demandez pas explicitement. Après tout, vous écrivez peut-être un document ^[14] sur la manière d'utiliser les 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 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.

Par exemple, pour un fichier nommé meteo.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 activée 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" meteo.txt
property 'svn:keywords' set on 'meteo.txt'
$

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 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é ces modifications 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 meteo.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 meteo.txt seront alors à nouveau substituées les informations qui se rapportent à la plus récente propagation du fichier.

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 doit effectuer la substitution du mot-clé par le mot-clé et sa valeur, il ne remplace que ces espaces, laissant la taille du champ inchangée. Si la valeur est plus courte que la largeur du champ, il reste des espaces pour combler la fin ; si la valeur est trop longue, elle est tronquée avec le caractère dièse (#) juste avant le caractère dollar ($) final.

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 donne 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

C'est joli et bien aligné au début. Mais quand vous propagez ce fichier (avec la substitution des mots-clés activée, bien évidemment), vous obtenez :

$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 (mer. 15 mars 2006) $:    Date de la dernière propagation

Le résultat n'est pas très heureux. Vous êtes 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 ressemble 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

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

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