# Conventional Commit Messages [](https://github.com/qoomon/starline)
See how [a minor change](#examples) to your commit message style can make a difference.
> [!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
### 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
### Initial 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](#footer)
### 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 .
```
- ```
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