Git Conventional Commits

The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.

  • Automatically generating CHANGELOGs.
  • 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.


Conventional Commits[1] specifies the structure of the commit message:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]


The type must use lowercase, cannot empty, followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space.

There are all available commit types:

  • build
  • chore
  • ci
  • docs
  • feat
  • fix
  • perf
  • refactor
  • revert
  • style
  • test


A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis.


The description is a short summary of the code changes, cannot be empty, and does not end with a period.


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.

A commit body is free-form and MAY consist of any number of newline separated paragraphs.

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.

A footer’s token MUST use - in place of whitespace characters, a only exception is made for BREAKING CHANGE.

A footer’s value MAY contain spaces and newlines.

Correlate with SemVer

Some commit types may affect SemVer changes:

  1. fix means patches a bug, this correlates with PATCH in Semantic Versioning.
  2. feat means introduces a new feature, this correlates with MINOR in Semantic Versioning.
  3. BREAKING CHANGE is in the footer, or appends a ! after the type/scope, this correlates with MAJOR in Semantic Versioning.



Gitmoji[2] is an initiative to standardize and explain the use of emojis on GitHub commit messages.

VS Code Extension

When committing in the VS Code, Conventional Commits[3] extension can help to generate a commit message.

The interface of Conventional Commits

GitHub Action

Release Please Action[4] is a GitHub Action, which can auto-generate and create releases based on commit messages.

Release Please Action will automatically create release pr includes generated CHANGELOG. When PR is merged, it will create a release, and you can run CI/CD and upload files to the release.

The PR created by Release Please Action


  1. "Conventional Commits". Retrieved 28 June 2022.
  2. "gitmoji". Archived from the original on 28 June 2022. Retrieved 28 June 2022.
  3. "Semantic Versioning". Archived from the original on 28 June 2022. Retrieved 28 June 2022.
  4. "Release Please Action". Archived from the original on 28 June 2022. Retrieved 28 June 2022.

Git Conventional Commits
Andy Zhang
Posted on
June 28, 2022
Licensed under