commit messages

I’ve had discussions with teammates about Git commit messages once in a while and there are discussions about it on the web. This article summarizes the general approach, and when and how to deviate from it (if you feel like doing so).

The general approach as described on the web can be summarized best by a template from Tim Pope, which is also – with minor modifications– in the Git online book:

" 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 "

Tim Pope, A Note About Git Commit Messages

Or, in short:

• capitalized.
• max. 50 chars for the summary.
• summary does not end with a period.
• summary is in imperative: “fix bug” instead of “fixed bug”.
• body wrapped at about 72 chars.
• summary and body separated by a blank line.

This is quite different from what I experienced in projects. What baffles me is that no source I found on the web includes the issue/ticket number in the commit message, which was quite common in projects that I participated in. Some projects even had a pre-commit hook to check for the issue number.

In general, the Git commit messages I’ve worked with looked more or less like this:

• summary starts with issue number, followed by a blank space and a hyphen or two blank spaces (whatever was used, was used consistently).
• summary contains what has been done and possibly why, but never how it has been done.
• summary was usually max. 50 chars – nobody cared about commit messages that were longer, but not excessively long.
• capitalization used according to each one’s preference. Generally, people didn’t care about this.
• no body. Nobody is going to read that anyway. Whoever wants more information: it’s in the issue.

The capitalization thing is something to think about. Some people might get irritated when confronted with a mix of capitalization and non-capitalization.

An Erlang project on GitHub doesn’t use the issue number, but instead uses the application/part of the project like “erts: …” or “ssl: …”. Notably, they don’t capitalize, but I assume they consistently start with lower case (there is no directive about this in the article). Also notably, it’s the only source I found that mandates not to end the summary line with a period - mentioning the summary is a title and thus shouldn’t end with a period.

In one company I worked at, the mandated standard was using only the issue number for the commit message and nothing else. All senior devs (including me) completely ignored that standard – and it is completely understandable why.

In my opinion, a good commit message standard for a team is:

• summary starts with issue number, followed by a blank space and a hyphen or two blank spaces - whatever is used, is used consistently.
• keep it short, around 50 chars or less.
• summary contains what has been done and possibly why, but never how it has been done.
• summary is precise. “Fixed some bug in …” is not precise.
• capitalization is appreciated, but not mandatory (unless the team agrees on a standard here).
• imperative form or else – it doesn’t matter.
• no period at the end of the summary.
• no body.

reference

Tim Pope, blog, A Note About Git Commit Messages

Git SCM online book, 5.2 Distributed Git - Contributing to a Project

erlang / otp repo on GitHub, Writing good commit messages

Chris Beam, blog, Introduction: Why good commit messages matter

Who-T, blog, On commit messages