Summary of Conventional Commits

5 min readAugust 25, 2021
gitcommitmessage

Conventional commits is a lightweight convention on top of commit messages. The specification doesn’t change the native git commit message guidelines but rather adds a structure to it. It provides an easy set of rules for creating an explicit commit history. This convention fits perfectly with semantic versioning, by describing the features, fixes, and breaking changes made in commit messages.


Structure of commit message

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit types

TypeSemVer
any of following types- A commit that has a footer:
BREAKING CHANGE: <description>

AND/OR

- A commit that has a ! after the type or optional scope:
<type>[optional scope]!: <description>
MAJOR
Breaking Change
featA new feature, introducing a new feature to the codebaseMINOR
fixA bug fix, patching a bug in your codebasePATCH
refactorA change that neither fixes a bug nor adds a feature-
docsDocumentation only changes-
styleChanges that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)-
perfA code change that improves performance-
testAdding missing or correcting existing tests-
choreChanges to the build process or auxiliary tools and libraries such as documentation generation-
ciChanges to the continuous integration-
buildChanges to the build process or code generation-

Commit scope

A scope may be provided to a commit’s type, to provide additional contextual information and is contained within parentheses.

Commit description (summary portion only)

  • Use imperative tone. e.g. add instead of added
  • Start with a lowercase and don’t end with a dot

Template file

Create a template file in your home directory ~/.gitmessage for a neat summary every time you run git commit command.


# ███╗   ███╗███████╗███████╗███████╗ █████╗  ██████╗ ███████╗
# ████╗ ████║██╔════╝██╔════╝██╔════╝██╔══██╗██╔════╝ ██╔════╝
# ██╔████╔██║█████╗  ███████╗███████╗███████║██║  ███╗█████╗
# ██║╚██╔╝██║██╔══╝  ╚════██║╚════██║██╔══██║██║   ██║██╔══╝
# ██║ ╚═╝ ██║███████╗███████║███████║██║  ██║╚██████╔╝███████╗
# ╚═╝     ╚═╝╚══════╝╚══════╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝
# <type>[optional scope]: <description>
#
# [optional body]
#
# [optional footer(s)]
# +-----------+----------------------------------------------------------+----------+
# | Type      |                                                          | SemVer   |
# +-----------+----------------------------------------------------------+----------+
# | any of    | A commit that has a footer:                              | MAJOR    |
# | following | BREAKING CHANGE: <description>                           |          |
# | types     |                                                          | BREAKING |
# |           | AND/OR                                                   | CHANGE   |
# |           |                                                          |          |
# |           | A commit that has a ! after the type or optional scope:  |          |
# |           | <type>[optional scope]!: <description>                   |          |
# +-----------+----------------------------------------------------------+----------+
# | feat      | A new feature, introducing a new feature to the codebase | MINOR    |
# +-----------+----------------------------------------------------------+----------+
# | fix       | A bug fix, patching a bug in your codebase               | PATCH    |
# +-----------+----------------------------------------------------------+----------+
# | refactor  | A change that neither fixes a bug nor adds a feature     | -        |
# +-----------+----------------------------------------------------------+----------+
# | docs      | Documentation only changes                               | -        |
# +-----------+----------------------------------------------------------+----------+
# | style     | Changes that do not affect the meaning of the code       | -        |
# |           | (white-space, formatting, missing semi-colons, etc)      |          |
# +-----------+----------------------------------------------------------+----------+
# | perf      | A code change that improves performance                  | -        |
# +-----------+----------------------------------------------------------+----------+
# | test      | Adding missing or correcting existing tests              | -        |
# +-----------+----------------------------------------------------------+----------+
# | chore     | Changes to the build process or auxiliary tools and      | -        |
# |           | libraries such as documentation generation               |          |
# +-----------+----------------------------------------------------------+----------+
# | ci        | Changes to the continuous integration                    | -        |
# +-----------+----------------------------------------------------------+----------+
# | build     | Changes to the build process or code generation          | -        |
# +-----------+----------------------------------------------------------+----------+
#
# Note: A scope may be provided to a commit’s type, to provide additional contextual
# information and is contained within parentheses.

Examples

Different types of commits

feat(api): add an endpoint for user profile updates
fix(profile): bug in user email update
refactor: extract repeated logic out of user profile controller
chore: add editor configurations

Breaking change

refactor!: drop support for node 0.12
feat: drop support for node 0.12

BREAKING CHANGE: node version 0.12 is no longer supported.
fix(api)!: drop support for node 0.12

Neither of these versions are supported by the Node project anymore
and continuing support for them was already preventing us from
picking up important fixes in other dependencies.

BREAKING CHANGE: node version 0.12 is no longer supported.

Why?

  • Automatically generating change logs.
  • Automatically determining a semantic version bump (based on the types of commits landed).
  • Communicating the nature of changes to teammates, the public, and other stakeholders.
  • Triggering build and publish processes.
  • Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.
  • Making it easier to write automated tools

Read more on Conventional Commits specification

Copyright © 2006 - 2021 Vahid Hallaji
The content and codes are open source and published under the CC BY-SA and MIT licences respectively unless otherwise noted.
If you find anything you can improve, please feel free to submit an issue or a pull request.
Built with Nextjs and deployed by Vercel.