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.
- 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)
- Body lines should be wrapped at 72 characters (warning | configurable)
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.
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.
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-msgThis 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.
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.
Just run the install command again or npm update commit-msg if you have
a package.json file.
npm uninstall commit-msgYou can configure this module by specifying a commitMsg key in your
package.json file. Possible configurations are:
- any key from the default
configobject - to turn off the validator once installed with hooks see disable validation
- to disable the hooks auto-install see disable hooks auto-install
- 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
You can disable the hooks installation in 2 ways:
- Set the
no[Client|Server]Hookkey to true in your package.json:
{
"commitMsg": {
"noClientHook": true,
"noServerHook": true
}
}- Set the
commitMsg.no[Client|Server]Hookkey to true ingit config:
git config commitMsg.noClientHook true
git config commitMsg.noServerHook trueYou can disable the validation by setting commitMsg: {disable: true, ...}
in your package.json file.
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.
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.
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.
The update hook can be installed in a (bare) repository
on a remote server to enforce your own commit message guidelines.
To greatly improve the validation speed make sure you have the optional prerequisites installed.
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 -hExamples below assume the module is installed at node_modules/commit-msg
in your project root.
Also see a note on performance.
node node_modules/commit-msg/bin/validate 'Fix bug'git rev-list --all --no-merges | node node_modules/commit-msg/bin/validate stdin# don't forget to replace <Author>
git rev-list --all --no-merges -10 --author='<Author>' | node node_modules/commit-msg/bin/validate stdinFor more examples see the script help.
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).
For some examples you can check out the commit-msg hook, the validate script or the test files.
message(string) The message to parseconfig(true|string|Config, optional) The config object, a string ortrue.- if
trueis given, it will search for the first package.json file starting from the current directory up, and use thecommitMsgconfig 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
- if
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).
file(string) The file path to parse the message from- (all other arguments are the same as above)
Return the original message as a string.
Return all errors and warnings as a string, one per line, in the same order as they were generated, including colors.
callback(err, instance)(function) The callback that will be called after the validation finisheserr(Error)instance(CommitMessage)
This is called automatically by the static methods parse() and
parseFromFile().
Return true if there are any errors after validation.
Return true if there are any warnings after validation.
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) { /* ... */ }
);The "error" string.
The "warning" string.
If you have problems see the TROUBLESHOOTING page.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent