Git repozitář

Založení repozitáře

Opakující studenti

Pokud jste předmět měli zapsaný v dřívějších semestrech, starý repozitář přesuňte a vytvořte znovu podle návodu níže.

Projekt lze přesunout v nastavení: Project → Settings → General → Advanced (dolů) → Change path

  • Přihlaste se do fakultního GitLabu

    Pro přihlášení použijte fakultní login (xNĚCO) a fakultní heslo.

  • Vytvořte si kopii šablony projektu

    Nalezněte projekt Student Repository Template ve jmenném prostoru pb071 a klikněte v něm na tlačítko Fork.

    fork 1

  • Vyplňte formulář pro klonování šablony

    1. Název projektu změňte na PB071 a cestu (Project Stub) pb071. Na názvu projektu nezáleží, je však nezbytné, aby cesta byla nastavena přesně.

    2. Poté vyberte cíl, což bude váš fakultní login (xprijmeni nebo xUČO).

    3. Změňte viditelnost projektu na Private. Pokud odevzdáte svoje řešení do veřejného projektu, bude přístupné i jiným studentům!

    4. Pokud vidíte nastavení Branches to include, vyberte možnost Only the default branch main.

    5. Ještě jednou si podle obrázku ověřte, že jste vyplnili vše, a nakonec klikněte Fork.

    fork 2

  • Zrušte Fork Relationship

    Jinak se vám může stát, že omylem vytvoříte Merge Request vůči původnímu veřejnému repozitáři, a vaše řešení uvidí ostatní studenti.

    V levém panelu vyberte Settings → General a pak ve středním panelu rozklikněte možnost Advanced. Nalezněte Remove fork relationship a proveďte.

    fork 3

  • Přidejte přístup k projektu cvičícím a odevzdávacímu skriptu.

    Levý panel → Members → Invite Member.

    • Přidejte uživatele kontr s právem Reporter.

    • Přidejte i svoje cvičící, taky s právem Reporter.

    invite 1
    invite 2
    Opravující

    Ve druhém týdnu semestru pak přidáte stejným způsobem i svoje opravující, tentokrát s právem Developer. To je důležité, jinak vám nebudou moci potvrdit odevzdání!

  • Nevíte, co s Gitem dělat?

    Zkuste se podívat do manuálu.

Pravidla

  • Viditelnost repozitáře musí být celou dobu Private.

    Porušení tohoto pravidla bude považováno za opisování.

  • Kromě vlastníka mohou být členové projektu pouze kontr, cvičící a opravující.

    Porušení tohoto pravidla se bude chápat jako opisování.

  • Od momentu prvního odevzdání je zakázáno repozitář smazat nebo upravovat jeho historii.

    Porušení tohoto pravidla způsobí technické problémy s klonem repozitáře, který má Kontr. Manuální oprava ze strany administrátora bude stát penalizaci 20 bodů.

  • Maximální povolená velikost repozitáře je 10 MB.

    Po překročení velikosti Kontr odevzdání odmítne, což se bude muset vyřešit úpravou historie. Viz penalizaci o bod výše.

  • Repozitář musí obsahovat soubor .gitignore.

    Účelem tohoto pravidla je zabránit studentům nahrát do repozitáře většinu zbytečných souborů. Pro příklad obsahu souboru viz manuál, a je již obsažen v kostře, kterou jste si naklonovali výše.

    Obsah souboru je plně v kompetenci studentů, při porušení jiných pravidel se na něj nebude brát ohled.

Nebojte se Git používat

I přes pravidla popsaná výše se nemusíte bát Git používat. Klidně si v repozitáři ukládejte kódy z cvičení, tak se naučíte Git používat lépe. Git má i několik vlastních ochran, které vám zabrání udělat chybu.

  • Používejte vždy git status a pečlivě čtěte výstup, zejména zda jste ve správné větvi (hwNN pro domácí úkoly, main pro ostatní).

  • Vyhněte se příkazům, které obsahují --force nebo -f. Pokud máte problém a nalezli jste řešení s tímto příkazem, raději kontaktujte svoje cvičící.

Domácí úkoly

Po zveřejnění úkolu bude v původním repozitáři projektu zveřejněná kostra, na které můžete začít pracovat. Níže uvedený postup vás provede vytvořením nové větve i odevzdáním úkolu na kontrolu kvality.

Pokud si nastavíte SSH klíč, nebudete muset při práci s GitLabem zadávat heslo.

Co dělat po zveřejnění úkolu

  • Začátek

    Pokud ještě nemáte naklonovaný repozitář, proveďte příkaz

    $ git clone https://gitlab.fi.muni.cz/LOGIN/pb071.git

    kde místo LOGIN doplňte svůj fakultní login (xprijmeni nebo xUČO). Poté nakonfigurujte svůj e-mail, jméno, a nainstalujte háčky.

    $ cd pb071
$ git config user.email '‹LOGIN›@fi.muni.cz'
$ git config user.name '‹FIRST NAME› ‹LAST NAME›'
$ etc/install-hooks.sh

  • Zjistěte stav repozitáře

    V repozitáři pomocí příkazu git status ověřte, že jste ve větvi main a nemáte žádné rozpracované změny:

    $ git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

    • Pokud v příkazu výše vidíte On branch hwNN, pak jste ve špatné větvi; použijte git switch main.

    • Pokud místo nothing to commit, working tree clean vidíte nějaké změnené soubory, pak tyto změny nahrajte nebo zrušte.

  • Stáhněte si do repozitáře kostru zadání

    $ git pull upstream main

    Pokud příkaz výše skončí s chybou fatal: 'upstream' does not appear to be a git repository, tak to znamená, že máte nový klon repozitáře, který nemá nastavený zdroj upstream. Ten si nastavte pomocí:

    $ git remote add upstream 'https://gitlab.fi.muni.cz/pb071/template.git'

    a zkuste příkaz výše znovu. Pokud dostanete chybu fatal: Need to specify how to reconcile divergent branches, tak to znamená, že proběhly změny nejen v upstream repozitáři, ale zároveň také ve vašem repozitáři. Git v tento moment neví, jakým způsobem má změny spojit dohromady, a ptá se vás na názor.

    Aby se změny urovnaly a zároveň byla historie vašeho repozitáře zachována, tak budete muset při stahování udělat takzvaný merge commit. Aby si to git zapamatoval, a dělal to příště automaticky, tak použijte:

    $ git config pull.rebase false

    Teď můžete zopakovat git pull upstream main. Budete přesunuti do textového editoru (nejspíše to bude nano), ve kterém můžete specifikovat zprávu merge commitu. Zprávu můžete nechat takovou, jaká je, a editor opustit. Nyní už byste měli mít úspěšně staženou kostru zadání.

  • Nahrajte kostru zadání do svého repozitáře na GitLabu

    $ git push

  • Vytvořte novou větev pro domácí úlohu

    $ git switch -c hwNN

    kde místo hwNN doplňte kód domácího úkolu.

  • Nahrajte novou větev na GitLab

    $ git push --set-upstream origin hwNN

    kde místo hwNN dosaďte kód úkolu.

    Odteď můžete pro tuto větev používat git push bez dalších argumentů.

  • Vytvořte Merge Request

    Bez existujícího MR nelze úkol odevzdat naostro, vytvořte jej proto ideálně hned. Vizte návod níže.

  • Můžete pracovat

    V adresáři hwNN pak naleznete kostru, a můžete začít pracovat.

    Dělejte pravidelně git commit a git push.

I přestože důrazně doporučujeme používat postup výše, můžete si kostru úkolu přidat do repozitáře i manuálně. Dodržte ale následující podmínky:

  • Kostru vkládejte do větve main.

  • Po vložení kostry ihned proveďte git commit a git push.

  • Až poté vytvořte novou větev pro domácí úkol.

Pokud tento postup nedodržíte, bude MR obsahovat kromě vašich změn i kostru a znepřehlední to opravu. Opravující pak může požadovat nápravu, což vám zabere mnohem více času, než se naučit doporučovaný postup.

Přepnutí do jiné větve

Pokud se potřebujete vrátit do jiné větve, např. kvůli opravě jiného úkolu, pak postupujte následovně:

  1. Pomocí git status ověřte jako výše, že nemáte žádné rozpracované změny.

  2. Proveďte git switch BRANCH kde BRANCH je název jiné větve, např. main nebo hwNN.

Odevzdání úkolu

Na odevzdání úkolu je nutno mít v repozitáři Merge Request pro kontrolu kvality.

Na každý úkol stačí jeden Merge Request

Proto pro každý domácí úkol vytvořte právě jeden Merge Request. Tento Merge Request nezavírejte, dokud nedostanete od opravujícího Approve.

Nový Merge Request po každém git push nebo před každým odevzdáním je zbytečný. Úpravou kódu se existující Merge Request pro příslušnou větev automaticky aktualizuje.

  • Ujistěte se pomocí git status, že jste ve větvi s úkolem, na kterém budete pracovat, a že nemáte žádné rozpracované změny.

  • Proveďte git push. Nevadí, pokud nedošlo k žádné změně.

Teď si otevřete projekt v GitLabu.

  • Otevřete si přehled MR

    V levém panelu vyberte Merge Requests a klikněte na New merge request.

    mr 1

  • Nastavte větve

    Zdrojovou větev vyberte hwNN pro kód úkolu, který chcete odevzdat. Cílovou větev vyberte main ve svém vlastním repozitáři.

    Pokud vám GitLab nabízí veřejný předmětový repozitář pro cílovou větev, pak jste nezrušili Fork Relationship podle návodu výše. Nepokračujte, ale nejdříve to opravte!
    mr 2

  • Na poslední obrazovce nastavte parametry MR

    Nejdříve změňte název na Draft: HWNN. Slůvko Draft: na začátku je důležité — zabrání vám omylem kliknout na Merge, což by způsobilo, že již nebudete moci dostat opravu.

    Dále pak vyberte jako Assignee sebe a Reviewer opravujícího a klikněte Create merge request.

    mr 3
    Kliknutím na Changes si můžete prohlédnout změny, které se chystáte dát na kontrolu.

  • Hotovo

    Opravující teď o vašem MR vědí.

Odevzdání pro opravu kvality kódu

Pokud opravující žádá o opravu chyb, přidá ke kódu v MR komentáře, které začínají FIX:. Pokud je chcete opravit, udělejte následující:

Nezavírejte existující MR!

  • Ověřte stav repozitáře

    Ujistěte se pomocí git status, že jste ve větve s úkolem, který opravujete.

  • Proveďte opravu kódu

    Využijte odevzdání nanečisto pro průběžnou kontrolu, a nakonec odevzdání naostro pro finální kontrolu.

    Každou změnu můžete i nadále nahrávat do větve pomocí git push, GitLab stav existujícího MR automaticky aktualizuje.

  • Požádejte o další kontrolu

    Když jste s opravou spokojeni, požádejte o novou kontrolu.

    • Pokud vedle jména opravujícího vidíte ikonu , stačí na ní kliknout.

    • Někdy tuto ikonu však GitLab nezobrazí. V takovém případě stačí na kartě Overview napsat komentář, ve kterém opravujícího označte (@LOGIN) a nechte mu vzkaz, např.

      @xlacko1 I fixed all the problems. Please re-review this assignment.
Nebojte se diskutovat o opravě
Pokud poznámce v odevzdání nerozumíte, můžete k ní přidat komentář a doptat se. Pokud se i přes diskusi s opravujícím domníváte, že je oprava špatně, zeptejte se cvičících nebo napište na xlacko1@fi.muni.cz.

Opravující jsou s odevzdáním spokojení, co dál?

Pokud máte od opravujícího Approve, technicky nemusíte nic dalšího dělat. Můžete si však svoje řešení zařadit do větve main, pokud chcete.

Následující operace neprovádějte, pokud opravující nepotvrdili opravu!
approved 1
approved 2

  • Zrušte Draft status

    Najděte tlačítko Mark as ready a klikněte na něj.

  • Zařaďte změny do hlavní větve

    Pokud je vše v pořádku, GitLab zobrazí tlačítko Merge, na které teď můžete kliknout.

Merge Request, na kterém máte Approve, můžete zavřít stisknutím Close, zařadit do main stisknutím Merge, nebo ignorovat.

Merge Request však nesmíte smazat. Takový krok zruší jeho existenci z GitLab API, včetně informace o Approve, takže z pohledu Kontru nebudete mít na úkol žádnou recenzi. O body z úkolu nenávratně přijdete.

Jak Kontr repozitář používá

S prvním odevzdáním úkolu si Kontr vytvoří kopii příkazem git clone. Pro vyšší efektivitu se tato kopie při dalším odevzdání pouze aktualizuje příkazem git pull --ff-only. To má za následek některá omezení popsána výše.

Historie repozitáře

Git je verzovací nástroj, tudíž jeho cílem je uchovávat různé verze projektu tak, jak se v čase měnily. Protože je navíc distribuovaný, tak si každý klon repozitáře uchovává celou kopii všech změn.

Další vlastností Gitu je tzv. kryptografické ověřování historie. Každá verze je označená hodnotou (hashem), která závisí na aktuálním stavu projektu a všech minulých verzích. Pokud někdo ve zdrojovém repozitáři historii změní, změní se tyto hodnoty pro všechny další verze. Kopie tohoto repozitáře při git pull poznají, že jejich historie je jiná a odmítnou nové verze.

Z toho důvodu smazání repozitáře a změna starší verze jsou z pohledu Gitu stejný problém. Klon repozitáře, který si drží Kontr, uvidí jiné verze a odmítne je přijmout, což vyžaduje zásah administrátora.

Velikost repozitáře

Kontr běží na stroji Aisa a jako běžný uživatel má omezené místo na disku. 500 studentů dokáže neuváženým používáním repozitáře toto místo snadno vyčerpat, např. ukládáním binárních souborů, výstupů, záznamů přednášek a jiného odpadu do repozitáře.

Git ukládá soubory komprimovaně a snaží se zamezit duplikaci. Tedy,

  • Textové soubory jsou uložené velice efektivně, protože se snadno komprimují.

  • Binární soubory s téměř náhodným obsahem komprimace zmenší jen nepatrně.

  • Soubory se stejným obsahem se v Gitu uloží jenom jednou.

Pokud budete do repozitáře ukládat pouze zdrojové kódy a jiné malé textové soubory (např. CMakeLists.txt, vlastní poznámky atd.), nemusíte se překročení limitu bát. Problém nastane, pokud do repozitáře budete ukládat kompilované programy, výstupy programu, ladící informace, hudbu, filmy, záznamy přednášek atd.

Limit 10 MB na velikost je velice velkorysý. Při správném používání Gitu byste neměli překročit 200 kB za semestr.

Soubor .gitignore

Pokud je tento soubor umístěný v kořeni repozitáře, pak každý řádek popisuje vzor názvů souborů, které má Git ignorovat. Požadavek na existenci tohoto souboru je tedy prevence, kterou se snažíme studentům zabránit, aby překročili limit na velikost repozitáře.

Vhodnou konfiguraci naleznete v předmětovém manuálu.

Cvičení

Kostry cvičení jsou k dispozici ke stažení na oficiálním webu.

Navíc je lze stáhnout do repozitáře téměř stejným způsobem, jako kostry domácích úkolů. Každý seminář má svoji vlastní větev, seminar-NN, např. seminar-05. Na rozdíl od domácích ukolů se však nepožaduje používat samostatné větve pro vypracování.

Zde uvedeme úplný, byť stručný postup pro stažení kostry. Podrobné vysvětlení všech kroků lze nalézt v postupu pro stažení kostry domácího úkolu.

  • Ověřte si, že je repozitář čistý.

    git status

  • Pokud nejste ve větvi main, proveďte

    git switch main

  • Stáhněte kostru cvičení; pro cvičení NN proveďte

    git pull upstream seminar-NN

  • Nahrajte kostru do svého repozitáře na GitLabu.

    git push

  • Hotovo, můžete pracovat.

    Pro seminář není třeba vytvářet samostatnou větev.

Miniúkoly

Miniúkoly jsou k dispozici ke stažení na oficiálním webu.

Stejně jako cvičení, i miniúkoly lze stáhnout z Git repozitáře. Postupujte stejně jako výše, akorát místo seminar-NN použijte mini-NN. Tedy stručně:

git status
git switch main
git pull upstream mini-NN
git push

Viz stránku s miniúkoly pro informace k testování miniúkolů.

Tipy

  • Nepoužívejte git add --all!

    Tento přepínač přidá do repozitáře všechny soubory kromě těch v .gitignore. Protože však pravidla v tomto souboru nemusí být dokonalá, můžete omylem přidat i nechtěné soubory.

  • Nepoužívejte příkazy s -f nebo --force!

    Tyto přepínače obvykle vypnou některé ochrany Gitu. Pokud na takový příkaz narazíte a netušíte, co dělá, nepoužívejte ho a kontaktujte raději někoho zkušenějšího (cvičící nebo konzultanty).

  • Před git commit pečlivě čtěte výstup git status!

    Pokud uděláte při git add chybu, Git napoví, jak ji opravit.

  • Špatný commit lze před git push ještě opravit.

    Podívejte se na manuál příkazu git reset. Pokud nevíte, co s tím, raději se zeptejte cvičícího nebo konzultanta.

  • Velikost repozitáře lze odhadnout i před commitem.

    user@aisa:pb071$ git gc --aggressive
user@aisa:pb071$ du -sh .git

  • Dávejte si pozor na Git v IDE.

    Některé nástroje v IDE jsou nepřehledné a mohou způsobit, že omylem něco v repozitáři pokazíte. Pečlivě čtěte všechna dialogová okna.