Generator szablonu commita Git

Generator szablonu commita Git

Dobrze opisany commit oszczędza czas całego zespołu. Szablon .gitmessage podpowiada strukturę wiadomości przy każdym zatwierdzeniu.

Format Conventional Commits

<typ>(<zakres>): <temat>

Dobra wiadomość commita

• Temat do ~72 znaków, w trybie rozkazującym („dodaj”, nie „dodałem”).
• Treść opisuje co i dlaczego, a nie jak.
• Osobny commit na jedną logiczną zmianę.

Jak aktywować?

git config --global commit.template ~/.gitmessage

Od tej pory edytor otworzy szablon przy git commit bez argumentu -m.

Jak działa generator szablonu commita Git

Generator szablonu commita Git nie tworzy commitów ani nie modyfikuje repozytorium. Działa jak prosty kompozytor tekstu: zbiera informacje, które chcesz mieć w wiadomości, i składa z nich plik .gitmessage. W praktyce wybierasz typ zmiany, opcjonalny zakres, temat, treść oraz stopkę. Narzędzie układa je w przewidywalnej kolejności: nagłówek Conventional Commits, pusta linia, opis oraz opcjonalne informacje końcowe. Dzięki temu nie musisz za każdym razem pamiętać o strukturze, a edytor otwiera gotowy szkielet.

Mechanizm opiera się na konfiguracji Git commit.template. Gdy ta wartość wskazuje na plik, Git wstawia jego zawartość do edytora przed zapisaniem commita. Linie zaczynające się od # pełnią rolę komentarzy i zwykle nie trafiają do finalnej wiadomości, o ile nie zmieniono core.commentChar. Puste linie i kolejność elementów mają znaczenie: Git oraz narzędzia analizujące historię rozpoznają nagłówek, treść i stopkę po układzie, a nie po dowolnym miejscu w pliku.

Wzór nagłówka to typ(zakres): temat. Zakres jest opcjonalny, a temat powinien mieścić się w około 72 znakach i być napisany w trybie rozkazującym. Generator podpowiada strukturę, ale nie waliduje commita — o tym, czy wiadomość jest poprawna, decyduje konwencja zespołu i ewentualne narzędzia takie jak commitlint i husky. Warto więc traktować .gitmessage jako instrukcję obsługi, a nie automatycznego strażnika formatu.

Przykład krok po kroku

1. W generatorze wybierasz typ feat, zakres auth i temat dodaj logowanie przez e-mail.
2. Powstaje nagłówek feat(auth): dodaj logowanie przez e-mail. Liczy 40 znaków, więc z zapasem mieści się w orientacyjnym limicie 72 znaków.
3. W polu treści wpisujesz: Dodaje formularz logowania, obsługę tokenu sesyjnego i czytelny komunikat o błędnych danych. Opisujesz co i dlaczego, zamiast streszczać zmiany w plikach.
4. Dodajesz opcjonalną stopkę, na przykład BREAKING CHANGE: usunięto stary sposób logowania, tylko jeśli zmiana rzeczywiście łamie zgodność wsteczną. W przeciwnym razie stopka zostaje pusta.
5. Generujesz plik .gitmessage i zapisujesz go w repozytorium albo w katalogu domowym, zależnie od tego, czy szablon ma działać w jednym projekcie, czy globalnie.
6. Ustawiasz Git tak, aby korzystał z tego pliku jako szablonu, a następnie wykonujesz git commit bez -m. Edytor otwiera gotową strukturę. Uzupełniasz treść, zapisujesz plik i zamykasz edytor.

Elementy szablonu .gitmessage

Praktyczne wskazówki

• Trzymaj jeden słownik typów i zakresów — generator podpowiada strukturę, ale spójność nazw modułów zależy od ustaleń w projekcie. Jeśli zespół używa zakresu auth, nie wprowadzaj jednocześnie autoryzacja, bo historia commitów stanie się niespójna.
• Zakres dodawaj tylko wtedy, gdy zawęża kontekst — przy zmianie dotyczącej całego repozytorium lepiej pominąć nawias niż wpisywać all lub projekt. Zakres ma pomagać w filtrowaniu, a nie wypełniać obowiązkowe pole.
• Pisz temat w trybie rozkazującym — dodaj, popraw, usuń, zamiast dodałem, poprawiono, usunięto. Taka forma jest krótsza, jednolita i lepiej współpracuje z narzędziami do generowania changelogów.
• Stopkę traktuj jako wyjątek — BREAKING CHANGE, informacja o współautorze lub odniesienie do zgłoszenia pojawiają się tylko wtedy, gdy naprawdę wnoszą kontekst. Nadmiar stopek rozmywa najważniejszą informację.
• Przetestuj szablon na jednym repozytorium — zanim ustawisz go globalnie, sprawdź, czy edytor, komentarze i układ pola nie przeszkadzają w codziennej pracy. Łatwiej poprawić jeden plik niż odzwyczajać zespół od złego nawyku.

Ograniczenia generatora

• Nie wymusza formatu — .gitmessage to podpowiedź. Jeśli użytkownik zmieni lub usunie wpis, commit nadal powstanie. Do egzekwowania konwencji potrzebne są commitlint i husky albo podobne narzędzia działające po stronie repozytorium.
• Nie gwarantuje długości tematu — generator może przypomnieć o orientacyjnym limicie 72 znaków, ale ostateczna długość zależy od wpisanej treści i konfiguracji edytora. Dłuższy temat nie zostanie automatycznie odrzucony.
• Nie zna konwencji zespołu — nie wybierze za Ciebie dozwolonych typów, zakresów ani języka wiadomości. To musi wynikać z dokumentacji projektu i ustaleń między autorami commitów.
• Nie zastępuje review — poprawny szablon nie oznacza, że commit jest logicznie spójny ani że opis wystarcza do zrozumienia zmiany. Nadal potrzebna jest kontrola człowieka.
• Nie obejmuje wszystkich ścieżek Git — przy merge, rebase, amend lub commitach tworzonych przez inne narzędzia szablon może zostać pominięty albo zastąpiony inną wiadomością. W takich sytuacjach konwencja zależy od dodatkowych skryptów i reguł.

Najczęstsze pytania