Git-Commit-Nachricht: Die Regeln, Beispiele und Konventionen

Warum eine Git-Commit-Nachricht wichtig ist

Eine Commit-Nachricht erklärt deine Änderungen allen, die den Code später lesen, auch deinem zukünftigen Ich.

In drei Monaten wirst du nicht mehr wissen, warum du diese Datenpipeline umgestaltet oder warum du für eine bestimmte Operation von Pandas zu Polars gewechselt hast. Deine Commit-Nachricht ist die einzige Aufzeichnung deiner Überlegungen. Ohne das musst du raten oder dich durch Slack-Threads und JIRA-Tickets wühlen.

Hier sind noch ein paar weitere Gründe, warum Git-Commit-Meldungen wichtig sind.

Code-Reviews gehen schneller mit klaren Commit-Meldungen. Dein Prüfer kann die Nachricht überfliegen, die Absicht verstehen und sich darauf konzentrieren, ob die Umsetzung passt. Vage Nachrichten zwingen die Prüfer dazu, deine Gedanken anhand der Diff herauszufinden.

Auch das Debuggen wird einfacher. Wenn ein Fehler auftaucht, kannst du mit git log oder git blame nachverfolgen, wann der problematische Code eingefügt wurde. Eine Nachricht wie „Authentifizierungsfehler beheben“ sagt dir überhaupt nichts. Eine Meldung wie „Fix Token-Ablaufprüfung in Auth-Middleware” zeigt dir direkt, wo das Problem liegt.

Teamarbeit hängt von einer übersichtlichen Historie ab. Wenn jemand deinem Projekt beitritt oder dort weitermacht, wo du aufgehört hast, wird er die Commits durchlesen, um zu verstehen, wie sich die Codebasis entwickelt hat. Klare Nachrichten machen deine Git-Historie zu einer Dokumentation, die dir wirklich weiterhilft.

Das Fazit ist, dass das Schreiben einer beschreibenden Commit-Nachricht 15 bis 30 Sekunden dauert. Aber es spart später viel Zeit und Verwirrung.

Die wichtigsten Regeln für eine gute Git-Commit-Nachricht

Gute Commit-Meldungen folgen ein paar einfachen Regeln – mehr ist es nicht.

Für zukünftige Leser schreiben

Deine Commit-Nachricht ist im Moment nicht für dich selbst gedacht – sie ist für alle, die sie in sechs Monaten lesen werden.

Diese Person könnte ein neues Teammitglied sein, das versucht zu verstehen, warum der Code so funktioniert, wie er funktioniert. Vielleicht bist du es, der versucht, sich daran zu erinnern, warum du eine bestimmte Entscheidung getroffen hast. So oder so, sie werden nicht den Kontext haben, den du heute hast.

Konzentrier dich auf die Absicht und die Argumentation, nicht nur auf das, was sich geändert hat. Der Diff zeigt, was sich geändert hat. Deine Nachricht sollte erklären, warum es geändert wurde und welches Problem es löst.

Sei klar und prägnant

Kurze, beschreibende Nachrichten sind einfacher zu überfliegen, wenn du Dutzende von Commits durchsiehst.

Eine Nachricht wie „Caching hinzufügen” ist echt vage. Eine Meldung wie „Redis-Caching für API-Antworten hinzufügen” sagt dir genau, was passiert ist. Du kannst es unter git log --oneline nachlesen und sofort sehen, was der Commit macht.

Deine Betreffzeile sollte die Frage beantworten: Was macht dieser Commit? Wenn du mehr als 50 bis 60 Zeichen brauchst, um das zu beantworten, machst du wahrscheinlich zu viele Änderungen auf einmal.

Bleib konsequent

Wenn dein Repository einheitlich ist, ist die Historie vorhersehbar und einfacher zu analysieren.

Wenn alle Commits das gleiche Format haben, kannst du den Verlauf schnell durchsehen. Du weißt, wo du nach der Art der Änderung, dem Umfang und der Beschreibung suchen musst. Teams, die einheitliche Formate durchsetzen, können auch Aufgaben wie das Erstellen von Änderungsprotokollen oder das Filtern von Commits nach Typ automatisieren.

Such dir einen Stil aus und bleib dabei. Wenn dein Team Imperative im Präsens benutzt, wechsle nicht einfach so zur Vergangenheitsform.

Erkläre, was und warum (nicht wie)

Der Code zeigt, wie du das Problem gelöst hast. Deine Commit-Nachricht sollte erklären, was das Problem war und warum du dich für diese Lösung entschieden hast.

Schreib nicht „load_data() umgeschrieben, um Listenkompréhension anstelle einer for-Schleife zu verwenden”. Schreib „Datenladen bei großen CSV-Dateien um 40 % beschleunigen“. Die erste Nachricht erklärt die Codeänderung. Der zweite erklärt die Auswirkungen.

Füge Kontext hinzu, wenn das zukünftigen Lesern hilft, deine Entscheidung zu verstehen. Wenn du drei verschiedene Ansätze ausprobiert hast, bevor du dich für diesen entschieden hast, sag das. Wenn es einen ähnlichen Fehlerbericht oder eine Designentscheidung gibt, verweise darauf.

Die Struktur einer Git-Commit-Nachricht

Die meisten Git-Commit-Meldungen haben eine Standardstruktur mit drei Teilen: Betreffzeile, Hauptteil und Fußzeile.

Betreffzeile

Die Betreffzeile ist eine einzeilige Zusammenfassung, die in „ git log --oneline “ und Pull-Request-Listen angezeigt wird.

Wenn möglich, solltest du es unter 50 Zeichen halten, höchstens 72. Diese Begrenzung sorgt dafür, dass die Nachricht in der Terminalausgabe und in der Benutzeroberfläche von GitHub richtig angezeigt wird, ohne abgeschnitten zu werden. Wenn deine Zusammenfassung nicht in 50 Zeichen passt, versuchst du wahrscheinlich, zu viele Änderungen in einem Commit zu beschreiben.

Benutz den Imperativ „ “ – schreib „add feature“ statt „added feature“ oder „adds feature“. Stell dir vor, du vervollständigst den Satz „Wenn dieser Commit angewendet wird, wird ...“. Also, „Wenn angewendet, fügt dieser Commit Redis-Caching hinzu” liest sich ganz normal, während „Wenn angewendet, fügt dieser Commit Redis-Caching hinzu” nicht so gut klingt.

Beispiele:

• fix null pointer exception in data loader

• add caching layer for API responses

• remove deprecated pandas functions

Körper (wenn nötig)

Überspringe den Hauptteil für einfache Änderungen. Wenn deine Betreffzeile den Commit komplett erklärt, bist du fertig.

Füge einen Text hinzu, wenn du erklären musst, warum du die Änderung vorgenommen hast, oder gib einen Kontext an, der zukünftigen Lesern hilft. Lass zwischen Betreff und Text eine Leerzeile – Git nutzt das, um die beiden Teile zu trennen.

Der Text sollte Fragen beantworten wie: Welches Problem löst das? Warum hast du dich für diesen Ansatz entschieden? Gibt's irgendwelche Nebenwirkungen oder Einschränkungen? Hast du auch andere Lösungen in Betracht gezogen?

Mach Zeilenumbrüche bei 72 Zeichen, damit der Text in der Terminalausgabe gut lesbar bleibt. Die meisten Texteditoren können das automatisch machen.

Beispiel:

add Redis caching for API responses

API response times were hitting 2-3 seconds for repeated queries.
Added Redis with 5-minute TTL to cache query results. This drops
response time to ~50ms for cached queries.

Considered using in-memory cache but Redis lets us scale horizontally
if needed.

Fußzeile (optional)

Nutze die Fußzeile, um auf verwandte Probleme, Pull-Anfragen oder wichtige Änderungen hinzuweisen.

Wenn dein Commit ein GitHub-Problem behebt, füge bitte Fixes #123 oder Closes #456 in die Fußzeile ein. GitHub schließt das Problem automatisch, wenn der Commit zusammengeführt wird. Für grundlegende Änderungen füge „ BREAKING CHANGE: “ hinzu, gefolgt von einer Beschreibung dessen, was kaputt gegangen ist und wie man migriert.

Beispiel:

remove support for Python 3.7

Python 3.7 reached end-of-life in June 2023. This commit drops
support and updates minimum version to Python 3.8.

BREAKING CHANGE: Python 3.7 users must upgrade to 3.8 or later.
Closes #789

Für die meisten Commits brauchst du keine Fußzeile – nur wenn du auf externe Referenzen verlinkst oder wichtige Änderungen markierst.

Häufige Arten von Git-Commit-Meldungen und wann man sie benutzt

Viele Projekte benutzen Präfixe für Commit-Typen, um Änderungen auf einen Blick zu kategorisieren.

Du musst dir keine strenge Liste von Bezeichnungen merken. Das Ziel ist, den Lesern zu helfen, schnell zu erkennen, welche Art von Änderung passiert ist, ohne den ganzen Diff lesen zu müssen.

Hier sind vier Kategorien, die du beachten solltest:

• Feature-Änderungen bringen neue Funktionen mit sich. Benutze Präfixe wie feat: oder add:, wenn du was Neues entwickelst – einen neuen API-Endpunkt, eine Datenverarbeitungsfunktion oder eine benutzerorientierte Funktion. Beispiel: feat: add CSV export for analysis results.

• Fehlerbehebungen, lösen vorhandene Probleme. Benutze „ fix: “, wenn du ein Verhalten korrigierst, das nicht wie gewünscht funktioniert hat. Das kann alles Mögliche sein, von einer Null-Zeiger-Ausnahme bis hin zu falschen Berechnungen in deinem Modell. Beispiel: fix: handle missing values in preprocessing pipeline.

• Dokumentationsaktualisierungen verbessern Code-Kommentare, README-Dateien oder Inline-Dokumentationen. Benutze „ docs: ”, wenn du die Funktionsweise des Codes nicht änderst, sondern ihn nur besser erklärst. Beispiel: docs: add usage examples for data loader class.

• Refactoring und Wartungsarbeiten machen die Codestruktur besser, ohne das Verhalten zu ändern. Benutz „ refactor: “, wenn du Code umstrukturierst, um ihn übersichtlicher und wartungsfreundlicher zu machen. Benutz einfach „ chore: “ für Routineaufgaben wie das Aktualisieren von Abhängigkeiten oder das Ändern von Build-Konfigurationen. Beispiele: refactor: extract validation logic into separate module oder chore: update pandas to 3.0.0.

Such dir den Typ aus, der deine Veränderung am besten beschreibt, und mach weiter – es ist wichtiger, konsequent zu sein, als das „perfekte“ Etikett zu finden.

Regeln für das Schreiben besserer Git-Commit-Meldungen

Hier ist eine Checkliste mit Regeln, die deine Commit-Meldungen nützlicher machen.

• Die Betreffzeile sollte nicht länger als 50 Zeichen sein. Das sorgt dafür, dass es in „ git log --oneline “, der Commit-Liste von GitHub und der Terminalausgabe ohne Abkürzungen richtig angezeigt wird. Wenn deine Nachricht nicht in 50 Zeichen passt, versuch, maximal 72 Zeichen zu verwenden.

• Benutze den Imperativ. Schreib „Funktion hinzufügen” statt „Funktion hinzugefügt” oder „fügt Funktion hinzu”. Deine Betreffzeile sollte den Satz „Wenn dieser Commit angewendet wird, wird ...“ vervollständigen. Also, „Wenn angewendet, fügt dieser Commit Caching hinzu“ ist richtig.

• Trenn Betreff und Text durch eine Leerzeile. Git nutzt diese Leerzeile, um zwischen der Zusammenfassung und der ausführlichen Erklärung zu unterscheiden. Ohne diese Einstellung zeigen Git-Tools deine Nachricht möglicherweise falsch an.

• Lass den Punkt am Ende der Betreffzeile weg. Du sparst Zeichen und die Betreffzeile ist sowieso kein vollständiger Satz. Schreib lieber fix null pointer in loader statt fix null pointer in loader.

• Schreib das erste Wort deiner Betreffzeile groß. Schreib lieber Add caching for API calls statt add caching for API calls. So bleibt dein Commit-Verlauf einheitlich und sieht professionell aus.

• Benutz den Text, um zu erklären, warum, nicht was. Der Diff zeigt, was sich geändert hat. Dein Text sollte die Gründe für die Änderung, alternative Ansätze, die du in Betracht gezogen hast, und alle Kompromisse, die du eingegangen bist, erklären.

• Den Text nach 72 Zeichen umbrechen. Das verhindert Probleme mit Zeilenumbrüchen in der Terminalausgabe und sorgt dafür, dass deine Commit-Meldungen in verschiedenen Tools gut lesbar bleiben.

• Mach jeden Commit atomar. Eine logische Änderung pro Commit. Wenn du einen Fehler behebst und Code umgestaltest, teile das in zwei Commits mit separaten Nachrichten auf.

Beispiele für eine gute Git-Commit-Nachricht

Hier sind ein paar Beispiele aus der Praxis, die zeigen, wie gute Commit-Meldungen in verschiedenen Situationen aussehen können.

Eine einfache Lösung

fix: handle NaN values in feature engineering

The preprocessing pipeline crashed when encountering NaN values
in the 'age' column. Added fillna() with median imputation before
scaling features.

Das klappt, weil es das Problem (NaN-Abstürze) erkennt, erklärt, wo es passiert ist (Vorverarbeitungs-Pipeline, Altersspalte), und die Lösung (Median-Imputation) beschreibt.

Eine neue Funktion

feat: add model performance tracking to MLflow

Added automatic logging of model metrics, parameters, and artifacts
to MLflow after each training run. This replaces our manual CSV
logging and makes experiment comparison much easier.

Metrics tracked: accuracy, precision, recall, F1 score
Training time also logged for performance monitoring.

Gute Feature-Commits erklären, was du gemacht hast, warum es nützlich ist und alle Details, die den Lesern helfen, den Umfang zu verstehen.

Eine Umgestaltung

refactor: split data_loader.py into separate modules

Moved dataset classes to datasets.py, transformation logic to
transforms.py, and utility functions to utils.py. The original
file was 800+ lines and hard to navigate.

No behavior changes - all tests still pass.

Refactor-Meldungen sollten klar machen, dass du die Funktionalität nicht geändert hast, sondern nur die Struktur. Der Satz „Alle Tests sind weiterhin bestanden“ beruhigt die Prüfer.

Ein Update der Dokumentation

docs: add examples for custom loss functions

Previous documentation showed only built-in loss functions.
Added three examples: weighted cross-entropy, focal loss, and
custom regression loss with L1 regularization.

Each example includes code and explanation of when to use it.

In Dokumentations-Commits solltest du erklären, was du dokumentiert hast und warum das nötig war.

Auf ein Problem oder Ticket verweisen

fix: prevent memory leak in batch processing

Large datasets caused memory usage to grow unbounded during batch
processing. The issue was holding references to processed batches
in the results list.

Changed to yield results instead of accumulating them in memory.
Memory usage now stays constant regardless of dataset size.

Fixes #247

Wenn du auf ein Problem verweist, gib bitte genug Infos dazu, damit man die Lösung versteht, ohne auf das Ticket klicken zu müssen. Der Befehl „ Fixes #247 “ unten sagt GitHub, dass es das Problem automatisch schließen soll, wenn dieses Commit zusammengeführt wird.

Alle Beispiele laufen so ab: Man fängt mit den Änderungen an, erklärt, warum sie gemacht wurden, gibt Infos, die für spätere Leser nützlich sind, und verweist auf ähnliche Probleme, wenn das passt.

Herkömmliche Commits als Standard für Git-Commit-Meldungen

Conventional Commits ist ein beliebtes Format, das Commit-Meldungen durch ein einfaches Präfixmuster strukturiert.

Grundformat

Das Format sieht so aus: type(scope): description.

Der Typ sagt dir, welche Art von Änderung du machst – feat für Features, fix für Bugfixes, docs für Dokumentation, refactor für Code-Umstrukturierungen und so weiter. DerBereich „ “ ist optional und zeigt, welcher Teil des Codes geändert wurde – wie zum Beispiel (auth) oder (api). DieBeschreibung „ “ erklärt, was du gemacht hast.

Beispiele:

feat(api): add endpoint for batch predictions
fix(auth): prevent token expiration edge case
docs(readme): add installation instructions for Windows
refactor(data): extract validation logic to separate module

Denk einfach dran, dass das 'ne Konvention ist und keine Pflicht. Git ist es egal, ob du dieses Format benutzt. Es geht hauptsächlich darum, dass das Team entscheidet, wie die Nachrichten strukturiert werden sollen, damit alles einheitlich ist und die richtigen Tools genutzt werden.

Wann sind normale Commits nützlich?

Teams, die ihre Release-Prozesse automatisieren, holen das Beste aus herkömmlichen Commits raus.

Tools können deinen Commit-Verlauf analysieren und automatisch Änderungsprotokolle erstellen. Wenn du eine Version markierst, checkt das Tool alle Commits seit der letzten Version, sortiert sie nach Typ (feat, fix, docs) und erstellt ein formatiertes Änderungsprotokoll. Das erspart dir die mühsame Suche nach den Änderungen zwischen den Versionen.

Herkömmliche Commits unterstützen auch die automatische semantische Versionierung. Wenn alle deine Commits seit der letzten Version repariert sind, erhöht das Tool die Patch-Version (1.2.3 → 1.2.4). Wenn du Funktionen hinzugefügt hast, wird die Nebenversion erhöht (1.2.3 → 1.3.0). Wichtige Änderungen führen zu einer großen Versionsänderung (1.2.3 → 2.0.0).

Aber wenn dein Team keine automatisierten Releases oder Changelog-Generierung nutzt, könnten herkömmliche Commits übertrieben sein. Die Struktur hilft Maschinen mehr als Menschen, also denk daran.

Häufige Fehler bei Git-Commit-Meldungen, die du vermeiden solltest

Selbst erfahrene Entwickler machen manchmal Fehler beim Schreiben von Commit-Meldungen, aber das hat eher mit Faulheit als mit mangelndem Wissen zu tun.

Hier sind ein paar Fehler, die du vermeiden solltest.

Unklare oder allgemeine Nachrichten

Nachrichten wie „Bug beheben“ oder „Code aktualisieren“ sagen zukünftigen Lesern nichts.

Wenn du nach einer bestimmten Änderung in git log suchst, musst du Dutzende von Commits durchsehen. Eine Nachricht mit dem Inhalt „Bug beheben“ zwingt dich dazu, den Diff zu öffnen und den Code zu lesen, um zu verstehen, was behoben wurde. Eine Meldung wie „Fix null pointer in data preprocessing” (Null-Zeiger in der Datenvorverarbeitung korrigieren) sagt dir sofort, ob das der Commit ist, den du suchst.

Allgemeine Nachrichten verschwenden die Zeit von allen. Wenn du dich nicht mehr genau daran erinnern kannst, was du geändert hast, um eine konkrete Nachricht zu schreiben, solltest du wahrscheinlich noch nicht committen.

Unzusammenhängende Änderungen mischen

Ein Commit sollte eine logische Änderung haben.

Wenn du einen Fehler behebst und nicht zusammenhängenden Code im selben Commit umgestaltest, erschwert das die Codeüberprüfung und macht das „ git bisect ” nutzlos. Wenn dieser Commit eine Regression verursacht, muss jemand rausfinden, welcher Teil der Änderung dafür verantwortlich ist. Wenn sie nur nur die Fehlerbehebung rückgängig machen wollen, geht das nicht – sie machen auch die Umgestaltung rückgängig.

Du solltest Änderungen immer in separate Commits aufteilen. Behebe den Fehler in einem Commit und refaktoriere in einem anderen. Jeder Commit sollte so sein, dass du ihn einzeln rückgängig machen kannst, ohne die Codebasis kaputt zu machen.

Wenn du die Änderungen schon lokal gemischt hast, benutze ` git add -p `, um Teile von Dateien separat vorzubereiten und sie in logischen Blöcken zu committen.

Nachrichten über laufende Arbeiten hinterlassen

Commits mit Nachrichten wie „WIP“ oder „temp fix“ sind lokal okay, sollten aber nicht in den Hauptzweig Zweig.

Bevor du deinen Feature-Zweig zusammenführst, räum mal deine Commit-Historie auf. Squash WIP-Commits in sinnvolle Commits mit passenden Nachrichten umwandeln. Schreib „asdf” und „etwas ausprobieren” in Beschreibungen um, die erklären, was du wirklich gemacht hast.

Benutz „ git rebase -i “, um Commits zusammenzufassen, Nachrichten umzuschreiben und Änderungen neu zu ordnen, bevor du sie pushst. Dein Team sollte einen übersichtlichen Überblick darüber bekommen, was sich geändert hat und warum, ohne sich durch deinen Debugging-Prozess kämpfen zu müssen.

Tipps für Teams, die Git-Commit-Meldungen nutzen

Wenn dein Team die Git-Historie wirklich nützlich machen will, braucht ihr Konsistenz. Hier sind ein paar bewährte Vorgehensweisen, die du beachten solltest.

Sagt euch frühzeitig auf einen gemeinsamen Stil ab. Entscheide, ob du normale Commits, ein eigenes Format oder einfach nur ein paar grundlegende Regeln verwenden willst. Entscheide dich für einen Ansatz und bleib mit dem ganzen Team dabei. Wenn die Hälfte deiner Commits „feat: Funktion hinzufügen” und die andere Hälfte „Neue Funktion hinzugefügt” heißt, wird es schwieriger, deinen Verlauf zu überblicken, und die Automatisierung kann kaputtgehen.

Der Stil ist nicht so wichtig wie die Leute, die ihn nachmachen. Einige Teams sagen lieber „add feature“ (Funktion hinzufügen) im Imperativ, andere sagen „added feature“ (Funktion hinzugefügt) in der Vergangenheit. Beide funktionieren gut, wenn man sie konsequent anwendet.

Schreib deine Konventionen irgendwo hin, wo du sie leicht finden kannst. Füge deinem Repo eine CONTRIBUTING.md-Datei hinzu, in der du dein Commit-Message-Format mit Beispielen erklärst. Nimm es in die Einführungsunterlagen für neue Teammitglieder auf. Wenn dich jemand fragt: „Wie soll ich diesen Commit formatieren?“, schick ihn einfach zur Dokumentation, statt es nochmal zu erklären.

Deine Dokumentation sollte das von dir verwendete Grundformat abdecken, wann du einen Text hinzufügen solltest und wann du es bei einer Betreffzeile belassen solltest, wie du auf Probleme oder Tickets verweisen kannst, sowie ein paar echte Beispiele aus deinem Repository.

Benutze Commit-Meldungen bei der Codeüberprüfung. Gute Commit-Meldungen machen die Überprüfung von Pull-Anfragen schneller und zielgerichteter. Die Prüfer können die Commit-Meldungen lesen, um den Verlauf der Änderungen zu verstehen, bevor sie sich mit dem Code beschäftigen.

Überprüfe bei der Überprüfung die Commit-Meldungen genauso wie du den Code überprüfst. Wenn eine Nachricht unklar oder irreführend ist, bitte darum, dass sie vor dem Zusammenführen umgeschrieben wird. Ein PR mit klaren Commits ist einfacher zu überprüfen, bei Bedarf leichter rückgängig zu machen und später leichter zu verstehen.

Fazit

Eine klare Commit-Nachricht dauert 30 Sekunden, spart aber später stundenlange Verwirrung.

Stell dir deine Commit-Historie als Dokumentation vor, die mit deinem Code einhergeht. Wenn du „Bug beheben“ statt „Null-Zeiger in der Datenvorverarbeitung beheben“ schreibst, verschwendest du die Zeit von allen, die diesen Commit später lesen – dich selbst eingeschlossen.

Behandle deine Commit-Meldungen wie Code. Wenn du schlampigen, unkommentierten Code nicht in die Produktion schicken würdest, dann schick auch keine schlampigen Commit-Meldungen. Benutz den Imperativ, halt die Betreffzeilen unter 50 Zeichen, erklär bei Bedarf im Text, warum du was machst, und mach jeden Commit atomar.

Jetzt weißt du, wie man aussagekräftige Commit-Meldungen schreibt. Um deine Fähigkeiten auf die nächste Stufe zu bringen, melde dich für unseren Git-Kurs für Fortgeschrittene an.