pixelbrackets
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 [BUGFIX] Change the order of JavaScript calls.
A bad commit subject is various changes.
💡 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 #16I 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.