Bereits 2008 hat Tim Pope einen Beitrag zum Thema Commit Messages in Git veröffentlicht. Folgende Best Pratice schlägt er dabei vor:
Capitalized, short (50 chars or less) summary
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body. The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.
Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug." This convention matches up with commit messages generated
by commands like git merge and git revert.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, followed by a
single space, with blank lines in between, but conventions vary here
- Use a hanging indent
Eine Commit Message sollte immer aus einem Titel bestehen, der sich in der ersten Zeile befindet. Dieser Titel sollte nicht mehr als 50 Zeichen enthalten und das Thema kurz und bündig beschreiben. Nutzt dafür die Befehlsform (Imperativ) mit Schlagworten wie „Fix“, „Add“ oder „Change“.
Nach dem Titel folgt eine Leerzeile, gefolgt von der Beschreibung. Diese sollte nicht mehr als 72 Zeichen pro Zeile enthalten. Um das zu erreichen sollten an den entsprechenden Stellen Zeilenumbrüche gesetzt werden. Weitere Paragraphen sind mit einer Leerzeile möglich. Ebenfalls möglich sind Auflistungen mit Bindestrichen oder Sternchen. Bei mehrzeiligen Auflistungen immer zwei Leerzeichen lassen (hängende Einzüge).
Do’s
- Schreibe den Titel im Imperativ. Nutze dabei aussagekräftige Wörter wie „Add“, „Fix“, „Change“ oder „Remove“ an Stelle von „Added“, „Fixed“… etc.
- Der erste Buchstabe des Titels muss groß geschrieben werden
- Die Zweite Zeile muss eine Leerzeile sein, da sie den Titel von der Beschreibung trennt
- Nutze Zeilenumbrüche und Leerzeilen in der Beschreibung um die Commit Message lesbar zu halten
Dont’s
- Der Titel sollte nicht mit einen Satzzeichen enden. Titel haben keine Satzzeichen am Ende. *g*
- Die Beschreibung sollte recht ausführlich erklären welche Anpassungen in euren Commit enthalten sind. Recht ausführlich heißt: Weder ein Einzeiler, noch ein Roman.
Nice2Know
- Wird die Beschreibung zu umfangreich, teile den Commit in einzelne Commits auf.
- Auflistungen sind mit Bindestrichen oder Sternchen möglich (bitte nicht mixen)
- Alle größeren IDE’s unterstützen euch bei der Einhaltung dieser Richtlinen
In der IDE PHPStorm können die Richtlinen für einen Commit angepasst werden.
Fazit
Weiterführende Informationen findet ihr z.B. in der offiziellen Distribution Guideline oder direkt im Beitrag vom Tim Pope. Dort begründet er bspw. wieso eine Zeichenbegrenzung sinnvoll ist. Zusammenfassend lässt sich sagen: Mit einheitlichen Commit Messages bleibt nicht nur die Git History toolübergreifend sauber, sondern auch das Projekt für alle Beteiligten nachvollziehbar.
