Conventional Commit Messages

See how a minor change to your commit message style can make a difference.

git commit -m"<type>(<optional scope>): <description>" \
  -m"<optional body>" \
  -m"<optional footer>"

Note

This cheatsheet is opinionated, however it does not violate the specification of conventional commits

Tip

Take a look at git-conventional-commits ; a CLI util to ensure these conventions, determine version and generate changelogs.

Commit Message Formats

General Commit

<type>(<optional scope>): <description>
_{empty line as separator}
<optional body>
_{empty line as separator}
<optional footer>

Initial Commit

chore: init

Merge Commit

Merge branch '<branch name>'

^{Follows default git merge message}

Revert Commit

Revert "<reverted commit subject line>"

^{Follows default git revert message}

Types

Changes relevant to the API or UI:
- feat Commits that add, adjust or remove a new feature to the API or UI
- fix Commits that fix an API or UI bug of a preceded feat commit
refactor Commits that rewrite or restructure code without altering API or UI behavior
- perf Commits are special type of refactor commits that specifically improve performance
style Commits that address code style (e.g., white-space, formatting, missing semi-colons) and do not affect application behavior
test Commits that add missing tests or correct existing ones
docs Commits that exclusively affect documentation
build Commits that affect build-related components such as build tools, dependencies, project version, CI/CD pipelines, ...
ops Commits that affect operational components like infrastructure, deployment, backup, recovery procedures, ...
chore Miscellaneous commits e.g. modifying .gitignore, ...

Scopes

The scope provides additional contextual information.

The scope is an optional part
Allowed scopes vary and are typically defined by the specific project
Do not use issue identifiers as scopes

Breaking Changes Indicator

A commit that introduce breaking changes must be indicated by an ! before the : in the subject line e.g. feat(api)!: remove status endpoint
Breaking changes should be described in the commit footer section, if the commit description isn't sufficiently informative

Description

The description contains a concise description of the change.

The description is a mandatory part
Use the imperative, present tense: "change" not "changed" nor "changes"
- Think of This commit will... or This commit should...
Do not capitalize the first letter
Do not end the description with a period (.)
I case of breaking changes also see breaking changes indicator

Body

The body should include the motivation for the change and contrast this with previous behavior.

The body is an optional part
Use the imperative, present tense: "change" not "changed" nor "changes"

Footer

The footer should contain issue references and informations about Breaking Changes

The footer is an optional part, except if the commit introduce breaking changes
Optionally reference issue identifiers (e.g., Closes #123, Fixes JIRA-456)
Breaking Changes must start with the word BREAKING CHANGE:
- For a single line description just add a space after BREAKING CHANGE:
- For a multi line description add two new lines after BREAKING CHANGE:

Versioning

If your next release contains commit with...
- Breaking Changes incremented the major version
- API relevant changes (feat or fix) incremented the minor version
Else increment the patch version

Examples

feat: add email notifications on new direct messages

feat(shopping cart): add the amazing button

feat!: remove ticket list endpoint

refers to JIRA-1337

BREAKING CHANGE: ticket endpoints no longer supports list all entities.

fix(shopping-cart): prevent order an empty shopping cart

fix(api): fix wrong calculation of request body checksum

fix: add missing parameter to service call

The error occurred due to <reasons>.

perf: decrease memory footprint for determine unique visitors by using HyperLogLog

```
build: update dependencies
```
```
build(release): bump version to 1.0.0
```

refactor: implement fibonacci number calculation as recursion

```
style: remove empty line
```

Git Hook Scripts to ensure commit message header format

Click to expand

commit-msg Hook (local)

Create a commit-msg hook using git-conventional-commits cli

pre-receive Hook (server side)

create following file in your repository folder .git/hooks/pre-receive

#!/usr/bin/env bash

# Pre-receive hook that will block commits with messages that do not follow regex rule

commit_msg_type_regex='feat|fix|refactor|style|test|docs|build'
commit_msg_scope_regex='.{1,20}'
commit_msg_description_regex='.{1,100}'
commit_msg_regex="^(${commit_msg_type_regex})(\(${commit_msg_scope_regex}\))?: (${commit_msg_description_regex})\$"
merge_msg_regex="^Merge branch '.+'\$"

zero_commit="0000000000000000000000000000000000000000"

# Do not traverse over commits that are already in the repository
excludeExisting="--not --all"

error=""
while read oldrev newrev refname; do
  # branch or tag get deleted
  if [ "$newrev" = "$zero_commit" ]; then
    continue
  fi

  # Check for new branch or tag
  if [ "$oldrev" = "$zero_commit" ]; then
    rev_span=`git rev-list $newrev $excludeExisting`
  else
    rev_span=`git rev-list $oldrev..$newrev $excludeExisting`
  fi

  for commit in $rev_span; do
    commit_msg_header=$(git show -s --format=%s $commit)
    if ! [[ "$commit_msg_header" =~ (${commit_msg_regex})|(${merge_msg_regex}) ]]; then
      echo "$commit" >&2
      echo "ERROR: Invalid commit message format" >&2
      echo "$commit_msg_header" >&2
      error="true"
    fi
  done
done

if [ -n "$error" ]; then
  exit 1
fi

⚠ make .git/hooks/pre-receive executable (unix: chmod +x '.git/hooks/pre-receive')

ancker1/conventional-commits-cheatsheet.md