summaryrefslogtreecommitdiff
path: root/d/tools/doc/subversion/svn.txt
blob: e5bfbd16f0fe67dd774d5b9b732496a342f88eb5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
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>