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.
Přejít: navigace | na začátek stránky | na konec stránky
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.
Přejít: navigace | na začátek stránky | na konec stránky
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:
- Na GitLabu FI vytvořte tlačítkem „New project“ nový repositář pojmenovaný PB029_sprava_verzi.
- 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“.
-
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.
-
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
Následně dokument přidejte do seznamu souborů spravovaných systémem Git.
$ 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]
$ git add dokument.tex
-
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."
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.
[main (root-commit) 917ae6b] Vložen původní TeXový dokument pro korekturu.
1 file changed, 38 insertions(+)
create mode 100644 dokument.tex
$ 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 -
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
Provedené změny si můžete snadno zobrazit.
On branch main
Your branch is up-to-date with "origin/main".
Changes not staged for commit:
(use "git add..." to update what will be committed)
(use "git checkout --..." to discard changes in working directory)
modified: dokument.tex
no changes added to commit (use "git add" and/or "git commit -a")
$ 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
-
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.
-
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.
-
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
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 show 4b6a5b5
$ git show HEAD
$ 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). -
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
-
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
a zkontrolujte, zda nalezl a opravil stejné chyby jako vy:
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(-)
$ git diff 4b6a5b5..03d5b8e
Parametry příkazu diff upravte, pokud se názvy verzí ve vašem případě liší. -
Na závěr si můžete prohlédnout seznam revizí
$ git log
a kompletní souhrn změn, které byly v původní verzi dokumentu provedeny
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.
$ 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.
Přejít: navigace | na začátek stránky | na konec stránky
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ů.
Přejít: navigace | na začátek stránky | na konec stránky
Nahlašování chyb na webu předmětu
- Vytvořte si kopii Git repositáře s webem předmětu přes tlačítko „Fork“.
- 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“.
-
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' -
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
Následně své změny odešlete do svého repositáře na GitLabu FI.
$ git commit --message "Fixed a typo on title page"
$ git push origin fix/typo-on-title-page
- 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.
$ 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.
Přejít: navigace | na začátek stránky | na konec stránky
Nahlašování chyb v autorské kuchařce
- Založte si účet na webové službě GitHub.
- 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.
- Vytvořte si kopii Git repositáře s autorskou kuchařkou přes tlačítko „Fork“.
-
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"
-
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' -
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
Následně své změny odešlete do svého repositáře na službě GitHub.
$ git commit --message "Fixed a typo in Chapter 2"
$ git push origin fix/chapter-two
- 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.