cz-customizable-ghooks

Integrate cz-customizable config with ghooks or husky to use a single configuration for commit message generation AND commit message validation.

Purpose

This package validates that a git commit message matches the rules defined in your cz-customizable config file (see cz-customizable). Example commit message rules.

Prerequisites

• git
• Node >= 4.x
• commitizen
• cz-customizable
• ghooks or husky

Make sure you have a git repository (git init) BEFORE installing ghooks, otherwise you have to take extra steps if you install ghooks before running git init.

Installation

This package is designed to be used in conjunction with commitizen, cz-customizable and either ghooks or husky.

1. Install pre-requisites (if not already installed):

npm i commitizen -g
npm i cz-customizable cz-customizable-ghooks

2. Configure cz-customizable in package.json:

"config": {
  "cz-customizable": {
    "config": "path/to/your/cz-customizable-rules.js"
  }
}

3. Install ONE of these git hook packages:

ghooks

1. Install ghooks:

npm i ghooks

2. Configure package.json:

"config": {
  "ghooks": {
    "commit-msg": "cz-customizable-ghooks $2"
  }
}

An example of this setup is in examples/ghooks.

husky

Install husky:

npm i husky

If you use husky v4 or under:

Configure the hooks in the package.json:

"husky": {
  "hooks": {
    "commit-msg": "cz-customizable-ghooks"
  }
}

If you use husky v5 or higher:

Inside the .husky folder, create a new script:
husky add .husky/commit-msg "npm run commit-msg -- \"$1\"".

Then create create the commit-msg script in the package.json:

"scripts": {
  "commit-msg": "cz-customizable-ghooks"
}

If you wish to specify the LOGGING_LEVEL flag, you can use cross-env:

"scripts": {
  "commit-msg": "cross-env LOGGING_LEVEL=debug cz-customizable-ghooks"
}

An example of this setup is in examples/husky.

Usage

Commit your changes to git as normal. If the commit message entered is invalid, the commit will be rejected with an error message (according to the rules specified in your cz-customizable config). Works with git command-line and visual Git tools (such as SourceTree).

Additional config

appendIssueFromBranchName

If this config value is set to true, the git branch name is queried, and an attempt is made to parse the branch name, looking for the ticketNumberPrefix and ticketNumberRegExp values. If found, they are appended to the commit message. If the branch name does not match the ticketNumberPrefix and ticketNumberRegExp expression, or if ticketNumberPrefix and ticketNumberRegExp are not provided, the full branch name is appended to the commit message.

This property was previously called appendBranchNameToCommitMessage.

Debugging

You can turn on debug logging by specifying LOGGING_LEVEL=debug before the cz-customizable-ghooks command.