@dwtechs/gitcommitvalidator

• Synopsis
• Motivation
• Installation
  • npm
  • Yarn
  • Local
• Usage
  • Command line
  • Patterns
  • Message
  • Prompt
  • Help
  • Workflow integration
• Contributors
• License
• Stack
• Dependencies

Synopsis

GitCommitValidator is an open source git commit message validator library.

Motivation

The goal of this library is to provide an easy way to check if the current commit message is valid before pushing it to the remote.

It's a good way to help developers keep their commit messages clean on the repository and facilitate the workflow of a project with strict naming rules.

The default pattern follows the principles described here.

You can also set your own rules using custom patterns.

You can validate branch names as well with GitBranchValidator

Installation

This library is written in Node.js. You must install Node.js and npm in order to run it.

npm

$ npm i @dwtechs/gitcommitvalidator -g

Yarn

$ yarn add @dwtechs/gitcommitvalidator -g

Locally

Alternatively, if you are planning to use GitCommitValidator within your npm package only or with npx you can install it as a devDependency in your project.

$ npm i @dwtechs/gitcommitvalidator --save-dev

$ yarn add @dwtechs/gitcommitvalidator --dev

Usage

This library is meant to be used in the Git "commit-msg" hook. Thus it is not bound to Javascript application only and can be used by any git repository.

On server side hooks, it can be installed for "pre-receive" or "update" hook.

You can learn more about Git hooks and how ti cutomize them in the Git Manual

Because hooks aren’t transferred with a clone of a project, you must distribute these scripts some other way and then have your users copy them to their .git/hooks directory and make them executable. You can distribute these hooks within the project or in a separate project, but Git will not set them up automatically for you.

Command line

$ gcvalidator --src <commit-message-file>

Alternatively if you did not install GitCommitValidator globally you can use npx.

$ npx gcvalidator --src <commit-message-file>

get the commit message

The commit-msg hook takes one parameter, which is the path to a temporary file that contains the commit message written by the developer. Therefore, you need to provide the path of this file:

$ gcvalidator --src $1

Where $1 should be equal to something like : .git/COMMIT_EDITMSG

Le library will then read the file in order to get the commit message.

Patterns

Default patterns

name	Pattern
commit	^(build|ci|doc|feat|fix|perf|refactor|style|test|chore|revert)([a-z0-9]{2,16}): [[A-Za-z0-9\#-]{2,12}] [A-Za-z0-9 !-_]{5,140}$
merge	^Merge branch '([a-zA-Z0-9\#-:/\.+]{5,65})' of ([a-zA-Z0-9\#-:/\.+]{10,90})$

The commit default pattern follows the principles described here. Which is a simplified version of conventional commits.

The merge default pattern is the default merge pattern used when Git is merging branches.

Custom patterns

You can use your own custom patterns by adding an optional regexp :

$ gcvalidator --src <commit-message-file> --patterns "^(feat|fix)\\([a-z0-9]{2,16}\\): \\[[A-Z0-9]{2,25}\\] [a-z0-9_\\. -]{3,60}$"

You can use several patterns if needed :

$ cd <git-project>
$ gcvalidator --src <commit-message-file> --patterns "pattern1" "pattern2" "pattern3"

If one of them is valid, the commit message will be valid.

Message

You can customize the end of the error message :

$ gcvalidator --src <commit-message-file> --message "You can learn more about commit message conventions of this project on https://dwtechs.github.io/efficient-git/conventional-commit/"

Prompt

If the commit message is not valid, the process will be blocked by default. You can use the option "--continue" to prompt the user instead.

$ gcvalidator --src <commit-message-file> --continue

In this case the user will be prompted about the invalid commit. He will be able to keep going if he choose so.

Git hooks are not run in an interactive environment. So this option will fail if used in a Git hook.

Help

You can access the documentation by passing the "help" parameter :

$ gcvalidator --help

Workflow integration

Validate commit messages on commit-msg hook by adding the following code in the .git/hooks/commit-msg file :

gcvalidator -src "$1"

You can use GitBranchValidator as well :

gbvalidator && gcvalidator -src "$1"

You can find git hooks examples in the ./hooks/ folder. To install them just paste them in the .git/hooks/ folder of your repositories.

options

Option	Alias	Type	description
--src	-s	string	The path of the temporary file containing the commit message (ex: .git/COMMIT_EDITMSG)
--patterns	-p	string	Use custom regexps. You can send multiple patterns
--message	-m	string	Add a custom message at the end of the error message
--continue	-c	string	Prompt the user if the commit message is not valid, instead of stopping the process. Does not work if used in Git kooks
--help	-h	boolean	Learn about library usage

Contributors

GitCommitValidator is still in development and I would be glad to get all the help you can provide for this project. To contribute please read contributor.md for detailed installation guide.

License

MIT

Stack

Purpose	Choice	Motivation
repository	Github	hosting for software development version control using Git
package manager	npm	default node.js package manager
unit testing	Jest	delightful testing with a focus on simplicity

Dependencies

Name	version
@dwtechs/checkhard	2.19.0
command-line-args	5.2.1
command-line-usage	6.1.3
prompts	2.4.2