commit-msg

commit-msg is a customizable git commit message parser and validator written in Node.js. It validates a given string based on best practices and can be used as a git hook, command line tool and/or directly through the API.

• Default validations
• Installation
  • Prerequisites
  • Install
  • Update
  • Uninstall
• Configuration
  • Disable hooks auto-install
  • Disable validation
  • Bypass validation
• Usage
  • Client-side hook
  • Server-side hook
  • Manual validation
  • Custom references
  • API
• See it in Action
• Troubleshooting

Default validations

• Subject and body should be separated by an empty line, if body exists (error | configurable)
• Subject should be capitalized (error | configurable)
• Subject has a soft and hard limit for max length (50 and 70) (warning and error | configurable)
• No consecutive whitespaces allowed in subject (error)
• Subject should not end with a period (error)
• Only certain special characters are allowed in the subject (error | configurable)
• Subject can be prefixed with certain type: component: and invalid types can de detected (error | configurable)
• GitHub issue references should be placed in the last paragraph of the body and they should exist on GitHub (error | configurable)
• Detection of non-imperative verbs in subject, eg. "Fixes bug" or "Fixed bug" instead of "Fix bug" (error | configurable) - using the Stanford Parser with a custom trained model for commit messages
• Body lines should be wrapped at 72 characters (warning | configurable)

Disclaimer

Only use it if you agree with the guidelines it follows and if the customization it offers is enough to meet your needs. I will not accept changes that do not adhere to the general rules outlined in the guidelines document, unless they come with very compelling reasons.

Installation

Note: This module is currently in active development (hence the 0.x version) and a stable v1.0.0 will be released in a few weeks. For this to happen it just needs more testing from the community, because the feature set is rather complete.

Prerequisites

• Node.js 0.12 or newer
• Java 8 or newer (required by the parser)

Install

The commands below should be run from your project's root directory.

IMPORTANT: On Windows, make sure you run the commands using administrator rights. Eg. open PowerShell using Run as administrator.

npm install commit-msg

This will install (symlink) the commit-msg and update hooks in your repo's hooks/ directory so you are ready to start committing. If any of these hooks already exist, a message will be displayed and the hooks will remain untouched. To disable the hooks installation see Configuration.

Global install

You can also install it globally using npm install commit-msg -g in which case you can use the command line validator as commit-msg -h.

Update

Just run the install command again or npm update commit-msg if you have a package.json file.

Uninstall

npm uninstall commit-msg

Configuration

You can configure this module by specifying a commitMsg key in your package.json file. Possible configurations are:

• any key from the default config object
• to turn off the validator once installed with hooks see disable validation
• to disable the hooks auto-install see disable hooks auto-install

Configuration examples

• Angular's Git Commit Guidelines - example file
• jQuery's Commit Guidelines - example file
• Gerrit's Commit message guidelines - example file
• GNOME's Guidelines for Commit Messages - example file

Disable hooks auto-install

You can disable the hooks installation in 2 ways:

1. Set the no[Client|Server]Hook key to true in your package.json:

{
  "commitMsg": {
    "noClientHook": true,
    "noServerHook": true
  }
}

2. Set the commitMsg.no[Client|Server]Hook key to true in git config:

git config commitMsg.noClientHook true
git config commitMsg.noServerHook true

Disable validation

You can disable the validation by setting commitMsg: {disable: true, ...} in your package.json file.

Bypass validation

If you know what you're doing you can skip the validation altogether using git commit --no-verify. Be aware that this will bypass the pre-commit and commit-msg hooks.

Usage

The default usage is through git hooks, that install automatically when you install the module in a git repository. There are also other possible usages, explained below.

Client-side hook

On the client side the commit-msg hook validates every commit you make, helping you follow the guidelines possibly enforced by the remote server you're pushing to.

If you get your commits rejected by the server, see Changing commit messages.

Server-side hook

The update hook can be installed in a (bare) repository on a remote server to enforce your own commit message guidelines.

A note on performance

To greatly improve the validation speed make sure you have the optional prerequisites installed.

Manual validation

The validator includes a script for validating messages directly from the command line. It is located at bin/validate and you can access it from anywhere using node <path-to-bin/validate>, eg:

# example acessing 'help' from your project root
node node_modules/commit-msg/bin/validate -h

Examples below assume the module is installed at node_modules/commit-msg in your project root.

Also see a note on performance.

Validate any given message(s)

node node_modules/commit-msg/bin/validate 'Fix bug'

Validate all commits from the local repository

git rev-list --all --no-merges | node node_modules/commit-msg/bin/validate stdin

Validate last 10 commits made by <Author>

# don't forget to replace <Author>
git rev-list --all --no-merges -10 --author='<Author>' | node node_modules/commit-msg/bin/validate stdin

For more examples see the script help.

Custom references

You can create your own references by simply putting your reference file in the lib/references directory. Take a look at the github reference for details on how to implement one.

Don't forget to disable the github reference to prevent it from being used. To do this specify references: {github: false} in your package.json file (see configuration).

API

For some examples you can check out the commit-msg hook, the validate script or the test files.

CommitMessage

CommitMessage.parse(message[, config], callback)

• message (string) The message to parse
• config (true|string|Config, optional) The config object, a string or true.
  • if true is given, it will search for the first package.json file starting from the current directory up, and use the commitMsg config from it, if any.
  • if string is given, it should be a directory path where the search for the package.json file will start, going up
  • if object is given, it will overwrite the default config object
• callback(err, instance) (function) The callback that will be called with the following params:
  • err (Error)
  • instance (CommitMessage)

This is the designated initializer (also validates the message).

CommitMessage.parseFromFile(file[, config], callback)

• file (string) The file path to parse the message from
• (all other arguments are the same as above)

<commitMessageInstance>.message: string

Return the original message as a string.

<commitMessageInstance>.formattedMessages: string

Return all errors and warnings as a string, one per line, in the same order as they were generated, including colors.

<commitMessageInstance>.validate(callback)

• callback(err, instance) (function) The callback that will be called after the validation finishes
  • err (Error)
  • instance (CommitMessage)

This is called automatically by the static methods parse() and parseFromFile().

<commitMessageInstance>.hasErrors(): boolean

Return true if there are any errors after validation.

<commitMessageInstance>.hasWarnings(): boolean

Return true if there are any warnings after validation.

CommitMessage.Config

CommitMessage.Config([cfg]): object

• cfg (object, optional) An object that will overwrite the default config object.

For example, to generate a warning instead of an error for the capitalized first letter check use:

CommitMessage.parse(
    msg,
    CommitMessage.Config({
        capitalized: { type: CommitMessage.Error.WARNING }
    }),
    function(err, instance) { /* ... */ }
);

CommitMessage.Error

CommitMessage.Error.ERROR: string

The "error" string.

CommitMessage.Error.WARNING: string

The "warning" string.

See it in Action

Troubleshooting

If you have problems see the TROUBLESHOOTING page.