ℹ Have a look at Git Commit Conventions
see CHANGELOG.md
npm install --global git-conventional-commits
- Create config file
git-conventional-commits init
- Adjust config
git-conventional-commits.json
to your needs
ℹ add help parameter -h
to commands to list all possible options
init [options] creates a config file template `git-conventional-commits.json`
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 format
Example git-conventional-commits.json
{
"convention" : {
"commitTypes": [
"feat",
"fix",
"perf",
"refactor",
"style",
"test",
"build",
"ops",
"docs",
"merge"
],
"commitScopes": [],
"releaseTagGlobPattern": "v[0-9]*.[0-9]*.[0-9]*",
"issueRegexPattern": "(^|\\s)#\\d+(\\s|$)"
},
"changelog" : {
"commitTypes": [
"feat",
"fix",
"perf",
"merge"
],
"includeInvalidCommits": true,
"commitScopes": [],
"commitIgnoreRegexPattern": "^WIP ",
"headlines": {
"feat": "Features",
"fix": "Bug Fixes",
"perf": "Performance Improvements",
"merge": "Merged Branches",
"breakingChange": "BREAKING CHANGES"
},
"commitUrl": "https://github.com/ACCOUNT/REPOSITORY/commit/%commit%",
"commitRangeUrl": "https://github.com/ACCOUNT/REPOSITORY/compare/%from%...%to%?diff=split",
"issueUrl": "https://github.com/ACCOUNT/REPOSITORY/issues/%issue%"
}
}
-
convention
commitTypes
an 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"]
commitScopes
an array of expected commit types- show warnings for unexpected scopes
- if not set or empty commit scope validation is disabled
- e.g.
["ui", "database"]
releaseTagGlobPattern
glob 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 (
issueRegexPattern
regex pattern to find issue IDs- e.g. Jira issue pattern
[A-Z]{3,}-\\d+
- e.g. Jira issue pattern
-
changelog
commitTypes
filter commits by type- a subset of
convention.commitTypes
plusmerge
commits
- if not set or empty commit type filter is disabled
- e.g.
["feat", "fix", "merge"]
- a subset of
commitScopes
filter commits by scopes- a subset of
convention.commitScopes
- if not set or empty commit scope filter is disabled
- e.g.
["ui"]
- a subset of
includeInvalidCommits
include commits without valid type: default:true
- if set to false all commits with undefined
commitTypes
will be removed from changelog
- if set to false all commits with undefined
commitIgnoreRegexPattern
filter commits by commit subject regex- default
^WIP
- default
headlines
a map of headline identifier and actual headline- a subset of
changelog.commitTypes
plusbreakingChange
Breaking Changes Section
- e.g.
{ "feat": "Features", "fix": "Bug Fixes", "breakingChange": "BREAKING CHANGES"}
- default
{ "feat": "Features", "fix": "Bug Fixes", "merge": "Merged Branches", "breakingChange": "BREAKING CHANGES"}
- a subset of
commitUrl
an 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
issueUrl
an 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
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.
- Create
.pre-commit-config.yaml
file in the root directory of your repository with following content.repos: - repo: https://github.com/qoomon/git-conventional-commits rev: <revision e.g. v2.1.0> hooks: - id: conventional-commits
- Install the
pre-commit
frameworkpip install pre-commit
- Install the commit-msg hook
pre-commit install -t commit-msg
- 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-msg
- Open
.git-hooks/commit-msg
with your favorite editor and paste following script#!/bin/sh # fix for windows systems PATH="/c/Program Files/nodejs:$HOME/AppData/Roaming/npm/:$PATH" git-conventional-commits commit-msg-hook "$1"
- Add and commit
.git-hooks/commit-msg
to repository ⚠️ Whenever you clone your repository with git hooks you need to enable git hooks once againgit config core.hooksPath .git-hooks
- Navigate to your repository directory
- Determine version by
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
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
npm install
npm test
npm login
npm publish