Conventional Commit Messages
See how a minor change to your commit message style can make a difference. Examples
Have a look at CLI util git-conventional-commits to ensure this conventions and generate changelogs
Commit 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
Types
- API relevant changes
feat
Commits, that adds or remove a new featurefix
Commits, that fixes a bug
refactor
Commits, that rewrite/restructure your code, however does not change any API behaviourperf
Commits are specialrefactor
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 testsdocs
Commits, that affect documentation onlybuild
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
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...
orThis commit should...
- Think of
- 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 CHANGES:
followed by space or two newlines. The rest of the commit message is then used for this.
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 CHANGES: ticket enpoints no longer supports list all entites.
-
fix(api): handle empty message in request body
-
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
commit-msg Hook (local)
- create following file in your local repository folder
.git-hooks/commit-msg
#!/usr/bin/env sh commit_message="$1" # exit with a non zero exit code incase of an invalid commit message # use git-conventional-commits, see https://github.com/qoomon/git-conventional-commits git-conventional-commits commit-msg-hook "$commit_message" # or verify $commit_message with your own tooling # ...
- ⚠ make
.git-hooks/commit-msg
executable (unix:chmod +x '.git-hooks/commit-msg'
) - set git hook directory to
.githooks
git config core.hooksPath '.git-hooks'
- commit
.git-hooks
directory if you want to share them with your team, they only need to call the git config command once after cloning the repository
pre-receive Hook (server side)
- create following file in your repository folder
.git/hooks/pre-receive
#!/usr/bin/env sh # 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
@qoomon this, sir, just made writing my commit messages much more meaningful and rewarding for me. Thanks for that :)