Dobry opis commita ma krótki tytuł (do ok. 50 znaków) w trybie rozkazującym, np.add login form validation, a jeśli zmiana tego wymaga, pustą linię i kilka zdań o tym, dlaczego ją wprowadzono. W większości zespołów commity pisze się po angielsku, a popularną konwencją jest Conventional Commits, czyli prefiks typu zmiany, np.feat:dla nowej funkcji ifix:dla poprawki. Gałęzie nazywa się podobnie: krótko, małymi literami, z myślnikami i prefiksem rodzaju pracy, np.feature/login-form.
Historia commitów to dziennik projektu. Za pół roku Ty albo ktoś z zespołu otworzy git log, żeby sprawdzić, kiedy i dlaczego coś się zmieniło. Opis zmiany albo fix nic wtedy nie powie. W tym artykule pokazuję, jak budować opis commita, czym są Conventional Commits, dlaczego warto pisać po angielsku i jak nazywać gałęzie.
Z czego składa się dobry opis commita?
Opis commita ma dwie części:
add validation for empty email field
The form was submitted with an empty email and the API returned
a 500 error. Now the form shows a message and does not send
the request.
- Tytuł to pierwsza linia. Dokumentacja Gita zaleca, żeby miał najwyżej 50 znaków i streszczał zmianę. Tytuł widzisz w
git log --oneline, na liście commitów na GitHubie i w pull requestach, więc często jest jedyną częścią opisu, którą ktoś przeczyta. Na końcu tytułu nie stawia się kropki. - Pusta linia oddziela tytuł od treści. Git traktuje wszystko do pierwszej pustej linii jako tytuł.
- Treść jest opcjonalna. Pisz ją, gdy z samego kodu nie widać, dlaczego zmiana była potrzebna: jaki był problem i czemu rozwiązałeś go tak, a nie inaczej. Co się zmieniło, pokazuje diff.
Krótki commit zapiszesz jedną linią z flagą -m. Gdy chcesz dodać treść, wpisz samo git commit: Git otworzy edytor, w którym napiszesz tytuł, pustą linię i treść.
git commit -m "add validation for empty email field"
git commit
Czas teraźniejszy czy przeszły: add czy added?
Tryb rozkazujący: add, fix, remove, a nie added, fixed, removed. Tak zaleca dokumentacja dla osób zgłaszających zmiany do samego Gita: opisz zmianę tak, jakbyś wydawał polecenie kodowi, np. „make xyzzy do frotz”, a nie „I changed xyzzy”.
Prosty test: tytuł powinien pasować do zdania „If applied, this commit will…”:
| Słaby tytuł | Lepszy tytuł | Dlaczego |
|---|---|---|
added login form | add login form | tryb rozkazujący |
fixing bug | fix crash when cart is empty | mówi, jaki błąd |
changes | rename getData to fetchUsers | mówi, co się zmieniło |
fix | fix wrong total for discounted items | sam typ to za mało |
update index.js | show loading spinner while fetching posts | nazwa pliku jest w diffie, cel nie |
WIP | add draft of product filters | wiadomo, czego dotyczy |
Tak samo działają komunikaty, które tworzy sam Git, np. Merge branch 'feature/login-form' albo Revert "add login form". Twoje commity będą do nich pasować.
Dlaczego opisy commitów piszemy po angielsku?
Gitowi jest wszystko jedno, w jakim języku piszesz. Po angielsku warto pisać z kilku powodów:
- Kod i tak jest po angielsku. Nazwy zmiennych, funkcji i bibliotek są angielskie, więc
fix fetchUsers timeoutczyta się naturalnie, apopraw timeout w fetchUsersmiesza dwa języki. - Zespoły są międzynarodowe. Nawet w polskiej firmie do projektu może dołączyć ktoś, kto nie zna polskiego, a historia commitów zostaje na lata.
- Open source i portfolio. Repozytorium na GitHubie oglądają też rekruterzy i programiści spoza Polski.
- Narzędzia. Konwencje takie jak Conventional Commits, generatory changelogów i przykłady w dokumentacji zakładają angielskie słowa kluczowe (
feat,fix,BREAKING CHANGE). - Brak problemów z polskimi znakami. Niektóre terminale i narzędzia nadal źle wyświetlają ogonki.
Wyjątek: jeśli zespół ustalił inaczej, trzymaj się ustaleń zespołu. Spójność historii jest ważniejsza niż wybór języka. Nie musisz znać angielskiego biegle, bo opisy commitów powtarzają kilkanaście czasowników (add, fix, remove, rename, update, move, refactor). Jeśli chcesz to podciągnąć, zajrzyj do artykułu o tym, jak uczyć się angielskiego jako programista.
Czym są Conventional Commits?
Conventional Commits to specyfikacja (obecnie w wersji 1.0.0), która dodaje do tytułu commita typ zmiany. Struktura wygląda tak:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Przykłady:
feat: add password reset form
fix(cart): correct total for discounted items
docs: describe local setup in README
refactor(api): extract fetchUsers to separate module
Jakie typy możesz stosować?
Sama specyfikacja definiuje tylko dwa typy: feat (nowa funkcja) i fix (poprawka błędu). Pozostałe typy są dozwolone. Najczęściej używa się zestawu z konfiguracji @commitlint/config-conventional, opartego na konwencji projektu Angular:
| Typ | Kiedy | Przykład |
|---|---|---|
feat | nowa funkcja | feat: add dark mode toggle |
fix | poprawka błędu | fix: prevent double form submit |
docs | tylko dokumentacja | docs: add API usage example |
style | formatowanie bez zmiany działania | style: format files with Prettier |
refactor | zmiana struktury kodu bez zmiany działania | refactor: split UserCard into smaller components |
perf | poprawa wydajności | perf: cache product list response |
test | testy | test: cover empty cart case |
build | system budowania, zależności | build(deps): bump vite to 6.0.0 |
ci | konfiguracja CI | ci: run tests on pull requests |
chore | prace porządkowe, które nie pasują wyżej | chore: remove unused images |
Aktualizację paczek w praktyce opisuje się jako build(deps): … albo chore(deps): …. Wybierz jedno i trzymaj się tego w projekcie.
Do czego służy zakres w nawiasie?
Zakres (scope) to opcjonalny rzeczownik w nawiasie, który mówi, której części projektu dotyczy zmiana: fix(cart):, feat(auth):, docs(readme):. Przydaje się w większych projektach. W małym repozytorium możesz go pominąć.
Jak oznaczyć zmianę, która coś psuje?
Zmianę łamiącą zgodność (breaking change), np. usunięcie pola z API, oznacza się wykrzyknikiem tuż przed dwukropkiem albo stopką BREAKING CHANGE: na końcu opisu:
feat(api)!: remove deprecated /v1/users endpoint
BREAKING CHANGE: clients must use /v2/users instead.
Co zrobić, gdy zmiana pasuje do kilku typów?
Specyfikacja odpowiada wprost: jeśli to możliwe, zrób kilka commitów. To dobra wskazówka niezależnie od konwencji. Jeśli w jednym commicie naprawiasz błąd, formatujesz pliki i dodajesz funkcję, rozdziel to na trzy commity.
Czy muszę stosować Conventional Commits?
Nie. To konwencja, a nie wymóg Gita. Opłaca się w projektach, w których historia commitów służy też do generowania changelogu albo numerów wersji, i w zespołach, które ją ustaliły. W repozytoriach z zadaniami na devmentor.pl wystarczy prostszy format: numer zadania i opis po angielsku, np. 01: sum numbers in array. Jak wygląda cały proces, opisuję w artykule o tym, jak wykonać zadania z GitHuba i oddać je do code review.
Jak to wygląda w prawdziwym projekcie?
Serwis devmentor.pl, który właśnie czytasz, rozwijamy z Conventional Commits. W połowie listopada 2026 roku jego historia liczyła 1 205 commitów. Tak rozkładają się w niej typy:
| Typ | Liczba commitów |
|---|---|
feat | 468 |
fix | 256 |
chore | 85 |
perf | 51 |
docs | 45 |
test | 41 |
refactor | 32 |
style | 12 |
content | 7 |
ci | 4 |
Kilka tytułów prosto z historii:
feat(blog): table of contents follows the real heading levels
feat(blog): free-material sign-up offer inside articles
fix(chat): teaser no longer waits forever on the navbar's closed menu
test: update stale unit tests to match intentional code changes
Zakres w nawiasie to część serwisu (blog, chat), więc już z samego tytułu widać, czego dotyczy zmiana. Typ content to nasz własny dodatek spoza listy commitlinta. Specyfikacja na to pozwala, byle cały zespół używał go tak samo.
Jak duży powinien być jeden commit?
Jeden commit to jedna zmiana logiczna. Jeśli w tytule chcesz napisać „and”, np. add login form and fix footer, to zwykle znak, że to dwa commity. Małe commity:
- łatwiej opisać, bo tytuł mieści się w 50 znakach,
- łatwiej przejrzeć w code review,
- łatwiej cofnąć (
git revert), gdy jedna z nich okaże się błędem.
Każdy commit powinien zostawiać projekt w stanie, który się uruchamia. Commit „w połowie zmiany” utrudnia późniejsze szukanie błędu w historii.
Co widzi mentor w code review?
W pull requeście oprócz końcowego kodu jest zakładka Commits z całą historią. Gdy commity są małe i dobrze opisane, np. 02: show error for empty input, a potem 02: handle negative numbers, mentor może przejść przez rozwiązanie krok po kroku i zobaczyć, jak do niego dochodziłeś. Wtedy łatwiej trafić z uwagą w konkretny moment, a nie tylko w efekt końcowy. Jeden commit zadania z całym zestawem pokazuje tylko wynik, a droga do niego znika.
Jak poprawić opis ostatniego commita?
Jeśli commit nie został jeszcze wypchnięty (git push), popraw opis przez --amend:
git commit --amend -m "fix crash when cart is empty"
Git zastąpi ostatni commit nowym, z tymi samymi zmianami i nowym opisem. Możesz też najpierw dodać zapomniany plik przez git add, a potem zrobić --amend, wtedy plik trafi do tego samego commita.
Jeśli commit jest już na GitHubie, --amend tworzy inną historię niż ta na serwerze i zwykły git push zostanie odrzucony. Na wspólnej gałęzi nie nadpisuj historii. Zostaw stary opis i zadbaj o następny. Wymuszony push (git push --force) nadpisuje historię innym osobom, więc używa się go tylko na własnej gałęzi, gdy wiesz, co robisz.
Jak opisać pierwszy commit w repozytorium?
Zwyczajowo Initial commit. Taki tytuł nadaje też GitHub, gdy tworzysz repozytorium z plikiem README. Jeśli pierwszy commit zawiera już coś konkretnego, możesz to opisać, np. chore: set up Vite project w konwencji Conventional Commits.
Jak nazywać gałęzie w Git?
Dla nazw gałęzi nie ma oficjalnej specyfikacji takiej jak Conventional Commits, ale w zespołach powtarza się kilka zasad:
- Prefiks rodzaju pracy i ukośnik:
feature/,fix/,docs/,refactor/,chore/. Często te same słowa, co typy commitów. Wiele narzędzi pokazuje gałęzie z ukośnikiem jak katalogi. - Krótki opis małymi literami, z myślnikami:
feature/login-form,fix/cart-total-discount. - Numer zadania z systemu zgłoszeń, jeśli zespół go używa:
feature/DM-142-login-form. Wtedy łatwo połączyć gałąź z zadaniem w Jirze czy GitHub Issues. - Po angielsku, z tych samych powodów co commity.
- Bez spacji i znaków specjalnych. Git odrzuci nazwę ze spacją (
my branch) albo z dwiema kropkami (feature..x). Polskie znaki technicznie przejdą, ale sprawiają kłopoty w terminalu i adresach URL.
| Słaba nazwa | Lepsza nazwa |
|---|---|
nowa | feature/product-filters |
poprawki-janka | fix/empty-cart-crash |
test123 | chore/update-eslint-config |
Feature_Login Form | feature/login-form |
Gałąź tworzysz i od razu się na nią przełączasz poleceniem:
git switch -c feature/login-form
Jak gałęzie i pull requesty wyglądają w codziennej pracy zespołu, opisuję w artykule o tym, jak wygląda praca zespołowa z gałęziami i pull requestami.
Dobry opis commita: lista kontrolna
Zanim zatwierdzisz commit, sprawdź:
- tytuł ma najwyżej ok. 50 znaków i nie kończy się kropką,
- tytuł jest po angielsku, w trybie rozkazującym (
add, nieadded), - tytuł mówi, co się zmieniło, a nie tylko w którym pliku,
- commit zawiera jedną zmianę logiczną,
- jeśli powód zmiany nie jest oczywisty, treść po pustej linii wyjaśnia dlaczego,
- jeśli projekt używa Conventional Commits, jest typ (
feat,fix…) i ewentualnie zakres.


