Commit messages are a valuable form of documentation, and they’re nearly as important as the actual code we write: future engineers on your project will refer to them as part of the debugging process to try to figure out what changed, when, and why. If you didn’t do a good job in writing a commit message, you’re making life much harder for the developers on your team, including yourself.

Good commit messages

A good commit message will provide a brief title, usually a more detailed description of the change, and context/justification for the change if it’s not trivially obvious.

It should include a link to the relevant ticket in JIRA/GitHub/your company’s issue tracker.

If you ever find yourself writing anything that looks like a list in a commit message, consider whether the changes should be split into multiple commits.

Further reading

Read over these posts, too:

• How to Write a Git Commit Message
• 5 Useful Tips For A Better Commit Message
• Writing good commit messages
• On commit messages

Q. I put a link to the JIRA ticket in the pull request description; should I put links to JIRA tickets in commit messages as well?

That’s a judgment call. It should definitely always go in the PR body, but I’ll often link to it in a commit message for context as well.

Keep in mind that while we use PRs for code reviews, their descriptions don’t become part of the git history the way that commit messages do. So if you’re just browsing commits on your computer (particularly via git-bisect), it’s useful to have issue numbers handy without having to trudge through GitHub looking for the PR that merged a particular commit in.