Conventional Commits Cheatsheet

conventional-commits-cheatsheet.md

Conventional Commit Messages

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

Tip

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

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

chore: init

Types

• API or UI relevant changes
  • feat Commits, that add or remove a new feature to the API or UI
  • fix Commits, that fix a API or UI bug of a preceded feat commit
• refactor Commits, that rewrite/restructure your code, however do not change any API or UI behaviour
  • perf Commits are special refactor commits, that improve performance
• style Commits, that do not affect the meaning (white-space, formatting, missing semi-colons, etc)
• test Commits, that add missing tests or correcting existing tests
• docs Commits, that affect documentation only
• build Commits, that affect build components like build tool, ci pipeline, dependencies, project version, ...
• ops Commits, that affect operational components like infrastructure, deployment, backup, recovery, ...
• chore Miscellaneous commits e.g. modifying .gitignore

Scopes

The scope provides additional contextual information.

• Is an optional part of the format
• Allowed Scopes depends on the specific project
• Don't use issue identifiers as scopes

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
• Breaking changes must be described in the commit footer section

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 CHANGE: followed by space or two newlines. The rest of the commit message is then used for this.

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

• 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 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

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

---

References

• https://www.conventionalcommits.org/
• https://github.com/angular/angular/blob/master/CONTRIBUTING.md
• http://karma-runner.github.io/1.0/dev/git-commit-msg.html

• https://github.com/github/platform-samples/tree/master/pre-receive-hooks
• https://git.521000.bestmunity/t5/GitHub-Enterprise-Best-Practices/Using-pre-receive-hooks-in-GitHub-Enterprise/ba-p/13863

no, I meant I was asking if I edited a comments in my codebase, what commit type it should fall into?
For example

+ // This function will add two numbers
fn add(x: i32, y: i32) {
  x+y
}

Currently I think that docs: add missing comments on function suits well, but whats your opinion about it?

Oh also, isn't it supposed to be BREAKING CHANGE: without s?

and, when we're removing something like remove pages, remove unused functions, replace a plugin with another one.
We use feat for that right? I've been using chore this whole time. I interpret it as the wildcard type.

@barraIhsan

Currently I think that docs: add missing comments on function suits well, but whats your opinion about it?

I would chose docs as well for these changes.

@barraIhsan

Oh also, isn't it supposed to be BREAKING CHANGE: without s?

yes you are right I'll fix that or add singular wording as well i think both singular and plural should be valid

@barraIhsan

Currently I think that docs: add missing comments on function suits well, but whats your opinion about it?

I would chose docs as well for these changes.

ahh okay then. Thanks for clarifying that out. I've been using it all wrong this whole time

@barraIhsan

and, when we're removing something like remove pages,

if that results in an change for the user it should be a feat otherwise it's probably refactor

remove unused functions,

probably it's a refactor commit, unless it changes the api of your project e.g. you project is an library and the function was exposed to lib users then it would be feat

replace a plugin with another one.

probably it's a refactor commit, unless it also change the the ui or api of your project

I've been using chore this whole time. I interpret it as the wildcard type.

chore should definitely not be used as a wildcard type or fallback type

ahh okay! Thanks for the clarification!