Git Commit-Template: einheitliche Commit-Nachrichten im Team erzwingen

1. Warum uneinheitliche Commit-Nachrichten teuer werden

Eine Commit-Historie ist im besten Fall eine lesbare Chronik, die erklärt, warum eine Änderung stattgefunden hat, nicht nur was geändert wurde. In der Praxis sieht die Historie vieler Repositories aber anders aus: Nachrichten wie fix, update oder wip tauchen im Wechsel mit ausführlichen Absätzen auf, ohne erkennbares Muster. Wer später mit git log oder git blame nach dem Grund einer Änderung sucht, findet in solchen Repositories oft nichts Brauchbares, obwohl die Information technisch vorhanden wäre, nur eben nicht strukturiert.

Das Problem verschärft sich mit der Teamgröße, weil jeder Entwickler seinen eigenen Stil mitbringt und ohne Vorgabe auch behält. Ein Reviewer kann eine unklare Nachricht zwar im Pull Request bemängeln, aber das kostet Zeit und führt selten zu einer dauerhaften Verhaltensänderung, weil die Korrektur immer erst nachträglich erfolgt. Ein Commit-Template setzt genau hier an, indem es die Struktur bereits im Editor vorgibt, bevor der Commit überhaupt erstellt wird, und damit die Wahrscheinlichkeit einer sinnvollen Nachricht deutlich erhöht.

2. Grundlagen: commit.template und .gitmessage

Git erlaubt es, per Konfiguration eine Textdatei zu hinterlegen, die beim Aufruf von git commit ohne -m als Vorlage im Editor erscheint. Die Konfigurationsoption heißt commit.template und verweist auf eine beliebige Datei, üblicherweise .gitmessage im Home-Verzeichnis oder im Repository selbst. Alles, was in dieser Datei mit einer Raute beginnt, wird als Kommentar behandelt und beim Speichern automatisch aus der endgültigen Nachricht entfernt, sodass sich die Vorlage frei mit Hinweisen und Beispielen füllen lässt, ohne die eigentliche Nachricht zu verunreinigen.

Für ein einzelnes Repository reicht eine lokale git config Einstellung, für ein ganzes Team ist es sinnvoller, die Vorlage als Datei im Repository zu versionieren und die Konfiguration über ein Setup-Skript oder direkt in der README zu dokumentieren. So sieht jeder neue Mitarbeiter dieselbe Vorlage, ohne sie manuell abtippen zu müssen.

# Vorlage im Repository ablegen
cat > .gitmessage <<'EOF'
# <typ>(<bereich>): <kurze Zusammenfassung, max. 50 Zeichen>
#
# Ausführlichere Beschreibung des Warum, nicht nur des Was.
# Zeilenumbruch bei etwa 72 Zeichen.
#
# Bezugnehmende Ticket-Nummer oder Issue-Referenz, z.B. Refs: JIRA-123
EOF

# Konfiguration für dieses Repository
git config commit.template .gitmessage

# Konfiguration global für alle Repositories eines Entwicklers
git config --global commit.template ~/.gitmessage

3. Aufbau einer guten Template-Datei

Eine bewährte Struktur orientiert sich an den Conventional Commits, weil das Format nicht nur für Menschen lesbar ist, sondern sich auch maschinell auswerten lässt, etwa für automatisch generierte Changelogs. Der Aufbau besteht aus einem Typ wie feat, fix, docs oder refactor, einem optionalen Bereich in Klammern und einer kurzen Zusammenfassung im Imperativ, gefolgt von einer Leerzeile und einem ausführlicheren Body.

Wichtig ist, dass die Vorlage konkrete Beispiele enthält statt nur abstrakter Platzhalter, weil Entwickler unter Zeitdruck eher eine Vorlage kopieren und anpassen, als eine Regel aus dem Gedächtnis zu rekonstruieren. Ebenso hilfreich ist ein Hinweis auf die maximale Zeilenlänge der ersten Zeile, weil viele Tools, darunter GitHub und GitLab, die erste Zeile in Listenansichten abschneiden und eine zu lange Zusammenfassung dort unleserlich wird.

4. Lokale Einrichtung vs. teamweite Verteilung

Eine rein lokale Vorlage, die jeder Entwickler manuell einrichtet, funktioniert nur so lange, wie niemand vergisst, sie einzurichten, und genau das passiert in der Praxis regelmäßig bei neuen Teammitgliedern oder frisch geklonten Maschinen. Zuverlässiger ist es, die Vorlage und die Konfiguration Teil eines Onboarding-Skripts zu machen, das ohnehin beim ersten Setup ausgeführt wird, etwa zusammen mit der Installation von Abhängigkeiten oder Git-Hooks.

Da commit.template selbst nicht versioniert werden kann, weil es sich um eine lokale Konfigurationsoption handelt, bleibt die Vorlage nur eine Empfehlung, solange sie nicht technisch erzwungen wird. Der nächste Schritt ist deshalb immer eine serverseitige oder CI-basierte Prüfung, die unabhängig von der lokalen Einrichtung greift.

#!/usr/bin/env bash
# scripts/setup-git.sh, Teil des Onboarding-Prozesses
set -euo pipefail

git config commit.template .gitmessage
git config core.hooksPath .githooks

echo "Git Commit-Template und Hooks eingerichtet."

5. Durchsetzung mit dem lokalen commit-msg Hook

Ein commit-msg Hook erhält den Pfad zur temporären Datei mit der eingegebenen Commit-Nachricht als Argument und kann den Commit-Vorgang mit einem Fehlercode abbrechen, bevor er überhaupt entsteht. Damit lässt sich technisch prüfen, ob eine Nachricht dem geforderten Format entspricht, etwa per regulärem Ausdruck gegen das Conventional-Commits-Schema.

Der Hook liegt im Verzeichnis .git/hooks, das nicht versioniert wird, weshalb er entweder über core.hooksPath auf ein versioniertes Verzeichnis umgeleitet oder über ein Tool wie Husky installiert werden muss. Wichtig ist, dass der Hook nur lokal greift und von jedem Entwickler mit --no-verify umgangen werden kann, weshalb er allein keine verlässliche Durchsetzung darstellt, sondern nur schnelles Feedback direkt beim Committen liefert.

#!/usr/bin/env bash
# .githooks/commit-msg
MSG_FILE="$1"
PATTERN='^(feat|fix|docs|style|refactor|perf|test|chore)(\([a-z0-9_-]+\))?: .{1,50}'

if ! grep -qE "$PATTERN" "$MSG_FILE"; then
  echo "Commit-Nachricht entspricht nicht dem geforderten Format." >&2
  echo "Beispiel: feat(checkout): Gutschein-Validierung ergänzen" >&2
  exit 1
fi

6. Verbindliche Durchsetzung mit commitlint in der CI

Weil lokale Hooks umgangen werden können, gehört die eigentliche Durchsetzung in die CI-Pipeline, wo sie nicht mehr optional ist. Das Tool commitlint prüft Commit-Nachrichten gegen ein konfigurierbares Regelwerk und wird üblicherweise mit der Preset-Konfiguration für Conventional Commits betrieben. In der Pipeline reicht ein Job, der alle neuen Commits eines Merge Requests oder Pull Requests gegen das Regelwerk prüft und bei Verstoß fehlschlägt.

Diese Prüfung sollte so früh wie möglich in der Pipeline laufen, weil sie schnell ist und keine Abhängigkeiten zu Build oder Tests hat. Ein fehlgeschlagener commitlint-Job liefert dem Entwickler außerdem eine präzise Fehlermeldung mit dem verletzten Regel-Namen, was die Korrektur deutlich einfacher macht als eine generische Ablehnung im Review.

# commitlint.config.js
module.exports = { extends: ["@commitlint/config-conventional"] };

# In der CI Pipeline, z.B. GitLab CI oder GitHub Actions
npx commitlint --from=origin/main --to=HEAD --verbose

7. Interaktive Unterstützung mit Commitizen

Statt sich auf das Gedächtnis der Entwickler zu verlassen, kann ein interaktives Tool wie Commitizen die Nachricht Schritt für Schritt abfragen: Typ, Bereich, Zusammenfassung, ausführliche Beschreibung und Breaking-Change-Hinweise werden nacheinander erfragt und am Ende zu einer formkonformen Nachricht zusammengesetzt. Der Aufruf erfolgt über git cz statt git commit und produziert dadurch praktisch immer eine valide Nachricht, ohne dass der Entwickler das Format aktiv im Kopf behalten muss.

Der Vorteil gegenüber einer reinen Text-Vorlage liegt in der geführten Eingabe, die Tippfehler im Typ-Feld praktisch ausschließt, weil die Auswahl aus einer Liste erfolgt statt aus freier Texteingabe. In Kombination mit dem commit-msg Hook als Fallback für Entwickler, die weiterhin git commit direkt nutzen, lässt sich so eine hohe Formatkonsistenz erreichen, ohne jedem Workflow vorzuschreiben, welches Tool er benutzen muss.

8. Automatisiertes Changelog aus Commit-Nachrichten

Ein strukturiertes Commit-Format zahlt sich am deutlichsten aus, sobald daraus automatisch ein Changelog erzeugt wird. Tools wie conventional-changelog oder release-please lesen die Commit-Historie seit dem letzten Release, gruppieren die Einträge nach Typ und erzeugen daraus eine strukturierte Release-Notiz, ohne dass ein Mensch die Änderungen manuell zusammenfassen muss.

Diese Automatisierung funktioniert nur zuverlässig, wenn die zugrunde liegenden Commit-Nachrichten tatsächlich konsistent sind, weshalb sie einen zusätzlichen, sehr konkreten Anreiz für Teams liefert, die Durchsetzung ernst zu nehmen: Ein einzelner Commit ohne korrekten Typ fällt im Changelog entweder ganz heraus oder landet in einer unpassenden Kategorie, was schnell auffällt und die Motivation für saubere Nachrichten im Alltag erhöht.

9. Einführung in einem bestehenden Repository

Bei einem gewachsenen Repository lohnt es sich nicht, alte Commit-Nachrichten rückwirkend anzupassen, weil das die Historie über git rebase massiv verändern würde und für alle bestehenden Klone zu Konflikten führt. Stattdessen wird die neue Regelung ab einem festen Zeitpunkt eingeführt, üblicherweise ab dem nächsten Release-Tag, und der commitlint-Job in der CI prüft nur Commits, die nach diesem Zeitpunkt entstanden sind.

Ein sanfter Einstieg besteht darin, die CI-Prüfung zunächst nur als Warnung laufen zu lassen, bevor sie nach einer Übergangsphase von wenigen Wochen zum Pflicht-Check wird, der einen fehlgeschlagenen Merge Request tatsächlich blockiert. So gewöhnt sich das Team an das neue Format, bevor es verbindlich durchgesetzt wird, und die Akzeptanz im Team ist am Ende deutlich höher als bei einer sofortigen harten Einführung.

10. Zusammenfassung

11. FAQ: Commit-Templates