Sinnvolle Commit Messages

Christian Siewert, 18. May 2016

Mit Sicherheit ist jeder schon einmal über Commits gefallen, aus denen er nicht schlauer wurde. Häufig liegt das an vagen, kurzen Aussagen in Commit Messages wie z.B. Anpassungen oder Diverse Änderungen.

Hier stelle ich ein paar Angewohnheiten vor, die meine Commit History davor bewahren, so zu enden wie in diesem XKCD:

XKCD - Git commit

Dies sind alles Meldungen, die wenig bis garkeine nützlichen Informationen enthalten. Die dargestellte Extreme habe ich zwar noch nicht gesehen, aber auch hier finden wir den Klassiker Code Additions/Edits. Überflüssiger kann es nicht sein: Dass irgendetwas hinzugefügt (oder gelöscht) bzw. angepasst wurde, ist selbsterklärend. Andernfalls hätte der Autor wohl kaum die Versionskontrolle bemüht.

It’s all fun and games until nobody has any idea what the hell is going on. – @ThePracticalDev

Was den Leser (dazu gehört auch das zukünftige Selbst!) vor allem interessiert, ist, warum diese Änderungen gemacht wurden, weshalb welche Entscheidungen getroffen wurden.

Einen ersten Hinweis darauf kann unter anderem eine Ticketnummer liefern. So lässt sich dann evtl. über Ticketsystem/Issue-Tracker nachvollziehen, was die Intention war.

Ohne weitere Informationen kann schonmal ein wenig Zeit verloren gehen: Tickethistorie muss studiert, die konkreten Änderungen müssen analysiert, Kollegen konsultiert werden usw.

Template

Um diesen Problemen entgegenzuwirken, schreibe ich Commit-Messages etwa nach dem Muster, wie es Tim Pope in seiner Note About Commit Messages vorschlägt:

<Ticketnr.> Kurze beschreibung, *was* geändert wurde

Nach einer Leerzeile folgen dann Erläuterungen, *warum* die Änderungen
gemacht wurden und was sie bewirken. Dabei versuche ich 80 Zeichen 
nicht zu überschreiten.

Weitere Absätze folgen nach weiteren Leerzeilen.
  • Die Ticketnummer ist hier optional und hängt i.d.R. auch vom jeweiligen Projekt ab.
  • Die einleitende Betreff-Zeile soll kurz zusammenfassen, was geändert wurde. Diese Zeile ist die, die in den Logs angezeigt wird. Details sind meist nicht weiter nötig. Die können wenn nötig z.B. mit diff-Tool abgefragt werden.
  • Der weitere Teil sollte dann erklären, warum welche Entscheidungen getroffen wurden, wie sich das neue zum alten Verhalten unterscheidet usw.

Im Gegensatz zu Tim Pope, der für den Betreff ~50 und für Erläuterungen <72 Zeichen je Zeile ansetzt, erlaube ich es mir, für beides max. 80 Zeichen zu verwenden.
Tim führt dabei (April 2008) die Lesbarkeit in der Konsole an. Das entspricht jedoch weniger meinem Workflow: Wenn ich Logs durchstöbere, nutze ich dafür in der Regel lieber eine bequeme GUI. Außerdem sind die meisten Konsolen - z.B. auch PowerShell - nicht (mehr) auf 80 Spalten begrenzt.

Warum halte ich mich dennoch an 80 Zeichen? Ergonomie: Auch wenn Monitore und Tools mehr Platz für weitaus längere Zeilen bieten, lässt sich Text dennoch einfacher erfassen, wenn er in der Breite begrenzt ist.

Zusätzlich formatiere ich die Messages, wenn nötig, mit Markdown. Z.B.: * für Bullet Points und `` für Code, etc.

Babysteps

Babysteps halte ich eigentlich aus anderen Gründen für eine sinnvolle Vorgehensweise. Doch gerade für das schreiben von Commit Messages sind sie sehr wertvoll.

Diverse Änderungen gehen sehr oft, mit Monster-Commits einher, In denen viel Code geändert wurde. Alternativ gibt es zahlreiche aufeinanderfolgende Commits mit der gleichen Message.

Eine Ursache dafür ist, dass Entwickler scheinbar den Überblick darüber verlieren, was sie genau und aus welchem Grund geändert haben. Dann scheint der Aufwand zu groß, die Details aufzuschlüsseln.

Mit Babysteps committe ich häufig kleine Änderungen und kann sie detailliert erklären. Mit Git halte ich es manchmal so, dass ich mehrere einzelne Commits, die zusammengehören zu einem einzigen zusammenfasse bevor ich pushe. Dadurch kann ich auch größere Commits mit genügend Details versehen.

Fazit

Das tatsächliche Format von Commit-Messages ist sicherlich Geschmacksache und hängt auch davon ab wie man mit den Logs arbeitet oder sie aufbereitet. Generell macht es das Schreiben von guten Commit-Messages jedoch einfacher, wenn man eine Vorlage hat, an der man sich orientieren kann.

Wer dazu in kleinen Schritten vorgeht, läuft weniger gefahr, Details seiner Änderungen beim Committen zu vergessen. Das hilft dem Team und erweckt nicht den Eindruck, als wüsste man nicht, was man eigentlich macht.

Wie schreibst du (bzw. dein Team) Commit Messages? Gibt es Meldungen, die dir besonders auffallen?

Resourcen