====== SVN használat ======

Az alábbi dokumentum célja, hogy technikai szinten tisztázzon pár fogalmat az SVN használattal kapcsolatban.

===== Definíciók =====

Az SVN-ben definiált fogalmak és műveletek móricka-definíciója:

==== Fogalmak ====

  * repository - A központi, szerver oldali, verziózott fájl-tároló, ebből csak egy példány van. Egy fál, vagy könyvtár több eltérő verzióját, azonosítható módon tartalmazza. Az alábbiakban a REP vagy URL rövidítést is használjuk a repository jelölésére.
  * verzió - A repositoryban tárolt fájlok egy adott pillanat beli állapota, egyfajta sorszámozott snapshot.
  * HEAD - A repositoryban tárolt legfrisebb verziószám jelölésére használatos elnevezés. Általában ha nem adunk meg verziószámot, az alapértelmezett a HEAD lesz.
  * branch - "Fejlesztési ág", "ág". A repository azon része, alkönyvtára, mely egyedi fejlesztéseket, kísérleti ágakat, támogatott disztribúciókat tartalmazza. Jellemzően a /branches könyvtárban kap helyet minden branch.
  * stable branch - "Stabil ág". Egy olyan, hosszabb távú támogatást élvező, jellemzően verziószámmal ellátott branch, melyet a fejlesztők "stabil" verziónak jelöltek meg. Csak a kritikus frissítéseket szokás belevezetni. Célszerűen csak egy ilyen van. Elterjedt megoldás, hogy a trunk látja el ezt a feladatkört, de elképzelhető más gyakorlat is.
  * development branch - "Fejlesztői ág". Értelemszerűen egy olyan branch, melyben fejlesztői, kísérleti munka folyik. Jellemzően több ilyen lehet.
  * trunk - "Kódtörzs", "törzs". A repository azon része, alkönyvtára, mely a szoftver fő fejlesztési irányát, kódbázisát képviseli. Jellemzően a /trunk alkönyvtárban kap helyet. A trunk-ben jellemzően minden fájl csak egyszer szerepel. Általában a trunk is egy branch.
  * tag - "Jelölés", "jel", "címke". Egy branch egy adott verziójának megkülönböztető céllal készített másolata. Jellemzően a /tags könyvtárban kap helyet. Elterjedt megoldás a stable branch fő verzióit tag-ekkel megjelölni, úgy, hogy a tag neve az adott stable branch verziószámát is tartalmazza. A tag gyakorlatilag egy soha meg nem változó, "statikus" branch.
  * working copy - "Munkamásolat", "munkapéldány". Egy fejlesztő által használt, a repository egy adott verziójából készült részleges, vagy teljes másolat, jellemzően egy branch vagy tag alkönyvtárának másolata. A másolatban .SVN nevű könyvtárakban meta-információk tárolódnak, melyeket kézzel szerkeszteni, másolni nem szabad. Jellemzően fejlesztői célokat szolgál. Általában a working copy csak egy branch adatait tartalmazza, nem szokás az egész repository-t working copyként használni. Az alábbiakban a WC rövidítést is használjuk a working copy jelölésére.
  * export - A repository egy adott verziójából készült részleges, vagy teljes másolat, egy branch vagy tag másolata. Ezt a fajta másolatot nem köti semmi a repository-hoz, így a rajta végrehajtott módosítások visszajuttatására már nincs lehetőség. Jellemzően disztribúciós célokat szolgál, ezért jellemzően a stable branch másolataként tekinthetünk rá.

==== Alapvető halmazműveletek ====

  * commit - A working copyban végrehajtott változtatások (vagy részhalmazuk) alapján új repository verzió létrehozása, a változtatások feltöltése. Fontos lépés a commithoz tartozó megjegyzési mező kitöltése, mely naplóbejegyzésként funkcionál a repository-ban. Ha több fejlesztő párhuzamosan ugyanazokat a fájlokat, ugyanazokon a helyeken módosítja a working copy-ban, az időrendben későbbi commit sikertelen lesz és az azt kezdeményező fejlesztő feladata a módosítási ütközések ("conflict") feloldása.
  * update - A working copy frissítése a repository, vagy branch valamely újabb verziója alapján, a lokális változásokat megőrizve. A commit-hoz hasonlóan itt is ütközések léphetnek fel, melyeket szintén fel kell oldania az update-et kezdeményező felhasználónak.
  * revert - A working copy-n (vagy részhalmazán) végrehajtott változtatások eldobása.
  * resolve - A commit vagy update által felderített ütközések feloldása. Alapvetően minden ütközés manuális beavatkozást igényel. A magasszintű eszközök általában fejlett támogatást nyújtanak hozzá.

==== Alapvető fájlműveletek ====

  * copy - Univerzális fájlművelet, fájlok vagy alkönyvtárak másolására használható különböző források és célok között, az SVN meta-információk megőrzésével. Létezik WC -> REP, WC -> WC, REP -> WC és REP -> REP irányú copy.
  * move, rename - Univerzális fájlművelet, a copy-hoz hasonlóan működik, de nem másolja, hanem mozgatja a fájlokat, alkönyvtárakat a megadott forrásból a célba.
  * delete - Univerzális fájlművelet. A copy és a move/rename műveletekhez hasonlóan működik, fájlok és könyvtárak törlésére használatos a working copy vagy a repository oldalán.
  * add - A working copy területén létrehozott új fájlok és könyvtárak hozzáadása a verziókövető-rendszerhez. A következő commit már ezeket is érinteni fogja. Értelemszerűen azon új fájlok és könyvtárak, melyekhez nem hozzuk létre az SVN meta-információkat az add művelettel, nem kerülnek bele a commitba. Sok SVN frontend (pl.: TortoiseSVN) a commit során automatikusan felajánlja az add lehetőségét, ezzel azonban óvatosan kell bánnunk, mert nem célszerű pl. a szövegszerkesztő által létrehozott átmeneti álományok verziókövetőbe történő betöltése.

==== Egyéb, ritkábban használatos elemi műveletek ====

  * checkout - A working copy kezdeti kimásolása a repository-ból. Jellemzően a fejlesztői munka megkezdése előtt, egyszer kell végrehajtani.
  * import - Még nem verziókezelés alatt álló fájlok és könyvtárak kezdeti betöltése a repository-ba. 
  * export - Export készítése (lásd: fogalmak).
  * switch - Working copy váltása. Eredménye gyakorlatilag azonos a working copy-ban található adatok kidobásával és egy másik branch checkout-olásával. Biztonsági ellenőrzéseket végez, hogy nem commitolt módosítások ne veszhessenek el és nem végez fölösleges fájlműveleteket. A repository URL változásának követésére is használható.
  * lock - A repository egy részéhez (alkönyvtárához, fájljához) tartozó terület zárolása. A lock megnehezíti a commitot a többi fejlesztő számára, de nem akadályozza azt meg (van "forced" commit és "forced" lock). Jellemzően nagyobb átalakítások során használatos, nem a mindennapi munka eszköze.
  * unlock - A lock inverz művelete, a zárolás feloldása.
  * merge - Az egyik legösszetettebb feladatot ellátó SVN művelet. Általános esetben a megadott két branch megadott két verziója közti különbségeket (ún. "changeset") kigyűjti, majd alkalmazza ezeket egy working copyra. Ha a megadott verziókat M és N betűkkel, a különböző helyeket pedig 1, 2 és 3 számokkal jelöljük, a következő esetek valósíthatók meg: (REP1@M - REP2@N) -> WC, (WC1@M - WC2@N) -> WC3, (REP@M-N) -> WC, (WC1@M-N) -> WC2.

===== Példák =====

Az alábbiakban a fejlett SVN használat, főként branching és tagging, jobb megértéséhez mutatunk pár gyakorlati példát. A példákban a műveletek általános leírásán kívül az SVN parancs parancssori használatát is szemléltetjük. A magasabb szintű SVN frontendek esetében az egyes műveletekhez külön támogatást is találhatunk, ám ezek is a szemléltetett primitív műveletekből épülnek fel.

A példákban használt repository (standard) alapfelépítése a következő:

<code>
/calc/tags
/calc/branches
/calc/trunk
</code>

A feltételezett repository URL: http://svn.example.com/repos/calc

==== Branch (vagy tag) létrehozása ====

A branch létrehozását mindig a repository oldalán kell kezdeményeznünk. Erre a feladatra a copy művelet a megfelelő. Jellemzően a trunk másolatát készítjük el. Ugyanez az eljárás használható tag létrehozására is.

Például, ha az új branch neve "my-calc-branch", az alábbi parancsot kapjuk:

<code>
$ svn copy http://svn.example.com/repos/calc/trunk \
           http://svn.example.com/repos/calc/branches/my-calc-branch
</code>

==== Branch törlése ====

Ha egy branch-ra már nincs szükségünk, nyugodtan törölhetjük, hisz a verziókövető rendszerben megmarad. A working copy egyszerűen törölhető, a repository oldalt pedig a delete művelettel törölhetjük.

Például az alábbi parancssort kapjuk:

<code>
$ svn delete http://svn.example.com/repos/calc/branches/my-calc-branch \
             -m "Removing obsolete branch of calc project."
</code>

==== Branch visszaállítása ====

A branch törlése, ahogy ezt említettük, nem jelenti a repository-ból való eltávolítását, csupán azt, hogy nem szerepel többé a HEAD verzióban. Egy megadott verzióban (pl.: 374) még létező branch visszaállítását a copy művelettel végezhetjük.

<code>
$ svn copy -r 374 http://svn.example.com/repos/calc/branches/my-calc-branch \
                  http://svn.example.com/repos/calc/branches/my-calc-branch
</code>

==== Branch visszaolvasztása a trunk-be ====

A lépések a következők:

  * Checkoutoljuk és/vagy updateljük a trunk-öt. A példánkban a WC a calc/trunk könyvtárban van.
  * A kiválasztott branch összes módosítását merge művelettel beolvasztjuk a working copy-ba. Jelen példánkban feltételezzük, hogy a branch létrehozásának verziószáma 341, az aktuális verzió pedig általában a HEAD.
  * Státuszt kérünk, feloldjuk az esetleges ütközéseket, stb.
  * Commitoljuk a módosított trunk working copy-t.

<code>
$ cd calc/trunk
$ svn update
At revision 405.

$ svn merge -r 341:HEAD http://svn.example.com/repos/calc/branches/my-calc-branch
U   integer.c
U   button.c
U   Makefile

$ svn status
M   integer.c
M   button.c
M   Makefile

# ...examine the diffs, compile, test, etc...

$ svn commit -m "Merged my-calc-branch changes r341:405 into the trunk."
Sending        integer.c
Sending        button.c
Sending        Makefile
Transmitting file data ...
Committed revision 406.
</code>

===== Hivatkozások =====

  * "Version Control with Subversion - For Subversion 1.0":http://svnbook.red-bean.com/en/1.0/