How to write better commit messages?

Miad Vosoughi Nia
@Miad_Vosoughi
• 3 min read
Git commit messages

What's the benefit of commit conventions?

Whether you are working alone or as a team it is always essential to define a git commit message convention. Having a well-organized and structured message history could save you a lot of time and effort when it comes to reviewing the commits, finding changes related to a bug, and generally maintaining a repository. It will also make it a lot easier to implement SemVer and use other git commands like git shortlog, git revert.

How to choose the best commit convention?

Depending on the type of project, and your team preference you can choose an existing commit convention or define a custom convention for your project. Whichever you choose, make sure you stick to it and be consistent.

What is conventional commits specification?

Conventional Commit Specification is one of the popular commit conventions that you can choose for your project. here we will have a sneak peek at it.

Commit message structure

According to Conventional Commit Specification messages should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
  1. Type: A commit type must always present and it could be one of the following fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test: and others.
  • fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning).
  • feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning).
  • Additional types are not mandated by the Conventional Commits specification and have no implicit effect in Semantic Versioning (unless they include a BREAKING CHANGE).
  • BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.
  1. Scope: an optional noun may be provided as additional contextual info wrapped in parenthesis. e.g. feat(auth): support google auth.
  2. Description: a description MUST immediately follow the colon and space after the type/scope prefix. The description is a summary of the code changes. It should be present tense. Not capitalized. No period in the end.”, and imperative like the type.
  3. Body: a longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description.
  4. Footer: one or more footers MAY be provided one blank line after the body. Each footer MUST consist of a word token, followed by either a :<space> or <space># separator, followed by a string value.

Some examples

refactor!: drop support for react 16.0.0

feat: add related blogs section

show related blogs in footer of blog page.

Reviewed-by: Z
Refs: #123