commitplease

Commitplease

This node.js module validates git commit messages while you commit, according to the rules specified in the jQuery Commit Guidelines. These are pretty generic, so this module should be useful for various projects that care about commit message formats.

Installation

npm install commitplease

A git version of 1.8.5 or newer is recommended. If you use git commit --verbose, it is required.

Usage

Just commit as usual. This modules installs a git commit-msg hook (unless suppressed, see below), automatically validating all commit messages as you enter them. Invalid messages will be rejected, with details on what's wrong and a copy of the input.

By default, the commit message needs to match the jQuery Commit Guidlines. See there for details, and below on how to change the default behaviour.

In addition, a subject (the first line) starting with "fixup!" and "squash!" is considered valid. These are generated by git commit --fixup and --squash. A component in square brackets like "[Tmp]" or "[fix]" is also considered valid, to be manually squashed later. Commit messages for merges like "Merge branch [...]" or "Merge into " are considered valid as well.

API

var validate = require('commitplease/lib/validate');
var errors = validate(commit.message);
if (errors.length) {
	postComment('This commit has ' + errors.length + ' problems!');
}

validate(message[, options]), returns Array

• message (String): The commit message to validate. Must use LF (\n) as line breaks.
• options (Object, optional): Use this to override the default settings, see properties and defaults below
• returns Array: Empty for valid messages, one or more items as String for each problem found

Options and their defaults:

component: true,
components: [],
markerPattern: '^(clos|fix|resolv)(e[sd]|ing)',
actionPattern: '^([Cc]los|[Ff]ix|[Rr]esolv)(e[sd]|ing)\\s+[^\\s\\d]+(\\s|$)',
ticketPattern: '^(Closes|Fixes) (.*#|gh-|[A-Z]{2,}-)[0-9]+',
limits: {
	subject: 72,
	other: 80
}

• component: The default true requires a component, set to false to skip the check.
• components: A list of valid components. When a component is found, it's compared to the ones specified in this array.
• limits: Line length limits, for subject and other lines.

The following options are experimental and are subject to change:

• markerPattern: A (intentionally loose) RegExp that indicates that the line might be a ticket reference. Is caseinsensitive.
• actionPattern: A RegExp that makes a line marked by markerPattern valid even if the line does not fit ticketPattern
• ticketPattern: A RegExp that detects ticket references: Closes gh-1, Fixes gh-42, WEB-451 and similar.

The ticket reference match will fail only if markerPattern succeeds and both ticketPattern and actionPattern fail.

When overwriting these patterns in package.json, remember to escape special characters.

Customizing the bundled options

The validation options can be overriden by configuring the commitplease property on your own project's package.json. This allows you to customize the validation rules.

Here's an example for specifiying what components are valid:

{
  "name": "Example",
  "description": "An example project with custom commit hook options",
  "devDependencies": {
    "commitplease": "latest"
  },
  "commitplease": {
    "components": [ "Build", "Test", "Core", "Legacy" ]
  }
}

In addition, you can specify the nohook option as something truthy, which prevents installation of the git commit-msg hook. This can be used when wrapping the commitplease validation API into another module, like a grunt plugin.

{
  "dependencies": {
    "commitplease": "latest"
  },
  "commitplease": {
    "nohook": true
  }
}

When using commitplease together with husky, the following configuration will let husky manage all the hooks and trigger commitplease as well:

{
  "scripts": {
    "commitmsg": "commitplease"
  },
  "commitplease": {
    "nohook": true
  }
}

However, since husky does not use npm in silent mode (and there is no easy way to make it do so), there will be a lot of additional output when a message fails validation. Therefore, using commitplease alone is recommended.

License

Copyright Jörn Zaefferer
Released under the terms of the MIT license.

---

Support this project by donating on Gratipay.