[git] Zásady commitování

Všeobecné návody jak při vývoji postupovat...
[phpBB Debug] PHP Warning: in file [ROOT]/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275: count(): Parameter must be an array or an object that implements Countable
Avatar
Gregory
Vedoucí vývoje
Příspěvky: 73
Bydliště: near Pilsen

[git] Zásady commitování

Příspěvek od Gregory » 22. listopad 2017 (12:44:26)

Každý příspěvek do git repozitáře je "zabalen" do takzvaného commitu. Ten obsahuje nejen změny v souborech ve formě rozdílu, ale i další informace. Jednou z důležitých informací je takzvaná "commit note", tedy poznámka k commitu, aby bylo jasné, k čemu se commit vztahoval, co opravoval nebo upravoval. Dále je obsažen hash, který jednoznačně commit identifikuje v celém repozitáři. Jedná se o 20B číslo, obvykle zapsáno v hexadecimálním tvaru (tedy 40 znaků, 0-9,A-F). Dále má commit autora, kterého lze buď explicitně určit při commitování, nebo lze použít výchozí hodnoty z globálního nebo lokálního nastavení. Poté je commit označen časovou značkou jeho vytvoření.

Pro nastavování a další záležitosti bude tento návod využívat pouze variantu git bash.

Autor
Autor commitu je dán buď explicitně při commitování přepínačem "--author" (zde vynecháme) nebo ho lze určit lokálně pro celý repozitář, případně globálně pro celý váš PC. Budeme se zabývat jen druhým způsobem, kdy nastavíme implicitního autora globálně pro váš počítač. Potřeba nastavovat autora lokálně vyvstává v momentě, kdy například pracujete na více projektech pro jiné subjekty a potřebujete mít všude jiný identifikátor a e-mail, a tak podobně.

Autor má dvě "složky" - jméno a email. E-mail nastavíme na ten, který jste si např. registrovali na GitHubu. Jméno taktéž použijeme buď vlastní, nebo přezdívku z GitHubu:

Kód: Vybrat vše

git config --global user.name "MojeJmeno"
git config --global user.email "mujemail@seznam.cz"
Pokud budete někdy z nějakého důvodu potřebovat nastavit autora zvlášť pro nějaký repozitář, lze vynechat parametr "--global"

Pokud se rozhodnete uvádět autora přímo při commitování, což se může hodit, pokud nahráváte něčí patch, jehož nejste autorem, lze použít přepínač při commitování:

Kód: Vybrat vše

git commit ... -s --author="PravyAutor <mailautora@atlas.cz>"
Nutno dodat, že v tomto případě musí být dodržen formát, tedy v uvozovkách bude jméno autora, mezera a v ostrých závorkách uveden email. Všimněte si také parametru "-s" - ten dá v záznamu commitu vědět, že jste to byli vy, kdo commit převzal a vložil do repozitáře. Není povinný, ale pro naše účely ho vyžadovat budeme - přecijen se jedná o určitý prvek, který dovoluje udržovat pořádek.

Správa a přidávání souborů

Jak jsem psal již v guide jinde, soubory se dají přidat příkazem "git add" buď hromadně (hvězdička), nebo po jednom. Ani jeden způsob není úplně ideální - "git add *" vám může přidat do repozitáře i věci, které nechcete, aby tam byly (dočasné soubory, konfigurace, ..), a přidávání po jednom zase bude trvat hrozně dlouho.

Pro začátek mějme přehled, co do repozitáře NEpatří:
  • konfigurační soubory (config.php, ..) (neplatí pro jejich předlohy, kde nejsou vyplněné položky)
  • dočasné soubory a cache
  • dynamicky generovaný obsah uživateli (avatary, obrázky v tématech, uploadované soubory, ..)
Někde na hraně jsou pak soubory projektů různých vývojových prostředí. Pokud používáte IDE jako NetBeans, není nutné jeho soubory do repozitáře vkládat. U MS Visual Studio je to již často diskutabilní. Projekty pro .NET (C#, VB, ..) tam své soubory mít mají, ovšem pro C++ se budeme snažit všude použít CMake (u emulátoru používaný je), takže projektové soubory MSVS pro C++ připojovat nebudeme.

Jak tedy přidávat správně soubory? Vyčleňme si cesty, které obsahují výše zmíněné soubory a ty přidávat nebudeme. Abychom si byli jisti, že do repozitáře budeme přidávat jen to, co tam chceme, postupujme po jednotlivých podsložkách (a podpodsložkách, ...) a přidávejme hromadně jejich obsah. Pokud se v nějaké složce vyskytuje více souborů a jeden z nich je config, nezbývá, než přidat buď všechny po jednom, nebo přidat hromadně všechny a pak jeden konkrétní soubor opět "vyndat" (k tomu níže), nebo použít .gitignore (také níže). Také je možné přidávat po příponách. Například téměř vždy u C++ projektů chceme přidat všechny zdrojové soubory s příponou .cpp.

Můžeme proto přidávat soubory a složky tímto stylem:

Kód: Vybrat vše

git add assets/*
git add app/models/* app/controllers/*
git add *.cpp
git add app/bootstrap.php
Pokud se vám náhodou povede zahrnout do výběru i soubor, který tam nemá co dělat, lze ho "vyjmout" příkazem:

Kód: Vybrat vše

git reset -- config.php
Nutno dodat, že tento příkaz nic nezmění fyzicky v tom souboru, ani ho nikam nepřesune/nevymaže. Jen ho vyjme ze současného stavu repozitáře.

Pro kontrolu je silně doporučeno zkontrolovat, zda jsme přidali všechny soubory co chceme, zda jsme nepřidali něco ze souborů, co v repozitáři nemají co dělat, a zda je vše v pořádku. Toho lze docílit příkazem:

Kód: Vybrat vše

git status
Výpis obsahuje několik sekcí. Soubory konfigurací a další co nemají v repozitáři co dělat by měly být v sekci "Untracked files" (po nastavení gitignore níže nebudou ani tam). Ostatní soubory budou v sekci "New files", "Changes staged for commit" nebo "Changes not staged for commit". Příkaz "git add" neslouží pouze k přidávání nových souborů do repozitáře, ale k "přípravě" souborů k commitování obecně. Stejným způsobem lze "přidat" (v git terminologii "stage") soubory k commitování a pak není třeba provádět výčet souborů v commit příkazu, případně používat "-a" přepínač. Z tohoto důvodu existují dvě sekce - "staged for commit" a "not staged for commit". Pokud použijete bezparametrický commit, budou se commitovat pouze soubory ze sekce "staged for commit". Pokud použijete přepínač "-a", budou se commitovat všechny sekce kromě "Untracked files".

.gitignore a složky pro dynamický obsah

V git repozitářích existují speciální soubory, který mají určitý význam pro správu repozitáře. Pro teď je důležitý soubor s názvem ".gitignore". Na začátku má tečku, a to z důvodu, že soubory začínající tečkou jsou na unixových systémech považovány za "skryté" (analogie ke skrytým souborům z Windows a jeho souborových systémů). Ve Windows se bude tento soubor pravděpodobně chovat jako soubor beze jména s příponou "gitignore", ale instalační program gitu vám pravděpodobně tyto "přípony" asocioval s textovým editorem.

Soubor .gitignore se může nacházet kdekoliv v projektu i na několika místech. Obsahuje po řádcích oddělený seznam souborů a cest, které se mají úplně ignorovat při správě repozitáře (git add, git status, ...). Můžeme proto v kořenovém adresáři repozitáře například vytvořit jeden takový gitignore a naplnit ho ignorováním konfiguračních souborů, a například všech souborů s příponou .env:

Kód: Vybrat vše

app/config.php
app/config.db.php
*.env
Nezapomeňme soubor .gitignore přidat do repozitáře, pokud není (git add), a provést commit, kromě speciálního významu jde o naprosto normální soubor.

Pro složky s dynamicky generovaným obsahem (cache, uploads, ..) lze vkládat přímo do nich soubor .gitignore s následujícím obsahem:

Kód: Vybrat vše

*
!.gitignore
Tento soubor říká, že se má ignorovat vše v této složce (hvězdička na prvním řádku), ale NEMÁ (vykřičník) se ignorovat soubor .gitignore. Toto způsobí, že složka zůstane v repozitáři prázdná, ačkoliv se do ní u vás generuje dynamický obsah. Není zde tedy riziko, že do vzdáleného repozitáře pošlete data, která tam být nemají.

Commit note

Commit note je další velmi důležitou částí commitu a všude mohou být jiné požadavky, co tam vlastně psát. Vždy je ale nutné napsat, co jste vlastně v tomto commitu upravili. Dále v rámci iCe Online budeme používat angličtinu.

Zásady lze shrnout bodově:
  • jednoznačná stručná poznámka o tom, co se v commitu změnilo
  • jednojazyčně (u nás angličtina)
  • obsahuje pouze základní ASCII znaky (tedy vynechme háčky a čárky, UTF-8 speciality, emoji, ..)
  • neobsahuje smajlíky ani jiné prvky typicky chatové konverzace
  • vše by se mělo vejít do 80 znaků (pokud ne, svět se nezboří, ale snažme se dodržet)
  • není zase zbytečně stručná (např. oblíbená commit note "fix", "repair", "files" nebo "small change")
  • pokud to repozitář vyžaduje, uvádějme i modul, ve kterém ke změně došlo (bude popsáno v samostatném příspěvku)

[phpBB Debug] PHP Warning: in file [ROOT]/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275: count(): Parameter must be an array or an object that implements Countable
[phpBB Debug] PHP Warning: in file [ROOT]/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275: count(): Parameter must be an array or an object that implements Countable
[phpBB Debug] PHP Warning: in file [ROOT]/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1275: count(): Parameter must be an array or an object that implements Countable