Přejít na:

Při tvorbě dokumentů v TeXu nebo (X)HTML můžeme používat obdobné prostředky pro správu verzí jako při programování. Jedním z nejjednodušších takových prostředků je systém Subversion (SVN); multiplatformní svobodný open-source klient–server systém pro správu verzí dostupný pro mnoho unixových operačních systémů a MS Windows.

Subversion zejména usnadňuje souběžnou práci více uživatelů na jednom projektu a zajišťuje trvalé uchování historických verzí projektu. Je založena na pracovním postupu kopie–úprava–sloučení, tedy data ze společného centrálního repositáře jsou stažena do soukromé lokální kopie, tam jsou modifikována, a pak je upravená verze odeslána zpět do repositáře (a tím zpřístupněna ostatním uživatelům).

Pozor: V rámci tohoto cvičení bude vhodné pracovat ve dvojicích. Už na začátku cvičení se proto prosím dohodněte s některým ze svých sousedů, se kterým budete později spolupracovat na ukázkových dokumentech. Pokud na vás dvojice nevyjde, můžete spolupracovat se cvičícím.

Není reálné stihnout úkoly spojené se systémem Subversion i systémem Git v rámci jednoho cvičení. Domluvte se proto se sousedem, který ze systémů během cvičení použijete. Pro úplné začátečníky je doporučeno použít systém Subversion.

Tip: Krom základního klienta pro příkazovou řádku a přímé integrace v různých IDE existuje několik grafických Subversion klientů.

Přejít: navigace | na začátek stránky | na konec stránky

Základy práce se Subversion

Systém Subversion (SVN) uplatňuje asymetrický klient–server model, ve kterém mnoho uživatelů pracuje s jedním centrálním SVN repositářem. V rámci rychlého úvodu do systému tedy budeme předpokládat, že pro nás SVN server někdo založil a my se nacházíme v roli uživatele, který chce repositář využívat.

V prvním kroku si stáhneme aktuální revizi souborů z repositáře příkazem svn checkout. svn checkout "<adresa repositáře>"
Server nás může požádat o autentizaci a následně již dojde ke stažení obsahu repositáře.

Soubory ve stažené pracovní kopii můžeme libovolně upravovat. V případě že jsme vytvořili nový soubor a přejeme si jej do repositáře začlenit s další revizí, použijeme příkaz svn add. svn add "<název souboru>"
Pakliže jsme změnili svůj názor a soubor do repositáře nebudeme chtít začlenit, použijeme příkaz svn delete. svn delete --keep-local "<název souboru>"
Pro kopírování, přesun a mazání souborů pak využijeme příkazy svn copy, svn movesvn delete. svn copy "<název kopírovaného souboru>" "<název nového souboru>"
svn move "<název přesouvaného souboru>" "<název nového souboru>"
svn delete "<název mazaného souboru>"
Pro zobrazení shrnutí našich změn oproti poslední revizi použijeme příkaz svn status. Pokud si přejeme zobrazit, jak naše změny ovlivnily obsah souborů, použijeme příkaz svn diff.

Tip: Subversion klient má integrovanou nápovědu: svn help
svn <podpříkaz> --help
svn checkout --help
svn log --help
svn diff --help

Ve chvíli, kdy jsme se svými změnami spokojeni, je můžeme zanést do repositáře. Nejprve si však pomocí příkazu svn update stáhneme veškeré nejnovější změny v repositáři. Pokud se změny netýkaly stejných částí souborů, které jsme editovali my, budou automaticky začleněny do naší pracovní kopie, aniž bychom museli řešit konflikty. Následně své změny odešleme do repositáře příkazem svn commit jako novou revizi. svn commit -m "<výstižný komentář k našim změnám>"

Pro zobrazení veškerých revizí uložených v repositáři použijeme příkaz svn log. Pro výpis obsahu souboru v konkrétní revizi pak použijeme příkaz svn cat. svn cat -r<číslo revize> "<název souboru>" Pro zobrazení veškerých změn mezi dvěma revizemi použijeme přikaz svn diff. svn diff -r<číslo počáteční revize>:<číslo koncové revize>
svn diff -r<číslo počáteční revize>:<číslo koncové revize> "<název souboru, který nás zajímá>"

Podrobné informace o systému Subversion naleznete v oficiální dokumentaci Subversion book. Tutorial pro použití Subversion při vývoji TeXových dokumentů vyšel jako článek ve Zpravodaji CSTUG (DOI: 10.5300/2011-1/21).

Přejít: navigace | na začátek stránky | na konec stránky

Použití s TeXem

Všichni studenti FI MU si mohou pro své projekty založit SVN repositář na fakultním serveru v k tomu určené aplikaci Fakultní administrativy.

  1. Založte si každý svůj vlastní repositář pojmenovaný ve tvaru <váš-fi-login>_PB029_cv4 (PB verzálkami!).
  2. Po vytvoření repositáře dodatečně přidělte
    • právo čtení pro uživatele sojka, xruzick7xnovot32,
    • právo zápisu pro svého souseda, se kterým budete na cvičení spolupracovat na cvičných dokumentech.
  3. Stáhněte si svůj repositář ze serveru do pracovní kopie na disku, kde budete provádět úpravy. Na Windows můžete použít grafického klienta TortoiseSVN; nabídka jeho funkcí je dostupná pod pravým tlačítkem myši ve správci souborů a informace o pokročilejších úkonech naleznete v online manuálu. Na všech platformách je pak dostupný klient pro příkazovou řádku (části vyznačené kurzívou nahraďte svými údají): $ cd ~
    $ svn checkout "https://svn.fi.muni.cz/fi/xruzick7_PB029_cv4/"
    Checked out revision 0.
  4. Stáhněte si jednoduchý LaTeXový dokument, ve kterém budete provádět korekturu, a uložte jej do kořenového adresáře vaší pracovní kopie: $ cd xruzick7_PB029_cv4/
    $ wget "https://www.fi.muni.cz/lemma/PB029/practices/sprava-verzi/files/dokument.tex"
    --2016-09-13 00:50:50-- https://www.fi.muni.cz/lemma/PB029/practices/sprava-verzi/files/dokument.tex
    Překládám www.fi.muni.cz (www.fi.muni.cz)… 147.251.48.1, 2001:718:801:230::1
    Navazuje se spojení s www.fi.muni.cz (www.fi.muni.cz)|147.251.48.1|:443… spojeno.
    HTTP požadavek odeslán, program čeká na odpověď… 200 OK
    Délka: 1121 (1,1K) [text/plain]
    Ukládám do: „dokument.tex“

    dokument.tex 100%[===================>] 1,09K --.-KB/s in 0s

    2016-09-13 00:50:50 (18,3 MB/s) – „dokument.tex“ uloženo [1121/1121]
    Následně dokument přidejte do seznamu souborů spravovaných systémem Subversion. $ svn add dokument.tex
    A dokument.tex
  5. Tuto původní verzi dokumentu, dosud bez vašich úprav, odešlete jako první revizi projektu do vašeho SVN repositáře na serveru. Nezapomeňte revizi vhodně okomentovat! $ svn commit -m "Vložen původní TeXový dokument pro korekturu."
    Adding         dokument.tex
    Transmitting file data .
    Committed revision 1.
    Pokud komentář neuvedete jako argument parametru -m, budete vyzvání k zadání komentáře interaktivně v textovém editoru.
  6. Nyní si otevřete soubor dokument.tex ve svém oblíbeném textovém editoru a v prvním odstavci textu, tzn. před značkou %%%, vyhledejte a opravte chyby. Následně si můžete snadno ověřit, že systém Subversion ví o změnách provedených v dokumentu. $ svn status
    M       dokument.tex
    Provedené změny si můžete snadno zobrazit. $ svn diff Opravený text odešlete s vhodným komentářem na server jako novou revizi. $ svn commit -m "Opraven první odstavec textu."
    Sending         dokument.tex
    Transmitting file data .
    Committed revision 2.
  7. Nyní nastává čas na spolupráci na dokumentu s vaším sousedem. Zjistěte si adresu jeho repositáře s jeho dokumentem, ve kterém provedl opravu prvního odstavce textu. (Pokud provedl správně nastavení přístupových práv při zakládání repositáře, měli byste mít právo přistupovat do jeho repositáře pro čtení i zápis.) Stáhněte si aktuální verzi obsahu jeho repositáře někam na disk, ale mimo pracovní kopii vašeho repositáře! $ cd ~
    $ svn checkout "https://svn.fi.muni.cz/fi/sojka_PB029_cv4/"
    A    sojka_PB029_cv4/dokument.tex
    Checked out revision 2.
    $ cd sojka_PB029_cv4/
  8. Prohlédněte si, jak soused dosud postupoval při vývoji svého dokumentu: $ svn log --verbose
  9. Následně se podívejte, jaké opravy provedl v prvním odstavci textu příkazem diff SVN klienta. Pokud byly změny provedeny v jediné revizi (např. revizi č. 2), použijte příkaz: $ svn diff -c2 Pokud bylo opravných revizí více (např. opravy odesílal postupně v revizích 2 až 4), můžete použít příkaz: $ svn diff -r1:4 Pokud najdete rozdíly mezi jeho a svým řešením, proveďte nutné opravy a novou verzi dokumentu odešlete na server příkazem svn commit (viz výše).
  10. Nyní si otevřete soubor dokument.tex svého souseda a ve druhém odstavci textu, tzn. za značkou %%%, vyhledejte a opravte chyby. Následně opravený text odešlete s vhodným komentářem do sousedova repozitáře jako novou revizi. $ svn commit -m "Opraven druhý odstavec textu."
    Sending         dokument.tex
    Transmitting file data .
    Committed revision 3.
  11. Vyčkejte, až opravu druhého odstavce textu provede také váš soused ve vašem dokumentu a odešle ji do vašeho repositáře. Následně se vraťte do pracovní kopie svého repositáře $ cd ~/xruzick7_PB029_cv4/ začleňte si změny, které odeslal do vašeho repositáře váš soused $ svn update
    Updating ".":
    U    dokument.tex
    Updated to revision 3.
    a zkontrolujte, zda nalezl a opravil stejné chyby jako vy: $ svn diff -c3 (Parametry příkazu diff samozřejmě upravte, pokud se čísla revizí ve vašem případě liší.)
  12. Na závěr si můžete prohlédnout seznam revizí $ svn log -v a kompletní souhrn změn, které byly v původní verzi dokumentu provedeny $ svn diff -r1:HEAD dokument.tex vypsat původní verzi dokumentu tak, jak vypadal v revizi 1 $ svn cat -r1 dokument.tex apod. Všechny verze odeslané do repositáře na server jsou zde navždy k dispozici v nezměnitelné podobě a můžeme se k nim v případě potřeby kdykoliv vrátit.
Přejít: navigace | na začátek stránky | na konec stránky

Použití s textovými procesory [nepovinné za 1 bonusový bod]

Jistou omezenou podporu pro týmovou spolupráci poskytují také textové procesory typu MS Office Word nebo LibreOffice Writer. Na počítačích v učebně je instalován kancelářský balík LibreOffice, na kterém si podporu sledování změn v textových procesorech vyzkoušíte.

  1. Stáhněte si a do svého repositáře uložte jednoduchý OpenDocument dokument: $ cd ~/xruzick7_PB029_cv4/
    $ wget "https://www.fi.muni.cz/lemma/PB029/practices/sprava-verzi/files/dokument.odt"
    --2016-09-13 00:53:42-- https://www.fi.muni.cz/lemma/PB029/practices/sprava-verzi/files/dokument.odt
    Překládám www.fi.muni.cz (www.fi.muni.cz)… 147.251.48.1, 2001:718:801:230::1
    Navazuje se spojení s www.fi.muni.cz (www.fi.muni.cz)|147.251.48.1|:443… spojeno.
    HTTP požadavek odeslán, program čeká na odpověď… 200 OK
    Délka: 19673 (19K) [application/vnd.oasis.opendocument.text]
    Ukládám do: „dokument.odt“

    dokument.odt 100%[========================>] 19,21K --.-KB/s in 0,007s

    2016-09-13 00:53:42 (2,77 MB/s) – „dokument.odt“ uloženo [19673/19673]
    Následně dokument přidejte do seznamu souborů spravovaných systémem Subversion. $ svn add dokument.odt
    A  (bin)  dokument.odt
    Jak vidíte, je soubor SVN klientem rozpoznán jako binární. Binární soubory je možné spravovat systémem Subversion, ovšem práce s nimi je komplikovanější. Není například možné si snadno zobrazit rozdíl mezi dvěma verzemi binárního souboru, tak jak to bylo možné příkazem svn diff u textových souborů.
  2. Tuto původní verzi dokumentu, dosud bez vašich úprav, odešlete do vašeho SVN repositáře na server. $ svn commit -m "Vložen původní OpenDocument dokument pro korekturu."
    Adding  (bin)  dokument.odt
    Transmitting file data .
    Committed revision 4.
  3. Nyní si otevřete soubor dokument.odt v LibreOffice Writer a v nastavení textového procesoru vyplňte svoje jméno, příjmení a iniciály, které budou použity pro identifikaci autorů změn. Nástroje → Možnosti … → LibreOffice → Uživatelské údaje
  4. Před prováděním jakýchkoliv úprav textu zapněte sledování změn v menu Úpravy → Sledování změn → Záznam
  5. V první části textu před horizontální linkou vyhledejte a opravte chyby. Prováděné změny budou v režimu sledování změn graficky vyznačeny, pokud tuto funkci nevypnete volbou Úpravy → Sledování změn → Zobrazit.
    Tip: Velmi obdobným způsobem je možné sledování změn aktivovat také v MS Office Word: Revize → Sledování změn Na kartě Revize můžete také v rozbalovacím menu snadno přepínat mezi různými způsoby zobrazení dokumentu:
    • Konečný se značkami graficky vyznačuje změny provedené v dokumentu,
    • volba Konečný zobrazuje novou podobu dokumentu bez vyznačení změn,
    • obdobné volby Původní se značkamiPůvodní pak pracují s původní podobou dokumentu před provedením sledovaných změn.
  6. Opravený text uložte a ověřte, že SVN ví o změnách v tomto souboru ve vaší pracovní kopii. $ svn status
    M       dokument.odt
    Všechny změny odešlete s vhodným komentářem na server jako novou revizi projektu. $ svn commit -m "Opraven první odstavec OpenDocument dokumentu."
    Sending         dokument.odt
    Transmitting file data .
    Committed revision 5.
  7. Nyní budete opět spolupracovat s vaším sousedem. Až odešle svou korekturu prvního odstavce OpenDocument dokumentu na server, přejděte do adresáře odpovídajícího jeho repositáři a aktualizujte svou pracovní kopii: $ cd ~/sojka_PB029_cv4/
    $ svn update
    Updating ".":
    A    dokument.odt
    Updated to revision 5.
  8. Otevřete si právě stažený dokument vašeho souseda a zkontrolujte jím provedené korektury v prvním odstavci. Úpravy → Sledování změn → Přijmout nebo odmítnout … V zobrazeném okně můžete myší vybrat jednotlivé zaznamenané změny. Místo editace bude zvýrazněno přímo v dokumentu. Následně můžete tlačítky Přijmout/Odmítnout jednotlivé úpravy potvrdit nebo zrušit.
  9. Po schválení/odmítnutí změn navržených vaším sousedem v prvním odstavci proveďte případné další nezbytné úpravy textu před horizontálním oddělovačem. Následně proveďte korektury i ve zbytku textu, novou podobu dokumentu uložte a odešlete do repositáře vašeho souseda. $ svn commit -m "Zpracovány korektury prvního odstavce a opraven druhý odstavec OpenDocument dokumentu."
    Sending         dokument.odt
    Transmitting file data .
    Committed revision 6.
  10. Vyčkejte na dokončení a odeslání oprav vašeho dokumentu vaším sousedem. Pak se vraťte do pracovní kopie svého repositáře a aktualizujte svou pracovní kopii: $ cd ~/xruzick7_PB029_cv4/
    $ svn update
    Updating ".":
    U    dokument.odt
    Updated to revision 6.
  11. Opět zkontrolujte navržené korektury a známým postupem je schvalte nebo odmítněte. Následně vypněte sledování změn v tomto dokumentu, dokument uložte a finální verzi odešlete na server jako novou revizi projektu. $ svn commit -m "Konečná schválená verze OpenDocument dokumentu."
    Sending         dokument.odt
    Transmitting file data .
    Committed revision 7.

Tip: V LibreOffice Writer je možné vedle sledování změn ukládat na úrovni souboru s dokumentem jeho revize obdobně, jako jsou ukládány revize v SVN. (V MS Office Word obdobná možnost chybí.) Soubor → Verze … → Uložit novou verzi Uložené verze si můžete později zobrazit nebo z nich vytvořit nový dokument obsahově odpovídající dané verzi. Uloženou revizi můžete také porovnat s aktuální podobu dokumentu a přijmout/odmítnout jednotlivé rozdíly mezi oběma podobami dokumentu.

Tip: V případě nedůsledné organizace spolupráce více autorů na společném dokumentu se můžete dostat do situace, kdy existují dva samostatné soubory s dokumentem a oba obsahují rozdílné změny, které je třeba sloučit pro vytvoření finální podoby dokumentu. V tomto případě můžete využít funkce porovnání dokumentů:

  • LibreOffice Writer Úpravy → Porovnat dokument …
  • MS Office Word Revize → Porovnat
Přejít: navigace | na začátek stránky | na konec stránky

Praktické úkoly k procvičení [nepovinné]

Přejít: navigace | na začátek stránky | na konec stránky