Ein Commit ist mehr als „Code speichern“. In Git wird damit ein kleiner, nachvollziehbarer Schritt in der Entwicklung festgehalten. Ob beim Code-Review, beim Nachbauen eines Bugs oder beim Erstellen von Release Notes: Oft entscheidet die Commit-Nachricht darüber, wie schnell sich ein Problem einordnen lässt. Gute Messages sparen Zeit, reduzieren Missverständnisse und machen die Historie auch Monate später noch lesbar.
Im Alltag entstehen schlechte Commit Messages selten aus Absicht, sondern aus Stress: „fix“, „wip“, „final“ oder „changes“ klingt schnell, hilft aber niemandem. Mit ein paar einfachen Regeln lässt sich eine Commit Message so schreiben, dass sie für andere (und für das Zukunfts-Ich) wirklich nützlich ist.
Warum Commit Messages in der Praxis so wichtig sind
Git speichert zwar jede Änderung, aber ohne Kontext bleibt die Historie schwer nutzbar. Eine gute Nachricht beantwortet im Kern: „Was wurde geändert und warum?“ Das ist besonders hilfreich in diesen Situationen:
- Code Review: Reviewer sehen schneller, welche Absicht hinter einem Change steckt.
- Bugfix-Rückverfolgung: Mit git bisect oder beim Blick auf eine Datei wird ein „Warum“ plötzlich entscheidend.
- Releases: Viele Teams generieren Changelogs aus Commits oder orientieren sich daran.
- Onboarding: Neue Teammitglieder verstehen die Entwicklungsgeschichte einfacher.
Wichtig: Eine Message ersetzt keine Dokumentation, aber sie ist ein zuverlässiges Mikro-Protokoll direkt am Code.
Der Aufbau: Betreff, Details und optionales „Warum“
Eine Commit-Nachricht darf kurz sein, sollte aber strukturiert wirken. In der Praxis hat sich ein 3-teiliger Aufbau bewährt:
1) Betreffzeile: knapp, eindeutig, handlungsorientiert
Die erste Zeile ist die wichtigste. Sie erscheint in Logs, in Pull Requests und in vielen Tools als Zusammenfassung. Gute Betreffzeilen:
- beschreiben das Ergebnis, nicht die Tätigkeit („Validierung ergänzen“ statt „Validierung gemacht“)
- sind konkret („Login-Redirect bei abgelaufener Session“ statt „Fix login“)
- vermeiden Füllwörter („Update“, „Changes“, „Stuff“)
Ein hilfreicher Test: Lässt sich der Betreff sinnvoll nach „Dieser Commit …“ ergänzen? Wenn ja, passt die Richtung.
2) Body: wenn nötig, nicht aus Pflichtgefühl
Viele Commits kommen ohne Body aus. Ein Body lohnt sich, wenn eine Änderung nicht sofort offensichtlich ist oder wenn Entscheidungen erklärt werden müssen. Typische Inhalte:
- Warum wurde es geändert (Motivation, Problem, Bug-Ursache)?
- Welche Alternative wurde verworfen (und warum)?
- Welche Nebenwirkungen sind zu beachten (Migration, Performance, Kompatibilität)?
Ein Body kann aus wenigen Sätzen bestehen. Entscheidend ist die Klarheit, nicht die Länge.
3) Referenzen: Tickets, Issues, Breaking Changes
Wenn im Team mit Tickets gearbeitet wird, hilft ein sauberer Verweis. Das muss nicht kompliziert sein: „Refs: ABC-123“ oder „Fixes #456“ (je nach System/Workflow). So kann später automatisch verknüpft werden, ohne dass man raten muss.
Konventionen, die Teams wirklich helfen (ohne Dogma)
Viele Teams nutzen eine feste Schreibweise, damit die Historie einheitlich bleibt. Eine verbreitete Methode ist Conventional Commits (Konvention für Prefixe wie feat/fix/docs). Das ist kein Muss, aber oft praktisch, weil sich Commits schnell scannen lassen und Tools darauf aufbauen können.
Wenn ein Prefix Sinn ergibt
Prefixe helfen, wenn ein Team regelmäßig Release Notes erstellt oder viele parallele Arbeiten laufen. Häufig genutzte Typen (als Orientierung):
- feat: neue Funktion oder neuer Use Case
- fix: Bugfix, also ein Fehler wird behoben
- refactor: Umstrukturierung ohne verändertes Verhalten
- docs: Dokumentation
- test: Tests
- chore: Wartung (z. B. Dependencies, Build)
Wichtig: Prefixe ersetzen nicht die eigentliche Aussage. „fix: stuff“ ist immer noch unklar.
Scope nutzen, wenn es im Projekt mehrere Bereiche gibt
Ein optionaler Scope (z. B. „fix(auth): …“) ist hilfreich, wenn eine Codebase mehrere Module hat. Er lohnt sich besonders bei Monorepos oder klar getrennten Bereichen (Frontend/Backend, Admin/User, API/Worker).
Beispiele: von „meh“ zu gut nachvollziehbar
Ein paar typische Verbesserungen aus dem Alltag:
| Schwache Nachricht | Bessere Alternative |
|---|---|
| fix | fix: Validierung für Passwort-Reset ergänzt |
| update api | feat(api): Pagination-Parameter limit/offset dokumentiert |
| wip | refactor(ui): Formular-Validierung in Hilfsfunktion ausgelagert |
| final | fix(auth): Logout löscht Session-Cookie zuverlässig |
Die bessere Variante macht ohne weiteren Kontext klar, welcher Bereich betroffen ist und was sich geändert hat.
Mini-Entscheidungshilfe für typische Commit-Situationen
Die schwierigste Frage ist oft: „Ist das jetzt ein fix, ein refactor oder doch ein feat?“ Diese kurze Orientierung hilft bei der Einordnung:
- Ändert sich das Verhalten für Nutzer:innen oder andere Systeme?
- Ja → eher feat (neu) oder fix (Fehler behoben).
- Nein → eher refactor/chore/test.
- War vorher etwas kaputt oder falsch, gemessen an der erwarteten Funktion?
- Ja → fix.
- Nein → weiter prüfen.
- Ist die Änderung „nur“ intern (Aufräumen, Struktur, Performance) ohne neue Features?
- Ja → refactor (Code-Änderung) oder chore (Build/Tools/Dependencies).
Kurze Praxis-Box: so entstehen gute Commit Messages
- Vor dem Commit kurz prüfen: Welche eine Änderung beschreibt dieser Commit wirklich?
- Betreff formulieren als Ergebnis: „X verhindert“, „Y ergänzt“, „Z entfernt“.
- Bei Bedarf einen kurzen Body: 1–3 Sätze „Warum“ und „Worauf achten“.
- Wenn ein Ticket existiert: Referenz ergänzen (z. B. „Refs: …“).
- Nach dem Commit einmal in git log –oneline schauen: Lässt sich die Historie gut scannen?
Häufige Fehler und wie sie sich vermeiden lassen
Zu große Commits: eine Nachricht kann nicht alles erklären
Wenn eine Commit-Nachricht „mehrere Themen“ beschreiben müsste, ist der Commit meist zu groß. Besser sind kleinere Schritte, die jeweils ein Ziel haben. Das macht Reviews und Reverts (Zurückrollen) deutlich einfacher.
„Und warum?“ fehlt bei riskanten Entscheidungen
Manche Änderungen sind technisch korrekt, aber ohne Begründung schwer zu bewerten: Workarounds, temporäre Flags, Performance-Tricks. Hier hilft ein kurzer Body, der die Entscheidung erklärt. Das stärkt die Nachvollziehbarkeit und reduziert spätere Diskussionen.
Merge-Commits als Informationsmüll
Automatische Merge-Commit-Texte sind oft wenig hilfreich. Wenn Merge-Commits im Workflow normal sind, lohnt es sich, sie bei Bedarf manuell zu ergänzen (z. B. „merge: neue Zahlungsoption und Fix für Timeout“). Alternativ kann ein Team auf Rebase-Workflows setzen.
Zusammenhang mit Branching und Rebase: was in Logs gut funktioniert
Commit Messages wirken nicht isoliert. Sie hängen am Workflow: Viele kleine, klare Commits sind in Feature-Branches gut reviewbar. Beim Rebase lassen sich Messages außerdem aufräumen (z. B. „squash“ und dann eine saubere Zusammenfassung schreiben). Wer tiefer einsteigen will: Git Branching verstehen – Workflow für Teams ohne Chaos und Git Rebase verstehen – Branches sauber zusammenführen.
Team-Regeln festlegen: klein starten, konsequent bleiben
Ein Team muss nicht sofort ein perfektes Regelwerk einführen. Oft reichen wenige Leitlinien, die im Alltag wirklich gelebt werden:
- Ein Commit = ein Thema (so gut es geht).
- Betreff beschreibt das Ergebnis, nicht die Tätigkeit.
- Prefixe nur, wenn sie im Team genutzt und verstanden werden.
- „Warum“ in den Body, wenn es nicht offensichtlich ist.
Wer bereits mit gezielten Übernahmen einzelner Commits arbeitet, profitiert besonders von klaren Messages, weil Commits dann wie Bausteine wirken. Passend dazu: Git Cherry-Pick verstehen – gezielt Commits übernehmen. Und wenn kurzfristig Änderungen geparkt werden, sollten spätere Commits trotzdem sauber benannt werden: Git Stash verstehen – Änderungen sicher parken und zurückholen.
Kurzer Spickzettel: gute Formulierungen für häufige Fälle
Wer sich beim Schreiben schwer tut, kann mit wiederkehrenden Mustern starten. Diese Formulierungen sind neutral und funktionieren in vielen Projekten:
- „fix: Fehler bei … verhindert“
- „feat: Unterstützung für … ergänzt“
- „refactor: Logik für … vereinfacht“
- „docs: Beispiel für … ergänzt“
- „test: Fälle für … ergänzt“
- „chore: Abhängigkeiten aktualisiert“ (nur, wenn das wirklich der Kern ist)
Mit der Zeit entsteht daraus eine klare Sprache im Team. Genau das macht eine Historie wertvoll: Sie lässt sich lesen wie eine Reihe kleiner, verständlicher Entscheidungen.
