Check staged contents before commiting

Documentation also available in French:

Because we love git hooks and npm, we want to share and automate code/content quality.

git-precommit-checks has to be loaded manually or using any wrapper around git hooks.

As you can read below we highly recommend Husky.

How does it look like?

Install

npm install --save-dev git-precommit-checks

How to setup my checking rules?

Configuration is loaded from the project root/top level directory using git-precommit-checks.config.js or git-precommit-checks.json, or from package.json so you can customize it according to your needs.

Here is an example using git-precommit-checks.json configuration file:

{
  "rules": [
    {
      "filter": "\\.js$",
      "nonBlocking": "true",
      "message": "You’ve got leftover `console.log`",
      "regex": "console\\.log"
    },
    {
      "message": "You’ve got leftover conflict markers",
      "regex": "/^[<>|=]{4,}/m"
    },
    {
      "message": "You have unfinished devs",
      "nonBlocking": "true",
      "regex": "(?:FIXME|TODO)"
    }
  ]
}

Same thing using JS configuration file:

module.exports = {
  display: {
    notifications: true,
    offendingContent: true,
    rulesSummary: false,
    shortStats: true,
    verbose: false,
  },
  rules: [
    {
      message: 'You’ve got leftover conflict markers',
      regex: /^[<>|=]{4,}/m,
    },
    {
      filter: /^(?!README(_fr)?\.md)$/,
      message: 'You have unfinished devs',
      nonBlocking: true,
      regex: /(?:FIXME|TODO)/,
    },
  ],
}

When using package.json file, you must add a dedicated git-precommit-checks key:

"git-precommit-checks": {
  "rules": [
    {
      "filter": "\\.js$",
      "nonBlocking": "true",
      "message": "You’ve got leftover `console.log`",
      "regex": "console\\.log"
    },
    {
      "message": "You’ve got leftover conflict markers",
      "regex": "/^[<>|=]{4,}/m"
    },
    {
      "message": "You have unfinished devs",
      "nonBlocking": "true",
      "regex": "(?:FIXME|TODO)"
    }
  ]
}

Each "pre-commit" entry is a checking rule: the pattern describes a regular expression that will be searched upon staged content. The associated message is displayed when the pattern is found.

Each rule will stop the commit when the associated pattern is found unless you set the nonBlocking key to true. Non blocking rules will print warning messages.

Only message and regex keys are mandatory.

You can also filter on files patterns using the filter key.

For instance, you'll get a warning about your package.json the first time you set the FIXME/TODO rule and every time you update that line. If you want to prevent such a warning you can extend that rule like this:

  {
    "filter": "^package\\.json$",
    "message": "You have unfinished devs",
    "nonBlocking": "true",
    "regex": "(?:FIXME|TODO)"
  }

⚠️ There is no default checks configured after install, so please be aware that nothing will happend without adding your own rules!

Display options

You can add an optional display entry in your config to enable some options:

"git-precommit-checks": {
  "display": {
    "notifications": true,
    "offendingContent": true,
    "rulesSummary": true,
    "shortStats": true,
    "verbose": true
  },
  …

• notifications: print error/warning summary using system notification.
• offendingContent: print offending contents right after associated file path and line number.
• rulesSummary: print rules as a table before parsing staged files.
• shortStats: print short stats (ie. 1 error, 1 warning.).
• verbose: print every performed action, files parsed, short summary/stats (errors and warnings number).

Usage

Triggering it straight with git hooks

After installing locally or globally your module, add the following code (or equivalent) to your project pre-commit hook .git/hooks/pre-commit:

#!/bin/sh
scriptName="git-precommit-checks"
scriptPath="$(npm bin)/$scriptName"

if [ -f $scriptPath ]; then
  $scriptPath
else
  echo "Can't find $scriptName module"
  echo "You can reinstall it using 'npm install $scriptName --save-dev' or delete this hook"
fi

Running git-precommit-checks with Husky

Husky is a great tool to manage git hooks from your package.json.

You can use it and call git-precommit-checks on pre-commit:

  "husky": {
    "hooks": {
      "pre-commit": "git-precommit-checks"
    }
  }

Contributing

Any contribution is welcomed. Here is our contribution guideline