qoomon/conventional-commits-cheatsheet.md

## conventional-commits-cheatsheet.md

      
    Raw
  

              conventional-commits-cheatsheet.md
            
          
    Conventional Commit Messages 

See how a minor change to your commit message style can make a difference.
Tip
Take 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 an 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 tools, dependencies, project version, ci pipelines, ...
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 depend 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.

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


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://github.community/t5/GitHub-Enterprise-Best-Practices/Using-pre-receive-hooks-in-GitHub-Enterprise/ba-p/13863