Important

Conventional Commits Corrected fixes the issue, introduced by Angular, of abbreviating feature to feat.

The issue is that feat is already a word in english, meaning

"An act or accomplishment of great courage, skill, or imagination; an achievement.".

Without wishing to be rude, I seriously doubt that adding any UI or API element, or anything happening in 99.9% of github repos can be accurately described as a feat. If you agree with this, then Conventional Commits Corrected is for you.

#stop-the-enshitification

Conventional Commits Corrected 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>"

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:
- feature 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 feature 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. feature(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 (feature or fix) incremented the minor version
Else increment the patch version

Examples

feature: add email notifications on new direct messages

feature(shopping cart): add the amazing button

feature!: 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='feature|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')

atomoil/conventional-commits-cheatsheet.md