Generator konfiguracji commitlint

Generator konfiguracji commitlint

Generator commitlint tworzy gotowy plik commitlint.config.js z regułami konwencji commitów. Wybierasz preset, limit nagłówka i dodatkowe reguły, a narzędzie dopisuje też fragment package.json z zależnościami.

Czym jest commitlint?

commitlint sprawdza, czy komunikaty commitów spełniają ustaloną konwencję: typ, zakres i opis. Połączenie z hookiem Husky blokuje commity niepoprawne formatowo, co utrzymuje czytelny i spójny historię repozytorium — przydatny w changelogach i semantycznym wersjonowaniu.

Przykład poprawnego commita

feat(auth): add password reset flow — typ, zakres w nawiasie, dwukropek i opis małymi literami bez kropki. Generator wymusza te zasady regułami header-max-length, subject-case i subject-full-stop.

Jak generator składa konfigurację commitlint

Generator zbiera trzy decyzje: preset, limit nagłówka oraz zestaw dodatkowych reguł. Na tej podstawie składa plik commitlint.config.js, w którym sekcja extends wskazuje pakiet wybranego presetu, a sekcja rules zawiera reguły nadpisujące lub uzupełniające ten preset. Do wyniku dołączany jest fragment package.json z zależnością odpowiadającą wybranemu pakietowi, więc od razu widzisz, co trzeba dopisać do devDependencies.

Sam commitlint działa już na zapisanym komunikacie. Hook commit-msg przekazuje mu ścieżkę do pliku z treścią commita, a walidator rozbija tekst na typ, zakres, opis i pozostałe części, po czym sprawdza je reguła po regule. Gdy któraś reguła zawiedzie, narzędzie wypisuje jej nazwę oraz znalezioną wartość, a hook przerywa tworzenie commita. Dlatego konfiguracja musi być kompletna: brak wpisu w rules oznacza, że dana zasada po prostu nie jest egzekwowana.

Preset to gotowy zestaw reguł dostarczany w osobnym pakiecie npm, a extends oznacza dziedziczenie tych ustawień. Reguły wpisane w sekcji rules mają pierwszeństwo nad presetem, dzięki czemu generator może wymuszać własne wartości dla limitu nagłówka, wielkości liter w opisie i kropki na końcu. Nazwa pakietu w extends musi zgadzać się z tym, co trafi do devDependencies — jeśli się rozjadą, Node nie znajdzie modułu i commitlint zakończy pracę błędem, jeszcze przed sprawdzeniem jakiegokolwiek commita.

Przykład krok po kroku: od wyboru presetu do zapasu w limicie

1. Wybierasz preset Conventional Commits. W wyniku pojawia się jedna zależność: @commitlint/config-conventional, a w pliku wpis extends z tym pakietem.
2. Ustawiasz limit nagłówka na 72 znaki. To dolna granica przedziału 72-100 zalecanego przez konwencję, więc zostawia miejsce na nieco dłuższe opisy bez wychodzenia poza bezpieczną długość.
3. Testowy nagłówek feat(auth): add password reset flow ma dokładnie 35 znaków: 10 na typ i zakres (feat(auth)), 2 na dwukropek ze spacją oraz 23 na opis. Do limitu 72 zostaje 37 znaków zapasu.
4. Wydłużasz opis do 60 znaków. Nagłówek liczy wtedy 72 znaki (10 + 2 + 60), czyli dokładnie tyle, ile wynosi limit — reguła header-max-length przepuszcza taki commit, bo przekroczenie wynosi 0.
5. Dopisujesz jeszcze jedno słowo i nagłówek rośnie do 80 znaków. Limit 72 zostaje przekroczony o 8 znaków, reguła header-max-length zwraca błąd, a hook commit-msg przerywa operację — commit nie powstaje.
6. Skracasz opis tak, aby cały nagłówek liczył 65 znaków. Warunek 65 mniejszy lub równy 72 jest spełniony, walidacja przechodzi, a gotowy plik commitlint.config.js i fragment package.json kopiujesz do repozytorium.

Presety w generatorze: klucz, etykieta i pakiet

Praktyczne wskazówki przy generowaniu configu

• Jeden preset na repozytorium — łączenie config-conventional z config-angular daje sprzeczne reguły i komunikaty o błędach, których nikt nie potrafi wyjaśnić. Wybierz preset odpowiadający zespołowi i trzymaj się go w całym projekcie.
• Preset Lerna tylko w prawdziwym monorepo — config-lerna-scopes czerpie zakresy z pakietów w repozytorium, więc w zwykłym projekcie nie ma z czego ich brać. W pojedynczym repozytorium bezpieczniej zostać przy Conventional Commits.
• Limit nagłówka ustawiaj z zapasem — wartość blisko górnej granicy oznacza, że prawie każdy dłuższy opis będzie wymagał skracania, a poprawianie commita w trakcie pracy irytuje bardziej niż sam limit. Krótszy limit wymusza zwięzłe pisanie.
• Przetestuj konfigurację przed pierwszym commitem — wrzuć wygenerowany plik do repozytorium i przepuść przez walidator przykładowy komunikat, zanim hook zacznie blokować pracę całemu zespołowi. Poprawki w configu są tańsze niż zbiorcze przepisywanie historii.
• Traktuj plik configu jak kod — leży w repozytorium, podlega przeglądowi i nie trafia do .gitignore. Dzięki temu każdy klon ma identyczne reguły, a zmiana konwencji jest widoczna w historii zmian.

Czego generator nie zrobi za ciebie

• Nie instaluje zależności — narzędzie tylko wypisuje fragment package.json z pakietem wybranego presetu. Instalację pakietu oraz podpięcie hooka commit-msg wykonujesz samodzielnie w repozytorium.
• Nie zna struktury twojego projektu — poza presetem Lerna nie sprawdza, czy zakres wpisany w nawiasie istnieje w repozytorium ani czy jest sensowny. Walidacja formatu to nie to samo co walidacja znaczenia.
• Nie ocenia treści komunikatu — commit w rodzaju fix: poprawka przejdzie wszystkie reguły mimo braku informacji o zmianie. O jakości opisów decyduje zespół i przegląd kodu, nie walidator.
• Nie konfiguruje hooków ani CI — plik configu to jedna warstwa. Bez hooka w repozytorium i bez kroku w pipeline commitlint nie uruchomi się sam, a błędy formatu przejdą niezauważone aż do wdrożenia.

Najczęstsze pytania