# PB029: Správa verzí elektronických dokumentů

Při přípravě elektronických dokumentů je žádoucí udržovat historii předchozích verzí, které vám v případě nutnosti umožní vrátit se ke starší verzi dokumentu, obnovit již smazané nebo upravené části textu, apod. S údržbou historie předchozích verzí vám mohou pomoci programy pro správu verzí.

Na tomto cvičení si představíme program Git pro správu verzí a službu GitLab FI, na které můžete své projekty spravované Gitem zveřejnit. Ukážeme si, jak můžete Git a GitLab FI využít při práci s TeXem a při nahlašování chyb ve studijních materiálech předmětu za bonusové body.

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.

## Správa verzí pomocí programu Git

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 takových prostředků je program Git. Git usnadňuje souběžnou práci více uživatelů na jednom projektu a zajišťuje trvalé uchování historických verzí projektu.

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

Tip: Více informací o systému Git se můžete dozvědět v seminární skupině „Mastering Git“ předmětu FI:PV177 Laboratory of Advanced Network Technologies vypisovaném v podzimním semestru 2022.

GitLab FI je webová služba dostupná studentům FI MU (osobám s fakultním účtem). Pomocí GitLab FI můžete zveřejňovat projekty, které spravujete pomocí programu Git, a spolupracovat na cizích projektech.

Tip: Více informací o službě GitLab FI najdete na webu FI MU.

## Použití Gitu s TeXem

Kromě udržování historie předchozích verzí umožňují programy pro správu verzí kolaborativní práci na textových dokumentech. Autoři, korektoři a redaktoři mohou nezávisle na sobě upravovat sdílený dokument. V případě, že více uživatelů upraví stejnou část dokumentu, program pro správu verzí konflikt rozpozná a napomůže s jeho vyřešením.

Utvořte dvojici a vyzkoušejte si kolaborativní práci na textových dokumentech pomocí Gitu:

1. Na GitLabu FI vytvořte tlačítkem „New project“ nový repositář pojmenovaný `PB029_sprava_verzi`.
2. Po vytvoření repositáře přidejte v levé postranní nabídce „Manage“ → „Members“ tlačítkem „Invite members“ svého souseda, se kterým budete na cvičení spolupracovat na cvičných dokumentech s přístupovými právy „Choose a role permission“ nastavenými na hodnotu „Developer“.
3. Nastavte základní informace o sobě a stáhněte si svůj repositář ze serveru do pracovní kopie na disku, kde budete provádět úpravy. Adresu stahovaného repositáře najdete na GitLabu FI pod tlačítkem „Clone“ v poli „Clone with HTTPS“.

   Tip: Na Windows můžete použít grafického klienta Git GUI; 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, který používáme v příkladech na této stránce. Části vyznačené kurzívou nahraďte svými údaji.

   Webová služba GitLab FI vám umožňuje přidávat, mazat, upravovat a přesouvat soubory přímo ze svého webového prohlížeče. Díky tomu můžete bod 3 v tomto seznamu přeskočit a následně se zcela vyhnout práci s příkazovou řádkou. Tento postup je ale vhodný pouze pro drobné úpravy v jednoduchých repositářích; alespoň jednou si proto vyzkoušejte plnohodnotný postup s vytvořením pracovní kopie na disku.

   `$ cd ~
   $ git config --global user.name "Vít Starý Novotný"
   $ git config --global user.email "witiko@mail.muni.cz"
   $ git clone https://gitlab.fi.muni.cz/xnovot32/PB029_sprava_verzi.git xnovot32_PB029_sprava_verzi
   Cloning into "xnovot32_PB029_sprava_verzi"...
   warning: You appear to have cloned an empty repository.
   Checking connectivity... done.
   `
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 xnovot32_PB029_sprava_verzi
   $ wget https://sojka.pages.fi.muni.cz/PB029_web/practices/sprava-verzi/files/dokument.tex
   --2016-09-13 00:50:50-- https://sojka.pages.fi.muni.cz/PB029_web/practices/sprava-verzi/files/dokument.tex
   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 Git. `$ git add dokument.tex`
5. Tuto původní verzi dokumentu, dosud bez vašich úprav, vložte jako první revizi do svého lokálního repositáře. Nezapomeňte revizi vhodně okomentovat! `$ git commit --message "Vložen původní TeXový dokument pro korekturu."
   [main (root-commit) 917ae6b] Vložen původní TeXový dokument pro korekturu.
   1 file changed, 38 insertions(+)
   create mode 100644 dokument.tex
   ` Pokud komentář neuvedete pomocí parametru `--message`, budete vyzvání k zadání komentáře interaktivně v textovém editoru. Následně své změny odešlete do vašeho repositáře na fakultním serveru. `$ git push
   Counting objects: 3, done.
   Delta compression using up to 2 threads.
   Compressing objects: 100% (2/2), done.
   Writing objects: 100% (3/3), 981 bytes | 0 bytes/s, done.
   Total 3 (delta 0), reused 0 (delta 0)
   To https://gitlab.fi.muni.cz/xnovot32/PB029_sprava_verzi.git
   * [new branch] main -> main`
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 Git ví o změnách provedených v dokumentu. `$ git status
   On branch main
   Your branch is up-to-date with "origin/main".
   Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
   (use "git checkout -- <file>..." to discard changes in working directory)
   modified: dokument.tex
   no changes added to commit (use "git add" and/or "git commit -a")
   ` Provedené změny si můžete snadno zobrazit. `$ git diff` Opravený text odešlete s vhodným komentářem na server jako novou revizi. `$ git add dokument.tex
   $ git commit --message "Opraven první odstavec textu."
   [main 4b6a5b5] Opraven první odstavec textu.
   1 file changed, 2 insertions(+), 2 deletions(-)
   $ git push
   Counting objects: 3, done.
   Delta compression using up to 2 threads.
   Compressing objects: 100% (2/2), done.
   Writing objects: 100% (3/3), 311 bytes | 0 bytes/s, done.
   Total 3 (delta 1), reused 0 (delta 0)
   To https://gitlab.fi.muni.cz/xnovot32/PB029_sprava_verzi.git
   917ae6b..4b6a5b5 main -> main
   `
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 soused správně nastavil přístupová práva při zakládání svého repositáře, měli byste mít právo přistupovat do jeho repositáře pro čtení i zápis. Stáhněte si sousedův repositář mimo pracovní kopii svého repositáře. `$ cd ~
   $ git clone https://gitlab.fi.muni.cz/sojka/PB029_sprava_verzi.git sojka_PB029_sprava_verzi
   Cloning into "sojka_PB029_sprava_verzi"...
   remote: Counting objects: 6, done.
   remote: Compressing objects: 100% (4/4), done.
   remote: Total 6 (delta 1), reused 0 (delta 0)
   Receiving objects: 100% (6/6), done.
   Resolving deltas: 100% (1/1), done.
   Checking connectivity... done.
   `
8. Prohlédněte si, jak soused dosud postupoval při vývoji svého dokumentu: `$ cd sojka_PB029_sprava_verzi
   $ git log
   commit 4b6a5b58b25e6399347dcc210f0a4aff4a5ebaee
   Author: Petr Sojka
   Date: Mon Sep 12 16:13:10 2016 +0200
   Opraven první odstavec textu.
   commit 917ae6b16c04cfb5fbc277972bb857cfea709f8a
   Author: Petr Sojka
   Date: Mon Sep 12 15:47:55 2016 +0200
   Vložen původní TeXový dokument pro korekturu.
   `
9. Následně se podívejte, jaké opravy soused provedl v prvním odstavci textu příkazem `diff`. Pokud byly změny provedeny v jediné revizi (např. v revizi s hašem 4b6a5b5… tak jako v přechozí ukázce kódu), použijte libovolný z následujících příkazů: `$ git show 4b6a5b58b25e6399347dcc210f0a4aff4a5ebaee
   $ git show 4b6a5b5
   $ git show HEAD
   ` Pokud bylo opravných revizí více, např. pokud soused opravy odesílal postupně v posledních čtyřech revizích, můžete použít následující příkaz: `$ git diff HEAD~4..HEAD` Pokud najdete rozdíly mezi svým a sousedovým řešením, proveďte nutné opravy (příkaz `commit`) a novou verzi dokumentu odešlete na server (příkaz `push`).
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 repositáře jako novou revizi. `$ git add dokument.tex
    $ git commit --message "Opraven druhý odstavec textu."
    $ git push
    Counting objects: 3, done.
    Delta compression using up to 2 threads.
    Compressing objects: 100% (2/2), done.
    Writing objects: 100% (3/3), 307 bytes | 0 bytes/s, done.
    Total 3 (delta 1), reused 0 (delta 0)
    To https://gitlab.fi.muni.cz/sojka/PB029_sprava_verzi.git
    4b6a5b5..03d5b8e main -> main
    `
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 xnovot32_PB029_sprava_verzi
    ` začleňte změny, které odeslal do vašeho repositáře váš soused `$ git pull
    remote: Counting objects: 3, done.
    remote: Compressing objects: 100% (2/2), done.
    remote: Total 3 (delta 1), reused 0 (delta 0)
    Unpacking objects: 100% (3/3), done.
    From https://gitlab.fi.muni.cz/xnovot32/PB029_sprava_verzi.git
    * branch main -> FETCH_HEAD
    4b6a5b5..03d5b8e main -> origin/main
    Updating 4b6a5b5..03d5b8e
    Fast-forward
    dokument.tex | 6 +++---
    1 file changed, 3 insertions(+), 3 deletions(-)
    ` a zkontrolujte, zda nalezl a opravil stejné chyby jako vy: `$ git diff 4b6a5b5..03d5b8e` Parametry příkazu `diff` upravte, pokud se názvy verzí ve vašem případě liší.
12. Na závěr si můžete prohlédnout seznam revizí `$ git log
    commit 03d5b8e295bac5852ce3d9e68d39308e1accd77c
    Author: Petr Sojka
    Date: Mon Sep 12 22:06:18 2016 +0200
    Opraven druhý odstavec textu.
    commit 4b6a5b58b25e6399347dcc210f0a4aff4a5ebaee
    Author: Vít Starý Novotný
    Date: Mon Sep 12 16:13:10 2016 +0200
    Opraven první odstavec textu.
    commit 917ae6b16c04cfb5fbc277972bb857cfea709f8a
    Author: Vít Starý Novotný
    Date: Mon Sep 12 15:47:55 2016 +0200
    Vložen původní TeXový dokument pro korekturu.
    ` a kompletní souhrn změn, které byly v původní verzi dokumentu provedeny `$ git diff 917ae6b..HEAD dokument.tex` vypsat původní verzi dokumentu tak, jak vypadal v první revizi `$ git show 917ae6b: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.

## Nahlašování chyb v materiálech předmětu

Pokud objevíte chybu v materiálech předmětu, můžete ji za bonusové body nahlásit, vizte prémiové úkoly. Pokud se jedná o chybu v přednáškových slidech nebo interaktivní osnově, můžete ji nahlásit vyučujícím osobně nebo e-mailem. Pokud jde ale o chybu na tomto webu, nebo v autorské kuchařce, můžete se také pocvičit v práci s Gitem a chybu přímo opravit v repositáři za extra bonusové body.

Tip: Další bonusové body můžete získat za využití programu pro správu verzí při přípravě svých zápočtových dokumentů.

### Nahlašování chyb na webu předmětu

1. Vytvořte si kopii Git repositáře s webem předmětu přes tlačítko „Fork“.
2. Podobně jako v předchozím zadání nastavte základní informace o sobě a stáhněte si svůj repositář ze serveru do pracovní kopie na disku, kde budete provádět úpravy. Adresu stahovaného repositáře najdete ve své kopii repositáře na GitLabu FI pod tlačítkem „Clone“ v poli „Clone with HTTPS“.
`$ git config --global user.name "Vít Starý Novotný"
$ git config --global user.email "witiko@mail.muni.cz"
$ git clone "https://gitlab.fi.muni.cz/xnovot32/xnovot32_PB029_web.git"
Cloning into "xnovot32_PB029_web"...
Checking connectivity... done.
`
3. Vytvořte si ve svém lokálním repositáři samostatnou pojmenovanou větev, ve které budete provádět úpravy. `$ cd PB029_web/
   $ git checkout -B fix/typo-on-title-page
   Switched to a new branch 'fix/typo-on-title-page'`
4. Pomocí svého oblíbeného textového editoru upravte např. soubor `public/content.html` a zaneste své úpravy jako revizi do své pracovní kopie: `$ git add public/content.html
   $ git commit --message "Fixed a typo on title page"
   ` Následně své změny odešlete do svého repositáře na GitLabu FI. `$ git push origin fix/typo-on-title-page
   `
5. V repositáři s webem předmětu v záložce „Merge requests“ klikněte na tlačítko „New merge request“ a vytvořte požadavek na začlenění změn z svého repositáře `xnovot32/PB029_web` a větve `fix/typo-on-title-page` do repositáře `sojka/PB029_web` a větve `main`.

### Nahlašování chyb v autorské kuchařce

1. Založte si účet na webové službě GitHub.
2. Na stroji, na kterém pracujete, si vytvořte SSH klíč a přidejte veřejnou část klíče do svého GitHub účtu jako prostředek pro autentizaci Gitu vůči službě GitHub. Postupujte podle návodu v dokumentaci služby GitHub.
3. Vytvořte si kopii Git repositáře s autorskou kuchařkou přes tlačítko „Fork“.
4. Podobně jako v předchozím zadání nastavte základní informace o sobě a stáhněte si svůj repositář ze serveru do pracovní kopie na disku, kde budete provádět úpravy. Adresu stahovaného repositáře najdete ve své kopii repositáře na GitHubu pod tlačítkem „Clone“ v poli „Clone with HTTPS“. `$ git clone "git@github.com:xnovot32/tt101.git"
   `
5. Vytvořte si ve svém lokálním repositáři samostatnou pojmenovanou větev, ve které budete provádět úpravy. `$ cd tt101/
   $ git checkout -B fix/chapter-two
   Switched to a new branch 'fix/chapter-two'`
6. Pomocí svého oblíbeného textového editoru upravte např. soubor `chapters/markup.tex` a zaneste své úpravy jako revizi do své pracovní kopie: `$ git add chapters/markup.tex
   $ git commit --message "Fixed a typo in Chapter 2"
   ` Následně své změny odešlete do svého repositáře na službě GitHub. `$ git push origin fix/chapter-two
   `
7. V repositáři s autorskou kuchařkou v záložce „Pull requests“ klikněte na tlačítko „New pull request“ a vytvořte požadavek na začlenění změn z svého repositáře `xnovot32/tt101` a větve `fix/chapter-two` do repositáře `witiko/tt101` a větve `main`.