SVN tutoriál

From MerlinWiki
Jump to: navigation, search

Přijdete-li na něco nového, neváhejte tuto stránku zmodifikovat. Speciálně pro různé "nestandardní" problémy je určena disuze k tomuto článku. Nenajdete-li zde odpověď, své dotazy směřujte na vedoucího své práce, případně na linux@.fit.vutbr.cz. (diskuze je záložka mezi 'Article' a 'Edit')

Subversion (http://subversion.tigris.org) (zkráceně SVN) je systém pro správu zdrojových kódů projektu. Velmi dobrá dokumentace k Subversion a částečně k SCM systémům obecně je (anglická) kniha Version Control with Subversion.

Contents

Obecný úvod k SCM systémům

SCM (Source Code Management nebo Source Config Management) je označení pro třídu programů a postupů, keré mají za cíl usnadnit (či vůbec umožnit) spolupráci více lidí na společných projektech. Zavádí se dva základní pojmy. 'Repozitory' je centrální (nebo někdy distribuovaná) databáze obsahující soubory daného projektu. Není zde pouze poslední stav, ale uchovávají se všechny změny a jsou také uživatelům dostupné. Druhým pojmem je 'pracovní kopie' ('working copy'), což je kopie nějakého stavu centrální databáze (repository) určená k lokálním úpravám. Situaci ilustruje následující obrázek:

ch02dia1.png

Běžný cyklus práce je potom následující (v závorkách příkazy pro Subversion):

  1. získání pracovní kopie z repozitory (svn checkout)
  2. modifikace pracovní kopie
  3. aktualizace - získání změn v repozitory (svn update)
  4. další modifikace pracovní kopie
  5. zjištění rozdílu pracovní kopie a repozitory (svn diff)
  6. publikace změn v pracovní kopii do repozitory (svn commit)

Každá publikace změn vytvoří novou vrerzi projektu v repozitory. Verze projektu (nebo repozitory) pak vypadají například takto:

ch02dia7.png

SCM je užitečný především, když na projektu pracuje více lidí najednou. Tím pádem vznikají konflikty typu "dva lidé modifikovali jeden soubor" a oba jej nyní chtějí prosadit zpět do repozitory. Většinou jsou SCM dostatečně chytré, aby změny obou uživatelů spojila a výsledek uložila do repository. Někdy se ale stane, že dva lidé například opravovali tutéž funkci a změny mezi sebou kolidují. SCM nyní nezbývá, než se obrátit na uživatele, aby problém vyřešil.

Instalace SVN klienta na Windows

  1. Stáhneme si intalační program z http://tortoisesvn.tigris.org/ a spustíme jej.
  2. Proklikáme se skrz instalační obrazovky a případně modifikujeme nastavení. Na závěr jsme vyzváni k restartování počítače.
  3. Pro použití SSH tunelování je nutné explicitně nastavit SSH klienta - v nastavení je to záložka Network a dole položka SSH Client - Tortoise má v sobě integrovaného klienta - TortoisePlink.exe - nachází se v adresáři s instalací Tortoise.

SVN klient v Linuxu

Ve školních instalacích je přístupný řádkový klient subversion (příkaz svn). Jednoduchý grafický klient je rapidsvn (http://rapidsvn.tigris.org/).

Více informací naleznete na http://subversion.tigris.org/.

rapidsvn.png

Komunikace s repository

Subversion podporuje několik komunikačních protokolů, jedním z nich je http (často anonymně přístupné repository pouze pro čtení), dalším nejpoužívanějším je svn+ssh, kdy svn využívá jako transportní vrstvu (+ autentizaci) protokol a program ssh. Při operacích s repository je potom nutné vybrat jeden z konkrétně podporovaných protokolů pro dané repository např. pro získání nové pracovní kopie z repository:

svn co http://merlin.fit.vutbr.cz/svn/TerrainEngine/trunk .

nebo

svn co svn+ssh://merlin.fit.vutbr.cz/svn/TerrainEngine/trunk .

Checkout projektu

Checkout znamená prvotní stažení projektu na počítač - vytvoření pracovní kopie.

Pro linux:

svn co http://merlin.fit.vutbr.cz/svn/TerrainEngine/trunk .

Pro Win:

  1. Vytvoříme si složku. Obyčejně ji pojmenujeme podle názvu projektu.
  2. Klikneme pravým tlačítkem na složku a v menu se nám objeví položka "SVN Checkout"
    01-checkout.png
     
  3. Vybereme ji a objeví se následující okno
     
    02-repository.png
     
  4. Nyní musíme zadat URL na server a lokální cestu, kde se nám projekt objeví.
    Například pro projekt TerrainEngine zvolíme
    URL of repository: http://merlin.fit.vutbr.cz/svn/TerrainEngine/trunk
    Checkout directory: C:\Documents and Settings\_login_\Desktop\TerrainEngine
     
  5. Pokud jde vše v pořádku, objeví se výpis podobný tomuto:
     
    03-finished.png
     
  6. Odklikneme ok a náš adresář by měl být nyní označen zelenou fajfkou, což značí, že jsme úspěšně checkoutovali náš projekt.
     
    04-newIcon.png
     
  7. Podíváme-li se do složky projektu, najdeme v ní zdrojáky, ale i speciální složku .svn. Tu nikdy nemažeme, protože obsahuje vnitřní SVN informace, které nám slouží při dalších operacích se zdrojáky.
     
    05-iconsInside.png
     

Modifikace souborů

Platí jedno nepsané pravidlo: Respektujeme styl psaní kódu druhých a nepřeformátováváme jej ani jej zbytečně nemodifikujeme. Něco jiného je odstraňování chyb, velmi špatně čitelný kód nebo dopisování vlastních funkcí. Jednoduše řečeno, k modifikaci bychom měli mít nějaký důvod.

Změníme-li nějaký soubor, objeví se na něm ikonka s vykřičníkem jakožto znak modifikovaného souboru. Chceme-li se podívat, co jsme ve zdrojácích vlastně změnili, vybereme v menu tlačítko SVN Diff a objeví se program ukazující na jedné straně "Working Base", což je originální verze z repository, a na druhé straně "Working Copy", což je náš soubor.
 
06-modified.png
 

Linux (obecně řádkový klient):

Stav souborů pro 'status' a 'update' může být následující:

A ... soubor přidán do repozitory
D ... soubor odstraněn z repozitory
U ... aktualizace soubory v pracovní kopii (update)
M ... soubor změněn oproti repozitory (stavu kdy byl s repozitory synchronizován)
C ... nastal konflikt mezi pracovní kopii a verzí z repozitory (update)
I ... soubor je subversion ignorován (*.o, *.bak atd)
G ... soubor byl úspěšne sloučen při aktualizaci (update)

svn diff; svn status;

Update projektu

Update slouží k aktualizování projektu. Množství lidí mohlo opravit mnoho chyb a rozšířit projekt o nové funkce, které bychom i my rádi používali. Všechny tyto novinky, které druzí nahráli do repository, můžeme mít i my ve své lokální kopii. Stačí provést operaci "update". Update zachová naše modifikace a pokusí se doplnit vše, co dodělali druzí.

  1. Klikneme na složku projektu a vybereme SVN update.
  2. Většinou proběhne vše v pořádku a v okně se nám vypíšou aktualizované soubory. Tímto je update dokončen.
  3. Někdy se stane, že v repository někdo modifikoval tentýž kód, který jsme modifikovali i my v našich lokálních souborech. To znamená, že došlo ke konfliktu. Objeví se výpis podobný tomuto:
     
    08-conflict.png
     
    Na ikonce konfliktního souboru nám vyskočí vykřičník a uvnitř souboru je konfliktní část označena jako
<<<<<<< .mine
... váš kód ...
=======
... kód v repository ...
>>>>>>>> .r16 (revize kódu z repozitory)
  1. Oba kódy usmíříme, například tak, že tam necháme jen ten správnější a lepší kód, přičemž ten druhý smažeme. Nebo vybereme z obou to nejlepší a zmixujeme to. V nerozhodných případech je lépe ponechat kód z repository. (každopádně je nutno odstranit řádky se značkami <<<, >>> a ===.
  2. Kód zkusíme projekt zkompilovat, abychom zjistili, zda naše usmiřování proběhlo úspěšně a zda je projekt funkční.
  3. Nyní je třeba říci SVN-ku, že jsme konflikty v souboru usmířili. To provedeme kliknutím na soubor a výběrem položky TortoiseSVN->Resolved v menu.
     
    10-resolved.png
     

Linux (obecně řádkový klient):

svn update; svn resolve;

Odeslání změn do repozitory

Pokud chceme publikovat naše změny v pracovní kopii pro ostatní, použijeme následující postup:

  1. svn update - abychom spojovali s aktuální verzí v repozitory a předešli konfliktům
  2. svn status - zjistíme co jsme všechno změnili vůči repozitory
  3. svn commit - parametrem je minimálně hláška pro log -m "informace o tom co se zmenilo"

Informaci pro log popisující změnu je dobré pořádně promyslet, využívá se potom v příkazu svn log, který podává informaci o historii projektu nebo jednotlivých souborů. Log by měl tedy dobře vystihovat co se změnilo aby to pak zpětně bylo patrné i z historie. Naprosto nevhodné jsou informace typu "mala zmena", "karlovy upravy" a podobne. Mnohem lepší je "opraveny překlepy v funkce() v funkce.c", "doplňen parametr programu --crash-me" nebo "oprava chyby přetečení bufferu in_buf ve funkci read_input() v input.c".

Odeslání změn - školní projekty s RO repository

Některé školní projekty mají veřejně (tj. pro studenty) dostupné repository jen pro čtení. Je tedy možno si stáhnout pracovní kopii nebo procházet obsah repository na webu, ale není možné commitovat své změny zpět.

Aby byla vaše práce na projektu vložena do repository, je potřeba ji poslat vedoucímu vaší práce. Doporučený postup je tento:

  1. Provedeme update projektu, aby používal poslední verzi zdrojáků z repository. Vyřešíme případné konflikty ve zdrojácích.
  2. Ověříme si novou kompilací a spuštěním, že projekt funguje.
  3. Odstraníme dočasné soubory z projektu. (make clean, vse co nezna svn status)
  4. Projekt zazipujeme (včetně všech složek .svn) a pošleme vedoucímu.

Nastavování vlastností

Subversion umí o jednotlivých objektech uchovávat i různé metainformace. V svn se nazývají property a nejdůležitější z nich jsou asi svn:ignore a svn:keywords.

První se nastavuje pro adresář a říká, které objekty (soubory, adresáře, symlinky) má při svých operacích subversion ignorovat. Například nechceme aby nás subversion neustále upozorňoval že se změnily objektové soubory nebo výsledná binárka. Pro ty nepoužíváme verzování a chceme aby si jich subversion vůbec nevšímal. Ve škole je dostupný skript svn-set-ignore.sh, který k nastavení této vlastnosti použije soubor .svnignore případne .cvsignore v daném adresáři. (takto se chová program CVS).

Druhou vlastností je svn:keywords. Nastavuje se pro soubor a říká, které tzv. klíčové slova se mají v daném souboru rozgenerovávat. Příkladem je $Author$ nebo $Revision$ či nejpoužívanější $Id$:

* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License.
*
* $Id$
* 

po commitu:

* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License.
*
* $Id: ripac.c 21 2005-04-14 17:19:27Z kasparek $
*


Pro nastavování vlastností jsou určeny příkazy

svn propset; svn propget; svn proplist

např pro výše uvedený příklad bylo nutno udělat:

svn propset svn:keywords "Id" ripac.c

Crash Gallery

Následující obrázky ukazují, když je něco opravdu špatně.


e01-mkactivity.png

Nejspíše nemáte zapisovací práva. Projekt byl checkoutován http protokolem z webu a tam pochopitelně právo zápisu není.


e04-commitFailed.png

Commit se z nějakého důvodu nezdařil. V tomto případě změnil někdo eol-style v repository na serveru a zároveň byly provedeny změny v lokálních souborech, čímž vznikla kolize. Možné řešení - uschovat si svoje pozměněné soubory jinam a v lokální repository je smazat. Pak provést update. Po té zpět nahrát svoje modifikované soubory. Následující commit by již měl fungovat.


e02-dberror.png

e03-locksTable.png

Tady pomůže už jen systémový administrátor. (Chyba je na straně serveru.) Nezbývá, než někoho kontaktovat.

Využití služby na serveru merlin

Windows řešení

Subversion je nainstalován i na serveru merlin.fit.vutbr.cz. Máte možnost vytvořit si zde vlastní repository, spustit si server naslouchajícím na Vámi daném portu a využívat výhod tohoto systému. POZOR: není možné nechat běžet svnserve trvale, proto je lepší nechat si zřídit oficiální repository v /svn (žádost obsahující název repozitory - pro projekty v předmětu kód předmětu a číslo - např. ICP01, loginy uživatelů a termín zrušení repository - lze zaslat na linux@fit.vutbr.cz)

Postup je následující:

1. Vytvoříme prázdný adresář, např.

mkdir ~/SVNRepository

2. V tomto novém adresáři vytvoříme repository. Protože budeme používat připojení k Subversion přes síť, jedinou volbou je virtuální filesystem FSFS. Jestliže se po spuštění následujícího příkazu podíváte do tohoto adresáře, zjistíte, že se v něm vytvořily příslušné adresáře a soubory.

svnadmin create --fs-type fsfs ~/SVNRepository

3. Upravíme nastavení souborů v adresáři ~/SVNRepository/conf/. Tento proces je výborně popsán v sekci Built-in authentication and authorization.

Příklad konfigurace osobního repository. Přihlašujeme se jako uživatel me, s heslem my_password. Nechceme, aby obsah repository viděl někdo jiný (neautorizovaný uživatel).

soubor authz není potřeba měnit, nevyužíváme jej.

soubor passwd:

[users]
me = my_password

soubor svnserve.conf:

[general]
anon-access = none
password-db = passwd

Pozn.: V uvedených souborech jsou uvedeny příklady použití. Nezapomeňte odstranit také znak # před názvy sekcí :-)

4. Spustíme démona na zvoleném portu. Pokud nevložíme parametr pro nastavení portu, je standardní hodnota 3690.

svnserve -d --listen-port 2222 -r ~/SVNRepository

5. Nyní se lze připojit na repository, např. pomocí TortoiseSVN - Repo-browser:

svn://merlin.fit.vutbr.cz:2222

Protože je spojení se serverem nezabezpečeno, je vhodné používat SSH. Ve Windows např. prostřednictvím tunelu v Putty:

putty.exe -L 3690:localhost:2222 xlogin00@merlin.fit.vutbr.cz

První číslo 3690 udádá port na Vašem počítači, tj. již nemusíme zadávat číslo portu u spojení na Subversion, a 2222 číslo portu, na kterém naslouchá démon.

V tomto případě se připojuje takto:

svn://localhost

Na konci práce je nutné démona ukončit, např. pomocí příkazu kill.

Linux/Cygwin řešení

  • spustit server stejně jako v předchozím prípadě (není nutné nastavovat filesystem) v ~/temp/svnrep
  • nakonfigurovat server stejně jako v předchozím případě
  • začít pracovat:
$ svn checkout svn+ssh://user@merlin.fit.vutbr.cz/homes/eva/xu/xuser/temp/svnrep

Automatická autentizace

Windows

Pokud je repozitář na serveru, který vyžaduje ssh autentizaci, je třeba před každou akcí zadat heslo. Existuje zde možnost, jak se přihlásit jen jednou třeba při startu systému a pak už se nechat autentizovat automaticky. Zde je jednoduchý postup pro systém Windows.

Pokud nemáte svůj veřejný a privátní klíč je třeba si jej vygenerovat pomocí programu puttygen. Spusťte program, nastavte generování SSH-2 RSA a stiskněte Generate. Až se vygeneruje klíč, zadejte heslo, kterým jej budete chránit. Tímto heslem se později budete přihlašovat. Stiskněte Save Private Key a uzložte svůj privátní klíč na disk. Pokud možno, na nějaké bezpečné místo. Nakonec zkopírujte do schránky veřejný klíč (Textové pole v horní části okna. Nepoužívejte save public key!) a vložte jej do souboru ~/.ssh/authorized_keys na serveru, pro který chcete automatizkou autentizaci. Např. pomocí příkazu:

 echo [public key] > .ssh/authorized_keys

Tomuto souboru můžete nastavit práva taková abyste k němu měli přístup pouze vy.

Na svém počítači teď musíte spustit autentizačního klienta - program pageant. V systray se objeví jeho ikonka. Double-clickem otevřete okno Pageant Key List. Zde přidáte svůj privátní klíč a zadáte jeho heslo.

Nyní budete při každém přístupu do repozitáře na serveru automaticky autentizováni. Program Pageant je třeba spustit při každém startu systému příkazem:

 pageant [private_key.ppk]

Tím se váš klíč přidá na seznam v pageantu.

Tato autentizace funguje i pro připojení přes putty, takže po zadání loginu na server, kde se nachází soubor authorized_keys, proběhne automatická autentizace a není třeba zadávat heslo.

Linux/UNIX/atd.

Vytvoření DSA certifikátu. Budete dotázáni na heslovou frázi, kterou se budete u tohoto klíče prokazovat. Lze zadat prázdnou, pro přístup na Merlina pak nebude potřeba heslo, ale jen klíč. Pro vyšší bezpečnost použijte nějakého autentizačního klienta.

 ssh-keygen -t dsa

Pro autentizaci tímto klíčem na serveru merlin:

 cat ~/.ssh/id_dsa.pub | ssh uzivatel@merlin.fit.vutbr.cz 'cat >> ~/.ssh/authorized_keys'

Externí odkazy

Personal tools
Namespaces

Variants
Actions
Navigation
Tools