Skip to content
Git Conventional Commits Util to generate Semantic Version and Markdown Change Log and Validate Commit Messag
JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
test
.gitignore
README.md
cli.js
git-conventional-commits.default.json
git-conventional-commits.json
package-lock.json
package.json

README.md

Git Conventional Changelog Generator

npm

Git Commit Convention

Install

npm install --global git-conventional-commits

Commands

  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

Usage

  • Create config file git-conventinal-commits init
  • Adjust config git-conventional-commits.json to your needs

Config File

Example git-conventional-commits.json

{
  "convention" : {
    "commitTypes": [
      "feat",
      "fix",
      "perf",
      "refactor",
      "style",
      "test",
      "build",
      "ops",
      "doc"
    ],
    "commitScopes": [],
    "releaseTagGlobPattern":  "v[0-9]*.[0-9]*.[0-9]*",
    "issueRegexPattern": "(^|\\s)#\\d+(\\s|$)"
  },

  "changelog" : {
    "commitTypes": [
      "feat",
      "fix",
      "perf",
      "merge",
      "?"
    ],
    "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 *
    • issueRegexPattern regex pattern to find issue IDs
      • e.g. Jira issue pattern [A-Z]{3,}-\\d+
  • changelog

    • commitTypes filter commits by type
      • a subset of convention.commitTypes plus
        • merge commits
        • ? commits with unexpected message format
      • if not set or empty commit type filter is disabled
      • e.g. ["feat", "fix", "merge" , "?"]
    • commitScopes filter commits by scopes
      • a subset of convention.commitScopes
      • if not set or empty commit scope filter is disabled
      • e.g. ["ui"]
    • commitIgnoreRegexPattern filter commits by commit subject regex
      • default ^WIP
    • headlines a map of headline identifier and actual headline
      • a subset of changelog.commitTypes plus
        • breakingChange 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"}
    • 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

Automatically Validate Commit Message Convention before Commit

  • 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 again by execute git config core.hooksPath .git-hooks

Release Workflow with git-conventional-commits

  1. Determine version by git-conventional-changelog version
  2. Update version in project files
    • Commit version bump git commit -am'build(release): bump project version to <version>'
  3. Generate change log by git-conventional-changelog changelog --release <version> --file 'CHANGELOG.md'
    • Commit change log git commit -am'doc(release): create <version> change log entry'
  4. Tag commit with version git tag -a -m'build(release): <version>' '<version-prefix><version>'
  5. Push all changes git push
  6. Build and upload artifacts

Build/Release

  • npm install
  • npm test
  • npm login
  • npm publish
You can’t perform that action at this time.