Wie verfasst man klare und konsistente Git-Commit-Messages?

Motivation: Allzu oft unverständliche Commit-Messages

In vielen Projekten – insbesondere wenn Juniorteams oder neu zusammengestellte Entwicklergruppen zusammenarbeiten – stösst man auf Commit-Messages wie „Stuff fixed“, „update code“ oder gar einfach „.“, die kaum bis gar keinen Mehrwert bieten. Das erschwert nicht nur die Zusammenarbeit, sondern führt auch zu zeitintensiven Rückfragen, wenn nachträglich nachvollzogen werden soll, was genau geändert wurde und warum.

Dieses Problem habe ich in Projekten immer wieder beobachtet und sehe darin grosses Verbesserungspotenzial. Aus diesem Grund entstand dieser Blog-Beitrag: Er soll zeigen, wie sich durch prägnante, strukturierte und konsistente Commit-Messages – gerade in heterogenen Teams – viel Zeit sparen lässt: bei der täglichen Entwicklung genauso wie bei Code-Reviews oder bei der Fehlersuche.

Warum sind gute Commit-Messages so essenziell?

1. Nachvollziehbarkeit der Entwicklung:
   Liegt der Grund für eine bestimmte Änderung einige Monate zurück, bieten aussagekräftige Commit-Messages ein schnelles Nachschlagewerk.
2. Effizientere Code-Reviews:
   Kurz und präzise beschriebene Änderungen erleichtern es Reviewerinnen und Reviewern, den Zweck des Commits auf einen Blick zu verstehen.
3. Einfachere Fehleranalyse (Debugging):
   Hat sich ein Bug eingeschlichen, kann man mithilfe aussagekräftiger Commits schnell ermitteln, wann und wie eine bestimmte Funktionalität verändert wurde.
4. Weniger Rückfragen im Team:
   Gerade in gemischten Teams mit Junior Developer:innen und Entwicklern kann es passieren, dass sich Unklarheiten häufen. Gute Commit-Messages klären oft bereits im Vorfeld wichtige Fragen.
5. Bessere Projektdokumentation:
   Kompaktes, gut lesbares „Logbuch“ des Projekts – eine Ressource, die zukünftige Veränderungen und Projektentscheidungen erleichtert.

Der ideale Aufbau einer Commit-Messages

Im Idealfall gliedert sich eine Commit-Message in drei Bereiche:

1. Kurze Zusammenfassung (Subject Line)
   • Verwenden Sie die imperative Form („Add ... “, „Fix ...“).
   • Formulieren Sie maximal 50 bis 72 Zeichen.
   • Beschreiben Sie in wenigen prägnanten Worten, was geändert wurde.
2. Leerer Absatz
   • Dieser sorgt für eine klare Abtrennung zwischen dem Titel und der Detailbeschreibung.
3. Ausführliche Beschreibung (Body)
   • Erklären Sie, warum und wie die Änderung durchgeführt wurde.
   • Nennen Sie etwaige Hintergründe, Architekturentscheidungen oder Referenzen zu Tickets/Issues.
   • Weisen Sie explizit auf „Breaking Changes“ oder notwendige Migrationen hin.
4. Footer (optional)
   • Fügen Sie hier Referenzen zu Issues oder Tickets ein (z. B. „Fix #123“).
   • Nutzen Sie ihn für spezielle Hinweise („BREAKING CHANGE“) oder Co-Autoren-Erwähnungen.

Wichtige Best Practices

1. Verwenden Sie die imperative Form

Durch das Formulieren von Commit-Messages im Imperativ („Add ...“, „Update …“) erreichen Sie eine klare, einheitliche und anwenderorientierte Sprache.

• Korrekt:
  • „Fix NullPointerException in order management"
  • "Add validation for input fields"
• Weniger geeignet:
  • „The NullPointerException has been fixed“
  • „Validation added“

2. Halten Sie die Zusammenfassung kurz

Maximal 50 Zeichen im Betreff sorgen dafür, dass Tools und Logs die Nachricht gut lesbar darstellen. Wichtige Details gehören in den Body.

3. Nutzen Sie den Body für Details

Der Body erlaubt es Ihnen, Hintergründe und Veränderungen genauer auszuführen. Insbesondere in Teamumgebungen mit Junior-Developer:innen und -entwicklern kann diese Erläuterung helfen, voneinander zu lernen und Code-Reviews zu beschleunigen.

4. Seien Sie konsistent im Team

Gerade in Projekten, in denen Junior- und Senior-Entwickler:innen und -entwickler zusammenarbeiten, ist ein gemeinsamer Stil besonders wichtig. Legen Sie Guidelines fest und sorgen Sie für deren Einhaltung.

5. Verweisen Sie auf Issues oder Tickets

Verknüpfen Sie Code und Projektmanagement-System, indem Sie Issues im Footer der Commit-Messages nennen. Dadurch haben alle Beteiligten einen direkten Bezug zu den ursprünglichen Anforderungen oder gemeldeten Fehlern.

6. Achten Sie auf atomare Commits

Ein Commit sollte stets eine in sich geschlossene Veränderung beinhalten. So lassen sich Probleme leichter eingrenzen oder auch rückgängig machen, ohne andere Teile des Codes zu gefährden.

Praxisbeispiele für Commit-Messages

Beispiel 1: Kurz und knapp

"Add email notifications for new registrations"

• Imperative Form: „Add ...“
• Kurze, verständliche Beschreibung

Beispiel 2: Ausführliche Beschreibung

Fix NullPointerException in the user administration

The method getUserDetails() could return null, which led to a
NullPointerException in the presentation layer. An
additional check now prevents null values from being used
are used unprotected.

Fix #42

• Subject Line (Titel): Fix NullPointerException …
• Body: Kurze Erläuterung von Problem und Lösung
• Footer: Verweis auf das zugehörige Issue

Beispiel 3: Breaking Change

Refactor the API endpoint for user profiles

The response format has been changed from JSON to XML.
All clients must adapt their implementations accordingly.

BREAKING CHANGE: The new format is not backwards compatible

• Kennzeichnung eines Breaking Changes
• Unmissverständlicher Hinweis für alle betroffenen Systeme

Beispiel 4: Convention-basierte Commit Messages (Conventional Commits)

feat(auth): Implement two-factor authentication

This change introduces two-factor authentication for all users.
This requires an additional security check before the system can be accessed.
system can be accessed.

Closes #101

• feat(auth): Zeigt Art und Scope des Commits an
• Erläuterung im Body, verlinktes Issue im Footer

Praktische Tipps aus der Projektarbeit

1. Integrieren Sie Commit Guidelines in Onboarding-Prozesse:
   Gerade für Juniors ist es hilfreich, wenn das Projekt-Repository bereits über klare Richtlinien oder Templates (z. B. .gitmessage) verfügt, die automatisch in die Commit-Message eingefügt werden.
2. Nutzen Sie automatisierte Prüfungen:
   Tools wie Commitlint ermöglichen es, Commit-Messages auf Einhaltung bestimmter Konventionen zu überprüfen.
3. Führen Sie kurze Schulungen im Team durch:
   Stellen Sie sicher, dass alle Teammitglieder die Vorteile verstehen, die saubere Commit-Messages mit sich bringen. Ein 30-minütiger Workshop zu diesem Thema kann bereits erhebliche Verbesserungen bewirken.
4. Geben Sie konstruktives Feedback:
   Wenn Juniors unpassende Commit-Messages schreiben, sollte das beim Code-Review gut begründet zurückgemeldet werden, damit sie sich verbessern können.
5. Setzen Sie sich realistische Ziele:
   Besser regelmässig kleine Commits mit passenden Nachrichten als seltene, grosse Sammelcommits, die niemand mehr durchschaut.

Fazit

Gerade in Projekten mit gemischtem Team – vom Junior bis hin zur Seniorentwickler:in oder -entwickler – sind klare und konsistente Commit-Messages ein mächtiges Instrument, um die Zusammenarbeit zu stärken und den Entwicklungsprozess effizient zu gestalten.

Werden die in diesem Beitrag vorgestellten Best Practices befolgt, entstehen eine nachvollziehbare Projekthistorie, weniger Rückfragen und eine reibungslosere Abstimmung untereinander. Eine gute Commit-Messages kostet nur wenige Extra-Sekunden beim Verfassen, bringt aber langfristig immense Vorteile bei Wartung, Debugging und Code-Reviews.

Weiterführende Links:

• Conventional Commits
• Semantic Versioning (Deutsch)
• Git Dokumentation (Offiziell)

Viel Erfolg beim Verfassen Ihrer nächsten Commit-Message!