Commit Message Style Guide
Sometimes when I come across a particularly grotesque line of code I’ll use
git-blame in the hopes that I’ll find a descriptive commit message. More often than not, though, it’ll look something like this:
Author: Lazy Developer <firstname.lastname@example.org>
Date: Wed Aug 17 15:54:52 2016 -0400
The commit message is useless, but
git-blame isn’t; I know who needs to be taken off of the Christmas card list.
Good commit messages provide documentation for each feature and line of code. Commit messages that describe the desired result of each code change can help other developers make sure they’re not inadvertently breaking any functionality.
Using a single well-written commit message per change makes it easy to use powerful tools like git-bisect and even simple ones like git-log.
The first line of a Git commit message is a brief summary of the change. It should complete the sentence: “This commit will…”.
The subject should:
- Be a 50 character phrase
- Start with a capital letter
- not end with punctuation
- Concisely describe the change
A blank line separates the subject and body. It is required, otherwise the message will be incorrectly parsed by
git-log and GitHub.
The body describes the change in detail. It should not only discuss what has changed but also why it has changed. If it helps, you may use bullet points or other plain-text formatting to help convey your message.
The body should:
- Answer how and why; not necessarily what.
- Have 72-character lines
- Be written in paragraph form
Optionally, the commit message may end with references to any Trello cards, GitHub Issues, JIRA tickets – anything that is relevant to this change.
Commit Message Hall of Shame
- “Added right func”
- “one more”
- “remove test”
- “I hope it works.”