Skip to content

How to Write a Good Commit Message

Writing commit messages seems to be one of the things that are not really taught. As a result, developers who don't actively seek out existing conventions and advice for writing commit messages often build bad habits and either create their own "convention" or their commit messages are inconsistent or outright unhelpful. It's best to have a good default that applys unless something else is explicitly specified.

A lot has been written about how to write good commit messages. As always, you're encouraged to do additional reading, maybe starting with the links provided at the bottom.

Most commit message conventions across many open-source and closed-source projects are some variant of the convention used by the Linux Kernel project and by Git itself.

Consider this hypothetical commit message: 

Write short imperative one-liner for simple changes
Note the use of the imperative mood. This may seem totally subjective, but it's a decades old practice. This way you can read it like a statement about what change is made by a given version. Some projects use past tense instead of present tense imperative for the header (like "Fixed unintended caching of frobulators" instead of "Fix ..."). Just avoid getting too creative; there's a lot of value in having consistent commit messages that can be read as statements explaining what change is made in that version. Note how Git itself also generates messages in the imperative mood, like "Merge branch ... into ...", and it's the most common convention.

Write short concise imperative header

After a blank like, optionally add additional information in the body.
The less trivial and obvious the change, the more detail you should
probably provide. Explain the why, not just the what and how.

Format the message using linebreaks. Your tool might help you with that,
otherwise insert linebreaks manually. Assume that the commit message
will be displayed in a variety of tools, including IDEs, terminals, and
web browsers. The header is about 50 characters wide, the body up to about 72 characters.

- Consider adding bullet points.
- Maybe add a link to an external resource, like
  https://stackoverflow.com/q/292357/3726133
- Remember that links to external resources may stop working in the
  future.

This longer commit message would be more appropriate for a more complicated change. Note that "more complicated" doesn't necessarily mean "larger". Do aim for small, intentionally scoped commits. However, sometimes even a small change might be worth explaining in more detail if it is not obvious.

Many teams add a ticket ID at the beginning of the header or some other predefined location in the commit message.

Another popular variant is conventional commits, which adds predefined labels to be added to the start of the header and optional footers to the end of the commit message, but the basic structure is the same.

Further Reading: