From b0d74346240bd6885ec0f888e8a179ac63e78c16 Mon Sep 17 00:00:00 2001 From: dufourj Date: Sun, 9 Oct 2005 17:10:30 +0000 Subject: Ajout de la documentation subversion. Restant a faire dessus : relecture et correction des liens. --- d/tools/doc/subversion/svn.txt | 371 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 371 insertions(+) create mode 100644 d/tools/doc/subversion/svn.txt (limited to 'd') diff --git a/d/tools/doc/subversion/svn.txt b/d/tools/doc/subversion/svn.txt new file mode 100644 index 0000000..e5bfbd1 --- /dev/null +++ b/d/tools/doc/subversion/svn.txt @@ -0,0 +1,371 @@ +*Title: How-To SVN (SubVersioN) +*Author: djerem +-------------------------- + +*TOC + +-------------------------- +* SVN, c'est quoi ? + +SVN est un outil qui permet à différentes personnes de travailler sur un même +projet, en même temps, sans être à côté et sans se géner les uns avec les +autres. De plus, il permet de garder des archives des différentes versions de +votre projet, afin de pouvoir y revenir à tout moment ou simplement pour +garder un hsitorique. + +Pour cela, il y a ce que l'on appelle un dépot (repository) contenant les +différentes versions du projet dont la plus récente. Il est gardé sur le +serveur (Lampion). Vous ne travaillerez jamais directement dans le dépot mais +toujours sur une copie de ce dépot. + +De manière générale, vous allez travailler de la facon suivante : vous +récupérez la dernière version du dépot afin d'en faire une copie locale, vous +la modifiez vous demandez à ce qu'elle soit mise à jour afin de refléter les +modifications que d'autres personnes ont pu faire. Vous terminez vos +modifications, puis ensuite vous envoyez votre version sur le dépot afin que +tout le monde puisse s'en servir. SVN s'occupera de gérer les différences +entres les fichiers. Et ainsi, tout le monde peut travailler en même temps sur +le projet sans être géné par la mise en commum. + +Il est important de comprendre que les modifications que vous faites +sur votre copie du dépot n'impacte que vous et ne seront disponnibles pour les +autres qu'au moment où vous les validerez sur le dépot. + +Bien que SVN soit capable de gérer le fait que deux personnes travaillent sur +le même fichier, il peut avoit des difficultés dans le cas où les +modifications se contredisent. On appelle cela un +[conflits (Gestion des conflits)]. La plupart du temps, les conflits sont +provoqués par deux personnes effectuant le même travail (modification d'une +même ligne de code par exemple) mais en le faisant de manières différentes. +Pour éviter ces conflits, il n'y a qu'une seule et unique solution : _la \ +communication !_ Il est très important de dire que l'on travaille sur telle ou +telle partie et quand on a besoin de toucher la partie dont quelqu'un d'autre +s'occupe, il faut lui demander à lui pour que sa soit fait sans conflits ! + +Une autre chose importante : le dépot est d'une certaine façon, la version +dont tout le monde dispose ! +_Il est donc important que lorsque vous validez vos modification dans le \ +dépot ([commit (commit (ci))]),_ +#---PASS-HTML +elle soit parfaitemenent fonctionnelle ! +#---PASS-HTML +Quoi de plus embettant que de se retrouver avec un projet qui ne compile pas +car un autre développeur à laisser des grosses fautes dans son code ?! + + +* La structure du dépot SVN + +Un dépot est généralement composé de la façon suivante : la branche +principale (trunk), les autres branches (branches), et les version sorties +(tags). + +La branche principale correspond à la branche de développement, celle qu'on +utilise tous. Des fois, il pourra arriver qu'on veuille essayer de faire le +code d'une certaine façon et que cela necessitera de gros changement. Pour +éviter de géner les autres lorsque l'on teste cette méthode, on développe dans +une branche à part pour géner personne. Généralement, on n'utilisera cette +méthode qu'en cas de gros changement à faire pour le code et elle nécessitera +consultation du responsable informatique ! Ne créez pas de branches pour une +modification qui nécessitera 3 heures de modification seulement. + +Les tags permettent de garder des versions clefs du projet, que l'on considère +comme stable. Il faut savoir qu'à chaque fois qu'un développeur mettra à jour +sa version du code sur le SVN, cela créera une nouvelle révision pour tous les +fichiers, même ceux qu'il n'a pas modifié. Il y aura donc plein de révisions. +Les tags permettent donc de garder une version que l'on considère comme utile +du projet (par exemple, un tag avant la pré-coupe, un après, un pour le +premier match...). + +Pour une utilisation normale du dépot SVN, vous aurez normalement besoin que +de la branche principale (trunk) : elle contient tout ce dont vous avez +besoin. De plus, ne prendre que la branche principale permet d'économiser en +place et en temps (pas besoin pour SVN de vérifier ni de transférer les autres +branches/tags). _Merci de prendre que la branche trunk !_ + + +* La configuration de SVN + +Vous pouvez spécifier l'éditeur que vous utilisez[Note: Cette commande \ +s'avere optionnelle et peut etre adaptee a vos besoin] : + + export SVN_EDITOR=vim + +Pour que ce changement soit fait de manière définitive, éditez votre |.bashrc| +et rajouter la ligne précédente en bas de votre fichier ou alors effectuer la +commande suivante : + + echo "export SVN_EDITOR=vim" >> ~/.bashrc + +Puis relancer votre console (ou faites |source .bashrc|) pour que vos +modifications soient prises en compte immédiatement. + + +* Les commandes de SVN + +De manière générale SVN marche de la façon suivante : + svn commande [arguments] +Les |[]| symbolise des arguments qui ne sont pas obligatoires. +Chaque commande est présentée avec sont sa version raccourcie entre +parenthèses. + +** checkout (co) + +Notez que pour la suite d'explication de cette commande, je considère que vous +avez que vous avez suivi le How-To Système de Ni (|d/sys/doc/|) afin d'avoir +un accés sur Lampion en ssh via l'hôte |robot|. + +Lorsque vous voulez récupérer une version du dépot depuis chez vous, il suffit +de faire : + + svn checkout svn+ssh://robot/svn/trunk [nom_local_alternatif] +Cette commande récupèrera tous ce qui est contenu dans le dossier |svn/trunk| du +dépot et créera un dossier |trunk| dans le dossier courant. +Si par exemple vous voulez récupérer que le dossier |trunk/i| (partie +informatique de la branche principale) et le mettre dans le dossier +|robot-info|, il suffit de faire + + svn checkout svn+ssh://robot/svn/trunk/i robot-info +Utilisez cette commande afin de récupérer la dernière version du dépot mais +vous n'avez pas besoin de le faire par la suite. C'est juste pour la première +fois et aussi si vous travaillez sur une autre machine ou que vous avez +supprimer votre version locale. + +Si vous travaillez sur Lampion, il faut remplacer |svn+ssh| par |file:///| + + svn checkout file:///robot/svn/trunk robot-svn + +Merci de ne toujours travailler avec ce qu'il y a dans la branche principale +(donc toujours avec au moins svn/trunk). + +** status (st, stat) + +Cette commande permet de regarder quelles sont les différences entre votre +version locale et la version du serveur. Ainsi vous pourrez voir si c'est +utile ou pas de mettre à jour (update) votre version et si cela va produire +des conflits : + + svn status [fichier ou dossier] +Cela vous renverra une liste de fichier avec leur status avant : + + A -> Fichier qui sera ajouter au dépot lors du prochain commit + D -> Fichier qui sera supprimer du dépot lord du prochain commit + M -> Fichier modifié localement + C -> Fichier à conflit + ? -> Fichier non connu par SVN (n'existe pas dans le dépot) + ! -> Fichier manquant +Lorsque vous avez un fichier marqué d'un |?| et que vous voulez le mettre dans +le dépot SVN, il suffit de l'[ajouter (add)]. +Lors de la suppression d'un fichier, pensez à utiliser la commande [delete\ +(delete (del, remove, rm))]. + +De manière générale, _vous devez faire cette commande très souvent._ + +Vous pouvez rajouter un |-v| pour avoir plus d'informations. + +** update (up) + +Cette commande permet de mettre à jour votre version locale. Elle correspond à +la même chose que [status (status (st, stat))], sauf qu'elle le fait pour de +vrai. Elle vous renverra aussi une liste de ce qu'elle a fait. Les +significations d'au dessus sont valables, mais en plus vous pourrez trouver : + + U -> Mise à jour du fichier car la version du dépot est différente + R -> Remplacement du fichier (del puis add) + G -> Mise à jour du fichier car la version du dépot et la votre ont \ +été modifiée (merge) + C -> Conflit +Avant d'utiliser cette commande, il faut faire la commande [status (status \ +(st, stat))] afin d'avoir une idée de ce qu'il va se passer et de ne pas avoir de +surprise à cause des [conflits (Gestion des conflits)]. + +** add + + svn add le_nom_du_fichier +Ajoute un fichier ou un répertoire (et tous ce qu'il y a dans ce répertoire!). +Cette commande sert à dire à SVN que vous ajoutez ce fichier dans le dépot, +sinon il ne s'en occupera pas. Notez que votre ajout sera validé sur le +serveur lors du prochain [commit (commit (ci))] seulement. + +Il est important de +#---PASS-HTML +ne pas ajouter n'importe quels fichiers dans le dépot SVN +#---PASS-HTML +. Eviter d'ajouter les fichiers qui peuvent être regénérés (fichiers objets +issus de compilation...). + +Vous pouvez utiliser le -N afin de ne pas effectuer un ajout récursif : + + svn add -N mon_nouveau_repertoire +Cela n'ajoutera que le répertoire sans son contenu. + +Si vous ne savez pas où faire autre ajout (dans quel dossier je vais mettre +mon how-to moi ?), surtout n'hésitez pas à demander. + +** delete (del, remove, rm) + + svn delete le_nom_du_fichier +Supprime un fichier ou un dossier. Il est important de comprendre que si vous +supprimez à la main un fichier, SVN ne pourra pas savoir si vous l'avez perdu +ou si vous voulez vraiment le supprimer. Il faut donc le lui dire. Notez que +lors de la suppression, il faut faire un [commit (commit (ci))] derrière pour +valider ces changements sur le dépot. +Il est important de +#---PASS-HTML +ne pas faire un |svn del| puis un |svn add| pour déplacer un fichier +#---PASS-HTML + ! Utiliser la commande [move (move (mv, rename, ren))] à la place. + +** copy (cp) + + svn copy le_nom_du_fichier_source le_nom_du_fichier_de_destination +Copie un fichier ou dossier. Très utile sur le dépot SVN, car il n'a pas a +créer un nouveau fichier avec un nouveau contenu mais à dire que c'est le même +que celui là. + +** move (mv, rename, ren) + + svn move le_nom_du_fichier_source le_nom_du_fichier_de_destination +Renome un fichier ou un dossier. +Il est important d'utiliser cette commande plutôt que de faire une suppresion +puis un ajout. Ceci permet un meilleur suivi des modifications et facilite +énormément le travail de SVN. + +** mkdir + +Créer un dossier. Créez le à la main et utilisez la commande [add] plutôt. + +** commit (ci) + +Cette commande permet de mettre à jour le dépot avec votre version local. +Lorsque vous faites cette commande, il faut au préalable avoir fait : + + * _un [status (status (st, stat))]/[update (update (up))]_, car il + faut avoir mis à jour sa version locale pour posséder la dernière + version avant de mettre à jour le dépot et _ne pas avoir de \ +[conflits (Gestion des conflits)]_. +#---PASS-HTML + * une vérification que vos modifications fonctionnent sans problème +#---PASS-HTML + (aucune erreur ni avertissement (warning) à la compilation et pas de + problème à l'exécution). +Une fois ces deux conditions vérifiées, vous pouvez mettre à jour le dépot : + + svn commit +Il vous sera demandez de mettre un message. Soyez clair et détaillé dans votre +message, afin que l'on puisse garder une trace des modifications que vous avez +faites sans avoir à regarder le code. Vous pouvez faire des commits pour des +petites choses comme par exemple corriger les fautes d'othographes de vos +commentaires et commiter juste après ça. +Vous pouvez également spécifier votre message en ligne de commande avec + + svn --message "votre message" commit +Quelque soit la raison de votre commit, importante ou non, +#---PASS-HTML +mettez un commentaire explicite de vos modifications +#---PASS-HTML + ! +Il est aussi possible de commiter que certains fichiers ou dossier en les +spécifiant en paramêtre : + + svn commit *.c include +Cela commitera tous les fichiers qui finissent par .c du dossier courrant +ainsi que tous le contenu du dossier include. + +** diff (di) + + svn diff [le_nom_du_fichier] +Vous donne la différence entre votre version du fichier et celle du dépot. Il +existe une facon plus compliqué de s'en servir pour comparer avec une version +précise etc... + +Pour avoir une version plus jolie dans votre vim préféré, essayez la commande +suivante : + svn diff mon_fichier | view - +Plus pratique, non ? + +** revert + + svn revert le_nom_du_fichier +Retourne à la version du fichier lors de votre dernière [update (update (up))] +: cela supprime donc les modifications locales que vous avez faites. + +** info + + svn info [le_nom_du_fichier] +Donne les informations sur le fichier. + +** log + + svn log [le_nom_du_fichier] +Affiche les logs des modifications apportés sur le fichier (affiche les +messages que vous avez mis lors des [commit (commit (ci))]). + +** resolved + + svn resolved le_nom_du_fichier +Voir la section sur la [gestion des conflits (Gestion des conflits)]. + +** help + svn help [commande] +Si vous voulez un peu plus d'informations sur une commande ou si vous avez +oublié son utilité ou l'argument à utiliser ave, vous pouvez demander de +l'aide à svn. + + +* Gestion des conflits + +Que faire en cas de conflits. Si vous n'avez pas encore fait le update mais +juste le status, vous ne pouvez pas faire grand chose, hormis supprimer vos +modification. Si vous pensez que ce n'est pas votre faute (vous bossez sur le +bon fichier, c'est quelqu'un d'autre qui n'aurait pas du bosser sur le +fichier), regarder les [informations (info)] sur le fichier et voyez avec lui +que faire. +Si vous avez fait update, vous allez posséder 4 fichiers pour le même fichier. +Par exemple pour toto.txt, vous aurez : + + * toto.txt : votre fichier avec des marqueurs de conflits dedans + * toto.txt.mine : votre fichier avant que vous fassiez update + * toto.txt.r20 : votre fichier avant que vous le modifier (votre dernier + update réussi) + * toto.txt.r21 : le fichier du serveur, modifié par quelqu'un d'autre + donc. +A noter que r20 et r21 varient. Ils correspondent à rOLD et rNEW. + + +Quand vous avez un conflit, il y a trois façons de s'en sortir : + 1. effacez vos changements (il n'était pas important). Pour cela faite + [svn revert le__nom__du__fichier (revert)] + 2. prendre la nouvelle version et perdre les changements que vous avez + fait (vous copiez à la main toto.txt.r21) + 3. réglez le conflit à la main. Pour cela éditez le fichier. Vous + trouverez des marqueurs dedans au niveau du conflit : + +^<< +<<<<< .mine +.. +.. +.. +======= +.. +.. +>>>>> .rNEW +^>> \ + + # Dans la partie au dessus du =====, cela correspond à votre code. La + partie en dessous correspond au code du dépot. A vous de migrez ce + code en un seul. Attention vous devez supprimer les marqueurs et + avoir du code fonctionnel qui incluent vos changements et ceux + effectués par l'autre personne. + +Une fois le conflit résolu, il faut dire à SVN que vous l'avez résolu ! Notez +que si vous lui dites que c'est résolu, +#---PASS-HTML +il ne vérifiera pas et vous croirera sur parole ! +#---PASS-HTML +Ne faites donc pas n'importe quoi ! Pour cela (sauf si vous avez fait la +solution numéro 1, [revert]) faites un [svn resolved le__nom__du__fichier \ +(resolved)]. + +#---PASS-HTML +Attention, un fichier peut contenir _plusieurs_ conflits ! +#---PASS-HTML -- cgit v1.2.3