Conventional Commit Messages

A commit message guideline based on the Conventional Commits Specification.

Commit Message Formats

Default

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

Merge Commit

Merge branch '<branch name>'

^{Follows default git merge message}

Revert Commit

Revert "<reverted commit subject line>"

^{Follows default git revert message}

Inital Commit

init

Types

API relevant changes
- feat commits add or remove a new feature
- fix commits fix a bug
refactor commits rewrite/restructure your code but does not change any API behaviour
- perf commits are special refactor commits that are specific to performance optimisations
style commits do not affect the meaning of the existing code (whitespace, formatting, missing semi-colons, etc.)
test commits add testing code or correct existing tests
docs commits affect documentation only
build commits affect build components (build tools, ci pipeline, dependencies, project version, etc.)
ops commits affect operational components (infrastructure, deployment, backup, recovery, etc.)
chore commits are miscellaneous commits e.g. modifying .gitignore

Scope (Optional)

The scope provides additional contextual information about the commit, such as a one-word description of a section of the codebase (e.g., fix(parser):.

It is an optional part of the format
Allowed scopes depends on the specific project
Don't use issue identifiers as scopes
In most cases the scope should be a one-word noun

Breaking Changes Indicator

Breaking changes should be indicated by an ! before the : in the subject line e.g. feat(api)!: remove status endpoint

Is an optional part of the format

Description

The description contains a concise description of the change.

Is a mandatory part of the format
Use the imperative, present tense: "change" not "changed" nor "changes"
- Think of This commit will... or This commit should...
Don't capitalize the first letter
No dot (.) at the end

Body

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

Is an optional part of the format
Use the imperative, present tense: "change" not "changed" nor "changes"
This is the place to mention issue identifiers and their relations

Footer

The footer should contain any information about Breaking Changes and is also the place to reference Issues that this commit refers to.

Is an optional part of the format
optionally reference an issue by its id.
Breaking Changes should start with the word BREAKING CHANGES: followed by space or two newlines. The rest of the commit message is then used for this.

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 CHANGES: ticket enpoints no longer supports list all entites.

fix(api): handle empty message in request body

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

fix: add missing parameter to service call

The error occurred because of <reasons>.

perf: decrease memory footprint for determine uniqe 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

commit-msg Hook (local)

ensure node and npx command is installed on your local machine

create following file in your local repository folder.git-hooks/commit-msg

#!/usr/bin/env sh

commit_message="$1"
# exit with a non zero exit code incase of an invalid commit message

# use git-conventional-commits, see https://github.com/qoomon/git-conventional-commits
npx git-conventional-commits commit-msg-hook "$commit_message"

# or verify $commit_message with your own tooling
# ...

⚠ make .git-hooks/commit-msg executable (unix: chmod +x '.git-hooks/commit-msg')
set git hook directory to .githooks git config core.hooksPath '.git-hooks'
commit .git-hooks directory if you want to share them with your team, they only need to call the git config command once after cloning the repository

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 messges 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')

jordan-chisl/conventional-commits-cheatsheet.md