summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--d/tools/doc/subversion/svn.txt371
1 files changed, 371 insertions, 0 deletions
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 <font color=red size="+1">
+elle soit parfaitemenent fonctionnelle !
+#---PASS-HTML </font>
+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 <font color=red size="+1">
+ne pas ajouter n'importe quels fichiers dans le dépot SVN
+#---PASS-HTML </font>
+. 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 <font color=red size="+1">
+ne pas faire un |svn del| puis un |svn add| pour déplacer un fichier
+#---PASS-HTML </font>
+ ! 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 <font color=red size="+1">
+ * une vérification que vos modifications fonctionnent sans problème
+#---PASS-HTML </font>
+ (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 <font color=red size="+1">
+mettez un commentaire explicite de vos modifications
+#---PASS-HTML </font>
+ !
+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 <font color=red size="+1">
+il ne vérifiera pas et vous croirera sur parole !
+#---PASS-HTML </font>
+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 <font color=red size="+1">
+Attention, un fichier peut contenir _plusieurs_ conflits !
+#---PASS-HTML </font>