Débuter avec Subversion
***********************

Bien débuter avec Subversion.

Introduction
============

Contrôle de version
-------------------

Subversion est logiciel libre (open-source) de contrôle de version.

C'est-à-dire que Subversion gère les fichiers dans le temps. Les fichiers sont déposés dans un dépôt central. Le dépôt peut-être vu comme un serveur de fichier classique, si ce n'est qu'il conserve tous les modifications réalisées à vos fichiers. Ceci vous permet de récuperer d'anciennes versions de vos fichiers, ou de consulter l'historique des modifications de vos fichiers.

Certaines systèmes de contrôle de version sont aussi des systèmes gestion de configuration. Ces systèmes sont spécifiquement conçus pour gérer des arborescences de code source, et ont des fonctionnalités qui sont spécifiques au développement de logiciel (comme la compréhension de language de programmation). Subversion ne fait pas parti de ces types de systèmes; Subversion est un système général qui peut-être utilisé pour gérer tout type d'ensemble de fichiers. (Il reste néanmoins parfaitement adapdé pour gerer du code source.)

Historique
----------

Subversion se veut être le successeur de CVS (http://www.cvshome.org).

Lors de l'écriture de Subversion, CVS était le standard des systèmes de contrôle de version libre utilisé par la communauté open-source. C'est un excellent produit, sérieux et avec une grande réputation de faibilité. Il a été conçu pour être parfaitement adapté au développement open-source.  Cependant, il a aussi quelques défauts qui sont difficilement corrigables.

Les concepteurs originels de Subversion se sont concentrés sur quelques objectifs simples:  ils ont décidé que Subversion sera un remplaçant fonctionnel de CVS. Subversion fera tout ce que CVS fait -- ceci en conservant le même model de développement et en corrigant les défauts les plus évidents. Les utilisateurs actuels de CVS sont la la cible prévilégiée de Subversion. Tout utilisateur de CVS doit être capable d'utiliser Subversion après un petit effort.

CollabNet (http://www.collab.net) a fourni les moyens initiaux nécessaires en 2000 pour débuter le travail de développement. Cette initiative est devenue un important projet open-source poussé par la communauté des développeurs de logiciel libre.

Audience
--------

Ce livre est destiné aux personnes ayant déjà utilisé un système de contrôle de version et pas forcément Subversion ou CVS. Il considère que le lecteur a un minimum de culture informatique et de connaissance d'utilisation d'Unix en ligne de commande.

Les personnes connaissant CVS peuvent sauter certaines sections de l'introduction qui décrive le modèle de versionnement concurrent de Subversion. Il existe également un guide rapide pour les utilisateurs de CVS dans l'appendice (see SVN pour les utilisateurs de CVS.).

Fonctionnalités
---------------

Quelles fonctionnalités de Subverion le rend meilleur que CVS? Voici une petit liste qui vous mettra en appétit:

  * Versionnement des répertoires Le dépôt de Subversion n'utilise pas les fichiers RCS contrairement à CVS; au-lieu de celà, il implémente un système de fichier versionné ``virtuel'' qui trace les arborescences dans le temps. Les fichiers et les répertoires sont versionnés. Ainsi, on trouve de réels commands ``move'' (déplacer) et ``copy'' (copier) du coté client.

  * Requête de changement atomique Une requête de changement du dépôt (central) est totalement réalisée ou pas du tout. Elle n'est jamais partiellement réalisée.

  * Interface réseau évoluée Le serveur réseau de Subversion est Apache, le client et le serveur communiquent ensemble en utilisant le protocole WebDav. (voir Architecture)

  * Accès réseau optimisé Un algorithme de detection de différences binaire est utilisé pour stocker et transmettre les écarts dans les deux sens, que ce soit un fichier texte ou de type binaire.

  * Méta-donnée Chaque fichier ou répertoire a un invisible tableau qui lui est attaché. Vous pouvez stocker n'importe quelles paire clée/valeur que vous voulez: propriétaire, permissions, icône, type mime, notes personnel, etc. Cette fonctionnalité donnée à l'utilisateur est à usage générale. Les propriétés sont versionnées dans le temps exactement comme le contenu des fichiers.

  * Capacité d'adaptation Subversion ne traine pas de ``boulet'' historiques; c'est principalement un ensemble de librairies C partagées avec des interfaces bien conçues. Ceci rend Subversion facilement maintenable et utilisable par d'autres programmes ou languages.

Architecture
============

Subversion a une conception modulaire; il est basé sur un ensemble de librairie C. Chaque librairie a un objectif précis et une interface bien conçue.

Si vous n'est pas interessé par les rouages internes de Subversion, sauté cette partie et allé à Installation et Concepts.

Voici un diagramme des différentes couches de Subversion. Le flux du programme débute en haut du diagramme (à l'initiative du l'utilisateur) et continue vers le bas.

                         +---------------------+
                         | ligne de commande   |
                         | interface graphique |
                         | programme client    |
              +----------+---------------------+---------+ <=== Interface client
              |              Librairie client            |
              |                                          |
              |         +---+                            |
              |         |   |                            |
      +-------+---------+   +--------------+--+----------+ <=== Interface réseau
      | Copie de travail|   | Accès distant|  | Accès    |
      | lib de gestion  |   | du dépôt     |  | local    |
      +-----------------+   +--------------+  | du dépôt |
                            |     neon     |  |          |
                            +--------------+  |          |
                               ^              |          |
                              /               |          |
                        DAV  /                |          |
                            /                 |          |
                           v                  |          |
                   +---------+                |          |
                   |         |                |          |
                   | Apache  |                |          |
                   |         |                |          |
                   +---------+                |          |
                   | mod_DAV |                |          |
                 +-------------+              |          |
                 | mod_DAV_SVN |              |          |
      +----------+-------------+--------------+----------+ <=== Interface du système de fichier
      |                                                  |
      |           Système de fichier de Subversion       |
      |                                                  |
      +--------------------------------------------------+

Système de fichier
------------------

Le système de fichier de Subversion n'est pas un système de fichier au niveau noyau qu'une personne peut installer sur un système d'exploitation (comme Linux ext2 fs). Au-lieu de celà, il désigne le concept de dépôt de Subversion. Le dépôt s'appuit sur une base de données -- actuellement Berkeley DB -- qui est un ensemble de fichiers .db . Cependant, une seule librairie accède à ces fichiers et exporte une API (interface) C qui simule un système de fichier -- plus spécifiquement un système de fichier versionné.

Ceci signifie qu'écrire un programme qui accède au dépôt est comme écrire un programme qui utilise une autre API de système de fichier: vous pouvez ouvrir en lecture ou écriture des fichiers et des répertoires de la même façon.

L'utilisation d'un moteur de base de données fournie d'autres fonctionnalités appréciables dont Subversion a besoin: intégrité des données, écriture atomique, restauration dans un état cohérent, et sauvegarde à chaud.

Interface réseau
----------------

Subversion est tout entier marqué par Apache. En son coeur, le client Subversion utilise la librairie d'exécution portable d'Apache (Apache Portable Runtime : APR). Ceci permet au client Subversion de se compiler et s'exécuter partout où le verseur httpd d'Apache le fait -- actuellement, la liste inclue la plupart des Unix, Win32, BeOS, OS/2, Mac OS X, et peut-être Netware.

Cependant, Subversion ne dépend pas que de APR -- le ``serveur'' Subversion est httpd d'Apache lui-même. httpd d'Apache est éprouvé depuis longtemps, c'est un serveur open-source extensible qui est prêt pour des utilisations sérieuses. Il peut supporter de fortes charges réseau, fonctionne sur de nombreuses plateformes, et est accessible via des pares-feu / proxy (firewalls). Il peut utiliser de nombreux différents protocoles d'authentification et supporte ``network pipelining and caching'' (comment traduit çà ?). En utilisant Apache comme serveur, Subversion profite de tous ces caractéristiques pour un coût nul.

WebDAV est le protocole réseau utilisé par Subversion. DAV (Distributed Authoring and Versioning : publication et versionnement distribué) mériterait un livre entier à lui seul (voir http://www.webdav.org/) -- pour résumer, c'est une extension du protocole HTTP qui permet de lire/ecrire et le versionnement de fichiers via le web. Le project Subversion espère une amélioration du support de ce protocol: tous les derniers gestionnaires de fichier de win32, MacOS, et GNOME support déjà ce protocole. Interopérabilité deviendra enfin petit à petit une réalité. (Cette partie est plustôt mal traduite !).

Pour les utilisateurs qui souhaitent seulement accéder à un dépôt Subversion sur leur disque local, le client peut aussi le faire; le réseau n'est pas nécessaire. La couche RA (``Repository Access'' qui permet d'accéder au dépôt) est une API abstraite implémentée par la librairie RA de DAV (accès réseau) et d'accès local. C'est le bénéfice d'écrire un système de gestion de version orienté ``librairie'': envie d'écrire un nouveau protocole réseau pour Subversion? Il suffit d'écritre une nouvelle librairie qui implément l'API RA.

Librairies clientes
-------------------

Du côté client, la librairie chargée de la ``copie de travail'' de Subversion gère des informations administratives dans le sous-répertoire spécial .svn dont l'objectif est similaire au répertoire d'administration de CVS qu'on trouve dans la copie de travail de CVS.

Un coup d'oeil à l'intérieur d'un répertoire .svn typique en montre un peu plus cependant. Le fichier ``entries'' contient de l'XML qui décrit l'état actuel du répertoire de copie de travail (et qui sert essentiellement à la même chose que les fichiers Entries, Root de CVS, ``and Repository files combined'' (comme traduire ?) ). Mais d'autres élements (et que l'on ne trouve pas dans CVS) fournissent un lieu de stockage pour les propriétés versionnées (les méta-données cités dans ``Fonctionnalités'' au-dessus) et un cache privé de la version du dépôt (C'est-à-dire sans les modifications locales à la copie de travail).  Ce dernier point permet de connaitre les modifications locales -- et de les annuler -- sans demander d'accès réseau. Les données d'authentification sont également stockées dans .svn/, au-lieu d'un seule fichier du type .cvspass.

La librarie ``client'' de Subversion a la plus large responsabilité; sa tâche est de combiner les fonctionnalités de la librairie gérant la copie de travail avec la librarie d'accès au dépôt, et ainsi de fournir une API de haut-niveau pour toute application qui veux réaliser des actions générales de control de révision.  (Par exemple: la routine C 'svn_client_checkout()' prend une URL en paramètre. Il passe cette URL à la librairie d'accès au dépôt et lance une session authentifiée avec le dépôt. Puis il demande au dépôt une certaine arborescence, et envoie cette arborescence à la librairie qui gére la copie de travail, qui ensuite écrit une copie de travail complète sur le disque (répertoires .svn et l'arborescence).)

La librairie cliente est conçue pour être utilisée par n'importe quelle application. Alors que les codes source de Subversion inclut un client en ligne de command standard, il doit être très facile d'écrire des clients graphiques au-dessus de la librairie cliente.

Installation
============

### Somebody please write this.  It should describe how to fetch various binary packages of Subversion for different platforms.  Maybe this will flesh out once RPMs, .debs, and BSD ports are widely available from standard locations?

Pour construire Subversion depuis le code source, see Compilation et installation.

Concepts
========

Si vous êtes actuellement un utilisateur de CVS, alors la première section, Comment développer avec Subversion, doit vous être familière. Vous devriez juste le parcourir rapidement, il n'y a rien de spécial dans la définition de ``Révision'' dans la seconde sous-section. A certain endroit, vous devriez probablement lire aussi l'appendice qui décrit les différences fondamentales entre CVS et SVN (see SVN pour les utilisateurs de CVS.).

Comment développer avec Subversion
----------------------------------

Répertoire de travail et dépôt
..............................

Imaginons que vous utilisez Subverion pour gérer un project de logiciel. Il y a deux choses avec lesquelles vous allez être en intéraction: votre répertoire de travail et le dépôt.

Votre répertoire de travail est une arborescence de répertoire ordinaire sur votre système et contenant les sources de votre projet. Vous pouvez éditer ces fichiers et compiler votre programme comme d'habitude. Votre répertoire de travail est votre propre espace privé de travail: Subversion ne change jamais les fichiers dans votre répertoire de travail, ou ne publie les modifications que vous y avez fait, sans que vous ne lui demandiez explicitement de le faire.

Après avoir fait quelques modifications à des fichiers dans votre répertoire de travail et vérifié que tout fonctionne correctement, Subversion fournie des commandes pour publier vos modifications auprès des autres personnes travaillant avec vous sur votre projet. Si les autres publient leurs propres modifications, Subversion fournie des commandes pour incorporer leurs modifications dans votre répertoire de travail.

Un répertoire de travail ``Subversion'' a des fichiers supplémentaires créé et maintenu par Subversion, pour l'aider à réaliser ses commandes. En particulier, ces fichiers aident Subversion à reconnaitre quel fichier contient des modifications non publiées et quels fichiers ne sont plus à jour par rapport au travail des autres.

Alors que votre répertoire de travail vous est uniquement dédié, le dépôt est le lieu publique commun que vous partagez avec ceux travaillant sur le projet. Pour publier vos modifications, vous utilisez Subversion pour les mettre dans le dépôt. (La signification exacte de celà sera fournie plus loin.)   Une fois que vos modifications sont dans le dépôt, les autres peuvent demander à Subversion d'incorporer vos modifications dans leurs répertoires de travail. Dans un environnement coopératif comme celui-ci, chaque utilisateur a son propre répertoire de travail (et peut-être plus d'un), et toutes les modifications dans les répertoires de travail seront reportées à un unique dépôt, partagé par tous les utilisateurs.

Un dépôt Subversion conserve une unique arborescence de répertoire, et enregistre l'historique des modifications de cette arborescence. le dépôt converse suffisament d'information pour recréer tout état antérieurs de l'arborescence, et donner les relations entre fichiers dans l'arborescence --- quel fichier est dérivé quel autre fichier.

Un dépôt Subversion peut converser le code source de plusieurs projets; habituellement, chaque projet est un sous-répertoire dans l'arborescence. Dans cette configuration, un répertoire de travail correspond généralement à un sous-répertoire particulier du dépôt.

Par exemple, supposons que vous avez une dépôt organisé comme çà :

     /trunk/paint/Makefile
                  canvas.c
                  brush.c
            write/Makefile
                  document.c
                  search.c

En d'autres mots, le répertoire racine du dépôt a un unique sous-répertoire appelé trunk, qui lui-même contient deux sous-répertoires: paint et write.

Pour obtenir votre répertoire de travail, vous devez descendre quelques sous-arborescences du dépôt. Si vous descendez /trunk/write du dépôt, vous obtenez une répertoire de travail comme celui là :

     write/Makefile
           document.c
           search.c
           .svn/

Ce répertoire de travail est une copie du répertoire /trunk/write du dépôt, avec une entrée supplémentaire --- .svn --- qui contient les informations nécessaires à Subversion comme mentionné plus haut.

Supposons que vous modifiez search.c. Comme le répertoire .svn conserve la date de dernière modification du fichier et son contenu d'origine, Subversion peut déterniminer que vous avez modifier le fichier.  Cependant, Subversion ne rend pas vos modifications publiques, tant que vous ne lui avez pas demandé explicitement.

Pour publier vos modifications, vous pouvez utiliser la commande commit de Subversion:

     $ pwd
     /home/jimb/write
     $ ls -a
     .svn/    Makefile   document.c    search.c
     $ svn commit search.c
     $

Maintenant que vos modifications de search.c sont remontées au dépôt; si un autre utilisateur descend une copie de travail de /trunk/write, il vera votre texte.

Supposont que vous avez un collaborateur, Felix, qui a descendu un répertoire de travail de /trunk/write en même temps que vous. Lorsque vos avez remonté vos modification de search.c, la copie de travail de Félix est restée inchangée; Subversion ne modifie un répertoire de travail qu'à la demande de l'utilisateur.

[Note du traducteur] ``check out'' a été traduit par ``descendre'' ce qui est satisfesant. ``commit'' a été pris dans le sens ``check in'' et traduit par ``remonter''.  Ceci est moins satisfesant. ``commit'' est plustôt le sens ``soumettre une requête de modification''. Cette requête peut aboutir ou non.  Par exemple, ``your changes have been committed to the repository'' peut se traduire par ``vos modifications ont été acceptéss et appliquées au dépôt''.  Je l'ai réduit à ``vos modifications ont été remontées au dépôt''.  Heureusement, l'expression ``check in'' est souvent utilisée à la place de ``commit''. Malheureusement, le terme ``remonté'' s'applique très mal aux parties techniques.

Pour mettre à jour son répertoire de travail, Felix peut utiliser la commande update de Subversion. Celà incorporera vos modifications dans son répertoire de travail, ainsi que tout ce qui a été remonté jusqu'à sa demande de mise à jour:

     $ pwd
     /home/felix/write
     $ ls -a
     .svn/    Makefile    document.c    search.c
     $ svn update
     U search.c
     $

Le sortie de la commande de svn update indique que Subversion à mise à jour le contenu de search.c. Notons que Felix n'a pas besoin de spécifier quels fichiers doivent être mise à jour; Subversion utilise les informations dans le répertoire .svn ainsi que des informations dans le dépôt pour déterminer quels fichiers doivent d'être mise à jour.

Nous expliquerons plus loin ce qui se passe lorsque vous et Felix avez fait des modifications au même fichier.

Transactions et numéro de révision
..................................

Une opération commit (remontée) de Subversion peut publier des modifications de plusieurs fichiers et répertoires dans une unique et atomique transaction. Dans votre répertoire de travail, vous pouvez modifier le contenu des fichiers, créer, supprimer, renommer, copier des fichiers et des répertoires, puis remonter l'ensemble complet des modifications comme un tout.

Dans le dépôt, chaque remontée est traitée comme une transaction atomique: soit tous les modifications remontées sont prise en compte, soit aucunes d'elles n'est prise en compte. Subversion essaie de maintenir cette atomicité même en cas de plantage de programme, de crash système, de problèmes de réseau, et d'autres actions de l'utilisateur. Nous appèlerons une ``remontée'' une transaction quand nous voudrons appuier cette aspect d'indivisibilité.

Chaque fois que le dépôt accepte une transaction, ceci crée un nouvel état de l'arborescence, appelé une révision. A chaque résivion est assigné un unique nombre entier, plus grand de un que le numéro de la révision précedante. La numéro de révision initiale après la création d'un dépôt est zéro, et le dépôt est un répertoire racine vide.

Contrairement à beaucoup d'autres systèmes, les numéros de révision de Subversion s'applique à une arborescence complète et non individuellement à chaque fichier. Chaque numéro de révision correspond à une arborescence entière.

Il est important de noter que les répertoires de travail ne correspondent pas toujours à un unique numéro de révision du dépôt; ils peuvent contenir des fichiers de plusieurs différentes révisions. Par exemple, supposons que vous avez descendu un répertoire de travail du dépôt dont la plus récente révision est 4:

     write/Makefile:4
           document.c:4
           search.c:4

A ce moment, le répertoire de travail correspond exactement à la révision 4 du dépôt. Cependant, supposons que vous faites une modification à search.c, et remontez cette modification. En considérant qu'il n'y a pas eu d'autre remontée, votre remontée a créé la révision 5 sur le dépôt, et votre répertoire de travail ressemble maintenant à çà :

     write/Makefile:4
           document.c:4
           search.c:5

Supposons que maintenant Felix remonte une modification au fichier document.c, créant ainsi la révision 6. Si vous utilisez svn update pour mettre à jour votre répertoire de travail, alors il doit ressembler à ceci :

     write/Makefile:6
           document.c:6
           search.c:6

Les modifications de Felix à document.c apparaissent dans le fichier de votre copie de travail, le contenu de Makefile est identique dans les révisions 4, 5 et 6, mais Subversion marquera votre copie de travail avec la révision 6 pour indiquer qu'il correspond aussi à la révision 6 de l'arborescence du dépôt. Donc, après avoir fait une mise à jour de votre répertoire de travail depuis sa racine, votre répertoire de travail correspondra exactement à une révision du dépôt.

Etat du répertoire de travail par rapport au dépôt
..................................................

Pour chaque fichier du répertoire de travail, Subversion enregistre deux informations essentielles.

  * Quelle révision de quel fichier du dépôt votre copie de travail est basée dessus (on dit aussi la révision de travail du fichier, et

  * un enregistrement de la date de la dernière mise à jour de la copie locale par le dépôt.

En founissant ces informations lors d'échange avec le dépôt, Subversion peut dire dans lequel des quatres états suivants est le fichier :

  * Inchangé et actuel. Le fichier est inchangé dans le répertoire de travail et aucune modification sur ce fichier n'a été remontée au dépôt depuis çà révision de base.

  * Localement modifié et actuel. Le fichier a été modifié dans le répertoire de travail et aucune modification sur ce fichier n'a été remontée au dépôt depuis sa révision de base. Il y a des modifications locales qui n'ont pas été remontées au dépôt.

  * Inchangé et dépassé. Le fichier n'a pas été modifier dans le répertoire de travail, mais il a été modifié dans le dépôt. Le fichier doit éventuellement être mise à jour pour le rendre actuel avec la révision publique.

  * Localement modifié et dépassé. Le fichier a été modifié dans le répertoire de travail et dans le dépôt. Le fichier doit être mise à jour; Subversion tentera de fusionner les modifications publiques avec les modifications locales. S'il ne peut faire la fusion automatiquement de façon convaincante, Subversion laisse à l'utilisateur la tâche de résoudre les conflits.

La commande status de subversion montre l'état de tout les éléments dans votre copie de travail. See Cycle de Travail Classique, en particulier la sous-section ``Examiner vos modifications''.

Subversion ne verrouille pas les fichiers
.........................................

Subversion ne prévient pas de la modification en même temps du même fichier par deux (ou plus) utilisateurs. Par exemple, si vous et Felix avez descendu une copie de travail de /trunk/write, Subversion vous autorise tous les deux à modifier write/search.c dans vos répertoires de travail.  Ensuite, la séquence suivante d'évènements a lieu:

  * Supposons que Félix essaie de remonter ses modifications de search.c en premier. Sa remontée réussie et son texte apparait dans la dernière révision du dépôt.

  * Lorsque que vous essayer de remonter vos modifications de search.c, Subversion refuse votre remontée et vous dit que vous devez mettre à jour search.c avant de le remonter.

  * Lorsque vous mettez à jour search.c, Subversion essaie de fusionner les modifications de Felix présentent dans le dépôt avec vos modifications locales. Par défaut, Subversion fait la fusion comme s'il appliquait un patch: si vos modifications locales ne recouvrent pas textuellement celles de Felix, alors tout va pour le mieux; sinon, Subversion vous laisse la tâche de résoudre les recouvrements de modifications.  Quoiqu'il en soit, Subversion préserve soigneusement une copie de l'original.

  * Une fois que vous avez vérifié que les modifications de Felix et vos modifications peuvent-être fusionnées correctement, vous pouvez remonter une nouvelle révision de search.c qui maintenant contient les modifications de tout le monde.

Certains systèmes de contrôle de version fournissent des ``verrouillage'', qui préviennent contre la modification d'un fichier si une personne travail déjà avec. Selon notre expérience, fusionner est préférable au verrouillage :

  * Les modifications ne sont généralement pas en conflit, donc le comportement de Subversion est le bon par défaut, alors que le verrouillage peut empécher un travail légitime.

  * Le verrouillage peut prévenir des conflits pour un fichier, mais non de conflits entre fichiers (par exemple, entre un fichier d'entête C et d'autres fichiers qui l'inclut), donc celà ne resoud pas réellement le problème; et finalement,

  * les gens oublient souvent qu'ils ont des verrouillages en cours, ceci pouvant devenir une cause de délais inutiles et de frictions.

Bien sûr, le processus de fusion doit être sous le contrôle de l'utilisateur.  Les patchs orienté texte, line par line, ne sont pas appropriés pour des fichiers au format strict, comme les images ou les exécutables. Subversion tente de vous avertir lorsque le fichier est dans un format binaire ou est d'un type mime différent de ``text/*''.  Pour ces fichiers au format strict, Subversion vous demandera lequel des deux contenus originaux prendre (le contenu du dépôt ou celui de votre copie de travail).  Voir Cycle de Travail Classique, et plus particuliairement la sous-section ``Fusionner les modifications des autres''.

Utilisation de Subversion
-------------------------

La section précédente vous a donné les grandes lignes du développement avec Subversion. Nous avons maintenant les connaissances nécessaires pour ``jouer'' avec Subversion avec des exemples que vous pouvez directement appliquer.

Créer un Dépôt
..............

Le client Subversion à l'interface abstraite pour accéder à un dépôt. Deux implémentations d' ``accès de dépôt'' (``Repository Access'' (RA) ) existe actuellement comme librairie. Vous pouvez voir quelle méthode est disponible sur votre client Subversion :

     $ svn --version
     svn, version 0.16.0
        compiled Jan  3 2003, 16:43:58

     Copyright (C) 2000-2004 CollabNet.
     Subversion is open source software, see http://subversion.tigris.org/

     The following repository access (RA) modules are available:

     * ra_dav : Module for accessing a repository via WebDAV (DeltaV) protocol.
          - handles 'http' schema
     * ra_local : Module for accessing a repository on local disk.
          - handles 'file' schema

Si vous ne voyer pas ra_local, celà signifie probablement que ``Berkeley DB'' (ou qu'un moteur de base donnée approprié) n'a pas été trouvé lors de la compilation de votre client. Pour utiliser les exemples qui suivent, l'accès de dépôt ra_local doit être disponible.

Commençons par créer un nouveau dépôt vide en utilisant l'outil svnadmin:

     $ svnadmin create myrepos

Considérons que vous avez un répertoire someproject qui contient les fichiers que vous voulez placer sous un contrôleur de version.

     someproject/foo
                 bar
                 baz/
                 baz/gloo
                 baz/bloo

Une fois que le dépôt, vous pouvez dans un premier temps y importer vos données en utilisant la méthode d'accès ra_local (invoqué en utilisant une URL ``file:'') et la commande import du client Subversion.

     $ svn import file:///usr/local/svn/repos1 someproject myproj
     ...
     Committed revision 1.

L'exemple ci-dessus crée un nouveau répertoire myproj à la racine du système de fichier du dépôt et y copie tous le contenu de someproject .

Créer quelques copies de travail
................................

Maintenant sortons une ``copie de travail'' de votre projet. Pour se faire, nous spécifions une URL vers le répertoire du dépôt que nous voulons. Le paramètre après l'URL nous permet de spécifier le nom du répertoire de la copie de travail.

     $ svn co file:///usr/local/svn/repos1/myproj wc
     A  wc/foo
     A  wc/bar
     A  wc/baz
     A  wc/baz/gloo
     A  wc/baz/bloo

Maintenant nous avons une copie de travail dans un répertoire local nommé wc et qui représente l'emplacement /myproj du dépôt (en supposant que la racine du dépôt est file:///usr/local/svn/repos.)

Pour le plaisir de l'exemple, dupliquons la copie de travail et faisons comme si cette copie appartenait à quelqu'un d'autre:

     $ cp -R wc wc2

A present, faisons quelques modifications à notre copie de travail originale:

     $ cd wc
     $ echo "new text" >> bar       # modification du contenu de bar
     $ svn propset color green foo  # Ajout d'une propriété à foo
     $ svn rm baz                   # programmons le répertoire baz à la suppression
     $ touch newfile
     $ svn add newfile              # programmons l'ajout de newfile

Celà nous fait beucoup de modifications ! Si vous nous quittez et êtes de retour le lendemain, comment pouvons nous connaitre les modifications déjà faites ? Simple. la commande status nous montre tout des ``modifications locales'' de notre copie de travail.

     $ svn status                   # Montre ce qui est localement modifié
     M   ./bar
     _M  ./foo
     A   ./newfile
     D   ./baz
     D   ./baz/gloo
     D   ./baz/bloo

D'après la sortie de svn status, trois éléments sont programmés (ou marqués) pour être supprimés ((D)elete) du dépôt, un élément est programmé pour être (A)jouté au dépôt et deux éléments ont leurs contenus (M)odifié. Pour plus de détail, relisez ce qui conserne svn status au chapitre 2.

Maintenant nous décidons de remonter nos changements, créant ainsi la révision 2 dans le dépôt.

     $ svn commit -m "fixed bug #233"
     Sending    bar
     Sending    foo
     Adding     newfile
     Deleting   baz
     Transmitting data...
     Committed revision 2.

L'argument -m est un moyen de spécifier une description des modifications: c'est une description spécifique de notre ensemble de modifications envoyé au dépôt. La description des modifications est maintenant liée à la révision 2.  Un futur utilisateur pourra lire les descriptions des modifications du dépôt et comprendre ce que font les modifications de la révision 2.

Finalement, Supposons que vous êtes maintenant Felix, ou un autre collaborateur.  Si vous allez à wc2, l'autre copie de travail que vous avez créé, ce repétoire de travail a besoin d'une commande svn update pour recevoir les modifications de la révision 2 :

        $ cd ../wc2    # Changement vers la sauvegarde de la copie de travail
        $ svn update   # récupération de modification du dépôt
        U   ./bar
        _U  ./foo
        A   ./newfile
        D   ./baz

La sortie de la commande svn update indique à Felix que baz a été supprimé ((D)eleted) de sa copie de travail, que newfile a été (A)jouté à sa copie de travail, et que bar et foo ont eu leur contenu mise à jour ((U)pdated).

Si pour diverses raisons bar a des modifications locales faites par Felix, alors les modifications du server (le dépôt) doivent être fusionnées dans bar: C'est-à-dire que bar doit maintenant avoir toutes les modifications. Quand les modifications du serveur sont fusionnées dans le fichier local modifié, deux scénarios sont possibles :

  * La fusion se passe confortablement. C'est-à-dire que les deux ensembles de modifications ne se recouvrent pas. Dans ce cas, svn update affiche un G (``mer(G)ed'').

  * les ensembles de modifications se recouvrent et un C pour (C)onflit est affiché. Voir la section ??? pour des informations sur comment réaliser une résolution de conflit.