# Conventional Commit Messages [![starline](https://starlines.qoo.monster/assets/qoomon/5dfcdf8eec66a051ecd85625518cfd13@gist)](https://github.com/qoomon/starline) See how [a minor change](#examples) 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](https://www.conventionalcommits.org/) > [!TIP] > Take a look at **[git-conventional-commits](https://github.com/qoomon/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 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 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. `feat(api)!: remove status endpoint` - Breaking changes **should** be described in the [commit footer section](#footer), if the [commit description](#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](#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 . ``` - ``` 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](https://github.com/qoomon/git-conventional-commits?tab=readme-ov-file#automatically-validate-commit-message-convention-before-commit) ### pre-receive Hook (server side) - create following file in your repository folder `.git/hooks/pre-receive` ```shell #!/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