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.

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.

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.

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:

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 ..." 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")
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.

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.

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

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.

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

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.

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

Navigace:

• PB029
  • Správa verzí pomocí programu Git
  • Použití Gitu s TeXem
  • Nahlašování chyb v materiálech předmětu
    • Nahlašování chyb na webu předmětu
    • Nahlašování chyb v autorské kuchařce

   

Copyright © 2005–2023 Petr Sojka, Michal Růžička, Dávid Lupták, Vít Starý Novotný, Tereza Vrabcová, Marie Stará