How to Write Useful Commit Messages

Effective commit messages simplify the code review process and aid long-term code maintenance. Unfortunately, commit messages don’t get much respect, so the world is littered with useless messages like Fix bug or Update UI.

There’s no widespread agreement about what makes a good commit message or why it’s useful, so I’m sharing my thoughts based on my 20 years of experience as a software developer.

• An example of a useful commit message
• What’s the point of a commit message?
  • Helps your code reviewer approach the change
  • Communicates changes to teammates, downstream clients, and end-users
  • Facilitates future bug investigations
  • Provides information to development tools
• Organizing information in a commit message
  • Put the most important information first
  • Use headings to structure long commit messages
• What should the commit message include?
  • A descriptive title
  • A summary of how the change impacts clients and end-users
  • The motivation for the change
  • Breaking changes
  • External references
  • Justifications for new dependencies
  • Cross-references to issues or other changes
  • Summaries of bugs or external references
  • Testing instructions
  • Testing limitations
  • What you learned
  • Alternative solutions you considered
  • Searchable artifacts
  • Screenshots or videos
  • Rants and stories
  • Anything you’re tempted to explain outside of the commit message
• What should the commit description leave out?
  • Information that’s obvious from the code
  • Critical details about maintaining the code
  • Short-term discussion
  • Preview URLs and build artifacts
• Further reading

An example of a useful commit message

Here’s an example of a useful, effective commit message: