qoomonGit Conventional Commits 
[!TIP] Also have a look at Git Conventional Commits Cheat Sheet
Changelog
see CHANGELOG.md
Usage
npx git-conventional-commits <command>
Commands
ℹ add help parameter -h to commands to list all possible options
init [options] create a config file template `git-conventional-commits.yaml`
version [options] determine version from conventional commits
changelog [options] generate change log from conventional commits
commit-msg-hook [options] <commit-msg-file> check for conventional commit message formatFirst Usage
- Run
npx git-conventional-commits init - Adjust config file
git-conventional-commits.yamlto your needs
Config File
Example git-conventional-commits.yaml
---
convention:
commitTypes:
- 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
- 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, ...
- docs # Commits, that affect documentation only
- chore # Miscellaneous commits e.g. modifying `.gitignore`
- docs
- merge
commitScopes: []
releaseTagGlobPattern: v[0-9]*.[0-9]*.[0-9]*
changelog:
commitTypes:
- feat
- fix
- perf
- merge
includeInvalidCommits: true
commitScopes: []
commitIgnoreRegexPattern: "^WIP "
headlines:
feat: Features
fix: Bug Fixes
perf: Performance Improvements
merge: Merges
breakingChange: BREAKING CHANGES
commitUrl: https://github.com/qoomon/git-conventional-commits/commit/%commit%
commitRangeUrl: https://github.com/qoomon/git-conventional-commits/compare/%from%...%to%?diff=split
issueRegexPattern: "#[0-9]+"
issueUrl: https://github.com/qoomon/git-conventional-commits/issues/%issue%
conventioncommitTypesan array of expected commit types- show warnings for unexpected types
- if not set or empty commit type validation is disabled
- e.g.
["feat", "fix", "doc", "style"]
commitScopesan array of expected commit types- show warnings for unexpected scopes
- if not set or empty commit scope validation is disabled
- e.g.
["ui", "database"]
releaseTagGlobPatternglob pattern to filter for release tags- release tags must contain semantic version (
[0-9]+\.[0-9]+\.[0-9]+) - default
*
- release tags must contain semantic version (
issueRegexPatternregex pattern to find issue IDs- e.g. Jira issue pattern
[A-Z]{3,}-\\d+
- e.g. Jira issue pattern
changelogcommitTypesfilter commits by type- a subset of
convention.commitTypesplusmergecommits
- if not set or empty commit type filter is disabled
- e.g.
["feat", "fix", "merge"]
- a subset of
commitScopesfilter commits by scopes- a subset of
convention.commitScopes - if not set or empty commit scope filter is disabled
- e.g.
["ui"]
- a subset of
includeInvalidCommitsinclude commits without valid type: default:true- if set to false all commits with undefined
commitTypeswill be removed from changelog
- if set to false all commits with undefined
commitIgnoreRegexPatternfilter commits by commit subject regex- default
^WIP
- default
headlinesa map of headline identifier and actual headline- a subset of
changelog.commitTypesplusbreakingChangeBreaking Changes Section
- e.g.
{ "feat": "Features", "fix": "Bug Fixes", "breakingChange": "BREAKING CHANGES"} - default
{ "feat": "Features", "fix": "Bug Fixes", "merge": "Merges", "breakingChange": "BREAKING CHANGES"}
- a subset of
commitUrlan URL template for generating markdown links to repository commits%commit%commit hash placeholder- eg
https://github.com/qoomon/git-conventional-commits/commit/%commit% - if not set or empty link generation is disabled
issueUrlan URL template for generating markdown links to an issue tracker%issue%issue id placeholder- eg
https://jira.example.org/browse/%issue% - if not set or empty link generation is disabled
Automatically Validate Commit Message Convention before Commit
To automatically validate commit messages, a git hook can be used in the commit-msg stage.
The hook can be created either manually or using the pre-commit framework.
Setup with the pre-commit framework
- Create
.pre-commit-config.yamlfile in the root directory of your repository with following content.repos: - repo: https://github.com/qoomon/git-conventional-commits rev: <RELEASE_TAG> hooks: - id: conventional-commits - Install the
pre-commitframeworkpip install pre-commit - Install the commit-msg hook
pre-commit install -t commit-msg
Setup manually
Setup Commit Message Hook to
- Navigate to your repository directory
cd <repository-path> - Create git hook directory
mkdir .git-hooks - Set update hooksPath
git config core.hooksPath .git-hooks Create commit message hook script and make it executable
touch .git-hooks/commit-msg && chmod +x .git-hooks/commit-msgOpen
.git-hooks/commit-msgwith your favorite editor and paste following script#!/bin/sh # fix for windows systems PATH="/c/Program Files/nodejs:$HOME/AppData/Roaming/npm/:$PATH" npx git-conventional-commits commit-msg-hook "$1"
- Add and commit
.git-hooks/commit-msgto repository[!IMPORTANT] Whenever you clone your repository with git hooks you need to enable git hooks once again
git config core.hooksPath .git-hooks
- Navigate to your repository directory
Release Workflow with git-conventional-commits
- Determine version by
npx git-conventional-commits version - Update version in project files
- Commit version bump
git commit -am'build(release): bump project version to <version>'
- Commit version bump
- Generate change log by
npx git-conventional-commits changelog --release <version> --file 'CHANGELOG.md'- Commit change log
git commit -am'docs(release): create <version> change log entry'
- Commit change log
- Tag commit with version
git tag -a -m'build(release): <version>' '<version-prefix><version>' - Push all changes
git push - Build and upload artifacts
Integration with existing repository
If you have an large existing repo with no release tags e.g. v1.0.0, or if you want the first changelog to be tidy, you need to create a release tag first.
- Create release tag for specific commit
git tag -a -m'build(release): 0.0.0' 'v0.0.0' - Push tag
git push origin v0.0.0This waynpx git-conventional-commitswill only considre commits based on the commit the release tag is pointing at.
Projects Using git-conventional-commits
Build/Release
npm installnpm testnpm loginnpm publish