Utilisation des clients
***********************

Comment bien utiliser votre client Subversion en 11 étapes.

Ce chapitre décrit plus en détail les commandes client. Pour une vue d'ensemble du mode de développement ``copier-modifier-fusionner'' avec un clients de type CVS, see Concepts.

Avant de commencer à lire, retenez que votre principale source d'information lorsque vous utilisez svn est : svn help. Le client en ligne de commande de Subversion est lui-même documenté et à tout moment svn help<sous-commande> décrira la syntaxe, les drapeaux, et le comportement de sous-commande.

Ce chapitre ne couvre nullement chaques options de chaques commandes secondaire des clients. Au lieu de cela, c'est une introduction, une conversation autour des tâches les plus communes que vous rencontrerez. Dans le doute, recourez à l'aide fournie par svn help.

descente
========

La plupart du temps, vous commencerez l'utilisation d'un dépôt Subversion en réalisant une descente de votre projet. l'opération de ``descendre'' vous fournit une copie de la tête (dernière révision) du dépôt Subversion que vous descendez.

     $ svn co http://svn.collab.net/repos/svn/trunk
     A  trunk/subversion.dsw
     A  trunk/svn_check.dsp
     A  trunk/COMMITTERS
     A  trunk/configure.in
     A  trunk/IDEAS
     ...
     Checked out revision 2499.

Bien que l'exemple descend le répertoire trunk, vous pouvez de la même manière descendre n'importe quel sous-répertoire du dépôt en spécifiant le sous-répertoire dans URL à descendre.

     $ svn co http://svn.collab.net/repos/svn/trunk/doc/handbook
     A  handbook/svn-handbook.texi
     A  handbook/getting_started.texi
     A  handbook/outline.txt
     A  handbook/license.texi
     A  handbook/repos_admin.texi
     A  handbook/client.texi
     Checked out revision 2499.

Puisque Subversion utilise le model ``copier-modifier-fusionner'' au-lieu de ``verrouiller-modifier-déverrouiller'',  vous êtes imédiatement prêt pour modifier les fichiers que vous venez de descendre. Ensemble des fichiers descendu est votre copie de travail. Vous pouvez aussi supprimer toute votre copie de travail sans conséquence (sauf si vous étiez sur le point de remonter des modifications, un nouveau fichier voir un répertoire). La suppression d'une copie de travail ne nécessite pas d'en informer le serveur Subversion.

Tout les répertoire de la copie de travail ont un espace d'administration, un sous-répertoire nommé .svn. La ls ne montre pas par défaut ce répertoire.  Quoique vous fassiez, ne supprimez et ne changez rien dans cet espace d'administration ! Pour gérer votre copie de travail, Subversion en a besoin.

Vous pouves exécuter svn help checkout pour connaitre les options de la ligne de commande permettant la descente: vous pouvez spécifier un répertoire après l'url de votre dépôt. Ceci mettra votre copie de travail dans le répertoire spécifié. Par exemple:

     $ svn co http://svn.collab.net/repos/svn/trunk subv
     A  subv/subversion.dsw
     A  subv/svn_check.dsp
     A  subv/COMMITTERS
     A  subv/configure.in
     A  subv/IDEAS
     ...
     Checked out revision 2499.

Cycle de Travail Classique
==========================

Subversion a de nombreuses fonctions et options, mais dans une utilisation quotidien classique vous en utiliserez qu'un nombre limité d'elles. Dans cette section nous présentons les opérations les plus classiques qui sont rencontrées lorsque vous travaillez avec Subversion.

Le cycle typique d'utilisation de Subversion ressemble à ceci :

  * Mise à jour de votre copie de travail

  * Faire des modifications

  * Examiner vos modifications

  * Fusionner les modifications des autres

  * Remonter vos modifications

Mise à jour de votre copie de travail (svn update)
--------------------------------------------------

En travaillant en équipe sur un projet, vous allez mettre à jour votre copie de travail: c'est-à-dire, récupérer les modifications des autres développeurs dans votre copie de travail. svn update provoque la synchronisation de votre copie de travail avec la dernière révision du dépôt.

     $ svn update
     U  ./foo.c
     U  ./bar.c
     Updated to revision 2.

Dans cet exemple, une autre personne a remonté des modifications de foo.c et bar.c depuis la dernière fois que vous avez mise à jour, Subversion à mise à jour vour copie de travail pour inclure ces modifications.

Examinons la sortie de svn update un peu plus. Lorsque le serveur envoie des modifications à votre copie de travail, un code est affiché a côté de chaque élément:

U  foo
     Le fichier foo a été mise à jour ((U)pdated) (modifications reçues du serveur) dans votre copie de travail.

A  foo
     Le fichier ou répertoire foo a été (A)jouté à votre copie de travail.

D  foo
     Le fichier ou réportoire foo a été supprimé ((D)eleted) de votre copie de travail.

R  foo
     Le fichier ou répertoire foo a été (R)emplacé dans votre copie de travail; c'est-à-dire, foo a été supprimé, et un nouvelle élément avec le même mot a été ajouté. Bien qu'il est le même nom, le dépôt les considère comme des objects distincts avec des historiques distincts.

G  foo
     Le fichier foo a reçu de nouvelles modifications du dépôt, mais il a aussi des modifications réalisées par vous-même. Les modifications n'intéragissent pas entre elles cependant, donc Subversion a pu fusionner (mer(G)ed) les modifications du dépôts dans le fichier sans problème.

C  foo
     Le fichier a reçu des modifications conflictuelles du serveur. les modifications du server recouvre vous propres modifications du fichier. Inutile de paniquer cependant. Ce recouvrement doit est résolu par un humain (peut-être vous); nous aborderons cette situation plus loin.

Faire des modifications (svn add, svn rm, svn cp, svn mv)
---------------------------------------------------------

Maintenant vous pouvez travailler et réaliser quelques modifications dans votre copie de travail.

Nous vérons quel type de modification vous pouvez faire dans à votre copie de travai.

Modification de fichier
     c'est le type de changement le plus simple. Contrairement à d'autre système de contrôle de version, nous n'avez pas besoin de dire à Subversion que vous avez l'intention de modifier un fichier; faites le. Plus tard, Subversion est capable de détecter automatiquement quel fichier a été modifié.

Modification d'arborescence
     Vous pouvez demander à Subversion de ``marquer'' des fichiers et des répertoire pour la suppresion ou d'addition dans le dépôt. Evidament, aucun ajout ou suppresion n'est réalisé dans le dépôt sans une remontée explite de votre part.

Pour faire des modifications de fichiers, utilisez votre éditeur de texte, votre traitement de texte, ou n'importe quelle méthode. Un fichier ne doit pas nécessairement être au format texte; les fichiers binaires sont également parfaitement pris en charge.

Il y a au moins quatre sous-commandes Subversion pour faire des modifications de l'arborescence. Une aide détaillée peut être abtenue avec svn help. Néanmoins, voici un résumé:

svn add foo
     Programme l'ajout de foo dans le dépôt. Lors de votre prochaine remontée, foo deviendra un fils permanent de son répertoire parent. Notons que si foo est un répertoire, seul le répertoire sera programmé pour l'ajout. Si vous voulez ajouter son contenu également, ajouté le drapeau --recursive.

svn rm foo
     Programme la suppression de foo dans le dépôt. foo est un fichier, Subversion le fait disparaitre de la copie de travail -- mais il peut être restauré avec svn revert (voir plus loin).  Si foo est un répertoire, il est simplement programmé pour la suppression. Après votre remontée, foo n'existera plus dans la copie de travai ni dans le dépôt.

svn cp foo bar
     Crée un nouvelle élément bar qui est un double de foo. bar est automatique programmé pour l'addition. Lors de l'ajout de bar au dépôt à la prochaine remontée, c'est une copie-historique qui est enregistré (enregistre que le contenu initiale de bar vient de foo).

svn mv foo bar
     C'est commande est équivalente à svn cp foo bar; svn rm foo. C'est-à-dire, bar est programmé pour l'addition en tant que copie de foo, et foo est programmé pour la suppresion.

Nous venons de voir des exemples de modifications de votre copie de travail. Néanmoins, il y a des cas d'utilisation qui modifient directement le dépôt. Ceci arrive généralement lorsqu'une sous-commande opère directement sur une URL, au-lieu d'un chemin de votre copie de travail. (En particulier, des utilisations spécifiques de svn mkdir, svn cp, svn mv et svn rm peuvent fonctionner avec des URLs.  Regarder ce que vous retourne svn help sur ces commandes pour plus de détails.)

Examinez vos modifications (svn status, svn diff, svn revert)
-------------------------------------------------------------

Donc maintenant que vous avez fini vos modification... vous vous dites: Quelle sont les modifications que j'ai fait ? Comment les consulter?

Subversion a été optimisé pour vous aider dans cette tâche, et il est capable de faire plein de choses sans accéder au dépôt ou utiliser le réseau. Votre copie de travail possède une copie de référence caché de chaque fichier et répertoire dans l'espace .svn. Cette copie de référence correspond au dernier état connu du dépôt. Grâce à çà, Subversion peut rapidement vous montrer les modifications faites sur votre copie de travail, ou eventuellement vous permettre d'annuler vos modification dans le répertoire de copie.

La commande svn staus est votre ami; devenez intime avec elle. Vous utiliserez svn status probablement plus que n'importe quelle autre commande.

Si vous exécutez la commande svn status à la racine de votre copie de travail sans arguments, elle donnera toutes les modifications de fichiers et d'arborescence que vous avez fait. Cet exemple est fait pour montrer tous les différents codes d'état que svn status peut retourner. Les texte à l'intérieur de [] n'est pas imprimé par svn status.

     $ svn status
     _ L    ./abc.c               [svn a un verrou dans son répertoire .svn pour abc.c]
     M      ./bar.c               [Le contenu de bar.c a des modifications locales]
     _M     ./baz.c               [baz.c a uniquement des modifications de propriété]
     ?      ./foo.o               [svn ne gère pas foo.o]
     !      ./foo.c               [svn gère foo.c mais un autre programme l'a supprimé]
     A  +   ./moved_dir           [ajout avec l'historique de là où il vient]
     M  +   ./moved_dir/README    [ajout avec historique et a des modifications locales]
     D      ./stuff/fish.c        [le fichier est programmé pour la suppression]
     A      ./stuff/things/bloo.h [le fichier est programmé pour l'ajout]

Le format de sortie de svn status affiche quatre colonnes de caractères suivi par plusieurs espaces suivi par le nom du fichier ou du répertoire. La première colonne donne l'état du fichier ou répertoire et/ou de son contenu. Les code utilisé sont

_      fichier_ou_répertoire
     Le fichier ou répertoire n'a pas été ajouté ou supprimé. Si fichier_ou_répertoire est un fichier, son contenu n'a pas été modifié.

A      fichier_ou_répertoire
     Le fichier ou répertoire fichier_ou_répertoire a été programmé pour être ajouté au dépôt.

M      fichier
     Le contenu du fichier fichier a été modifié.

D      fichier_ou_répertoire
     Le fichier ou répertoire fichier_ou_répertoire a été programmé pour être supprimé du dépôt.

?      fichier_ou_répertoire
     Le fichier ou répertoire fichier_ou_répertoire, n'est pas pris en compte par le système de contrôle de révision. Vos pouvez supprimer l'affichage des fichiers marqués d'un point d'intérogation en ajoutant l'option --quiet (-q), ou en utilisant la propriété svn:ignore sur répertoire parent,  see Propriétés.

!      fichier_ou_répertoire
     Le fichier ou répertoire fichier_ou_répertoire est sous le contrôle de révision mais il est manquant dans la copie de travail. Ceci peut arriver si le fichier ou le répertoire est supprimé en utilisant une commande non-Subversion. Pour restaurer le fichier ou répertoire manquant, vous pouvez utiliser svn update (récupération depuis le dépôt) ou svn revert fichier_ou_répertoire (récupération avec la copie de référence caché dans .svn).

La seconde colonne donne l'état des propriétés du fichier ou du répertoire, see Propriétés. Si un M apparait dans la seconde colonne, alors les propriétés ont été modifiées, sinon un espace est affiché. Si uniquement les propriétés du fichier ou du répertoire sont modifiées, alors il y a _M d'affiché pour la première et seconde colonnes. Le premier _ est affiché pour montrer clairement que les propriétés sont modifiées mais pas le contenu.

La troisième colonne affiche uniquement un espace ou un L qui signifie que svn a verrouillé l'élément dans l'espace .svn de la copie de travail. Vous verrez un L si vous exécuté svn status dans un répertoire où svn commit est en cours d'attente de l'édition de la description des modifications. S'il n'y a pas d'exécution en cours de commande svn alors il est probable qu'un commande svn se soit arrêté de force et le verrou ainsi laissé doit être levé en exécutant svn cleanup. Les verroux apparaissent typiquement lorsqu'une commande Subversion a été interrompue avant qu'elle soit totalement réalisée.

La quatrième colonne vous montrera un espace ou un + qui signifie que le fichier ou répertoire est programmé pour être ajouté ou modifié, avec un historique joint supplémentaire. Ceci arrive typiquement lorsque vous utilisez svn cp ou svn mv sur un fichier ou un répertoire. Si vous voyez A   +, ceci signifie que l'élément est programmé pour être ajouté avec un historique joint. L'élément peut-être un fichier ou la racine d'une arborescence copiée.  _   + signifie qu'un élément fait parti d'une arborescence programmée pour ajout avec historique.  C'est-à-dire que l'élément accompagne un de ses répertoires parents qui est programmé pour la copie. M   + signifie que le fichier fait parti d'une arborescence programmée pour ajout avec historique, et qu'il a des modifications locales. Lorsque vous remonterez les modifications, en premier le père est ajouté avec historique (copié), ce qui signifie que ce fichier existera automatiquement dans cette copie. Les modifications locales du fichier seront appliquées à cette copie juste après.

Par défaut, svn status ignore les fichiers qui correspondent aux aux motifs *.o, *.lo, *.la, #*#, *.rej, *~ et .#*. Si vous voulez ajouter d'autre motifs à cette liste par défaut, edité la propriété svn:ignore du répertoire parent. Si vous voulez voir l'état de tous les fichiers en ignorant les motifs par défaut de svn status et ceux de svn:ignore, utilisez l'option de la ligne de commande --no-ignore.

Si un chemin est donné à la commande, les informations fournies seront limités à ce chemin.

     $ svn status stuff/fish.c
     D      stuff/fish.c

Cette commande a aussi un mode verbeux, --verbose (-v), qui montrera l'état de tous les éléments dans votre copie de travail:

     $ svn status -v
     M               44        23    joe       ./README
     _               44        30    frank     ./INSTALL
     M               44        20    frank     ./bar.c
     _               44        18    joe       ./stuff
     _               44        35    mary      ./stuff/trout.c
     D               44        19    frank     ./stuff/fish.c
     _               44        21    mary      ./stuff/things
     A                0         ?     ?        ./stuff/things/bloo.h
     _               44        36    joe       ./stuff/things/gloo.c

Ceci est la ``forme long'' de l'affichage de svn status.  La premier colonne est inchangée. La seconde colonne fournie le numéro de révision de la copie de travail de l'élément. La troisième et quatrième colonne montre la révision de dernière modification de l'élément et qui l'a modifié.

Enfin, il y a le drapeau --show-update (-u), qui contact le dépôt et ajoute des informations sur ce qui est dépassé:

     $ svn status -u -v
     M      *        44        23    joe       ./README
     M               44        20    frank     ./bar.c
     _      *        44        35    mary      ./stuff/trout.c
     D               44        19    frank     ./stuff/fish.c
     A                0         ?     ?        ./stuff/things/bloo.h

Remarquer les deux astérisques: si vous lancez svn up maintenant, vous recevrez des modifications pour README et trout.c. Soyez prudent. Vous devez absorber ces modifications du serveur pour README avant de le remonter au risque de voir votre remontée refusée car votre fichier est dépassé (plus d'information sur ce sujet plus bas).

L'autre façon d'examiner les modification est d'utiliser la commande svn diff. Vous pouvez voir exactement toutes les modifications faites avec la commande svn diff sans arguments, qui affiche les modifications de fichier dans le format ``unified diff''.

     $ svn diff
     Index: ./bar.c
     ===================================================================
     --- ./bar.c
     +++ ./bar.c	Mon Jul 15 17:58:18 2002
     @ -1,7 +1,12 @
     +#include <sys/types.h>
     +#include <sys/stat.h>
     +#include <unistd.h>
     +
     +#include <stdio.h>

      int main(void) {
     -  printf("Sixty-four slices of American Cheese...\n");
     +  printf("Sixty-five slices of American Cheese...\n");
        return 0;
      }

     Index: ./README
     ===================================================================
     --- ./README
     +++ ./README	Mon Jul 15 17:58:18 2002
     @ -193,3 +193,4 @
     +Note to self:  pick up laundry.

     Index: ./stuff/fish.c
     ===================================================================
     --- ./stuff/fish.c
     +++ ./stuff/fish.c  Mon Jul 15 17:58:18 2002
     -Welcome to the file known as 'fish'.
     -Information on fish will be here soon.

     Index: ./stuff/things/bloo.h
     ===================================================================
     --- ./stuff/things/bloo.h
     +++ ./stuff/things/bloo.h  Mon Jul 15 17:58:18 2002
     +Here is a new file to describe
     +things about bloo.

la commande svn diff génère ce résultat en comparant votre copie de travail avec la référence dans .svn. Les fichier programmés pour l'ajout sont affichés avec tout leur contenu en ajout, les fichiers pour la suppression sont affiché avec tout leur contenu en suppression.

Maintenant supposons que vous voyez cette affichage et réalisez que vos modifications à README sont érronées; peut-être avez-vous éditer le mauvais fichier.

La commande svn revert répond à ce type de problème. Elle supprime tous les modifications.

     $ svn revert README
     Reverted ./README

Le fichier est ramener a son état avant modification en l'écrasant avec la copie de référence de .svn. Remarquer aussi que svn revert peut annuler toutes opérations programmées -- Dans le cas où vous décidez que vous ne voulez pas ajouter un nouveau fichier, ou que vous ne voulez pas supprimer un fichier.

Dernier point, ces trois commandes (svn status, svn diff, svn revert) peuvent être utilisées sans accès réseau (sauf svn status -u).  Ceci facilite la gestion de vos modifications en cour lorsque vous voyagez en avion...

Fusionner les modifications des autres (résolution de conflit)
--------------------------------------------------------------

Vous avez vu comment la commande svn status -u peut vous aider a déterminer les risques de conflit. Supposons que vous lancez svn update et quelque chose d'intéressant se produit:

     $ svn up
     U  ./INSTALL
     G  ./README
     C  ./bar.c

Le codes U et G ne nous intéressent pas ici; ces fichiers ont proprement intégrés les changements du dépôt.

Le C signifie que nous somme en présence d'un conflit. Les conflits ont lieu lorsque les modifications du dépôt recouvrent les votres. Ce problème doit être résolu manuellement.

Lorsqu'un conflit arrive:

  * Un C est affiché durant la mise à jour et Subversion mémorise que le fichier est en ``conflit''.

  * Trois fichiers dont le nom débute par tmp sont créés; ces fichiers sont les originaux des fichiers qui ne peuvent pas être fusionnés ensemble.

  * Des marqueurs de conflit sont placés dans les fichier pour repérer les zones de recouvrement.

Dans cette situation, Subversion ne vous permet pas de remonter le fichier tant que les trois fichiers temporaire n'on pas été supprimés.

Si vous obtenez un conflit, vous devez soit (1) faire la fusion manuellement des textes en conflits (en examinant et en éditant les marqueurs de conflit dans le fichier), (2) copier un des fichiers tmp* en haut de votre fichier de travail, ou (3) exécuter svn revert pour perdre tous vos modifications.

Une fois que vous avez résolu les conflits, vous devez en informer Subversion en supprimant les trois fichiers tmp*.  La commande svn resolve est un racourçi qui ne fait rien sinon supprimer les trois fichiers tmp* pour vous. Lorsque les fichiers tmp* sont supprimés Subversion ne considère plus le fichier en état de conflit.

Remonter vos modifications
--------------------------

Enfin! vos éditions sont finies, vous avez fusionné tous les mise à jour du serveur et vous êtes prêt à remonter vos modifications.

La commande svn commit envoie tous de vos modifications au dépôt. Lorsque vous remontez une modification, vous devez fournir une description des modifications. Votre description restera attachée à la nouvelle révision que vous avez créé.

     $ svn commit -m "Added include lines and corrected # of cheese slices."
     Sending        bar.c
     Transmitting file data .
     Committed revision 3.
     $

Une autre façon de spécifier une description des modifications est de les mettre dans un fichier et de fournir le nom du fichier avec l'option -F. Si la description des modifications n'a pu être fournie avec les options -m ou -F, alors Subversion lancera automatiquement l'éditeur spécifié par la variable d'environnement $EDITOR pour que vous composiez la description des modifications.

Le dêpot ne s'occupe pas de savoir si vos modifications sont cohérentes ou non. Il vérifie uniquement que personne d'autre n'a changé aucun des fichiers que vous remontez depuis la dernière fois que vous les avez sortie (svn co) ou mise à jour (svn update). Si quelqu'un l'a fait, toute la remontée achoue avec un message indiquant que un ou plusieurs de vos fichiers sont dépassés. Il vous faut lancer svn upade, traiter tous les fusions ou conflits qu'il en résulte et recommencer votre remontée.

Nous avons couvert les commandes les plus fondamentales pour travailler avec Subversion. Vous pouvez exécuter svn help <nom de la commande> pour avoir une aide sur toute les commandes présentées dans cette section.

Historique
==========

Le dépôt trace toutes les remontées et vous permet d'explorer cet historique.

Il y a deux commandes qui extraient les informations relatives à l'historique de votre depôt. svn log vous montre des informations globales de l'historique: les descriptions de modification attachées à chaque révision et quels fichiers/répertoires ont changé pour chaque révision. La commande svn diff est elle plus ``précise''.  Elle vous montre les modifications apportées à un fichier dans le temps.

svn log
-------

Pour avoir des imformations de l'historique d'un fichier ou d'un répertoire, vous utilisez la commande svn log. svn log vous dira qui a modifié le fichier, à quel révision, l'heure et la date de la révision et la description des modifications qui a accompagné la remontée.

     $ svn log
     ------------------------------------------------------------------------
     rev 3:  fitz | Mon, 15 Jul 2002 18:03:46 -0500 | 1 line

     Added include lines and corrected # of cheese slices.
     ------------------------------------------------------------------------
     rev 2:  someguy | Mon, 15 Jul 2002 17:47:57 -0500 | 1 line

     Added main() methods.
     ------------------------------------------------------------------------
     rev 1:  fitz | Mon, 15 Jul 2002 17:40:08 -0500 | 2 lines

     Initial import
     ------------------------------------------------------------------------

Remarquez que les descriptions des modifications sont affichées dans l'ordre chronologique inversé. Si vous désirez voir une plage différente de révision dans un ordre particulier, ou voir une seule révision utilisé l'option --revision (-r).

     $ svn log -r 5:19
     ... # Montre les descriptions de modification de 5 à 19 dans l'ordre
             # chronologique.
     $ svn log -r 19:5
     ... # Montre les descriptions de modification de 5 à 19 dans l'ordre
             # inversé.
     $ svn log -r 8
     ...

Vous pouvez aussi examiner l'historique des descriptions de modification pour un unique fichier ou répertoire en spécifiant le chemin:

     $ svn log foo.c
     ...
     $ svn log http://foo.com/svn/trunk/code/foo.c
     ...

les commandes affichent les descriptions de modification uniquement pour les révisions où le fichier/répertoire (ou l'URL) a changé.

La commande svn log a l'option --verbose (-v) aussi. Avec cette option, la liste des fichiers/répertoires modifiés est également incluse pour chaque révision:

     $ svn log -r 8 -v
     ------------------------------------------------------------------------
     rev 8:  jrandom | 2002-07-14 08:15:29 -0500 | 1 line
     Changed paths:
        U /trunk/code/foo.c
        U /trunk/code/bar.h
        A /trunk/code/doc/README

     Frozzled the sub-space winch.

     ------------------------------------------------------------------------

svn diff
--------

Nous avons déjà vu la commande svn diff dans la section précédante. Elle affiche les différences d'un fichier dans le format ``unified diff''. Il y a peu, nous l'avons utilisé pour montrer les modifications locales réalisées à notre copie de travail.

En fait, il y a trois utilisations distinctes de la commande svn diff:

Examiner les modifications locales
..................................

Exécuter svn diff sans option compare vos fichiers de travail avec les versions de référence cachées dans espace .svn.

     $ svn diff foo
     Index: ./foo
     ===================================================================
     --- ./foo
     +++ ./foo	Tue Jul 16 15:19:53 2002
     @ -1 +1,2 @
      An early version of the file
     +...extra edits

Comparaison de la copie de travail avec le dépôt
................................................

Si option --revision(-r), suivi d'un numéros de révision, est passé, alors votre copie de travail est comparée à une révision particuliaire du dépôt.

     $ svn diff -r 3 foo
     Index: ./foo
     ===================================================================
     --- ./foo
     +++ ./foo	Tue Jul 16 15:19:53 2002
     @ -1,2 +1,2 @
      An early version of the file
     -Second version of the file
     +...extra edits

Comparaison dépôt à dépôt
.........................

Si deux numéros de révision sont passés à -r, alors les deux révisions (du dépôt) sont directement comparées.

     $ svn diff -r 2:3 foo

     Index: ./foo
     ===================================================================
     --- ./foo
     +++ tmp.280.00001	Tue Jul 16 15:22:19 2002
     @ -1 +1,2 @
      An early version of the file
     +Second version of the file

Si vous lisez l'aide incluse dans svn (svn help diff), vous découvrirez que vous pouvez également fournir une URL au-lieu de votre copie de travail. C'est particuliairement appréciable pour inspecter des modifications alors que vous n'avez pas de copie de travail disponible:

     $ svn diff -r 23:24 http://foo.com/some/project
     ...

Branche et Etiquetage
=====================

Branchement avec svn cp
-----------------------

Les branches et les étiquettess sont des concepts généraux commnun à la plupart des systèmes de contrôle de révision. Si vous n'êtes pas familier avec ces concepts, vous trouverez un bonne introduction d'explication dans le livre libre de CVS de Karl Fogel : http://cvsbook.red-bean.com/cvsbook.html#Branching_Basics

Ici, vous devez avoir compris comment chaques remontées crées une nouvelle et complète arborescence dans le dépôt. Si ce n'est pas le cas, lisez ce qui est relavitif aux révisions, see Transactions et numéro de révision, ou see Les numéros de révision sont différents maintenant.

Comme vous le suspectez, le système de fichier (du dépôt) ne grossit pas de 652 nouveaux fichier/répertoire à chaque fois qu'une nouvelle révision est crée. Au-lieu de çà, chaque nouvelle arborescence est faite principalement de pointeurs sur des fichiers/répertoires déjà existant. Un nouveaux noeud est créé uniquement lorqu'un élément est modifié, tout le reste de la révision utilise un espace de stockage partagé avec d'autres révisions d'arborescence. Cette technique montre que le système de fichier du dépôt est capable de faire des copies ``bon marchées'' (en espace disque). Ces copies bon marchées ne sont rien d'autre qu'un entrée de répertoire pointant sur un fichier existant (un peu comme le fait la commande ln sous Unix). Ce principe est la base de l'étiquetage et des branchements.

Branchement avec svn cp
-----------------------

Supposons que nous avons un dépôt dont la révision de tête (la plus récente) est 82. Dans ce dépôt il y a un sous-répertoire mooIRC qui contient un projet de logiciel prêt à être étiqueté. Comment allons nous l'étiqueter? Très simple: nous faisons une copie bon marchée de ce répertoire. En d'autres mots, nous créons un nouveau répertoire (quelque part ailleur dans le système de fichier) qui pointe sur ce noeud spécifique  qui représente le répertoire mooIRC à la révision 82. Bien sûr, vous pouvez nommer ce nouveau répertoire comme bon vous semble (probablement quelque chose comme mooIRC-beta).

La façon la plus simple de faire cette copie est avec la commande svn cp qui peut également opérer uniquement sur des URL.  Ainsi cette copie peut avoir lieu uniquement côté serveur:

     $ svn cp http://foo.com/repos/mooIRC \
              http://foo.com/repos/mooIRC-beta
     Committed revision 83.

Maintenant, aussi longtemps que vous ne modifié pas le contenu de ce répertoire mooIRC-beta, cette entrée pointera toujours sur le noeud qui représente mooIRC au moment de la création de mooIRC-beta (c'est à dire la révision 82). Ceci est un étiquetage.

Mais supposons mooIRC-beta ne soit pas sacré, et qu'ainsi, vous décidé d'y faire des modifications. Et supposons que vous continuez également à faire des modifications dans l'original mooIRC répertoire. Ainsi, vous avez deux répertoires au début identique -- leurs ancêtre commun est mooIRC dans la révision 82 -- mais qui maintenant divergent dans le temps par leur contenu. En d'autres mots, ils representent différentes branches de votre projet.

Il est très important de remarquer que le système de fichier de Subversion n'a aucune ``conscience'' des ``étiquetages'' ou ``branches''.  Il ne considère que les répertoires et tous les répertoires sont égaux. Le concept d'étiquetage et de branche attaché à un répertoire particulier n'ont qu'un sens humain.

C'est pour cette raison qu'il est de la responsabilité de l'utilisateur (et de l'administrateur du dépôt Subversion) de choisir de bonnes rêgles de nommage pour distinguer les branches, étiquetages... Par exemple, voici une bonne organisation possible de votre dépôt:

        /
        /projectA
        /projectA/trunk/
        /projectA/branches/
        /projectA/tags/
        /projectB
        /projectB/trunk/
        /projectB/branches/
        /projectB/tags/

Chaque fois que /projectA/trunk atteind un état étiquetable, faites une copie du répertoire quelque part dans /projectA/tags/ et mettez la copie en lecture seule. Utiliser la même procédure pour créer une branche dans /projectA/branches.

Voici une autre bonne organisation possible:

        /
        /trunk
        /trunk/projectA
        /trunk/projectB
        /branches
        /branches/projectA
        /branches/projectB
        /tags
        /tags/projectA
        /tags/projectB

Ou, bien sûr, vous pouvez également mettre chaque projet dans un dépôt dédié. Ceci est de votre responsabilité. D'autres informations ici: see FAQ.

Basculer vers une branche avec svn switch
-----------------------------------------

La commande svn switch vous permet de ``déplacer'' certaine partie ou tout votre copie de travail vers une branche ou une étiquette. Par exemple, supposons que j'ai une copie de travail de mooIRC, et que je veux travailler sur un sous-système tel qu'il apparait dans un sous-répertoire de mooIRC-beta. En même temps, je veux que le reste de ma copie de travail reste sur sa branche d'origine mooIRC.  Pour le faire, je bascule le sous-répertoire approprié vers le point de la nouvelle branche.

     $ svn switch http://foo.com/repos/mooIRC-beta/subsystems/renderer \
                  mooIRC/subsystems/renderer

     U  mooIRC/subsystems/renderer/foo.c
     U  mooIRC/subsystems/renderer/bar.h
     U  mooIRC/subsystems/renderer/baz.c

Maintenant mon sous-répertoire renderer de ma copie de travail représente un répertoire différent sur le serveur.

En fait, svn swith est une version plus ``rigolote'' de svn update.  Alors que svn update a la possibilité de déplacer votre copie de travail dans le temps (en mettant à jour à la dernière révision, ou en allant à la révision spécifiée avec l'option -r), svn switch est capable de déplacer votre copie de travail dans le temps et l'espace.

Si votre copie de travail à plusieurs aborescences de différents lieux de dépôt, tout continue de fonctionner comme d'habitude. Lorsque vous faites une mise à jour, vous recevrez, comme prévu, les patches apropriés a chaques arborescences. Lorsque vous ferez une remontée, vos modifications locales restent appliquées avec une unique et atomique modification au dépôt.

Déplacer des modifications avec svn merge
-----------------------------------------

Supposons qu'une équipe de programmeur travaillant sur la branche mooIRC-beta a corrigé un bug critique, et que l'équipe travaillant sur la branche mooIRC originale veut appliquer ces modifications également.

La commande svn merge répond à cette situation. Vous pouvez penser à svn merge comme un cas spécial de svn diff; simplement, au-lieu d'affiche un ``unified diff'' à l'écran, il applique les modifications à votre copie de travail. Ces nouvelles modifications sont locales à votre copie de travail.

Par exemple, supposons que la correction du bug soit arrivé à la remontée de la révision 102 de la branche mooIRC-beto.

     $ svn diff -r 101:102 http://foo.com/repos/mooIRC-beta

     ...   # diffs sent to screen

     $ svn merge -r 101:102 http://foo.com/repos/mooIRC-beta mooIRC
     U   mooIRC/glorb.c
     U   mooIRC/src/floo.h

Alors que l'affichage de svn merge est similaire à svn update ou svn switch, La commande n'applique que des modifications temporaires à vos fichiers de travail. Une fois que les différences sont appliquées comme des modifications locales, vous pouvez les examiner comme d'habitude avec svn diff, svn status, ou les annuler comme d'habitude avec svn revert. Si les changement sont acceptable, vous pouvez les remonter.

Revenir en arrière avec svn merge
---------------------------------

Une autre utilisation courante de svn merge est pour revenir en arrière sur une modification qui a été remontée. C'est-à-dire que vous avez remonté des modifications dans la révision 10, et que plus tard vous décidez qui y a une erreur. Vous pouvez facilement ramener l'arborescence à l'état de la révision 9 avec la commande svn merge.

     $ svn commit -m "change some stuff"
     Sending        bar.c
     Sending        foo.c
     Transmitting file data ..
     Committed revision 10.
     $

     ... # le développeur continu et réalise qu'il y a une erreur

     $ svn merge -r 10:9 .
     U ./bar.c
     U ./foo.c
     $ svn commit -m "oops, reverting revision 10"
     Sending        bar.c
     Sending        foo.c
     Transmitting file data ..
     Committed revision 11.

Si vous n'êtes pas revenu en arrière sur les modifications dans votre répertoire courant (C'est-à-dire que vous voulez revenir en arrière pour un fichier spécifique, ou tous les fichiers d'un répertoire spécifique), alors la syntaxe est légèrement différente, parce que vous devez dire à svn merge où il doit fusionner les modifications.

     $ svn merge -r 10:9 baz/ baz/
     U ./baz/bar.c
     U ./baz/foo.c
     $ svn commit -m "reverting revision 10's changes in baz/"
     Sending        baz/bar.c
     Sending        baz/foo.c
     Transmitting file data ..
     Committed revision 12.
     $

     ... # le développeur continu et réalise qu'il y a une erreur

     $ svn merge -r 13:12 baz/foo.c baz/foo.c
     U ./baz/foo.c
     $ svn commit -m "reverting revision 12's change to foo.c"
     Sending        baz/foo.c
     Transmitting file data .
     Committed revision 15.

Conservez à l'esprit que revenir en arrière sur des modifications avec cette méthode est comme toutes les autres opérations avec svn merge, ainsi vous devriez utiliser svn status et svn diff pour confirmer que votre travail est dans l'état que vous voulez qu'il soit, et puis utiliser svn commit pour envoyer la version finale au dépôt.

Branches vendeur
----------------

Parfois, vous voulez géner/modifier, dans votre dépôt, des codes source modifiés par une tierce partie tout en suivant les modifications apporté par la tierce partie.  Dans CVS, ceci peut s'appeler une ``branche vendeur''.  Subversion n'a pas formellement de ``branche vendeur'', mais il est suffisament flexible pour vous permettre de faire pratiquement la même chose.

La procédure générale se déroule comme ceci. Vous créé un répertoire pour conserver la branche vendeur. Ici nous utiliserons /vendor. Puis vous importez le code de la tierce partie dans un sous-répertoire de /vendor, et enfin copiez ce sous-répertoire dans /trunk où vous faites vos modifications locales. A chaques sorties d'une nouvelle version par la tierce partie que vous voulez tracer, vous l'importez dans la branche vendeur puis fusionnez les modification dans /trunk, et resolvez si nécessaire les conflits entre vos modifications les celles de la branche vendeur.

Faisons un essai et rendons çà un peu plus claire avec un exemple.

Premièrement, l'importation initiale.

     $ svn mkdir http://svnhost/repos/vendor/foobar
     $ svn import http://svnhost/repos/vendor/foobar ~/foobar-1.0 current

Maintenant, nous avons la version courante du projet foobar dans /vendor/foobar/current. Nous en faisons une autre copie, ainsi nous pourrons toujours nous référer à cette version, puis nous la copions dans la branche trunk (la branche de développement) afin de pouvoir travailler dessus.

     $ svn copy http://svnhost/repos/vendor/foobar/current    \
                http://svnhost/repos/vendor/foobar/foobar-1.0 \
                -m `étiquetage de foobar-1.0'
     $ svn copy http://svnhost/repos/vendor/foobar/foobar-1.0 \
                http://svnhost/repos/trunk/foobar             \
                -m `copie de foobar-1.0 dans trunk'

Maintenant nous n'avons qu'à sortie une copie de /trunk/foobar pour commencer à travailler!

Plus tard, les développeurs de l'entreprise FooBar Widgets sortent une nouvelle version de leurs codes, et vous voulez mettre à jour la version du code que vous utilisez. Premièrement, vous sortez le répertoire /vendor/foobar/current, puis copiez la nouvelle version dans cette copie de travail. Gérez les renommages, les ajouts et les suppressions manuellement puis faite la remontée.

     $ svn co http://svnhost/repos/vendor/foobar/current ~/current
     $ cd ~/foobar-1.1
     $ tar -cf - . | (cd ~/current ; tar -xf -)
     $ cd ~/current
     $ mv foobar.c main.c
     $ svn mv main.c foobar.c
     $ svn rm dead.c
     $ svn add doc
     $ svn add doc/*
     $ svn commit -m `importation de foobar 1.1 dans la branche vendeur'

Diantre, que c'est compliqué. N'ayez crainte, la plupart des cas sont nettement plus simple.

Que c'est-il passé? foobar 1.0 a un fichier nommé main.c. Ce fichier a été renommé en foobar.c dans la version 1.1. Ainsi, votre copie de travail a le vieux main.c, que svn connait, et le nouveau foobar.c dont svn n'a pas connaissance. Nous renommons foobar.c en main.c et utilisant svn mv pour lui redonner son nouveau nom. Ainsi, svn sait que foobar.c est un descendant de main.c. dead.c a été supprimé dans 1.1, et finalement, ils ont écrit de la documantation que nous ajoutons.

Puis nous copions /vendor/foobar/current vers /vendor/foobar/foobar-1.1 ainsi vous pourrez toujours vous référer à la version 1.1 en utilisant ce nom.

     $ svn copy http://svnhost/repos/vendor/foobar/current    \
                http://svnhost/repos/vendor/foobar/foobar-1.1 \
                -m `étiquetage de foobar-1.1'

Maintenant que vous avez une copie de référence de foobar 1.1 dans /vendor, vous n'avez plus qu'à fusionner leurs changements dans /trunk et tout est fini. Cette opération peut-être faite comme çà :

     $ svn co http://svnhost/repos/trunk/foobar ~/foobar
     $ cd ~/foobar
     $ svn merge http://svnhost/repos/vendor/foobar/foobar-1.0 \
                 http://svnhost/repos/vendor/foobar/foobar-1.1
     $
     ... # résoudre tous les conflits entre leurs modifications et vos
             # modification.
     $ svn commit -m `merging foobar 1.1 into trunk'

Voilà qui est fait. Vous avez maintenant une copie de foobar 1.1 avec toutes vos modifications fusionnées dans votre arborescence.

Les branches vendeurs qui ont beaucoup d'ajouts, suppressions et déplacements peuvent utiliser le script svn_load_dirs.pl fourni avec Subversion. Ce script automatise les étapes d'importations précédentes et minimise les erreurs. Vous devez néanmoins toujours utiliser la commande svn merge pour fusionner la nouvelle version de foobar dans votre copie locale contenant vos modifications locales.

Ce script prend en compte les cas où Subversion requière une remontée pour pouvoir renommer à la fois un fichier et un répertoire, comme dans le cas ou vous avez une branche vendeur qui renomme foobar-1.1/docs/doc.ps en foobar-1.2/documents/doc-1.2.ps. Ici, nous devons renommer docs en documents, faire une remontée, puis renommer doc.ps en doc-1.2.ps. Vous ne pouvez pas faire les deux renommages sans la remontée car doc.ps a déjà été renommé une fois de docs/doc.ps en documents/doc.ps.

Ce script compare toujours le répertoire en cours d'importation avec ce qu'il y a actuellement dans le dépôt Subversion et réalise les ajouts, suppressions et renommages de fichiers et répertoires nécessaires pour que le dépôt Subversion corresponde au répertoire importé. De cette manière, il peut être utilisé avec un répertoire Subversion vide côté dépôt lors du premier import mais aussi pour tous les imports suivant pour mettre à jour la branche vendeur.

Pour le premier import de foobar-1.0 situé dans ~/foobar-1.0:

     $ svn_load_dirs.pl -t foobar-1.0                      \
                        http://svnhost/repos/vendor/foobar \
                        current                            \
                        ~/foobar-1.0

svn_load_dirs.pl prend trois arguments au moins. Le premier argument, http://svnhost/repos/vendor/foobar, est l'URL servant de base pour les opérations de svn_load_dirs.pl. Dans ce cas, nous travaillerons dans la partie vendor/foobar du dépôt Subversion. L'argument suivant, current, est relatif au premier et est le répertoire où l'importation courante sera faite. Dans ce cas c'est http://svnhost/repos/vendor/foobar/current. Le dernier argument, ~/foobar-1.0, est le répertoire à importer. Enfin, l'argument de l'option -t est également relatif à http://svnhost/repos/vendor/foobar et dit à svn_load_dirs.pl de créer l'étiquette http://svnhost/repos/vendor/foobar/foobar-1.0 pour le répertoire importé.

L'importation de foobar-1.1 peut-être réalisée de la même façon:

     $ svn_load_dirs.pl -t foobar-1.1                      \
                        http://svnhost/repos/vendor/foobar \
                        current                            \
                        ~/foobar-1.1

Le script examine le répertoire courant http://svnhost/repos/vendor/foobar/current et détermine quelles modifications doivent lui être appliquées pour qu'il corresponde à ~/foobar-1.1. Le script est suffisament attentif pour remarquer qu'il y a des fichiers ou répertoires qui existent dans 1.0 et non dans 1.1, et demandera si vous voulez réaliser des changements de nom. A ce moment, vous pouvez indiquer que main.c a été renommé en foobar.c puis indiquer qu'il n'y a plus de renommage à réaliser.

Le script supprime alors dead.c, ajoute doc et doc/* au dépôt Subversion, et finalement crée l'étiquette foobar-1.1 dans http://svnhost/repos/vendor/foobar/foobar-1.1.

Suppression de branche ou d'étiquette avec svn rm
-------------------------------------------------

La commande svn rm peut opérer sur des URL. Un fichier ou un répertoire peut-être supprimé du dépôt à ``distance'' sans la présence d'une copie de travail:

     $ svn rm http://foo.com/repos/tags/mooIRC-bad-tag -m "deleting bad tag"
     Committed revision 1023.

Bien sûr, c'est une forme de remontée immédiate, ainsi une description des modifications est requise (-m).

Propriétés
==========

Subversion vous permet d'attacher n'importe quelle ``Méta-donnée'' à un fichier ou un répertoire. Nous appèlerons ces données des propriétés et elles peuvent être vues comme un ensemble de paire nom/valeur attaché à chaque élément dans votre copie de travail.

Pour mettre ou récupérer une propriété d'un fichier ou d'un répertoire, utilisez les commandes svn propset et svn propget. Pour lister tous les propriétés d'un élément, utilisez svn proplist.  Pour supprimer une propriété, utilisez svn propdel.

     $ svn propset color green foo.c
     property `color' set on 'foo.c'

     $ svn propget color foo.c
     green

     $ svn propset height "5 feet" foo.c
     property `height' set on 'foo.c'

     $ svn proplist foo.c
     Properties on 'foo.c':
       height
       color

     $ svn proplist foo.c --verbose
     Properties on 'foo.c':
       height : 5 feet
       color : green

     $ svn propdel color foo.c
     property `color' deleted from 'foo.c'

Les propriétés sont versionnées comme l'est le contenu des fichiers.  Ceci signifie que de nouvelles propriétés peuvent être fusionnées dans vos fichiers de travail, et peuvent parfois être en conflit également.  La valeur des propriétés n'est pas obligatoirement du texte cependant.  Par example, vous pouvez attacher une valeur de propriété binaire en utilisant l'option -F:

     $ svn propset x-face -F joeface.jpg foo.c
     property `x-face' set on 'foo.c'

Subversion founit également une méthode confortable pour éditer des propriétés existantes: svn propedit. Lorsque vous exécutez cette commande, Subversion ouvre la valeur de la propriété en question dans votre éditeur favori (en fait, l'éditeur que vous avez défini avec $EDITOR dans votre interpréteur de commande) et vous pouvez éditer la valeur comme n'importe quel fichier texte. Ceci est particuliairement agréable pour des propriétés qui sont un tableau de valeurs séparés par des retour-chariot (voir plus bas).

Les modifications de propriétés restent considérées comme des ``modifications locales'' et ne sont pas permanentes tant que vous ne les avez pas remontées. Comme les modifications de texte, les modifications de propriétés peuvent être vuess avec svn diff, svn status et également annulées avec svn revert:

     $ svn diff
     Property changes on: foo.c
     ___________________________________________________________________
     Name: color
        + green

     $ svn status
     _M   foo.c

Remarquez qu'une seconde colonne est apparue dans l'affichage de svn status; le souligné initial indique que vous n'avez pas modifié le contenu du fichier, mais le M signifie que vous avez modifié les propriétés. svn status essaie de cacher la seconde colonne des propriétés lorsqu'un élément n'a pas de propriété du tout. C'est un choix de conception, pour faciliter les nouveaux utilisateurs à ce concept. Lorsque des propriétés sont créées, éditées ou mise à jour sur un élément, cette seconde colonne apparait toujours après.

Enfin, ne soyez pas inquiet de la façon non-standard dont Subversion affiche actuellement les différences de propriété. Vous pouvez continuer a utiliser svn diff et rediriger sa sortie pour créer un fichier patche utilisable. Le programme patch ignorera les patches de propriété; il a la règle d'ignorer tout ce qu'il ne comprend pas. Cependant, dans une future version de Subversion, nous commencerons à utiliser un nouveau format de patche qui décrit les modifications de propriété et les copies/renommages de fichiers.

Propriétés spéciales
--------------------

Subversion n'a pas de règles particulières à l'égard des propriétés. Elles peuvent être utilisées à n'importe quel propos. La seule restriction est que Subversion s'est réservé les noms avec le préfixe svn: pour son propre usage. Un certain nombre de propriétés ``magique'' commence avec ce préfixe. Nous traitons de leures caractéristiques ici.

svn:executable
..............

C'est une propriété pour les fichiers uniquement et qui peut être mis à n'importe quelle valeur. Son existance modifier les permissions du fichier pour permettre son exécution.

svn:mime-type
.............

Actuellemnt, Subversion examine la propriété svn:mime-type pour décider si le fichier est de type texte ou binaire. Si le fichier n'a pas de propriété svn:mime-type ou si la valeur de la propriété correspond à text/*, alors Subversion considère que c'est un fichier texte. Si le fichier a la propriété svn:mime-type mise à autre chose que text/*, alors le fichier est considéré comme binaire.

Si Subversion considère que le fichier est binaire, il ne tentera pas de fusionner durant une mise à jour. Au-lieu de çà, Subversion crée deux fichiers dans votre copie de travail (un fichier correspondant au dépôt et un autre à votre copie de travail). Celui avec vos modifications locales est renommé avec l'extension .orig.

Subversion aide l'utilisateur en tentant de détecter la présence d'un fichier binaire lors d'un svn import ou svn add. Si le fichier est considéré comme binaire par ces commandes, elles mettent la propriété svn:mime-type à application/octet-stream au fichier qui vient être ajouté. Si Subversion s'est trompé lors de sa détection, vous pouvez toujours supprimer ou éditer la propriété.

Enfin, si la propriété svn:mime-type est mise, alors mod_dav_svn l'utilisera pour remplire l'entête Content-type: lors d'une réponse à une requête http GET. Ceci rend l'affichage des fichiers plus agréable lors de la consultation d'un dépôt avec un navigateur web.

svn:ignore
..........

Si vous attachez cette propriété à un répertoire, les fichiers avec un certain motif dans leur nom seront ignorés par svn status.  Par exemple, supposons que je ne veux pas voir les fichiers objets ou les fichiers de sauvegarde dans le listing de svn status:

     $ svn status
     M  ./foo.c
     ?  ./foo.o
     ?  ./foo.c~

En utilisant svn propedit, je peux mettre la valeur de svn:ignore à une liste de motifs délimités par des retours-chariot:

     $ svn propget svn:ignore .
     *.o
     *~

svn:keywords
............

Subversion a l'abtitude de substituer certains mots-clé par des chaines de caractère utilent dans les fichiers textes. Par exemple, si je place ce texte dans un fichier:

     Ceci est le dernier rapport de la ligne de front.
     $LastChangedDate$
     Les comulus sont plus nombreux à l'approche de l'été.

Subversion est capable de substituer la chaine $LastChangedDate$ avec l'actuelle date de dernière modification du fichier.  Le mot clé n'est pas supprimé durant la substitution, Il n'y a que l'information spécifique qui est placé après le mot clé qui est substitué.

     Ceci est le dernier rapport de la ligne de front.
     $LastChangedDate: 2002-07-22 21:42:37 -0700 (Mon, 22 Jul 2002) $
     Les comulus sont plus nombreux à l'approche de l'été.

Il y a quatre mots-clé que Subversion sait comment substituer:

LastChangedDate
     La dernier date quand le fichier a été modifié. L'abbréviation Date peut-être utilisée. La substitution du mot clé $LastChangedRevision ressemble à quelque chose comme $LastChangedDate: 2002-07-22 21:42:37 -0700 (Mon, 22 Jul 2002) $.

LastChangedRevision
     La dernière révision quand le fichier a été modifié. L'abbréviation Rev peut-être utilisée.  La substitution du mot clé $LastChangedRev$  ressemble à quelque chose comme $LastChangedRevision: 144 $.

LastChangedBy
     Le dernier utilisateur qui a changé le fichier. L'abbréviation Author peut-être utilisée. La substitution du mot clé $LastChangedBy$ ressemble à quelque chose comme $LastChangedBy: joe $.

HeadURL
     L'URL complète de la dernière version du fichier dans le depôt. L'abbréviation ``URL'' peut-être utilisée. La substitution du mot clé $HeadURL$ ressemble à quelque chose comme $HeadURL: http://svn.collab.net/repos/trunk/README $.

Pour activer un mot-clé ou fixer un mot-clé, vous avez simplement besoin de mettre la propriété svn:keywords à une liste de mot-clé que vous voulez substituer. Les mots clé non listés dans svn:keywords ne seront pas substitués :

     $ svn propset svn:keywords "Date Author" foo.c
     property `svn:keywords' set on 'foo.c'

Lorsque que vous remonterez ces changements de propriété, vous découvrirez que toutes les occurrences de $Date$, $LastChangedDate$, $Author$, et $LastChangedBy$ auront leurs valeurs de substitutions dans foo.c.

svn:eol-style
.............

Par défaut, Subversion ne prête pas attention aux fins de ligne. Si un fichier texte a LF, CR or CRLF pour fins de ligne, alors celles-ci sont les fins de ligne qui existeront dans le fichier pour le dépôt et la copie de travail.

Mais si les développeurs travaillent sur différentes plateformes, les fins de ligne peuvent être la source de nuisances. Par exemple, si un développeur sous win32 et un développeur sous Unix modifient l'un après l'autre le même fichier, les fins de ligne du fichier changent entre les révisions du dépôt. Ceci rend l'examen ou la fusion des différences très difficile, car chaques lignes apparaissent avoir changé pour chaque version du fichier.

La solution ici est de mettre la propriété svn:eol-style à ``native''. Celà permet au fichier d'apparaitre avec les fins de ligne ``native'' dans chaqu'un des systèmes d'exploitation des développeurs. Remarquez, néanmoins, que le fichier est toujours avec des fins de ligne LF dans le dépôt. Ceci prévient les problèmes de fin de ligne ``bidon'' de révision en révision.

Alternativement, vous pouvez forcer un fichier à toujours conserver une convention de fin de ligne spécifique : mettez la propriété svn:eol-style d'un fichier à LF, CR ou CRLF. Un fichier .dsp de win32 par exemple, qui est utilisé par les outils de développement Microsoft, doit toujours avoir des fins de ligne CRLF.

svn:externals
.............

See Modules.

Modules
=======

Parfois il est utile de construire une copie de travail qui est faite de différentes sorties. Par exemple, vous voulez que différents sous-répertoires correspondent à différents endroits du dépôt.

Une méthode possible est de commencer par une sortie d'une copie de travail puis d'exécuter svn switch dans différents sous-répertoires. Mais c'est du boulot. Ne serait-il pas agréable de définir -- en un seul lieu -- exactement comment vous voulez que la copie de travail soit?

Ceci est connu en tant que module. vous pouvez définir un module en attachant une autre propriété ``magique'' à un répertoire: la propriété svn:externals.

     $ svn propget svn:externals projectdir
     subdir1/foo       http://url.for.external.source/foo
     subdir1/bar       http://blah.blah.blah/repositories/theirproj
     subdir1/bar/baz   http://blorg.blorg.blorg/basement/code

En considérant que cette propriété est attachée au répertoire projectdir, alors lorsque vous faite une sortie, vous obtenez aussi ce qui est défini par la propriété.

     $ svn checkout http://foo.com/repos/projectdir
     A  projectdir/blah.c
     A  projectdir/gloo.c
     A  projectdir/trout.h
     Checked out revision 128.

     Fetching external item into projectdir/subdir1/foo
     A  projectdir/subdir1/foo/rho.txt
     A  projectdir/subdir1/foo/pi.txt
     A  projectdir/subdir1/foo/tau.doc
     Checked out revision 128.
     ...

En modifiant la valeur de la propriété de svn:externals, la définition du module peut changer dans le temps et les appels suivants à svn update mettront à jour votre copie de travail de façon approprié.

Révisions
=========

Comme vous l'avez sans doute remarqué, beaucoup de commandes Subversion sont capable de traiter le drapeau -r. Ici nous décrirons quelques méthodes pour spécifier des révisions.

Le client Subversion comprend plusieurs mots clé de révision. Ces mots clé peuvent-être utilisé à la place d'un entier comme argument de l'option -r, et désigne un numéro de révision spécifique.

HEAD
     La dernière révision dans le dépôt.

BASE
     La révision de référence dans .svn d'un élément de la copie de travail.

COMMITTED
     La dernière révision dans laquelle un élément a changé.

PREV
     La révision juste avant la dernière révision où l'élément à changé. (Théorique c'est équivalent à COMMITTED - 1).

Quelques exemples de mots clé de révision en action:

     $ svn diff -r PREV:COMMITTED foo.c
     # montre la dernière modification remontée de foo.c

     $ svn log -r HEAD
     # montre la description de modification de la dernière remontée au dépôt

     $ svn diff -r HEAD
     # compare votre fichier de travail (avec ses modifications locales) à la
     # dernière version dans le dépôt

     $ svn diff -r BASE:HEAD foo.c
     # compares la version de référence de foo.c dans .svn (sans
     # modifications locales) avec la dernière version dans le dépôt

     $ svn log -r BASE:HEAD
     # montre toutes les descriptions de modification depuis la dernière mise à
     # jour

     $ svn update -r PREV foo.c
     # revient en arrière sur les dernières modifications de foo.c remontées au
     # dépôt. (la révision de travail de foo.c est diminuée.)

Autres commandes
================

svn cleanup
-----------

Lorsque Subversion modifie votre copie de travail (ou toutes informations à l'intérieur de .svn), il essaie de la faire de la façon la plus sûre possible. Avant toute modification, il écrit ces intentions dans un un ``logfile'', puis exécute les commandes du ``logfile''. C'est similaire dans la conception à un système de fichier journalisé; si l'utilisateur fait Contrôle-C ou si la machine se plante, le ``logfile'' reste. En réexécutant les ``logfiles'', le travail peut être terminé, et votre copie de travail peut revenir à un état consistant.

Et c'est exactement ce que fait svn cleanup: il recherche dans votre copie de travail des ``logfile'' que sont restés et les réexécute, supprimant ainsi les verrous dans le processus. Utilisez cette commande si Subversion vous dit que certaines parties de votre copie de travail sont ``verrouillées''. Enfin, svn status affichera un L a côté des éléments verrouillés.

     $ svn st
       L    ./somedir
     M      ./somedir/foo.c

     $ svn cleanup
     $ svn st
     M      ./somedir/foo.c

svn info
--------

En général nous essayons de décourager les utilisateurs de lire directement le fichier .svn/entries utilisé pour tracer les éléments. Au lieu de celà, les curiosités peuvent être ``calmées'' en utilisant la command svn info qui affiche la plupart des informations tracées :

     $ svn info client.texi
     Path: client.texi
     Name: client.texi
     Url: http://svn.collab.net/repos/svn/trunk/doc/handbook/client.texi
     Revision: 2548
     Node Kind: file
     Schedule: normal
     Last Changed Author: fitz
     Last Changed Rev: 2545
     Last Changed Date: 2002-07-15 23:03:54 -0500 (Mon, 15 Jul 2002)
     Text Last Updated: 2002-07-16 08:48:04 -0500 (Tue, 16 Jul 2002)
     Properties Last Updated: 2002-07-16 08:48:03 -0500 (Tue, 16 Jul 2002)
     Checksum: 8sfaU+5dqyOgkhuSdyxGrQ==

svn import
----------

La commande import est un moyen rapide de remonter une arborescence de fichiers non versionnée dans un dépôt.

Il y a deux façon d'utiliser cette commande:

     $ svnadmin create /usr/local/svn/newrepos
     $ svn import file:///usr/local/svn/newrepos mytree
     Adding  mytree/foo.c
     Adding  mytree/bar.c
     Adding  mytree/subdir
     Adding  mytree/subdir/quux.h
     Transmitting file data....
     Committed revision 1.

L'exemple précédent place le contenu du répertoire mytree directement à la racine du dépôt:

     /foo.c
     /bar.c
     /subdir
     /subdir/quux.h

Si vous donnez un troisième argument à la commande svn import, il utilisera l'argument comme le nom du nouveau sous-répertoire à créer dans l'URL.

     $ svnadmin create /usr/local/svn/newrepos
     $ svn import file:///usr/local/svn/newrepos mytree fooproject
     Adding  mytree/foo.c
     Adding  mytree/bar.c
     Adding  mytree/subdir
     Adding  mytree/subdir/quux.h
     Transmitting file data....
     Committed revision 1.

Le dépôt doit maintenant ressembler à :

     /fooproject/foo.c
     /fooproject/bar.c
     /fooproject/subdir
     /fooproject/subdir/quux.h

svn export
----------

La commande export est un moyen rapide de créer une arborescence de fichier non versionnée d'un répertoire d'un dépôt.

     $ svn export file:///usr/local/svn/newrepos/fooproject
     A  fooproject/foo.c
     A  fooproject/bar.c
     A  fooproject/subdir
     A  fooproject/subdir/quux.h
     Checked out revision 3.

Le répertoire résultant ne contiendra aucun espace d'administration .svn et toutes les méta-données de propriété sont perdues. (N'utilisez pas cette technique pour faire des backups; elle est probablement meilleur pour faire un paquetage des sources.)

svn ls
------

La commande ls vous permet d'avoir des informations sur des fichiers d'un répertoire du dépôt.

     $ svn ls http://svn.collab.net/repos/svn
     http://svn.collab.net/repos/svn:
     _    2738 bmatzell        0 Jul 26 13:07 clients/
     _    2743   rooneg        0 Jul 26 18:07 trunk/
     _    2703    brane        0 Jul 24 22:07 branches/
     P    2734   kfogel     2331 Jul 26 10:07 COMMITTERS
     _    2698   rooneg        0 Jul 24 18:07 tags/

Les colonnes vous disent si le fichier a des propriétés (``P'' s'il en a, ``_'' s'il n'en a pas), la révision de la dernière mise à jour, l'utilisateur qui a fait la dernière mise à jour, sa taille, la date de dernière mise à jour et le nom du fichier.

svn mkdir
---------

C'est un autre commande partique et qui a deux usages.

Premièrement, elle peut être utilisée pour simultanément créer un nouveau répertoire dans la copie de travail et le programmé pour l'ajout:

     $ svn mkdir new-dir
     A     new-dir

Ou, elle peut être utilisée pour instantanément créer un répertoire dans le dépôt (aucune copie de travail n'est nécessaire):

     $ svn mkdir file:///usr/local/svn/newrepos/branches -m "made new dir"
     Committed revision 1123.

Encore une fois, c'est une forme de remontée immédiate et une description de modification est requise.

* Configuration d exécution::

Configuration d exécution
=========================

Lorsque vous exécuter pour la première fois le client en ligne de commande svn, il cré un espace de configuration par utilisateur. Sur un système Unix-like, un répertoire .subversion/ est créé dans le répertoire personnel de l'utilisateur. Sur un système Win32, un dossier Subversion est créé dans un endroit approprié pour le faire (typiquement quelque part dans Documents and Settings\username, mais çà dépend du système.)

Proxy
-----

Au moment de l'écriture de ce guide, l'espace de configuration contient uniquement un élément: un fichier proxies. En renseignant des valeurs dans ce fichier, votre client Subversion peut opérer via un proxy http. (Lisez le fichier lui-même pour les détails; il contient sa propre documentation.)

Config
------

Prochainement -- très prochainement -- un fichier config existera dans cet espace pour définir des préférences générales de l'utilisateur. Par exemple, l'éditeur à utiliser préféré ($EDITOR), les options a passer à svn diff, les préférences pour le format de date et heure, etc. Voir la question #668 pour les détails (http://subversion.tigris.org/issues/show_bug.cgi?id=668).

Espace de configuration multiple
--------------------------------

Sur Unix, un administrateur peut créer des préférences Subversion ``global'' en créant et remplissant un espace /etc/subversion/. Les fichiers de configuration par utilisateur écrasent ces valeurs par défauts cependant.

Sur Win32, un administrateur a l'option de créer trois autres emplacements: un dossier global Subversion dans l'espace ``All Users'', un ensemble de registres de configuration globaux, ou un ensemble de registres de configuration par utilisateur. Les registres de configuration sont défini dans:

     HKCU\Software\Tigris.org\Subversion\Proxies
     HKCU\Software\Tigris.org\Subversion\Config
     etc.

Pour clarifier les chose, voici l'ordre de recherche de la configuration à l'exécution sous Win32. Chaque configuration d'un emplacement écrase la configuration de l'emplacement précédent:

  * global registry

  * global Subversion folder

  * user registry

  * user Subversion folder