Jak psát dobré commit zprávy (a proč na tom záleží)

Commit zpráva je poznámka pro budoucího čtenáře – často pro vás za půl roku. Když hledáte, proč někdo změnil timeout z 30 na 5 sekund, zpráva „fix“ vám nepomůže. Zpráva „Zkrátit timeout platební brány, aby uživatel nečekal na chybu 30 s“ ano.

Struktura dobré zprávy

Krátký souhrn do ~50 znaků

Volitelné tělo oddělené prázdným řádkem. Vysvětluje CO a PROČ,
ne JAK – to je vidět z diffu. Řádky zalamujte kolem 72 znaků.

Refs: #123

Pravidla, která se osvědčila:

Předmět do zhruba 50 znaků, maximálně 72. GitHub delší předměty zkracuje.
Rozkazovací způsob: „Přidat“, „Opravit“, „Odstranit“ (anglicky „Add“, „Fix“). Zpráva doplňuje větu „Tento commit…“.
Bez tečky na konci předmětu.
Prázdný řádek mezi předmětem a tělem – nástroje jako git log --oneline berou jen první řádek.
Tělo vysvětluje motivaci, kontext, vedlejší dopady a alternativy, které jste zavrhli.

Špatně vs. dobře

Špatně	Lépe
`fix`	`Opravit pád při prázdném košíku`
`změny`	`Přesunout validaci e-mailu do serializeru`
`WIP`	(ukliďte před PR pomocí `git rebase -i`)
`Opraveny chyby a přidána nová funkce exportu a změněn design`	tři samostatné commity
`Updated index.js`	`Načítat produkty stránkovaně po 50`

Pokud se předmět nedá napsat bez „a“, commit pravděpodobně dělá víc věcí a stojí za to ho rozdělit. Pomůže git add -p, kterým do commitu přidáte jen vybrané části souboru.

Conventional Commits

Rozšířená konvence, která přidává strojově čitelný typ:

<typ>(<oblast>): <popis>

feat(api): přidat endpoint pro export objednávek
fix(auth): neodhlašovat uživatele po obnovení tokenu
docs: doplnit postup nasazení do README
refactor(db): sjednotit připojení přes jeden pool
chore(deps): aktualizovat Django na 5.1

Běžné typy: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.

Zpětně nekompatibilní změnu označíte vykřičníkem nebo patičkou:

feat(api)!: odstranit zastaralý endpoint /v1/orders

BREAKING CHANGE: klienti musí přejít na /v2/orders.

Přínos: z historie lze automaticky generovat changelog a určovat další verzi podle sémantického verzování – fix zvýší patch, feat minor, breaking change major.

Šablona commitu

Git umí při git commit (bez -m) předvyplnit editor šablonou:

cat > ~/.gitmessage <<'EOF'
# <typ>(<oblast>): <popis do 50 znaků>

# Proč je změna potřeba?

# Refs: #
EOF
git config --global commit.template ~/.gitmessage

Řádky začínající # se do zprávy neuloží.

Automatická kontrola: commitlint

V JavaScriptových projektech lze formát vynutit pomocí commitlint a Husky:

npm install --save-dev @commitlint/cli @commitlint/config-conventional husky
echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js
npx husky init
echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg

Zpráva, která nevyhovuje, zastaví commit. (Syntaxe husky init platí pro Husky v9; starší verze používaly husky install.)

Odkazy na issue a automatické uzavírání

GitHub rozpozná klíčová slova v commitu nebo PR: Fixes #42, Closes #42, Resolves #42. Po sloučení do výchozí větve se issue uzavře samo. Pouhé #42 vytvoří jen odkaz.

Spoluautoři

Pokud jste na změně pracovali ve dvou, přidejte na konec zprávy patičku:

Co-authored-by: Jana Dvořáková <[email protected]>

GitHub pak commit zobrazí u obou autorů.

Oprava zprávy

git commit --amend            # poslední commit, ještě nepushnutý
git rebase -i HEAD~3          # starší commity: u nich změňte pick na reword

Už pushnuté zprávy na sdílené větvi raději neměňte – vyžadovalo by to force push.

Jazyk: čeština, nebo angličtina?

Obojí je v pořádku, hlavně jednotně v celém projektu. Open source a mezinárodní týmy obvykle píší anglicky. Interní projekt čistě českého týmu klidně česky – s diakritikou si Git i GitHub poradí.

Rychlý tip

Když máte velký diff a nevíte, jak ho shrnout, spusťte git diff --staged, výstup vložte do ColdHost AI v režimu Programování a požádejte o návrh zprávy ve formátu Conventional Commits. Návrh vždy zkontrolujte – jen vy víte, proč jste změnu dělali.