SubVersion pro K2 atmitec syst Obsah Co je SubVersion.................................................................................................................................. 1 Příprava před používáním SVN ............................................................................................................ 1 Běžná práce se SubVersion...................................................................................................................... 2 Stážení aktuální verze z repository...................................................................................................... 2 Potvrzení změn do repository ............................................................................................................. 2 Nahrání nového projektu do repository.............................................................................................. 3 Prohlížení změn projektu .................................................................................................................... 3 Pokročilé operace se SubVersion ............................................................................................................ 4 Současná editace jednoho souboru dvěma uživateli .......................................................................... 4 Označení důležitých verzí .................................................................................................................... 4 Práce s větvemi ................................................................................................................................... 5 Často kladené dotazy .............................................................................................................................. 7 Mohu si lokálně zobrazit SVN detaily souborů? .............................................................................. 7 Lze do souboru automaticky zapisovat, o jakou revizi se jedná?.................................................... 7 Mohu nechat TortoiseSvn zapamatovat své heslo?........................................................................ 8 Proč se mi nezobrazují ikony stavu u souborů? .............................................................................. 8 Které soubory z K2ky dávat do repository?..................................................................................... 8 Jak si mohu SVN rozbít? .................................................................................................................. 8 Kde mohu získat další informace o SubVersion?............................................................................. 9 Rejstřík ................................................................................................................................................... 10
Co je SubVersion SubVersion (SVN) je systém pro správu verzí. Slouží hlavně jako centrální uložiště souborů s evidencí změn a především s podporou spolupráce více osob na jednom projektu. Ve společnosti K2 atmitec syst je SubVersion používán především pro archivaci "speciálů" zákazníků, pro evidenci změn a pro spolupráci na projektech. Centrálním úložiště (repository) je přístupné adrese https://svn.syst.cz/svn/k2/ z firmy i mimo ni. Uživatelé se autorizují našimi doménovými účty qgirit\jmeno.prijmeni. Pro přístup používáme speciálního klienta TortoiseSVN, který je integrován do Windows Exlorera (průzkumník, složky) a všechny funkce jsou přístupné přes druhé tlačítko myši. Stejně tak v Total Commanderu.
Příprava před používáním SVN Nainstalujte si klienta TortoiseSvn, který najdete na našem síťovém V:\Tools\SubVersion\TortoriseSvn-xxx.msi (alternativně stahnutelný http://tortoisesvn.net/downloads ). Po instalaci je třeba restartovat počítač.
disku z
Běžná práce se SubVersion Stážení aktuální verze z repository Napoprvé, kdy ještě nemáte adresář získaný a spravovaný přes SubVersion, postupujte následovně: 1. V kontextovém menu adresáře (druhé tlačítko myši) zvolte "SVN Checkout". 2. V dialogu zadejte adresu https://svn.syst.cz/svn/K2/ (viz Obrázek 1). 3. Klikněte na tlačítko "..." za adresou a vyberte adresář, který chcete stáhnout – pro ostré skripty zákazníků /Zak/Firma/trunk. 4. Po potvrzení dialogu se Vám data ze serveru stáhnou (do adresáře, který je uveden v poli Checkout directory). Každá další aktualizace tohoto adresáře provedete přes volbu "SVN Update" v kontextovém menu adresáře. Pokud požadované soubory nebudete chtít po úpravě nahrát zpět na server, tak místo "SVN Checkout" vyberte "TortoiseSVN / Export".
Obrázek 1 - Staženi z repository
Potvrzení změn do repository 1. Nejprve si stáhněte aktualizace ze serveru. Tedy, v kontextovém menu adresáře zvolte "SVN Update". 2. Pokud máte soubor, který na serveru neexistuje, je nutné ho přidat (TortoiseSVN / Add), prosté nahrání do adresáře nestačí. Obdobně pro vymazání souboru použijte TortoiseSVN / Remove (nebo jej lze odeberat při potvrzování změn). 3. Pro nahrání změn zvolte v kontextovém menu souboru nebo adresáře příkaz "SVN Commit". 4. V dialogu zkontrolujte, které změny nahráváte na server. Vždy vyplňujte stručný popis charakterizující změnu. Potvrzením pak zpřístupněte své úpravy na server.
Pokud nechcete některé typy souborů nahrávat na server (např. MujPokus.pas), zajistíte to volbou "TortoiseSVN / Add to ignore list". Typy souborů, které chcete vždy ignorovat, zadáte v nastavení TortoiseSvn / Settings / záložka General do pole Global ignore pattern, já maximalisticky používám "Bin Debug Release obj Obj ClientBin *.dir *.bak *.suo *.user *.ncb *.jpg *.exe *.dll bin *.log *.ind orig prep .#* itkGaussianDistribution.cxx .cvsignore CVS .* *.asv *.~* *~ Generated_Code"
Nahrání nového projektu do repository Následující návod udává, jak nahrát projekt do repository obecně. Doporučení postup pro zanesení do repository z běžící K2ky zákazníka naleznete v často kladených otázkách. 1. Vyčistěte všechny nepotřebné soubory a adresáře. V repository mají být pouze aktuálně platné zdrojové kódy nebo sestavy. (Pro seznam souborů viz v Často kladené otázky.) 2. V kontextovém menu hlavního adresáře zvolte TortoiseSvn / Import. 3. V dialogu zadejte cestu pro import (např. https://svn.syst.cz/svn/K2/Zak/Linet/trunk ) a vyplňte komentář. Data zákazníků patří do adresáře /Zak/Firma/trunk (nezapomeňte trunk pro označení ostré větve), Vaše soukromé projekty do /Home/Prijmeni, testy do /Test, projekty vývoje do /Proj a obecně využitelné nástroje do /Util. 4. Pokud chcete s verzí dále pracovat přes SVN, je nutné si ji stáhnout (viz Stažení aktuální verze z repository).
Prohlížení změn projektu •
SVN Stav souborů: U souborů spravovaných přes SVN je jejich aktuální stav indikován překryvným symbolem u ikonky ... viz Obrázek 2. Na naší firmě platí striktní zásada, že po ukončení Vaší práce u zákazníka nesmí v projektu zůstat žádný soubor nepotvrzený (tedy nesmí zůstat žádná červená nebo modrá ikonka).
Obrázek 2 - Ikony SVN stavu souboru
•
• •
Provedené změny: Pro zobrazení rozdílu mezi současnou a původní verzí změněného souboru zvolte v jeho kontextovém menu TortoiseSvn / Diff. Objeví se Vám porovnání původní a aktuální verze. Je zde možná i korekce změn. Toto porovnání lze vyvolat např. i před potvrzením (Commitem) Vašich změn do repository. Historii změn v projektu vyvoláte např. pomocí volby TortoiseSvn / "Show log". Autora a důvody změn pro každý řádek kódu získáte pomocí funkce TortoiseSvn / Blame z kontextového menu souboru.
Pokročilé operace se SubVersion Současná editace jednoho souboru dvěma uživateli Může dojít k situaci, že dva uživatelé editují zároveň jeden soubor, každý ve své lokální kopii (např. ZP provede drobnou opravu ve skriptu přímo u zákazníka, zatímco SIčko zapracovává na firmě novou funkčnost). SVN takové případy pomáhá řešit efektivně pomocí následujícího postupu. 1. První uživatel potvrdí své změny do repository. 2. Vy jakožto druhý uživatel si stáhnete aktuální verzi z repository (potvrzení neaktuální verze SVN neumožní). 3. SVN sloučí do pracovní kopie změny, které udělal první uživatel. Pokud editace probíhala na jiných řádcích zdrojového souboru nebo pokud je editace shodná, výsledek automatického sloučení změn je totožný, jako kdyby oba uživatelé pracovali se stejným souborem. 4. Konflikt: V ojedinělých případech, kdy oba uživatelé zároveň editovali různým způsoben stejné řádky, SVN detekuje konflikt. a. SVN provede částečné sloučení, zahlásí konfliktní stav a označí jej zvláštní ikonou (viz. Obrázek 2). b. Konflikt vyřešte editací sporných řádek vyznačených v pracovní kopii. Buďto v libovolném editoru zrevidujte řádky mezi značkami "<<<<<<<" a ">>>>>>>", nebo použijte nástroj TortoiseSvn / Edit Conflicst. c. Konflikt označte za vyřešený pomocí volby TortoiseSvn / Resolved. 5. Zkontrolujte správnost současné verze a potvrďte ji do repository. Popsané automatické slučování změn je možné jen u textových souborů, u binárních je nutné situaci řešit ručně. SVN umožňuje i uzamknutí souborů pro výhradní editaci. SVN ve skutečnosti funguje na principu přenášení změn, tzn. že porovná předchozí vezi souboru (tu si ukládá v adresáři .SVN) a novou verzi. Zjistí např., že přibyl řádek ten a ten, jiný řádek byl změněn a že jste smazali ten a ten soubor. Takto přes zněmy interpretuje stažení nové verze, commit verze i slučování změn a větvení. Pokud se tato operace nepovede, hlásí konflikt.
Označení důležitých verzí 1. Pro projekt, jehož konkrétní verzi chcete označit pro zjednodušení budoucího přístupu, zvolte TortoiseSvn / Branch/Tag. 2. Zadejte adresu, která bude stejná jako adresa projektu. Místo označení aktuální verze "/trunk" ale zadejte předem vytvořený adresář "/tags/" a připište krátký název (viz Obrázek 3). V projektech oddělení vývoje budeme značit verze ve stylu "V_1.2", verze poskytnuté jednotlivým zákazníkům jako "Z_Firma" a importované verze projektů jako "I_ZCvska". 3. Význam verze stručně popište do pole message a ujistěte se že křížek "Switch working copy..." není zatržen. Potvrzením dialogu vznikne v repository snadno přístupná virtuální kopie požadované verze projektu umístěná ve složce tags.
Obrázek 3 - Vytvoření kopie v repository
Práce s větvemi V naší firmě platí zásada, že se v repository na adresách /Zak/Nazev/trunk /trunk nebo /Proj/Nazev/trunk mohou vyskytovat pouze verze, které se mohou objevit v K2ce zákazníka (výjimku tvoří nové projekty). Průběh prací, které zatím nesmí být v trunku, si můžete verzovat verzovat v kopii projektu a po dokončení práce přenést do trunku k zákazníkovi až ostrý výsledek. SVN k tomu poskytuje mechanizmus tzv.. vývojových větví (Branch). ( Větve jsou v podstatě kopií opií projektu v jiné složce, přičemž SVN podporuje přenos změn z jedné složky do druhé (tzv Merge) (viz Obrázek 4). 1. Větev vytvoříte příkazem TortoiseSvn / Branch/Tag. V dialogu zadejte adresu, která bude stejná jako adresa projektu, místo "/trunk" ale zadejte předem vytvořený adresář "/branches/" a připište název větve (např. /branches/Work). Abyste pracovali se založenou větví, tak zaškrtněte "Switch working worki copy...". 2. Změny,, které nyní budete provádět v projektu, budou potvrzovány do větve, jako by se jednalo o samostatný projekt. 3. Nyní chceme zapracovat acovat své změny do ostré větve. Ostrou větev buďto máme někde staženou do jiné pracovní kopie nebo si přepneme svoji pracovní kopii. Přepnutí provedete spuštěním TortoiseSvn / Switch a zadáním větve (v našem případě /Zak/Firma/trunk). /Zak/Firma/trunk) 4. Pro přenos do pracovní kopie spusťte TortoiseSvn / Merge, v průvodci zvolte "Reintegrate a branch", zadejte adresu zdrojové větve (v našem případě /Zak/Firma/branches/Work) a potvrďte dialogy. 5. SVN sloučí změny do pracovní kopie (při opakovaném spuštění se přenesou vždy pouze nové změny).. Zkontrolujte správnost verze, vyřešte případné konflikty a novou verzi potvrďte do repository. • Alternativa: Můžete přenést pouze některé změny z větve (např. pouze Vaše úpravy z testovací větve Linetu do ostré firmy). firmy V tom případě po příkazu TortoiseSvn / Merge zvolte "Merge range of revisions", ions", zadejte adresu zdrojové větve (/Zak/Linet/branches/TestLinet). Rozklikněte ěte Show log a označte označte pouze Vámi provedené změny. Po potvrzení dialogů se přenesou do pracovní kopie pouze tyto změny.
•
Alternativa: Soubor lze vyvětvit i do stejné složky, např. Skript.pas na Skript_Novy.pas, na němž pak budete pracovat, po otestování zákazníkem změny přenesete zpět do Skript.pas a Skript_Novy.pas odstraníte. Při zpracování přes SVN budete mít uchovanou celou historii procesu.
Obrázek 4 - Graf práce s větví projektu
Často kladené dotazy Mohu si lokálně zobrazit SVN detaily souborů? Ano, v Průzkumníku Windows lze u složek spravovaných přes SVN zobrazit SVN detaily souborů (viz Obrázek 5). Pokud je budete chtít opakovaně zobrazovat, tak proveďte následující nastavení: Průzkumník Windows / menu / Nástroje / Možnosti složky / záložka Zobrazení, vypnout zhruba 4. křížek "Pamatovat nastavení každé složky" a též kliknout na tlačítko "Obnovit všechny složky". Pak si již v Průzkumníku nad adresářem spravovaným SVN můžete druhým tlačítkem myši na záhlaví sloupců přidat příslušné detaily, které začínají slovem SVN. Situace je řešitelná i Total Commanderu, ale nastavení je složitější (viz http://tortoisesvn.net/node/32 ).
Obrázek 5 - Detaily souborů spravovaných přes SVN
Mohu používat jiný program pro porovnávání souborů? Pro porovnávání souborů, zvýraznění změn a především pro slučování i řešení konfliktů lze používat libovolný program, který je spustitelný z příkazové řádky (WinMerge, po troše nastavování třeba i MS Word). Osobně doporučuji Perforce Merge, umí i 3-way merge (nedocenitelné při řešení konfliktů) a má velmi řešení příjemný design i ovládání. Stačí nainstalovat tento externí nástroj z V:\Tools\SubVersion\ (z instalačního balíku pouze modul Visual Merge Tool) a v TortoIseSvn / Settings / Diff Tool a / Merge tool nastavit cestu k nainstalovanému p4merge.exe.
Obrázek 6 – Řešení konfliktu pomocí Perforce Merge (porovnávání má rozhraní jednodušší)
Lze do souboru automaticky zapisovat, o jakou revizi se jedná? Ano, do souborů spravovaných přes SubVersion lze pomocí automatické náhrady klíčových slov zapisovat číslo jejich revize, autora či umístěnív repository. Aby se to dělo ve Vámi přidaných souborech, tak je třeba nastavit vlastnost (property) každého souboru svn:keywords= Rev URL ". V hlavičce skriptů pak používám tato klíčová slova (údaje nezadávám - nahradí se): @Repository: $URL: https://svn.syst.cz/svn/K2/Proj/IO_Rozhrani/trunk/K2R/ISTree.pas$ @Verze: $Rev: 24$ Standardně do hlaviček našich skriptů ale klíčová slova pro náhradu nedáváme, protože všechny skripty spravované naší firmou mají být napojeny na SubVersion a protože od K2v130 může být nutné podepisovat aktuální verze souborů, které by se cyklicky měnili jednak podpisem a jednak záměnou klíčového slova revize. Další informace o náhradě klíčových slov získáte v nápovědě TortoiseSvn pod hesly "Project Settings" a "SubWCRev program". Mohu nechat TortoiseSvn zapamatovat své heslo? Na svém počítači na firmě je zapamatování Vašeho jména a hesla úplně v pořádku. Při práci na stroji zákazníka však zapamatování nedávejte. Pokud by se tak omylem stalo, zapamatování odstraňte v TortoiseSvn / Settings / záložka "Saved data" pomocí tlačítka Clear za "Authentication data". Proč se mi nezobrazují ikony stavu u souborů? Pro zobrazení SVN stavu na síťových discích je třeba provést následující nastavení: Zaškrtněte volbu TortoiseSvn / Settings / Icon Overlay / Drive Types / Network drives. Pro zobrazení ikon SVN stavů v Total Commanderu stačí v menu Configuration / Options na záložce Icons zapnout volbu "Show overlay icons". Jak a které soubory z K2ky dávat do repository? Do repository dáváme soubory K2ky zákazníka, které jsou určující pro funkci systému, tedy: • • • • • •
.\SestavyW\Special\ – soubory a podadresáře .\SestavyW\ – vybrané soubory, ale typicky RF_K2.pas .\K2_3main.ini .\Conf\ – definice speciálních poznámkových formulářů (.zbp) .\Mandant\ – vybrané soubory, ale typicky RF_Firm.pas, ExtFields.xml, TabMod.xml .\Mandant\Form_X\ – soubory a podadresáře (bez jazykových mutací stačí Form_0)
Tyto soubory najdete jako šablonu též v repository jako /Zak/_Sablona. Data běžícího zákazníka můžete do repository dostat následovně: 1. přes Repository broswer zkopírovat /Zak/_Sablona na /Zak/NovyZakaznik 2. přejmenovat přes Repository Broswer adresář mandanta /Zak/_Sablona/trunk/Mandant.VLOZ na NovyZakaznik 3. stáhnout trunk do K2ky (lze bez obav do běžící ostré K2ky – šablona neobsahuje soubory nenulové délky a tutíž už z principu nic nemodifikuje) 4. Postupně přidat nové požadované soubory či celé adresáře a odstraniť pomocné *.VLOZ 5. Po potvrzení je hotovo
Aby se v K2ce zákazníka nemotali ikony SVNka, tak doporučuji vypnout křížek TortoriseSVN / Settings / Icon overlay / Show overlay for unversioned items. Jak si mohu SVN rozbít? Pokud byste ve své lokální kopii provedly nežádoucí změny a neuváženě potvrdili tyto změny, tak v repository vznikne odpovídající nežádoucí verze (třeba i se smazanými adresáři). Původní verze tam ale zůstává a lze se k ní vrátit. Lokální pracovní kopii můžete rozbít manipulací se skrytým adresářem .SVN, který obsahuje veškeré údaje o napojení na repository a předchozí verzi. Nicméně, tím nepřijdete o své soubory, stačí si znovu jinam stáhnout verzi ze serveru a zanést Vaše změny. Pro zrušení vazby na SubVersion stačí odstranit všechny .SVN podadresáře projektu. Kde mohu získat další informace o SubVersion? • V nápovědě vyvolané přes TortoiseSvn / Help. • Na internetu (Google, http://subversion.tigris.org/ , http://tortoisesvn.tigris.org/ , http://svnbook.red-bean.com/ ) • Od svých kolegů nebo ve složitějších případech od Ondry Horáčka jakožto našeho garanta pro SubVersion.
Rejstřík Add, 2 Blame, 3 Branch, 5 Branch/Tag, 4, 5 Diff, 3 Edit Conflicts, 4 Export, 2 Help, 8 Checkout, 2 Ignore list, 3 Import, 3 Konflikt, 4 Merge, 5 Náhrada klíčových slov, 7 Princip, 4 Property, 7
Remove, 2 Repository, 1 Resolved, 4 Settings, 3, 7, 8 Show log, 3 síťový disk, 8 sloučení změn, 4 SubVersion, 1 SVN. viz SubVersion SVN detaily souborů, 7 svn:keywords, 7 Switch, 5 TortoiseSVN, 1 Total Commander, 1, 7, 8 Update, 2
