Generator konfiguracji pre-commit

Generator konfiguracji pre-commit

pre-commit uruchamia zestaw hooków przed zapisaniem commita. Jeśli któryś hook zgłosi błąd albo sam poprawi plik, commit zostaje zablokowany, zanim wadliwy kod trafi do repozytorium. Generator składa konfigurację pre-commit, czyli plik .pre-commit-config.yaml, z 10 hooków podstawowych i 3 dodatkowych (Prettier, ESLint, Black). Wynik kopiujesz albo pobierasz jako gotowy plik.

Popularne hooki

Hooki podstawowe pochodzą z repozytorium pre-commit/pre-commit-hooks i trafiają do pliku jako jeden wpis z rev: v4.6.0. Domyślnie zaznaczone są trailing-whitespace, end-of-file-fixer, check-yaml i check-added-large-files.

Przykład

Wynik dla zestawu „Podstawowy” z domyślnie zaznaczonymi hookami i włączonymi ustawieniami domyślnymi ma 12 linii (gotowy plik skopiuj z narzędzia, bo wcięcia w YAML muszą być zwykłymi spacjami):

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

default_stages: [pre-commit]
default_language_version:
  python: python3

Zestawy PHP, Node i Python zmieniają tylko hooki dodatkowe: PHP dodaje Prettiera, Node – Prettiera i ESLint, Python – Blacka. Zaznaczenie hooków podstawowych zostaje bez zmian.

Instalacja

pip install pre-commit, następnie zapisz plik w głównym katalogu repozytorium i wykonaj pre-commit install. Od tej pory hooki działają przy każdym commicie.

Jak działa generator konfiguracji pre-commit

Generator nie uruchamia hooków samodzielnie. Tworzy plik .pre-commit-config.yaml, czyli deklarację repozytoriów i hooków, które pre-commit ma pobrać i wykonać przy commicie. Każde repozytorium trafia do sekcji repos jako osobny wpis z trzema polami: repo, rev oraz hooks. Pole repo wskazuje adres repozytorium hooka, rev oznacza konkretną wersję, a hooks zawiera listę identyfikatorów do uruchomienia.

Wszystkie zaznaczone hooki podstawowe lądują w jednym wpisie pre-commit-hooks, zawsze w kolejności z tabeli powyżej. Prettier, ESLint i Black mają własne repozytoria i są dopisywane za nim właśnie w tej kolejności. Nad wynikiem widać liczbę hooków, repozytoriów i linii pliku, a pod nim tabelę z opisem każdego wybranego hooka.

Dwie opcje dotyczą całego pliku. Ustawienia domyślne dopisują na końcu default_stages: [pre-commit] oraz default_language_version z wybraną wersją Pythona: python3, python3.10, python3.11 lub python3.12. Po ich wyłączeniu wersja Pythona nie trafia do pliku. Opcja fail_fast dodaje fail_fast: true, więc pre-commit zatrzyma się na pierwszym hooku z błędem, zamiast pokazać komplet problemów naraz.

Przy pierwszym uruchomieniu pre-commit odczytuje plik i dla każdego repozytorium tworzy izolowane środowisko. Hooki działają na plikach zgłoszonych do commita, a ich kolejność wynika z kolejności wpisów w pliku. Jeśli którykolwiek hook zwróci błąd, commit zostaje przerwany. Sam generator nie sprawdza, czy narzędzia pasują do projektu — tylko składa poprawny fragment konfiguracji z dostępnych wpisów.

Przykład krok po kroku

1. Masz repozytorium z trzema plikami do sprawdzenia: app.js, style.css i main.py. To trzy różne typy plików, więc poza hookami podstawowymi potrzebujesz trzech dodatkowych.
2. Zostawiasz cztery domyślne hooki podstawowe i zaznaczasz Prettier, ESLint i Black. Dla Prettiera zostaje wpisana rewizja v4.0.0-alpha.8, dla ESLinta v9.9.0, dla Blacka 24.8.0.
3. Generator zwraca sekcję repos z czterema wpisami. Nagłówek repos i wpis pre-commit-hooks z czterema hookami zajmują 8 linii, każdy z trzech wpisów dodatkowych po 4 (repo, rev, hooks, id), a ustawienia domyślne kolejne 4. Razem 24 linie, 7 hooków i 4 repozytoria.
4. Pobierasz plik, zapisujesz go w katalogu głównym repozytorium i uruchamiasz pre-commit install. Przy pierwszym commicie pre-commit przygotowuje cztery środowiska: pre-commit-hooks, mirrors-prettier, mirrors-eslint i psf/black.
5. Najpierw działają hooki podstawowe, potem Prettier formatuje app.js i style.css, ESLint sprawdza app.js, a Black formatuje main.py. Jeśli któryś hook zgłosi błąd albo zmieni plik, commit zostaje zablokowany.
6. Dodajesz poprawki przez git add i ponawiasz commit. Gdy wszystkie hooki zakończą się powodzeniem, commit przechodzi, a pliki są już po formatowaniu.

Tabela referencyjna wpisów

Praktyczne wskazówki

• Po wklejeniu pliku uruchom pre-commit autoupdate. Rewizje z generatora są zapisane w jego kodzie i z czasem się starzeją; po podbiciu wersji sprawdź, czy nowsze wydanie nie wymaga innej konfiguracji.
• Uruchom hooki na wszystkich plikach po dodaniu konfiguracji: pre-commit run --all-files pozwoli wykryć problemy w plikach, których nie dotyczył pierwszy commit.
• Nie poprawiaj wcięć ręcznie. Wpis repo, rev i hooks musi mieć właściwy poziom; generator tworzy go spójnie, a ręczna edycja łatwo psuje YAML.
• Kolejność wpisów jest stała: hooki podstawowe, Prettier, ESLint, Black. Prettier działa przed ESLint, więc linter dostaje kod już sformatowany. Inną kolejność ustawisz, przenosząc cały wpis razem z rev i hooks.
• W zespole pracującym na Windowsie i Linuksie zaznacz mixed-line-ending, a w repozytoriach z plikami konfiguracyjnymi także detect-private-key.
• Używaj tej samej konfiguracji w CI: pre-commit run --all-files w potoku da wynik zbliżony do lokalnego, jeśli środowisko ma te same zależności.

Ograniczenia i co zaburza wynik

• Brak konfiguracji narzędzi: generator dodaje tylko wpisy repo i hook id. Nie tworzy plików .prettierrc, eslint.config.js ani pyproject.toml, więc bez nich część hooków nie zadziała zgodnie z oczekiwaniami.
• Brak argumentów hooków: do pliku nie trafia args, dlatego check-added-large-files używa domyślnego limitu 500 kB. Inny próg dopiszesz ręcznie, np. args: ['--maxkb=1000'].
• Brak sprawdzania zgodności wersji: wpisy mają sztywne rewizje, a generator nie wie, czy współpracują z wersjami Node, Pythona i bibliotek w projekcie.
• Brak analizy plików repozytorium: narzędzie nie skanuje projektu, więc nie dobierze hooków za Ciebie. Jeśli zaznaczysz Black w repozytorium bez Pythona, hook nie będzie miał plików do pracy.
• Brak wykluczeń: generator nie ustawia exclude ani files, więc Prettier, ESLint i Black mogą analizować pliki, które chcesz pominąć, co zaburza wynik lub spowalnia commit.