C.V.S. pour les développeurs

• 1.1 C'est quoi CVS ?
• 1.2 A quoi ça sert ? Comment ça marche ?
• 1.3 Qu'est-ce que ça ne fait pas ?

• 2.1 Installer et configurer CVS sur le poste client.
  • 2.1.1 Sous Linux
    • 2.1.1.1 Vérification
    • 2.1.1.2 Installation
  • 2.1.2 Sous Windows
    
    
  • 2.1.3 Configuration des variables systèmes
• 2.2 Créer une copie privée du projet

• 3.1 Mise à jour du référentiel.
  • 3.1.1 La commande " commit "
  • 3.1.2 La résolution des conflits
• 3.2 Ajout et suppression de fichiers.
  
  

• 4.1 Généralites
  
  
  • 4.1.1 Les principales options globales du client CVS
  • 4.1.2 Les options générales des commandes
• 4.2 Les commandes courantes et leurs options spéciales
  • 4.2.1 checkout
  • 4.2.2 update
  • 4.2.3 Affichage des résultats des commandes checkout et update
  • 4.2.4 commit
  • 4.2.5 add
  • 4.2.6 remove
• 4.3 Les commandes pour le suivi des versions
  • 4.3.1 status
  • 4.3.2 log
  • 4.3.3 diff
    
    
  • 4.3.4 annotate
    
    
  • 4.3.5 history
    
    

• 5.1 Coordination et sérialisation des développements
  
  
  • 5.1.1 watch
  • 5.1.2 edit
  • 5.1.3 unedit
  • 5.1.4 watchers
  • 5.1.5 editors
• 5.2 Echanges avec l’extérieur : import/export, création de patches…
  • 5.2.1 export
  • 5.2.2 import
  • 5.2.3 release
  • 5.2.4 rdiff ou patch
• 5.3 Etiquettes et branches
  • 5.3.1 tag
  • 5.3.2 rtag
  • 5.3.3 Branches et fusions
    • 5.3.3.1 Intérêt de la branche
    • 5.3.3.2 Création d’une branche
    • 5.3.3.3 Accès à une branche
    • 5.3.3.4 Numérotation des branches
    • 5.3.3.5 Fusion d’une branche
    • 5.3.3.6 Quelques réflexions
  5.4 Les fichiers d’environnement
  • 5.4.1 ~/.cvsrc
  • 5.4.2 ~/.cvsignore
• 5.5 La substitution des mots-clés
• 5.6 Les formats de dates
• 5.7 Les étiquettes collantes
• 5.8 Un exemple de conflit

• 6.1 Bibliographie et liens
• 6.2 Au risque de nous répéter…

• Présentation

1. C’est quoi CVS ?

2. CVS est l’abréviation pour " Concurrent Versions System ". Cet outil, LA principale référence dans son domaine, permet de suivre l’historique des fichiers de type " texte ". Il est donc particulièrement adapté pour la gestion des fichiers sources dans le cadre d’un développement coopératif.

   C’est un logiciel libre sous licence GNU.

   On peut affirmer que CVS est aujourd’hui devenu un standard du logiciel libre.

   Le site officiel de CVS se trouve à l’adresse suivante : www.cvshome.org. Vous pourrez y télécharger la dernière version du produit (1.11.4 lors de la rédaction de ce document). Vous y trouverez également documentation (en anglais ) et forum de discussion.

3. A quoi ça sert ? Comment ça marche ?

4. Dans le cas qui nous intéresse, à savoir le développement d’un projet dans un cadre coopératif, CVS va nous permettre de conserver l’historique de toutes les modifications apportées aux fichiers sources.

   CVS fonctionne sur le principe du client-serveur.

   Sur le serveur se trouvent les originaux des fichiers sources de chaque projet. Ils sont stockés dans le référentiel (en anglais : repository).

   Le développeur ne modifie jamais directement le référentiel. Il dispose d’une copie dans son environnement personnel ( ce répertoire propre peut d’ailleurs se trouver soit sur la même machine que le référentiel, soit sur une machine distincte capable de se connecter au serveur via un réseau ). Le développeur travaille donc dans son " bac à sable " ; quand il a terminé et testé ses modifications, il demande leur mise à jour dans le référentiel. CVS se charge alors automatiquement de mettre à jour le numéro de version de chaque fichier modifié.

   En fait, l’outil conserve, pour chaque fichier, un historique des modifications et non pas les versions successives de chaque fichier, ce qui permet un gain de place évident. Ce fonctionnement est également très utile pour retrouver un bogue : si on connaît la dernière version où ce bogue n’apparaissait pas, il est possible de lister toutes les modifications apportées au fichier incriminé depuis cette version stable. Nous verrons plus loin, dans le corps de ce document, les différentes possibilités de CVS et les commandes utiles au développeur.

   CVS permet à plusieurs développeurs de travailler sur le même fichier source. Dans son fonctionnement standard, il ne verrouille pas a priori les fichiers ; son mode de fonctionnement est optimiste : il suppose que les conflits sont rares et souvent faciles à résoudre. Si deux développeurs ont modifié le même fichier, CVS sait résoudre le conflit à la seule condition que les modifications n’aient pas été apportées à la même partie de code. Dans le cas contraire, c’est le dernier développeur qui veut mettre à jour le référentiel qui devra régler manuellement le problème (plus loin nous verrons comment).

    

5. Qu’est-ce que ça ne fait pas ?

Comme dit juste au-dessus, CVS ne sait pas régler automatiquement les conflits liés à la modification par plusieurs développeurs de la même partie de code à l’intérieur d’un fichier source.

De même, il n’est pas approprié à la gestion de fichiers binaires. Par commodité ( pour générer plus facilement les distributions, par exemple ), les fichiers exécutables ou les images peuvent être stockés au même niveau que le référentiel ; mais il ne faut pas attendre de miracles de la part de CVS.

Par ailleurs, si CVS est indispensable pour le suivi des modifications et la gestion des versions, il ne remplace en aucun cas le suivi de projet : méthodes de travail et de communication entre développeurs, règles de programmation, tests de non régression, etc… Il ne peut pallier à une absence d’organisation. Dans le même ordre d’idées, il faudra se poser quelques questions concernant la sécurité : qui peut accéder au référentiel du projet ? par quel moyen ? ne vaut-il pas mieux verrouiller dans certains cas des fichiers sensibles ? Mais toutes ces interrogations relèvent plus du rôle de l’administrateur et ont leur place dans un autre document.

• Les premiers pas

Ce document s’adressant en priorité aux développeurs, nous supposons que CVS est installé et entièrement configuré sur le serveur. Dans notre exemple, le référentiel du projet est installé dans le répertoire  /usr/local/cvs d’un serveur hôte accessible par l’adresse mon-serveur.org et s’appelle projettest. Votre compte d’accès au serveur est : develop1/xw31kz. Nous ne nous intéresserons donc qu’au côté " client ". Tout d’abord, une petite question : sur quel système d’exploitation travaillez-vous ?

- Linux : dans ce cas, la plupart des distributions de Linux contiennent une version de CVS. Si CVS est déjà installé sur votre machine, il suffit de définir quelques variables système. Sinon, vous pouvez télécharger une version de CVS (www.cvshome.org ) et procéder à son installation ( cf.2.1.1 ).

- Windows : il faut charger et installer un client CVS, par exemple WinCVS à l’adresse

http://cvsgui.sourceforge.net (cf.2.1.2).

1. Installer et configurer CVS sur le poste client.

2.  

   1. Sous Linux

   2.  

      1. Vérification

      2. CVS contient son propre client CVS. Pour vérifier si CVS est installé, il suffit de taper sur la ligne de commande :

         cvs

         Si le système sait interpréter cette commande, il en affichera les différentes options et paramètres. Vous pouvez alors passer directement au paragraphe 2.1.3

          

      3. Installation

      Sinon, le plus simple est d’installer CVS à partir des sources. Commencez par récupérer le fichier le plus récent à l’adresse : http://ccvs.cvshome.org/servlets/ProjectDownloadList ( par exemple,

      cvs-1.11.4.tar.gz, la dernière distribution à ce jour, en format GZip ).

      Puis, sur la ligne de commandes, placez vous dans le répertoire dans lequel vous souhaitez installer le produit (ex. /usr/local/src )et tapez les ordres suivants :

      tar xzvf cvs-1.11.4.tar.gz

      cd cvs-1.11.4

      ./configure

      make

      make install

      L’installation est terminée.

       

   3. Sous Windows

   4. Téléchargez WinCVS à l’adresse : http://cvsgui.sourceforge.net ou un site miroir. Vous pouvez également utiliser un autre client CVS de votre choix, comme TurtoiseCVS. Mais dans notre exemple ci-dessous, nous utiliserons WinCVS 1.2 Stable (fichier WinCvs120.zip de 3618 Ko).

      Décompressez le fichier téléchargé dans un répertoire temporaire, puis procédez à l’installation en cliquant sur le fichier setup.exe .

       

   5. Configuration des variables systèmes

   Il reste à configurer 3 variables système:

   CVSROOT qui donne l’identification de l’utilisateur, l’adresse du serveur distant et le chemin d’accès au référentiel du projet sur le serveur (dans notre exemple : /usr/local/cvs sur le serveur).

   CVS_RSH indique quel est l’utilitaire d’accès au référentiel externe. Par défaut, CVS utilise rsh ; pour plus de sécurité,  il est conseillé d’utiliser ssh.

   CVSEDITOR sert à renseigner l’éditeur de texte qui servira à renseigner les messages et commentaires lors des mises à jour du référentiel. Si cette variable d’environnement n’est pas renseignée, CVS utilisera l’éditeur défini par la variable EDITOR . Si aucune des deux variables n’est positionnée, CVS provoquera une erreur d’exécution.

   Sous Linux, la syntaxe pour définir ces variables dépend du shell. En Bourne shell, on utilisera la commande " export " ; en C shell, la commande setenv.

   Ex. en Bourne shell :

   export CVSROOT=develop1/xw31kz@mon-serveur.org:/usr/local/cvs

   export CVS_RSH=ssh

   export CVSEDITOR=vim

   Pour éviter d’avoir à retaper ces instructions à chaque fois, il est fortement conseillé de les enregistrer dans un fichier d’initialisation qui s’exécute automatiquement à l’ouverture d’une session (ex. fichier bash).

   Sous Window, et à condition d’utiliser WinCVS, le paramétrage des mêmes variables d’environnement se fait au travers d’un écran comme celui figurant ci-après :

    

   

3. Créer une copie privée du projet

Il faut commencer par créer le répertoire dans lequel nous allons récupérer l’image locale du référentiel. Pour notre exemple, nous travaillerons dans le répertoire cvs dans l’arborescence /home/monrep. On tapera donc la commande :

cd /home/monrep

mkdir cvs

Importons maintenant sur notre machine locale le projet de développement :

cvs checkout projettest

Cette commande va dupliquer localement l’intégralité du module projettest. En fait, cvs checkout sert normalement à comparer les modifications apportées aux fichiers et répertoires du projet et à les répercuter sur la base locale. Comme il s’agit de sa toute première utilisation, aucun fichier n’est trouvé localement et par conséquent l’ensemble des fichiers est rapatrié.

Si aucune erreur ne s’est produite, un répertoire projettest a été créé dans l’arborescence locale /home/monrep/cvs. Il contient tous les fichiers sources du projet et un sous-répertoire CVS que l’outil utilise pour la gestion de ses données.

Voilà, vous êtes prêts à travailler sur les sources dans votre répertoire local.

• Travailler avec CVS

1. Mise à jour du référentiel.

2.  

   1. La commande " commit "

   2. Après avoir modifié certains fichiers, vous souhaitez mettre à jour le référentiel en y répercutant toutes les modifications que vous avez apportées au projet dans votre base locale.

      Pour vérifier quels sont les fichiers qui nécessitent leur mise à jour, tapez la commande :

      cvs checkout projettest

      Les fichiers modifiés sont identifiés par la lettre " M " devant leur nom. Attention, cette commande n’effectue pas réellement la mise à jour du référentiel distant. Il est nécessaire d’utiliser pour cela :

      cvs commit

      L’outil vous demande alors de saisir un message pour commenter la mise à jour que vous effectuez. C’est à cette occasion qu’il utilise la variable CVSEDITOR définie au § 2.1.3 pour savoir quel éditeur de texte doit servir à la saisie du message. Selon ce qui aura été défini dans les méthodes de développement standard, il conviendra de saisir dans ce commentaire : votre nom, l’objet de vos modifications, etc.

      Comme toutes les commandes cvs, la commande commit accepte des options et/ou des paramètres. Ainsi, plutôt que de saisir votre commentaire au travers d’un éditeur de texte, vous pouvez le taper directement sur la ligne de commande, en utilisant l’option -m. Par exemple :

      cvs commit -m ‘develop1 : correction des formats de dates’

      La commande commit demande explicitement à cvs de mettre à jour le référentiel. A cette occasion, il se peut que cvs détecte un conflit. C’est le cas si un autre utilisateur a validé ses propres modifications pendant que vous apportiez localement des correctifs ou des améliorations au projet. Si un fichier nommé fichier1.txt du référentiel n’est plus dans l’état où vous l’aviez récupéré, cvs signale le problème et n’effectue pas la mise à jour.

       

   3. La résolution des conflits

Deux cas peuvent alors se présenter :

1. Les modifications que vous avez apportées au fichier ne se trouvent pas au même endroit que celles appliquées par l’autre utilisateur. Dans ce cas cvs sait résoudre facilement le conflit. Il suffit d’utiliser la commande :

2. cvs update fichier1.txt

   Ceci met à jour votre fichier local, en y répercutant les modifications appliquées par l’autre utilisateur. Vous êtes prêt à tenter un nouveau " commit ".

3. Il se peut, malheureusement, que cvs ne soit pas en mesure de fusionner automatiquement les modifications dans votre fichier. C’est le cas si vous avez modifié la même partie de code que l’autre utilisateur ou si les modifications sont très complexes et très imbriquées. Vous n’avez alors pas d’autre solution que d’intervenir manuellement pour résoudre le conflit. Pas de panique : il suffit d’éditer le fichier fichier1.txt ; les deux versions du code qui n’a pas pu être fusionné apparaissent clairement entre deux balises ; vous devriez sans trop de peine pouvoir régler le problème ( pour exemple, cf. § 5.8).

Pour valider les modifications sur le référentiel, il vous suffit de retaper la commande :

cvs commit fichier1.txt

Remarque : l’organisation et la méthodologie du développement peuvent contribuer à diminuer le risque de conflits. Comme indiqué en préambule, l’outil cvs travaille sur un mode optimiste et ne verrouille pas a priori les fichiers. Dans le cadre du développement d’une application, il est d’autant plus indispensable d’établir des règles et des méthodes. Une organisation des équipes, une communication régulière entre développeurs, un suivi du projet, des mises à jour fréquentes du référentiel minimiseront les situations conflictuelles.

Dans le cadre du développement coopératif, vous pouvez être amené à créer un nouveau fichier ou à supprimer un fichier existant. Mais une création ou une suppression de fichier, pas plus que la modification d’un fichier existant, ne se répercute pas automatiquement sur le référentiel. Les fichiers sont ajoutés ou supprimés localement. Pour mettre à jour le projet distant, il va falloir l’indiquer explicitement.

Pour ajouter un nouveau fichier, on utilisera la commande cvs " add " ; pour la suppression, la commande cvs " remove ".

Exemple d’ajout d’un fichier :

cvs add -m ‘Ajout du fichier nouvau_fichier.txt’ nouveau_fichier.txt

cvs commit nouveau_fichier.txt

Exemple de suppression de fichier :

cvs remove vieux_fichier.txt

cvs commit vieux_fichier.txt

Notons enfin que, puisque cvs conserve tout l’historique des modifications, un fichier effacé par la commande " remove " peut toujours être récupéré et rajouté au projet par la commande " add ".

Nous avons à présent identifié les commandes de base pour travailler avec cvs en tant qu’utilisateur. Les paragraphes suivants nous permettrons :

• d’étudier quelques options de ces commandes de base
• d’approfondir nos connaissances sur le suivi de projet avec CVS
• de conclure par quelques réflexions sur les règles de méthodologie.

1. Les commandes CVS

2.  

   Avec les quelques commandes que nous avons vues ci-dessus, il est déjà tout à fait possible de travailler avec CVS et de contribuer à un projet de développement en tant qu’utilisateur. Mais le développeur n’est généralement pas un utilisateur ordinaire ; c’est un être curieux qui désire en savoir davantage. Voyons donc les petits plus que CVS peut nous apporter : de nouvelles commandes ou options qui nous faciliterons la tâche ou nous permettrons de mieux comprendre le suivi des versions ou des distributions.

    

   1. Généralites

On distingue deux grandes catégories d’options qui accompagnent la plupart des commandes CVS: les options globales et les options générales.

• les options globales sont celles qui se trouvent à gauche de la commande et qui sont communes à toutes les commandes du client CVS
• les options générales sont celles qui se trouvent à droite de la commande comme un paramètre de la commande en question.

Par exemple, dans la commande

cvs -q checkout projettest, l’option -q est dite globale (elle se trouve à gauche de la commande checkout)

Dans la commande

cvs add -m ‘Ajout du fichier nouvau_fichier.txt’ nouveau_fichier.txt, l’option -m est dite générale (elle se trouve à droite de la commande add).

De surcroît, chaque commande peut avoir des options qui lui sont particulières.

Les options générales décrites ci-dessous sont valables pour la plupart des commandes du client CVS. Il existe cependant des exceptions et certaines options n’auraient pas de sens en association avec certaines commandes. Le tableau récapitulatif en fin de paragraphe indique, pour chacune des commandes, les différentes options générales supportées par le produit.

-D date_spec : utilise la dernière version immédiatement antérieure à la date passée dans le paramètre date_spec. Pour les formats de dates, voir le paragraphe 5

-f : lorsqu’on indique une date ou une étiquette à une commande, CVS ignore normalement les fichiers qui n'existaient pas à la date indiquée ou qui n’ont pas d’étiquette. Cette option -f permet d’inclure les fichiers qui sont dans ce cas.

-kkflag : modifie le mode de substitution des mots-clés (pour plus de détails sur cette notion, cf. § 5 infra)

Sachez que l’utilisation la plus fréquente de l’option -k est la syntaxe -kb qui signale à CVS qu’un fichier doit être traité comme étant un binaire. D’autre part -kk inhibe complètement la substitution des mots-clés.

-l : n’exécute la commande que sur les fichiers du répertoire local ; par défaut l’exécution des commandes se fait de manière récursive sur les sous-répertoires.

-n : CVS permet de lancer un programme de contrôle lors de l’exécution d’une commande ; l’option -n inhibe le lancement de ces programmes.

-R : n’est utile qu’après utilisation de l’option -l ; rétablit le fonctionnement standard qui exécute récursivement la commande sur les fichiers du répertoire courant et ses sous-répertoires

-r nom_étiquette : force CVS à utiliser un numéro de version identifié par la variable nom_étiquette plutôt que la version la plus récente. En plus des étiquettes définies par les commandes " tag " et " rtag " (voir ces commandes, § 5.3), il existe 2 étiquettes par défaut : HEAD identifie la version la plus récente du référentiel et BASE identifie la version la plus récente mise à jour dans le répertoire local de travail.

CVS sait gérer un historique mis à jour lors de chaque utilisation des commandes checkout, commit, rtag, update et release. Pour cela, il faut avoir créé un fichier nommé history dans le répertoire $CVSROOT/CVSROOT/ sur le serveur (dans l’arborescence du référentiel).

La commande history permet alors d’afficher des informations de ce fichier historique sous différents formats et selon plusieurs critères de tri (chronologie, utilisateur, type de modification).

En plus des options générales -D et -r, les options particulières suivantes s’appliquent :

-a: par défaut, seul l’historique de l’utilisateur courant est affiché ; cette option force la commande à afficher l’historique de tous les utilisateurs

-c: signale chaque modification du référentiel par la commande commit

-f nomfichier: donne les informations sur le fichier nomfichier

-l: n’affiche que la dernière modification

-m module: affiche le rapport pour un module particulier (l’option -m peut être répétée plusieurs fois dans une même commande history)

-p référentiel: affiche le rapport pour un référentiel particulier (l’option -p peut être répétée plusieurs fois dans une même commande history)

-r vers: affiche des informations concernant les versions, en cherchant dans tous les fichiers du référentiel depuis que la version ou l’étiquette du nom de vers apparaît dans ces fichiers

-t étiquette: équivalent à l’option -r, mais ici seul le fichier history est parcouru ; cette option est donc beaucoup plus rapide

-u util: montre les enregistrements correspondant à l’utilisateur util

-w : n’affiche l’historique que pour le répertoire courant

-x typeact: extrait de l’historique les enregistrements correspondant au type d’action typeact. Chaque type d’action est identifié par une lettre (ces lettres peuvent être combinées dans le paramètre typeact). Certaines commandes n’ont qu’une seule lettre pour identifier leur action ; par contre les commandes update et commit donnent lieu à plusieurs types d’action. C’est ce que montre le tableau ci-dessous :

Pour une liste exhaustive des options de la commande history, il est recommandé de se référer à la documentation de CVS (notamment le manuel de Cederqvist et alii - cf. 6.1)

1. Utilisation avancée de CVS

2. Dans ce chapitre, nous allons aborder quelques commandes, destinées certes à l’utilisateur de CVS, mais un peu plus orientées vers l’administration de projet. C’est dire qu’elles ne sont généralement pas utilisées quotidiennement dans le cadre d’un développement. Pour les utilisateurs qui souhaitent se limiter à un usage courant de l’outil CVS, il est possible de sauter cette partie et de passer directement au chapitre 6.

    

   1. Coordination et sérialisation des développements

   2.  

      Beaucoup d’organisations peuvent trouver le fonctionnement standard de CVS tout à fait à leur goût et donc s’en contenter.

      D’autres préféreront maîtriser mieux le processus de développement, savoir qui modifie un fichier à un instant donné pour permettre aux utilisateurs de se coordonner et s’informer mutuellement, pour éviter les conflits au moment de la mise à jour du référentiel. Il est notamment possible d’empêcher deux utilisateurs de modifier simultanément le même fichier, ce qui revient à modifier le comportement standard de CVS qui se base sur un mode de verrouillage optimiste.

       

      1. watch

      2. Par défaut, CVS autorise chaque développeur à éditer n’importe quel fichier de son répertoire de travail et à le modifier à tout moment. Les autres développeurs ne sont pas avertis de cette action, et ne le seront que lors de l’exécution d’une commande qui compare le contenu du référentiel avec leur propre répertoire de travail (update, checkout, commit) . La commande watch permet de mettre en place un dispositif de surveillance des fichiers qui permettra aux développeurs ne plus avoir de mauvaise surprise au moment de la mise à jour, puisqu’ils pourront être avertis préalablement des modifications faites par les autres.

         cvs watch on [-lR] files . . . : précise que les utilisateurs devront lancer la commande cvs edit pour pouvoir éditer les fichiers files. CVS rend les fichiers de travail files accessibles en lecture seulement. Le paramètre files peut contenir des noms de répertoires. S’il est omis, c’est l’ensemble du référentiel qui est soumis au dispositif de surveillance

         cvs watch off [-lR] files . . . : A l’inverse, la sous-commande off rend l’accès en lecture-écriture aux fichiers bridés par la sous-commande on.

         Il est possible de demander à CVS de nous avertir quand certaines actions concernent un fichier.

         cvs watch add [-a action] [-lR] files . . . : ajoute l’utilisateur courant à la liste des personnes à prévenir lors des modifications de fichiers. L’option -a précise quels sont les événements que CVS doit signaler :

         edit : un autre développeur a appliqué la commande edit au fichier surveillé

         commit : un autre utilisateur a validé ses modifications apportées aux fichiers

         unedit : un autre utilisateur a renoncé aux modifications faites sur les fichiers, soit en utilisant la commande unedit, soit en utilisant la commande release, soit en supprimant physiquement les fichiers et en les recréant par la commande update.

         all : pour toutes les actions décrites ci-dessus (utilisé par défaut)

         none : pour aucune des actions (n’a d’intérêt qu’avec la commande edit)

         L’option -a peut apparaître plusieurs fois dans la commande ou être omise (dans ce cas, l’action par défaut est all)

         cvs watch remove [-a action] [-lR] files . . . : annule une demande de notification établie en utilisant la commande cvs watch. Si l’option -a est présente, seules les actions explicitement indiquées sont annulées.

         Quand il y a lieu d’avertir les utilisateurs, cvs fait appel au fichier d’administration appelé notify. Chaque ligne de ce fichier est une expression régulière suivie par une commande à exécuter. Si ce fichier ne devait comporter qu’une seule ligne, ce serait la ligne standard ci-dessous :

         ALL mail %s -s "Information de notification CVS"

         C’est d’ailleurs ce que contient le fichier history créé par défaut par la commande init. Cette ligne de commande a pour conséquence de prévenir les utilisateurs (%s est une variable à laquelle CVS substitue le nom d’utilisateur lors de l’exécution de la ligne de commande) par courrier électronique.

         Si on n’adapte pas un peu le procédé, les utilisateurs recevraient tous leur informations sur le serveur, ce qui n’est pas vraiment pratique. On pourrait évidemment écrire un script pour rediriger l’information ; mais CVS nous facilite la tâche en nous permettant d’associer à chaque utilisateur une adresse de notification. Il suffit pour cela de créer un fichier users dans le répertoire CVSROOT avec, pour chaque utilisateur, une ligne au format utilisateur :valeur. Pour peu que valeur contienne une adresse électronique, CVS utilisera cette information en lieu et place du nom d’utilisateur.

          

      3. edit

      4. Comme un fichier placé sous surveillance grâce à la commande watch n’est accessible qu’en lecture seule, il n’est pas possible de le modifier. Pour le rendre accessible en mode lecture-écriture et prévenir les autres utilisateurs de notre intention de le modifier, nous utiliserons la commande edit.

         cvs edit [options] files . . . : Les options sont les mêmes que pour la commande watch add. Les fichiers sont rendus accessibles en lecture-écriture ; CVS avertit les utilisateurs ayant sollicité un avertissement quand les fichiers files sont appelés par la commande edit ; ces fichiers sont temporairement placés sous surveillance pour l’utilisateur (sauf si l’option -a est positionnée) et la surveillance ne sera levée que par l’application des commandes unedit ou commit à ces fichiers.

          

      5. unedit

      6. cvs unedit [-lR] files . . . : abandonne tout ce qui a été fait sur les fichiers files et les remet en conformité avec le référentiel. CVS rend ces fichiers accessibles en lecture seule et en avertit les utilisateurs ayant demandé à être informés en cas d’action de type unedit

          

      7. watchers

      8. cvs watchers [-lR] files . . . : donne la liste des utilisateurs ayant placé les fichiers files sous surveillance. Le compte rendu indique les fichiers surveillés et l’adresse de chaque observateur.

          

      9. editors

      cvs editors [-lR] files . . . : donne la liste des utilisateurs qui sont en train d’éditer et de modifier les fichiers files. Le compte rendu indique l’adresse électronique de l’utilisateur, le moment où il a commencé à modifier un fichier, ainsi que l’adresse de l’hôte et le répertoire de travail où se trouve le fichier modifié.

       

   3. Echanges avec l’extérieur : import/export, création de patches…

   4.  

      1. export

      2. Cette commande fonctionne de la même manière que la commande checkout. Elle permet d’exporter les fichiers du référentiel sans les répertoires spécifiques à l’administration de CVS. Elle sert notamment à préparer une distribution des sources d’un module. Il convient d’utiliser les options courantes -D date ou -r révision pour créer une copie avec comme critère, soit la date, soit la version.

         Les options globales du tableau 4.1.2 s’appliquent ici. Les options particulières sont celles de la commande checkout :

         -d répertoire : crée le répertoire passé en paramètre pour y copier les fichiers, au lieu d’utiliser le nom du module

         -n : empêche l’exécution de programmes de contrôle

          

      3. import

      4. Cette commande sert à importer la totalité d’une distribution de sources d’origine externe dans le répertoire contenant le référentiel. Elle est utilisée notamment pour créer le référentiel à l’origine. Elle permet aussi d’intégrer au référentiel du code développé en dehors de l’outil CVS. La syntaxe de la commande est la suivante :

         cvs import -m "Import - Création du projet initial" directory étiquette_origine étiquette_version

         A quoi correspondent les 3 arguments ?

         directory : est le nom du répertoire dans lequel seront importés les sources. CVS copie les fichiers du répertoire courant dans le répertoire $CVSROOT/directory.

         étiquette_origine : en anglais " vendor tag ", c’est un nom symbolique pour la branche (par défaut, la branche est 1.1.1)

         étiquette_version : c’est un nom symbolique pour la version

         L’option -m permet d’associer un commentaire directement sur la ligne de commande ; sinon, CVS ouvre l’éditeur de texte pour que l’utilisateur saisisse ce commentaire.

         L’option -k autorise la substitution de mots-clés (cf. 5.5 pour cette notion)

         L’ option spécifique -b nom_branche  permet d’indiquer un nom de branche vers laquelle effectuer l’import. Par défaut, CVS utilise la branche 1.1.1 comme branche d’origine.

         Cederqvist et alii (cf. 6.1) donne d’exemple suivant :

         Supposons que nous ayons deux équipes, l’équipe rouge et l’équipe bleue, qui nous envoient des sources. Nous voulons importer les contributions de l’équipe rouge dans la branche 1.1.1 et utiliser l’étiquette d’origine ROUGE. Nous souhaitons importer les contributions de l’équipe bleue dans la branche 1.1.3 et utiliser l’étiquette d’origine BLEU. Alors les commandes que nous utiliserons sont :

         cvs import directory ROUGE RG_1-0

         cvs import -b 1.1.3 directory BLEU BL_1-5

         Attention, CVS n’établit aucune corrélation entre la branche de l’option -b et le nom symbolique de branche de l’argument étiquette_origine.

         Les autres options supplémentaires sont :

         -I nom : force CVS à ignorer le fichier dont le nom est contenu dans le paramètre nom. Cette option peut être répétée plusieurs fois sur la même commande. Si on veut forcer CVS à traiter tous les fichiers, on utilise -I !

         Voir également le fichier cvsignore (cf. 5.4)

         -W spec : précise dans le paramètre spec les fichiers qui doivent être filtrés pendant l’import (par exemple, pour identifier les fichiers binaires).

         Ex. : cvs import -I ! -W "*.exe -k ’b’" first-dir vendortag reltag

         filtre tous les fichiers (-I !) et identifie les fichiers se terminant par l’extension .exe comme étant des binaires.

         La commande import affiche sur la sortie standard les codes états suivants :

         U nomfic : le fichier existait déjà dans le référentiel et n’a pas été modifié localement

         N nomfic : le fichier est nouveau, il a été ajouté au référentiel

         C nomfic : le fichier existait dans le référentiel et il a été modifié localement ; une fusion est nécessaire

         I nomfic : le fichier a été ignoré

         L nomfic : le fichier est un lien symbolique, CVS l’ignore.

          

      5. release

      6. On utilise la commande release pour supprimer proprement un répertoire. Bien entendu, il est possible de supprimer manuellement un répertoire, mais alors CVS n’en concerne aucune trace ; alors qu’avec la commande release le fichier history peut être renseigné (à condition qu’il soit activé).

         Cette méthode évite aussi de perdre involontairement des modifications. En effet, release vérifie qu’il n’existe pas de modifications non mises à jour, que vous l’exécutez à partir d’un répertoire situé immédiatement au-dessus d’un répertoire de travail cvs, et que le référentiel est cohérent.

         Une seule option est possible :

         -d : supprime la copie de travail de vos fichiers locaux, sinon ces fichiers resteront dans votre répertoire. Attention, si vous avez ajouté à la main des répertoires, sans les ajouter au référentiel, ils seront supprimés sans avertissement même s’ils ne sont pas vides. Pour éviter de courir ce risque, il convient de toujours ajouter les répertoires par la commande add.

         Avant d’exécuter la commande release, CVS édite un rapport d’une ligne pour chaque fichier qui n’est pas à jour. Voir le tableau ci-dessous pour la signification des statuts de chaque ligne.

         Code	Signification
         U fichier P fichier	Il existe une version plus récente de ce fichier dans le référentiel et vous n’avez pas mis à jour votre copie locale
         A fichier	Le fichier a été ajouté à votre répertoire local, mais vous n’avez pas validé cet ajout. Ce fichier sera perdu si vous supprimez votre copie des sources
         R fichier	Le fichier a été supprimé de votre répertoire local, mais pas du référentiel, car vous n’avez pas validé cette suppression
         M fichier	Le fichier contenu dans votre copie privée a été modifié localement.
         ? fichier	Le fichier est dans votre répertoire mais ne correspond à rien pour l’outil CVS : il est absent du référentiel et ne correspond pas à un fichier que CVS doit ignorer. Il sera perdu.

          

          

      7. rdiff ou patch

      Cette commande permet de réaliser un fichier au format " patch " à partir des différences entre deux versions. Avec ce fichier patch, il est alors possible de mettre à jour une distribution antérieure.

      Le patch peut être réalisé à partir des critères date ou version, en utilisant respectivement les options -D et -r. Si la distribution se trouve dans différents répertoires, il conviendra d’utiliser l’option -p pour que le patch puisse retrouver dans ces différents répertoires les anciens sources nécessitant une mise à niveau.

      En plus des options communes, rdiff peut être appelé avec les options suivantes :

      -c : utilise le format contextuel de la commande diff (voir plus haut) ; c’est le format par défaut

      -s : génère un rapport résumé des modifications intervenues sur les fichiers au lieu de créer un patch. Cela permet de savoir quels fichiers ont changé depuis une date ou une version donnée.

      -t : affiche à l’écran les différences entre les deux dernières versions. Cela permet de savoir quel est le dernier changement intervenu sur un fichier.

      -u : utilise le format contextuel unidiff pour l’affichage des différences ( usage anecdotique !)

      Pour illustrer l’utilisation de rdiff pour générer un patch, nous reprendrons l’exemple cité par Cederqvist (cf. 6.1) :

      Supposez que nous receviez un message électronique de foo@example.net qui vous demande une mise à jour pour passer de la version 1.2 à la version 1.4 du compilateur tc. Vous n’avez pas sous la main un tel patch, mais avec CVS vous allez pouvoir facilement le créer avec la commande suivante :

      cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | Mail -s ’Le patch que vous avez demandé’ foo@example.net

      Cette commande utilise le format de sortir diff (cvs rdiff -c) pour extraire les différences entre la version FOO1_2 et la version FOO1_4 du fichier tc (-r FOO1_2 -r FOO1_4 tc) ; le résultat de cette commande est ensuite redirigé vers une commande mail qui l’envoie à l’adresse électronique foo@example.net en y ayant joint un message d’information ( | Mail -s ’Le patch que vous avez demandé’ foo@example.net).

       

   5. Etiquettes et branches

   6. Les numéros de version attribués automatiquement aux fichiers par CVS vivent leur propre vie. Par défaut, la version originelle de chaque fichier est 1.1. Ces numéros de version n’ont pas forcément un quelconque rapport avec les numéros de distribution de l’application. Les numéros de version peuvent changer plusieurs fois entre deux distributions ; par ailleurs une distribution comprend des fichiers ayant des numéros de version différents. Ainsi, si on prend pour exemple une petite application document comprenant trois fichiers ( entete.txt, page.txt et resume.txt ), la distribution DIST-3_2 de l’application document peut inclure les fichiers avec les versions suivantes :

      entete.txt 3.11

      page .txt 3.22

      resume.txt 3.20

       

      1. tag

      2. Pour attribuer un nom symbolique (ou étiquette) à une version donnée d’un fichier, on utilisera la commande tag. Pour vérifier les étiquettes d’un fichier et leur correspondance avec les numéros de version, c’est la commande status -v qui nous servira.

         Une étiquette doit commencer par une lettre, minuscule ou majuscule. Elle peut contenir des lettres, des chiffres, ainsi que les caractères - (tiret) et _ (souligné), mais pas de point, de virgule ou de caractères spéciaux. CVS reconnaît par défaut les deux étiquettes BASE et HEAD, comme nous l’avons indiqué plus haut dans l’explication de l’option générale -r : HEAD identifie la version la plus récente du référentiel et BASE identifie la version la plus récente mise à jour dans le répertoire local de travail.

         Une étiquette peut être appliquée à un fichier seul, un groupe de fichier ou un répertoire complet.

         Cette opération est immédiatement prise en compte, sans qu’il y ait besoin de la valider en exécutant une commande commit. Sans option, la commande s’applique à la version locale des fichiers ; attention donc si cette version locale ne correspond pas à celle du référentiel. Pour éviter ce risque, il faudrait toujours utiliser la commande tag avec l’option -c.

         En plus des options générales -l et -R, les options spécifiques sont :

         -b : crée une étiquette de branche ( voir ci-dessous 5.3.3)

         -c : vérifie que la version locale du fichier correspond à celle du référentiel. Dans le cas contraire, l’opération échoue et l’étiquette n’est pas posée.

         -d : l’étiquette est effacée. A utiliser très prudemment. Pour renommer une étiquette, il est conseillé de créer une nouvelle étiquette avec les mêmes caractéristiques, puis de supprimer l’ancienne. Par exemple, si on veut renommer DIST-3_2 en STABLE-3 :

         cvs tag -r DIS-3.2 STABLE-3

         cvs tag -d DIS-3.2

         -F : permet de déplacer une étiquette, par exemple d’une version de fichier vers une autre. Par exemple si la distribution DIST-3_2 de notre application document doit inclure désormais la version 3.25 du fichier page.txt au lieu de la version 3.22, nous utiliseront la commande ci-dessous :

         cvs tag -r 3.25 -F DIST-3_2 page.txt

          

      3. rtag

      4. Alors que la commande tag travaille à partir de l’environnement local, la commande rtag permet d’appliquer une étiquette directement au référentiel, soit selon un critère de dates, soit sur la dernière version des fichiers.

         Ses options sont identiques à celles de la commande tag. S’y ajoutent les options :

         -a : pour effacer l’étiquette des fichiers détruits par remove

         -n : pour n’exécuter aucun programme de marquage du module

          

      5. Branches et fusions

      6. CVS permet de faire des modifications sur une ligne de développement séparée, connue sous le nom de branche. Quand on modifie des fichiers sur une branche, ces modifications n’apparaissent pas sur le tronc principal ni sur les autres branches.

         Une fois stabilisées, ces modifications pourront être reportées sur le tronc principal ou sur les autres branches par une opération de fusion. Cela consiste à lancer la commande cvs update -j pour mettre à jour son répertoire local ; puis à valider cette version par la commande commit qui copiera réellement les modifications sur les autres branches.

          

         1. Intérêt de la branche

         2. Supposons que nous ayons diffusé la distribution 1.0 de l’application document. Nous continuons à développer cette application et prévoyons une nouvelle distribution 1.1 pour le semestre prochain. Manque de chance, un bogue bloquant s’est glissé dans la distribution 1.0 et nos clients exigent un correctif immédiat (ça c’est déjà vu, je pense !). Nous détectons le bogue. Nous saurions le corriger. Hélas, la version en cours de développement est encore totalement instable et ne nous permet pas de réaliser un patch.

            La solution, c’est de créer une branche sur l’arbre des versions pour tous les fichiers de la version 1.0 ; à partir de ce moment, il est possible de modifier la branche sans perturber le tronc. Quand les modifications sur la branche sont terminées, on a le choix : soit on les intègre au tronc principal, soit on les laisse sur la branche (dans ce cas, cela suppose qu’on ait corrigé le bogue simultanément sur la branche et sur le tronc.

             

         3. Création d’une branche

         4. La branche se crée avec la commande tag -b. Par exemple :

            cvs tag -b BR_1_0_patch

            Cette commande, exécutée dans notre répertoire de travail, crée un nom symbolique de branche basée sur la version actuelle des fichiers de notre répertoire local. Par contre, il faut savoir que cette branche est créée dans le référentiel et pas dans notre environnement local (même si elle est basée, dans notre exemple, sur la version des fichiers contenus dans notre répertoire local). Notre environnement local n’est pas automatiquement réorienté vers la branche que nous venons de créer.

            Pour créer une branche non basée sur le répertoire local, on utilise la commande rtag.

            cvs rtag -b -r dist-1-0 BR_1_0_patch document

            crée la branche BR_1_0_patch à partir de l’étiquette dist-1-0 du module document (cet exemple de commande correspond à la méthode de création d’une branche pour résoudre un bogue dans une version antérieure, comme expliqué ci-dessus).

             

         5. Accès à une branche

         6. Il y a deux façons d’accéder à la nouvelle branche, soit en se créant une nouvelle copie de travail à partir du référentiel, soit en écrasant le contenu de sa copie de travail existante avec le contenu de la branche. En supposant que le répertoire de travail soit nommé document :

            - dans la première hypothèse, on utilise la commande checkout avec l’option -r et l’étiquette de branche :

            checkout -r BR_1_0_patch document

            - dans la seconde hypothèse, il faut appeler la commande update pour remettre à jour son environnement local :

            update -r BR_1_0_patch document

            La branche BR_1_0_patch est substituée à la copie de travail d’origine, peu importe qu’elle ait eu pour source le tronc principal ou une autre branche. Nos modifications sont fusionnées et les conflits éventuels sont signalés.

            Une fois qu’on a obtenu une copie de travail attachée à une branche particulière, cette copie restera liée à cette branche jusqu'à ce qu’on en décide autrement. Ceci signifie que les changements issus de la copie de travail ajouteront de nouvelles versions sur cette branche seulement, tout en laissant inchangés le tronc principal et les autres branches.

            La commande status permet de savoir qu’elle branche est opérationnelle dans la copie de travail. C’est le champ " sticky tag " (étiquette collante) qui nous renseigne :

            cvs status -v entete.txt

            ===================================================================

            File: entete.txt Status: Up-to-date

            Version: 3.11 Sat Jan 25 08:45:12 2003

            RCS Version: 3.11 /cvsroot/document/entete.txt,v

            Sticky Tag: BR_1_0_patch (branch: 3.11.2)

            Sticky Date: (none)

            Sticky Options: (none)

            Existing Tags:

            BR_1_0_patch (branch: 3.11.2)

            dist-1-0 (revision: 3.11)

             

         7. Numérotation des branches

         8. On peut schématiser l’évolution des numéros de version d’un fichier en disant qu’il s’agit d’une suite de nombres entiers qui s’incrémentent de un en un. On représentera l’évolution d’un fichier sur le tronc principal de la manière suivante :

            1.1 à 1.2à 1.3à 1.4à 1.5

            Cependant, CVS ne se limite pas à un développement linéaire. L'arbre des versions peut être divisé en branches, où chaque branche est une ligne de développement indépendante. Des changements faits sur une branche peuvent facilement être reportés sur le tronc principal.

            Chaque branche se présente sous la forme d’un numéro de branche, composé d'un nombre impair de nombres entiers séparés par des points. Le numéro de branche est créé en ajoutant un nombre entier au numéro de la version à partir de laquelle la branche est issue. Plusieurs branches peuvent être issues d’une même version. Toutes les versions sur une branche ont des numéros de version constitués en ajoutant un nombre au numéro de branche. Exemple tiré du manuel de Cederqvist (cf. 6.1) :

            Branche 1.2.2.3.2 1.2.2.3.2.1 à 1.2.2.3.2.2

            Branche 1.2.2 1.2.2.1à 1.2.2.2à 1.2.2.3

            Tronc principal 1.1 à 1.2à 1.3à 1.4à 1.5

            Branche 1.2.4 1.2.4.1à 1.2.4.2à 1.2.4.3

             

            Il n’est pas indispensable de connaître la façon est construit le numéro de branche, mais pour satisfaire votre curiosité sachez que CVS part du numéro de version dont dérive la branche et y accole, séparé par point, le premier nombre pair disponible. La première branche issue de la version 1.2 sera numérotée 1.2.2 ; la seconde 1.2.4, etc.

             

         9. Fusion d’une branche

         10.  

             On peut fusionner des changements faits sur une branche vers la copie de travail en utilisant l’option -j nom_branche de la commande update. Cela fusionne dans notre copie de travail les changements faits entre le point où la branche a bifurqué et la plus récente version sur cette branche.

             Reprenons une partie de notre exemple, en supposons qu’on ait donné à la branche 1.2.4 le nom symbolique SITE_PILOTE et que notre module document ne contienne que le fichier entete.txt :

             Tronc principal 1.1 à 1.2à 1.3à 1.4à 1.5

             Branche 1.2.4 1.2.4.1à 1.2.4.2à 1.2.4.3 étiquette SITE_PILOTE

             Nous procéderons donc comme suit :

             cvs checkout document

             cvs update -j SITE_PILOTE entete.txt

             cvs commit -m "Mise à jour de l’application au niveau atteint par SITE_PILOTE"

             La première commande demande à CVS de retrouver la dernière version du module document (c’est à dire 1.5).

             La seconde fusionne, dans notre copie locale du fichier entete.txt, toutes les modifications effectuées sur la branche ( donc entre la version 1.2 et la version 1.2.4.3 ).

             La troisième valide enfin toutes ces modifications dans la version 1.6 du fichier, dans le référentiel :

             Tronc principal 1.1 à 1.2à 1.3à 1.4à 1.5à 1.6

             Branche 1.2.4 1.2.4.1à 1.2.4.2à 1.2.4.3 étiquette SITE_PILOTE

              

             Puis, la branche SITE_PILOTE et le tronc principal peuvent chacun continuer à