Skip to content

Instantly share code, notes, and snippets.

@qoomon

qoomon/conventional-commits-cheatsheet.md

Last active May 4, 2026 18:44
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save qoomon/5dfcdf8eec66a051ecd85625518cfd13 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save qoomon/5dfcdf8eec66a051ecd85625518cfd13 to your computer and use it in GitHub Desktop.
Download ZIP
Conventional Commits Cheatsheet
Raw
conventional-commits-cheatsheet.md

Conventional Commit Messages starline

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 feature to/of/from 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, ...
  • ops Commits that affect operational aspects like infrastructure (IaC), deployment scripts, CI/CD pipelines, backups, monitoring, or recovery procedures, ...
  • chore Commits that represent tasks like initial commit, 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 (.)
  • In 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)

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

References


@qoomon
Copy link
Copy Markdown
Author

qoomon commented Jan 11, 2026

@RedCMD it's test:. perf: is an special refactor: commit. And refactor should only be used for feature related refactoring.

@JohnnyWalkerDigital
Copy link
Copy Markdown

JohnnyWalkerDigital commented Apr 6, 2026 •
edited
Loading

@ttytm

While the order in your answer is already a strong foundation. I think the priority order can be improved. Attempt below trying to match the current conventional Commit semantics:

The problem with this priority order (and the reason I didn't do it) is because it means if you refactor a test then you're told to label your commit refactor: when it should be labelled test:.

@mts2410
Copy link
Copy Markdown

mts2410 commented Apr 25, 2026 •
edited
Loading

I would like to challenge the restrictiveness of the rule stating that the issue identifier should not appear in the scope.

Including the issue identifier in the scope-or at least somewhere in the first line of the commit message-provides significant practical value. Many Git providers and tools display only the first line of a commit message in history views by default, making it much easier to quickly scan commits and associate them with their corresponding issues without needing to open each commit individually.
Another example is a command such as git log --left-right --oneline A...B which is a standard way of comparing commits between branches, and having issue identifiers in the first line of commits provides clear practical value.

I believe this rule is a bit too restrictive and overlooks a practical usability advantage. It may be worth reconsidering or allowing flexibility in this case.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment