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.

Création et configuration d'un dépôt

Dans ce chapitre (dans la section intitulée « Stratégies de déploiement d'un dépôt »), nous avons passé en revue quelques décisions importantes à prendre avant de créer et de configurer votre dépôt Subversion. Maintenant nous allons enfin mettre les mains dans le cambouis ! Dans cette section, nous voyons comment créer un dépôt Subversion et comment le configurer pour qu'il effectue des actions personnalisées lorsque certains événements ont lieu.

Création d'un dépôt

La création d'un dépôt Subversion est une tâche incroyablement simple. L'utilitaire svnadmin, fourni avec Subversion, dispose d'une sous-commande qui est justement destinée à cela (svnadmin create)  :

$ # Créer un dépôt
$ svnadmin create /var/svn/depot
$

Si l'on considère que le répertoire parent /var/svn existe déjà et que vous avez les droits suffisants pour modifier ce répertoire, la commande précédente crée un nouveau dépôt dans le répertoire /var/svn/depot avec le magasin de données par défaut (FSFS). Vous pouvez choisir explicitement le type de système de fichiers avec l'option --fs-type qui accepte comme argument soit fsfs, soit bdb.

$ # Créer un dépôt FSFS
$ svnadmin create --fs-type fsfs /var/svn/depot
$
$ # Créer un dépôt Berkeley DB
$ svnadmin create --fs-type bdb /var/svn/depot
$

Après l'exécution de cette simple commande, vous disposez d'un dépôt Subversion. En fonction de la manière dont vos utilisateurs accéderont à ce nouveau dépôt, vous aurez peut-être besoin de bidouiller les droits du système de fichiers. Mais comme l'administration système de base est plutôt hors de propos dans ce livre, nous laissons en exercice au lecteur le soin d'explorer plus avant ce sujet.

[Astuce] Astuce

Le chemin en argument de svnadmin est juste un chemin classique du système de fichiers, pas une URL comme celles que le client svn utilise pour spécifier un dépôt. Les commandes svnadmin et svnlook sont toutes les deux considérées comme des utilitaires coté serveur : elles sont utilisées sur la machine qui héberge le dépôt pour examiner ou modifier certains aspects du dépôt et ne sont pas capables d'effectuer des actions via le réseau. Une erreur classique des nouveaux utilisateurs de Subversion est d'essayer de passer une URL (même « locale » comme file://) à ces deux programmes.

Dans le sous-répertoire db/ de votre dépôt, vous trouvez l'implémentation du système de fichiers suivi en versions. Le nouveau système de fichiers suivi en versions de votre dépôt commence sa vie à la révision 0, qui est définie comme contenant le répertoire racine (/) et lui seul. Initialement, la révision 0 possède une seule propriété de révision, svn:date, dont la valeur est la date de création du dépôt.

Maintenant que vous disposez d'un dépôt, il est temps de le personnaliser.

[Avertissement] Avertissement

Alors que certaines parties d'un dépôt Subversion sont conçues pour être examinées et modifiées « à la main » (comme les fichiers de configuration et les procédures automatiques), vous ne devez pas (et vous ne devriez pas avoir besoin de) modifier les autres parties « à la main ». L'outil svnadmin est censé être suffisant pour toutes les modifications à apporter à votre dépôt, mais vous pouvez également vous servir d'outils tiers (comme la suite d'outils Berkeley DB) pour configurer les parties adéquates du dépôt. Ne tentez surtout pas de manipuler manuellement l'historique du suivi de versions en touchant aux fichiers du magasin de données du dépôt !

Mise en place des procédures automatiques

Une procédure automatique (hook en anglais) est un programme activé par certains événements du dépôt, comme la création d'une nouvelle révision ou la modification d'une propriété non suivie en versions. Certaines procédures automatiques (appelées « pré-hooks ») sont déclenchées avant l'opération sur le dépôt et permettent à la fois de rendre compte de ce qui va se passer et d'empêcher que cela se passe. D'autres procédures automatiques (appelées « post-hooks ») sont déclenchées après la fin d'un événement et servent à effectuer des tâches de surveillance (mais pas de modification) du dépôt. Chaque procédure automatique reçoit suffisamment d'informations pour déterminer la nature de l'événement, les modifications proposées (ou effectuées) du dépôt et le nom d'utilisateur de la personne qui a déclenché l'événement.

Le sous-répertoire hooks contient, par défaut, des modèles pour diverses procédures automatiques :

$ ls depot/hooks/
post-commit.tmpl          post-unlock.tmpl  pre-revprop-change.tmpl
post-lock.tmpl            pre-commit.tmpl   pre-unlock.tmpl
post-revprop-change.tmpl  pre-lock.tmpl     start-commit.tmpl
$

Il y a un modèle pour chaque type de procédure automatique que le dépôt Subversion sait prendre en charge ; en examinant le contenu de ces modèles de scripts, vous pouvez voir ce qui déclenche le script et quelles données sont passées en paramètres. Vous trouvez également dans beaucoup de ces scripts des exemples d'utilisation permettant de réaliser des tâches récurrentes utiles, en conjonction avec d'autres programmes fournis avec Subversion. Concrètement, pour activer une procédure automatique, il suffit de placer dans le répertoire depot/hooks un programme ou un script exécutable, qui sera invoqué via le nom de la procédure automatique (comme start-commit pour le début d'une propagation ou post-commit pour la fin d'une propagation).

Sur les plateformes Unix, cela veut dire fournir un programme ou un script (pouvant être un script shell, un programme Python, l'exécutable binaire d'un programme en C ou tout un tas d'autres choses) dont le nom est exactement le nom de la procédure automatique. Bien sûr, les modèles qui sont fournis ne le sont pas juste à titre d'information. Le moyen le plus facile pour mettre en place une procédure automatique sur les plateformes Unix consiste tout simplement à copier le fichier du modèle adéquat vers un nouveau fichier qui n'aura pas l'extension .tmpl, d'adapter son contenu à votre environnement et de vous assurer qu'il est exécutable. Sous Windows, comme l'extension du fichier détermine s'il est exécutable ou non, vous devez fournir un programme dont la base du nom est le nom de la procédure automatique et dont l'extension est l'une de celles reconnue comme exécutable par Windows, comme .exe pour les programmes ou .bat pour les fichiers batch.

Les procédures automatiques de Subversion sont lancées par l'utilisateur propriétaire du processus ayant accès au dépôt Subversion. La plupart du temps, on accède au dépôt via un serveur Subversion, donc cet utilisateur est le même que celui qui fait tourner le processus serveur sur le système. Les procédures automatiques elles-mêmes doivent être configurées pour être exécutables, au niveau du système d'exploitation, par ledit utilisateur. Cela implique également que tout programme ou fichier (y compris le dépôt Subversion) utilisé directement ou indirectement par la procédure automatique l'est par ledit utilisateur. En d'autres termes, faites bien attention aux problèmes de droits d'accès et d'exécution qui peuvent empêcher les procédures automatiques d'effectuer correctement les tâches pour lesquelles elles ont été conçues.

Il y a plusieurs procédures automatiques implémentées dans le dépôt Subversion et vous pouvez obtenir des détails sur chacune d'elles dans Guide de référence des procédures automatiques de Subversion. En tant qu'administrateur du dépôt, vous devez décider quelles procédures automatiques vous voulez mettre en œuvre (c'est-à-dire les nommer correctement et leur donner les droits appropriés) et de quelle manière. Lorsque vous prenez cette décision, gardez à l'esprit l'architecture de votre dépôt. Par exemple, si vous vous servez de la configuration du serveur pour déterminer les droits de propagation sur votre dépôt, vous n'avez pas besoin de mettre en place un contrôle d'accès de ce style via les procédures automatiques.

Par défaut, le dépôt Subversion exécute les procédures automatiques avec un environnement vide — c'est-à-dire sans aucune variable d'environnement définie, même pas $PATH (ou %PATH% sous Windows). C'est ainsi que de nombreux administrateurs sont perplexes lorsque leurs programmes fonctionnent correctement à la main mais pas dans Subversion. Assurez-vous de définir explicitement toutes les variables d'environnement nécessaires dans votre procédure automatique.

Subversion 1.8 introduit une nouvelle façon de gérer l'environnement dans lequel s'exécutent les procédures automatiques, le fichier de configuration de l'environnement des procédures automatiques. Si le serveur Subversion trouve un fichier nommé hooks-env dans le sous-répertoire conf/ du dépôt, il analyse ce fichier à la manière d'un fichier .INI et insère les options et variables qu'il a trouvées dans l'environnement de la procédure automatique via des variables d'environnement.

La syntaxe du fichier hooks-env est très simple : chaque nom de section correspond à la procédure automatique à laquelle la section s'applique (tels que pre-commit ou post-revprop-change) et les éléments à l'intérieur des sections sont les variables d'environnement dont on souhaite définir les valeurs. En plus, il existe une section générale [default], qui permet de définir la valeur de variables d'environnement pour toutes les procédures automatiques (sauf si cette variable est explicitement redéfinie à l'intérieur d'une section particulière à une procédure automatique). Exemple 5.1, « hooks-env (configuration personnalisée de l'environnement des procédures automatiques) » fournit un exemple de fichier de configuration hooks-env.

Exemple 5.1. hooks-env (configuration personnalisée de l'environnement des procédures automatiques)

# Toutes les procédures seront configurées en français encodé en UTF-8
# et auront le répertoire contenant nos utilitaires dans leur chemin
# par défaut.

[default]
LANG = fr_FR.UTF-8
PATH = /usr/local/svn/tools:/usr/bin


# Les procédures post-commit et post-revprop-change ont aussi besoin
# de nos programmes personnalisés pour la synchronisation

[post-commit]
PATH = /usr/local/synctools-1.1/bin:%(PATH)s

[post-revprop-change]
PATH = /usr/local/synctools-1.1/bin:%(PATH)s

[Note] Note

Exemple 5.1, « hooks-env (configuration personnalisée de l'environnement des procédures automatiques) » montre aussi la fonctionnalité de substitution des chaînes de caractères de l'analyseur du fichier de configuration. Dans cet exemple, la valeur de l'option PATH (récupérée depuis la section [default] du fichier) remplacera à la volée le texte %(PATH)s dans les sections dédiées à chaque procédure automatique. Pour plus d'informations sur le fonctionnement de cette syntaxe, reportez-vous au fichier README.txt qui se trouve dans le répertoire de configuration de Subversion (et pour plus d'information sur ce répertoire, lisez la section intitulée « Zone de configuration des exécutables »).

Bien sûr, avoir exactement les mêmes informations dans chaque fichier de configuration de l'environnement des procédures automatiques, dans chaque répertoire conf/ de chaque dépôt serait vite très lourd, surtout quand vous devez les modifier tous. C'est pourquoi le serveur Subversion vous permet de spécifier un emplacement alternatif (possiblement partagé) pour ces informations de configuration.

Utilisations classiques des procédures automatiques

Les procédures automatiques du dépôt permettent de réaliser une large palette de fonctions, mais la plupart est en fait utilisée pour quelques actions simples : la notification, la validation et la réplication.

Les procédures de notification sont celles qui indiquent à quelqu'un que quelque chose est arrivé. Celles que l'on retrouve le plus souvent dans l'utilisation de Subversion envoient des courriels de compte-rendu de propagation (resp. de modification de propriété de révision) aux membres du projet, elles sont pilotées par la procédure automatique post-commit (resp. post-revprop-change). Il existe beaucoup d'autres types de notification, depuis l'intégration dans un outil de suivi de bogues jusqu'au robot IRC qui annonce que quelque chose a changé dans le dépôt.

Pour ce qui concerne la validation, les procédures automatiques start-commit et pre-commit sont largement utilisées pour autoriser ou interdire des propagations en fonction de divers critères : l'auteur de la propagation, le format ou le contenu du message de propagation voire même des détails de bas-niveau relatifs aux modifications faites aux fichiers et dossiers par la propagation. De la même manière, la procédure automatique pre-revprop-change agit comme un point de passage obligé pour les modifications des propriétés de révisions, ce qui est particulièrement utile compte tenu du fait que les propriétés de révisions ne sont pas suivies en versions et ne sont donc modifiées qu'en détruisant l'ancienne valeur.

Une catégorie de validation des modifications se généralise depuis la sortie de Subversion 1.5 : la validation du logiciel client lui-même. Quand la fonctionnalité de suivi des fusions (qui est décrite en détails dans Chapitre 4, Gestion des branches) est apparue dans Subversion 1.5, les administrateurs de Subversion ont eu besoin de s'assurer que, une fois que certains commençaient à utiliser cette fonctionnalité, alors tous leurs fusions devaient être suivies. Afin de réduire la chance que quelqu'un propage une fusion non suivie vers le dépôt, ils ont utilisé la procédure automatique start-commit pour examiner les capacités annoncées par le client Subversion. Si celui-ci n'indiquait pas savoir suivre les fusions, la propagation était interdite avec un message pour l'utilisateur lui indiquant de mettre à niveau le client Subversion ! Exemple 5.2, « procédure automatique start-commit qui s'assure que le client sait suivre les fusions. » donne un exemple de script start-commit qui implémente précisément cette fonction.

Exemple 5.2. procédure automatique start-commit qui s'assure que le client sait suivre les fusions.

#!/usr/bin/env python
import sys

# sys.argv[3] contient la liste, séparée par des ':', des capacités du client
if 'mergeinfo' not in sys.argv[3].split(':'):
  sys.stderr.write("""\
ERREUR : les propagations (commit) vers ce dépôt ne sont possible
qu'avec des clients qui savent suivre les fusions. Veuillez mettre à
niveau votre client à Subversion 1.5 ou ultérieur.
""")
  sys.exit(1)

Depuis Subversion 1.8, les clients qui propagent des modifications sur un serveur Subversion 1.8 fournissent toujours une chaîne indiquant leurs capacités mais fournissent aussi des informations complémentaires les concernant en utilisant des propriétés éphémères de transaction. Ces propriétés éphémères de transaction sont principalement des propriétés de révision qui sont définies sur la transaction de propagation par le client dès qu'il a l'occasion de le faire au moment de la propagation. Elle sont automatiquement supprimées par le serveur juste avant que la transaction ne devienne une révision. Vous pouvez inspecter ces propriétés, pendant le laps de temps séparant les procédures automatiques start-commit et pre-commit, à l'aide des mêmes outils que ceux que vous utilisez pour inspecter les autres propriétés non suivies en versions.

Vous trouverez ci-après les propriétés éphémères de transactions que Subversion reconnait actuellement :

svn:txn-client-compat-version

Contient la chaîne de caractères indiquant la version de la bibliothèque Subversion dont le client se réclame compatible. C'est utile pour décider si le client implémente le jeu de fonctionnalités suffisant pour gérer proprement les données du dépôt.

svn:txn-user-agent

Contient la chaîne de caractères décrivant le « programme utilisateur » (user agent en anglais) qui effectue la propagation. La bibliothèque Subversion définit la première partie de cette chaîne mais un programme tiers qui utilise l'API (client avec une interface graphique, etc.) peut y ajouter des informations personnalisées.

[Note] Note

alors que la plupart des clients va transmettre les propriétés éphémères de transaction assez tôt dans le processus de transaction et pouvoir ainsi être examinées par la procédure automatique start-commit, certaines configurations de Subversion vont entrainer que ces propriétés ne seront définies dans la transaction que plus tard dans le processus de propagation. Les administrateurs doivent donc prendre le parti d'effectuer les validations basées sur les propriétés éphémères à la fois dans les procédures automatiques start-commit et pre-commit (dans le premier cas pour éviter qu'un client invalide ne transmette le contenu de la propagation, dans le deuxième cas « juste au cas où » les vérifications n'auraient pas pu être effectuées par la procédure automatique start-commit).

Comme nous l'avons déjà noté, les propriétés éphémères de transaction sont supprimées de la transaction juste avant qu'elle ne soit promue en nouvelle révision. Certains administrateurs peuvent vouloir conserver les informations de ces propriétés pour plus tard. Nous vous conseillons alors d'utiliser la procédure automatique pre-commit pour copier les valeurs des propriétés vers de nouvelles propriétés avec un nom différent. En fait, le code source distribué avec Subversion fournit un script persist-ephemeral-txnprops.py (situé dans le dossier tools/hook-scripts/), qui fait exactement cela.

La troisième catégorie que l'on rencontre souvent dans l'utilisation des procédures automatiques concerne la réplication. Que ce soit pour simplement faire une copie de sauvegarde ou pour un scénario impliquant des dépôts mirroirs, les procédures automatiques peuvent s'avérer critiques. Lisez la section intitulée « Sauvegarde d'un dépôt » et la section intitulée « Réplication d'un dépôt » pour davantage d'informations sur ces aspects de la maintenance du dépôt.

Trouver des procédures automatiques ou écrire les vôtres

Comme vous pouvez l'imaginer, il n'est pas concevable d'avoir un de procédures automatiques et de scripts divers qui ne soient librement accessibles que ce soit au sein de la communauté Subversion ou ailleurs. En fait, la distribution Subversion fournit plusieurs procédures automatiques utilisées un peu partout dans son répertoire tools/hook-scripts/. Cependant, si vous ne trouvez pas votre bonheur dans ce répertoire, vous pouvez écrire la vôtre. Lisez Chapitre 8, Intégration de Subversion pour obtenir des informations sur le développement d'applications utilisant l'API publique de Subversion.

[Avertissement] Avertissement

Bien que les procédures automatiques soient capables de faire tout et n'importe quoi, leurs auteurs devraient faire preuve de modération dans un domaine précis : ne modifiez pas une transaction de propagation en utilisant une procédure automatique. Bien que cela soit tentant de corriger automatiquement certaines erreurs, raccourcis ou violations de politique constatées dans les fichiers propagés, cela peut causer des problèmes. Subversion conserve en cache, côté client, certaines parties des données du dépôt et si vous modifiez une transaction de propagation de cette façon, ces caches seront périmés sans que cela ne puisse être détecté. De telles incohérences peuvent aboutir à des comportements surprenants et inattendus. Au lieu de modifier la transaction, contentez-vous de vérifier la transaction dans la procédure automatique pre-commit et rejetez-la si elle ne remplit pas les conditions nécessaires. Entre autre avantages,vos utilisateurs prendront ainsi des habitudes de travail empreintes de respect des procédures et de qualité.

Configuration de la base de données Berkeley DB

Un environnement Berkeley DB peut encapsuler une ou plusieurs bases de données, fichiers de journalisation, de région et de configuration. L'environnement Berkeley DB a un ensemble propre de valeurs configurées par défaut comme le nombre de verrous autorisés à un instant donné, la taille maximum des fichiers de journalisation, etc. La logique du système de fichiers Subversion choisit des valeurs par défaut pour différentes options de configuration du gestionnaire Berkeley DB. Cependant, il se peut que votre dépôt nécessite une configuration différente en raison de l'architecture de vos données et des méthodes d'accès.

Les concepteurs du gestionnaire de bases de données Berkeley DB savent que les besoins varient entre les différentes applications et environnements de bases de données, c'est pourquoi ils proposent des mécanismes pour modifier, à l'exécution, une grande partie des valeurs des options de configuration. BDB vérifie la présence d'un fichier nommé DB_CONFIG dans le répertoire d'environnement (à savoir le sous-répertoire db du dépôt) et en extrait les valeurs des options. Subversion crée ce fichier lorsqu'il crée le reste du dépôt. Initialement, le fichier contient des options par défaut ainsi que des pointeurs vers la documentation en ligne de Berkeley DB afin de vous renseigner sur l'utilisation de ces options. Bien sûr, vous êtes libre d'ajouter n'importe quelle option prise en compte par Berkeley DB dans votre fichier DB_CONFIG. Soyez juste attentif au fait que, bien que Subversion n'essaie jamais de lire ou interpréter le contenu de ce fichier et qu'il n'en utilise pas directement la configuration, les changements induits dans le comportement de Berkeley DB ne doivent pas aller à l'encontre du comportement attendu par Subversion. Par ailleurs, les changements effectués dans DB_CONFIG ne sont pris en considération qu'après avoir effectué une restauration de l'environnement de la base de données avec la commande svnadmin recover.

Avec Subversion 1.6, le système de fichiers FSFS possède plusieurs paramètres que l'administrateur peut configurer pour piloter finement les performances ou l'utilisation du disque de leurs dépôts. Vous pouvez trouver ces options (et leur documentation) dans le fichier db/fsfs.conf du dépôt.