tl;dr Write useful Git commit messages by following an appropriate message format.
Git requires messages for every commit. These are shown in the Git log. So whenever it is necessary to examine the history of a file, it is very painful if these messages don't contain any useful information, as this requires diving into the sourcecode and diff of every single commit. The same applies to reviews, for example to check all changes in a feature branch.
Commit messages therefore should always
- …describe the change
- What was the reason for the change?
- What is changed?
- …be comprehensible.
A good commit subject is
A bad commit subject is
💡 I good trick is to mentally review the subject and message preceding
each with the sentence
When pushed, this commit will _______.
Based on the TYPO3 commit message format and best practice guides I wrote an example message format, which may be used as a convention.
[FEATURE] Short summary of changes introduced by this patch More detailed explanatory text, if necessary. Wrap it to ca 74 characters. The first line is treated as the subject of the commit message and the rest of the text as the body. The blank line separating the subject from the body is critical (unless you omit the body entirely). Write your commit message in the imperative present tense ("Fix bug" and not "Fixed bug"), since a commit is a set of instructions for how to go from a previous state to the new state and the commit message should describe this process. This convention matches up with generated commit messages by commands like git merge and git revert. The title has to have one of these prefixes: [BUGFIX] (fixes a bug), [FEATURE] (any new feature, also small additions) and [TASK] (none of the above, e.g. code cleanup). These flags might be added additionally: [!!] (breaking change), [DB] (the database definition needs to be updated), [CONF] (some configuration changed), [SECURITY] (fix a security issue). Help others to understand what you did (Motivation for the change? Whats the difference to the previous version?). Keep it simple and avoid repeating information that is already contained in the issue tracker (descriptions how to reproduce a bug should remain in the ticket). Add relationships to the issue tracker at the bottom of the commit message, using common tags like "Ref", see http://is.gd/commit_refs. * Bullet points are okay, too * An asterisk is used for the bullet Resolve #42 Ref #4 #8 #15 #16
I maintain an up-to-date version of this snippet as Gist.
BTW: A list of funny and crappy commit messages is available at whatthecommit.com. Don't appear on that list, write good commit messages instead.