root/alternc-doc/trunk/admin/svn.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->

<chapter id="admin.svn">
<title>Subversion, utilisation côté développeur</title>

<para>
Subversion, aussi appellé SVN, est un logiciel permettant de travailler à plusieurs sur des sources communs.
</para>
<para>
Il permet de transférer un ensemble de fichiers depuis un serveur, d'y effectuer des modifications localement, puis de valider ces modifications. SVN gère les conflits si 2 personnes modifient le même fichier, il permet aussi de retrouver chaque modification faites sur les sources dans le temps, sous forme de fichier "diff" (lignes ajoutées, modifiées et supprimées sur chaque fichier) et permet de revenir sur l'une d'elle pour corriger d'éventuelles erreurs.
</para>
<para>
SVN est un descendant du logiciel CVS, autre système, plus ancien, de gestion de sources en commun. Il existe d'autres systèmes comme DARCS ou ARCH/TLA qui effectuent le même genre de tâche : la gestion concurrente de sources et le partage de documents en commun.
</para>




<sect1><title>Concepts de base de subversion</title>

<para>
Lorsque l'on utilise subversion sur son ordinateur, on travaille sur son ordinateur localement, sur une copie des sources. Les sources sont situés sur un serveur subversion, dans ce que l'on appelle un dépôt. Un administrateur de dépot vous fournit généralement l'adresse du dépot. Cette adresse, appellée URL, peut prendre plusieurs formes comme suit : 
<example><title>Exemple d'url de dépot SVN</title>
<para>
<screen>svn://svn.example.com/monprojet/trunk
svn+ssh://svn.debian.org/var/lib/svn/debian-edu/trunk
http://corp.mycompany.com:8080/svn/internal/
https://dev.alternc.org/svn/alternc/alternc/trunk
</screen>
Ce ne sont, bien sur, que des exemples. Subversion supportant de nombreux protocoles de transfert d'information, il est possible que d'autres forme d'url existent. 
</para>
</example>
Si votre administrateur de dépôt vous a fourni un nom d'utilisateur et un mot de passe, il se peut que vous ayez besoin d'ajouter le nom d'utilisateur à cette url. Il se place dans ce cas juste après le <code>://</code> et avant le nom de domaine. On fait suivre le nom d'utilisateur d'un <code>@</code>, à la manière des emails. L'url devient alors : 
<screen>svn+ssh://john@svn.debian.org/var/lib/svn/debian-edu/trunk/</screen>
</para>

<note><title>A propos des commandes de ce chapitre</title>
<para>
Dans la suite de ce manuel, nous présenterons des commandes de subversion. Ces commandes sont accessibles via l'outil en ligne de commande <command>svn</command> ou via un menu permettant de lancer cette commande, selon le logiciel que vous utilisez. Les exemples de commandes de cette documentation seront données sous forme de commande pour le logiciel SVN en console, à vous de trouver l'équivalent dans votre logiciel, les termes utilisés étant généralement les mêmes.
</para>
</note>

<sect2><title>Récupérer les fichiers sources dans leur état actuel</title>
<para>
 La première commande subversion à connaître est celle permettant d'obtenir une copie locale (sur votre machine) des sources distants (fichiers situés dans le dépôt distant). Pour cela, on utilise la commande <command>checkout</command>, parfois abbréviée <command>co</command>. On l'utilise comme suit : <command>svn checkout &lt;url du dépôt&gt;</command>
Par exemple : 
</para>
<example><title>Exemples d'obtention d'une copie d'un dépôt</title>
<para>
<screen>
$ svn checkout svn://svn.example.com/monprojet/trunk
$ svn co svn+ssh://philippe@svn.debian.org/var/lib/svn/debian-edu/trunk
</screen>
</para>
</example>

<para>
La commande svn peut vous demander un mot de passe si vous utilisez un compte disposant de droits étendus. Dans ce cas, saisissez votre mot de passe lorsque le système vous le demande.
</para>
<para>
Vous devez voir alors la liste des fichiers téléchargés sur votre machine au fur et à mesure de leur arrivée, comme suit : 
<screen>
$ svn checkout svn://svn.debian.org/svn/debian-edu/trunk
A  trunk/html
A  trunk/html/logs
A  trunk/html/logs/cd-build.log
A  trunk/html/logs/overview.log
A  trunk/html/logs/securitylist.html
A  trunk/html/logs/buglist.html
A  trunk/html/logs/README
A  trunk/html/index.html
A  trunk/security
A  trunk/security/README
A  trunk/src
 ...
</screen>
</para>
<para>
 Une fois téléchargés, vous disposez des fichiers dans un nouveau dossier local, et vous pouvez les lire, les modifier localement, bref, faire ce que vous voulez dessus. Vous noterez dans chaque dossier de ces sources la présence d'un dossier <code>.svn</code>, généralement caché. Ce dossier permet à Subversion de s'y retrouver et de savoir quels fichiers ou dossier vous avez modifié. 
</para>
</sect2>

<sect2><title>Mettre à jour son dépôt local</title>
<para>
Quelques temps après avoir utilisé checkout pour aller récupérer les sources, l'on peut souhaiter mettre à jour cette copie locale, pour y récupérer les modifications effectuées par les autres développeurs. Pour cela, on utilise tout simplement la commande <command>update</command>. Pour lancer cette commande, il faut bien évidemment être situé dans la copie locale. En voici un exemple : 
</para>
<example><title>Exemple de mise à jour d'une copie locale</title>
<para>
<screen>
trunk$ svn update 
U  trunk/html/logs/overview.log
U  trunk/html/logs/buglist.html
M  trunk/html/logs/README
 ...
</screen>
Vous remarquerez le détail des informations fournies par svn : les lignes avec U montrent les fichiers mis à jour, celles avec M montrent les fichiers que vous avez modifié (M) et qui n'ont donc pas été mis à jour si besoin.
</para>
</example>
</sect2>

<sect2><title>Valider ses modifications sur le dépôt</title>
<para>
  Si vous effectuez des modifications dans les fichiers de votre copie locale, vous devez ensuite valider ses modifications en renvoyant les fichiers ainsi modifiés sur le serveur, au dépôt. Subversion suivant les modifications en détail, il est nécessaire d'accompagner cet envoi d'un petit commentaire expliquant de quoi il s'agit. 
</para>
<para>
  Pour envoyer les modifications sur le dépôt, on utilise la commande <command>svn commit</command> qui regarde la liste des fichiers modifiés et les renvois au dépôt. Cette commande lance votre éditeur pour vous demander de remplir le commentaire associé à vos modifications. On peut l'accompagner de la liste des fichiers à modifier, si l'on souhaite ne valider que certains d'entre eux. 
</para>
</sect2>

<sect2><title>Ajouter ou supprimer des fichiers au dépôt</title>
<para>
  Lorsque l'on crée de nouveaux fichiers ou dossiers dans les sources, il faut signaler à subversion que ces fichiers doivent être ajoutés au dépôt. Pour cela, on utilise la commande <command>svn add</command>. On précise derrière cette commande la liste des fichiers ou dossiers à ajouter au dépôt.
</para>
</sect2>

</sect1>




<sect1><title>Utilisation de SVN sur votre système d'exploitation</title>

<para>
Ce chapitre présente l'utilisation de SVN sur les systèmes d'exploitation suivants : Windows (98SE, 2000, XP) et Linux (en console et sous environnement Kde ou Gnome). Il propose l'installation de logiciels de gestions de sources utilisant le protocole SVN et explique les paramètres de base.
</para>


<sect2><title>Installation de SVN sous Windows</title>
<para>
Sous Windows, vous pouvez utiliser le logiciel tortoiseSvn disposnible sur le site <ulink url=""></ulink>. Il s'agit d'une extension à l'explorateur windows qui permet d'accéder facilement aux fichiers d'un dépôt subversion, et de gérer les fichiers correspondants. Les icônes des fichiers reflettent leur état dans le svn (à jour, modifié, non présent dans le dépôt ...)
<graphic fileref="images/tortoise_svn_1.jpg" format="JPG"></graphic>
</para>
</sect2>

<sect2><title>Installation de SVN sous Linux</title>
<para>
Sous Linux, vous pouvez utiliser de nombreux logiciels pour vous connecter à un serveur Subversion. Le plus classique est SVN lui-même. Il existe cependant 2 clients habituels qui sont esvn et rapidsvn. 
</para>
<sect3><title>Svn en ligne de commande</title>
<para>
Sous Debian GNU/Linux, on installe subversion avec la commande <command>apt-get install subversion</command>. Sous mandrake, on utilise <command>urpmi subversion</command>. Si vous utilisez une autre distribution, utilisez la méthode d'installation habituelle d'un logiciel pour installer subversion.
</para><para>
Une fois installé, on ne dispose que de la ligne de commande de svn, qui s'exprime sous la forme suivante : <command>svn &lt;commande&gt; &lt;parametres&gt;</command>
</para><para>
Les commandes classiques de svn se retrouvent donc directement depuis la ligne de commande. En voici quelques exemples : 
</para>
<example><title>Exemple de commande SVN</title>
<para>
Pour aller chercher la version actuelle des sources d'un dépot distant, nous utilisons, par exemple : 
<screen>svn checkout svn://svn.example.com/monprojet/trunk</screen>
Pour ajouter un fichier nouvellement inséré dans les sources, nous appelons : 
<screen>svn add monimage.gif monsource.php</screen>
Pour supprimer un fichier des sources, on utilise : 
<screen>svn remove vieuxtruc.php</screen>
Pour valider ses modifications dans les sources, on tape : 
<screen>svn commit</screen>
Le logiciel nous demande alors le commentaire associé à ce jeu de modifications. On peut aussi préciser les fichiers que l'on veut valider, si l'on ne veut pas valider toutes ses modifications d'un seul coup.
Enfin, si l'on veut mettre à jour sa copie locale, on utilisera : 
<screen>svn update</screen>
</para>
</example>
<para>
SVN en ligne de commande est donc un outil relativement simple pour gérer directement sa copie locale depuis une console Linux.
</para>
</sect3>



<sect3><title>Esvn, client graphique sous KDE</title>
<para>
Si vous utilisez KDE, vous pouvez installer esvn, un client subversion graphique, pour gérer votre dépôt local. Sous Debian GNU/Linux, on installe esvn avec la commande <command>apt-get install esvn</command>. Sous Mandrake, on utilise <command>urpmi esvn</command>. Si vous utilisez une autre distribution, utilisez la méthode d'installation habituelle d'un logiciel pour installer esvn.
</para><para>
Une fois installé et lancé, vous tombez sur la fenêtre ci-dessous. Cliquez sur <command>file</command> puis <command>checkout</command> pour aller récupérer une copie locale des fichier du dépôt distant.
  <graphic fileref="images/esvn_1.jpg" format="JPG"></graphic>
</para><para>
Les commandes classiques de subversion se retrouvent ensuite dans les menus de ce logiciel : 
  <graphic fileref="images/esvn_2.jpg" format="JPG"></graphic>
  <graphic fileref="images/esvn_3.jpg" format="JPG"></graphic>
  <graphic fileref="images/esvn_4.jpg" format="JPG"></graphic>
</para>
</sect3>


<sect3><title>Rapidsvn, client graphique sous Gnome</title>
<para>
Si vous utilisez Gnome, vous pouvez installer rapidsvn, un client subversion graphique, pour gérer votre dépôt local. Sous Debian GNU/Linux, on installe esvn avec la commande <command>apt-get install rapidsvn</command>. Sous Mandrake, on utilise <command>urpmi rapidsvn</command>. Si vous utilisez une autre distribution, utilisez la méthode d'installation habituelle d'un logiciel pour installer esvn.
</para><para>
Une fois installé et lancé, vous tombez sur la fenêtre ci-dessous. Cliquez sur <command>repository</command> puis <command>checkout</command> pour aller récupérer une copie locale des fichier du dépôt distant.
  <graphic fileref="images/rapidsvn_1.jpg" format="JPG"></graphic>
Remplissez ensuite les paramètres demandés et cliquez sur OK pour aller récupérer les fichiers source.
  <graphic fileref="images/rapidsvn_2.jpg" format="JPG"></graphic>
</para><para>
Les commandes classiques de subversion se retrouvent ensuite dans les menus de ce logiciel : 
  <graphic fileref="images/rapidsvn_3.jpg" format="JPG"></graphic>
  <graphic fileref="images/rapidsvn_4.jpg" format="JPG"></graphic>
</para>
</sect3>

</sect2>
</sect1>

</chapter>