Name	Name	Last commit message	Last commit date
parent directory ..
.nojekyll	.nojekyll
README.md	README.md
index.html	index.html

Modern native git hooks made easy

Husky improves your commits and more 🐶 woof!

You can use it to lint your commit messages, run tests, lint code, etc... when you commit or push. Husky supports all Git hooks.

Features

Zero dependencies and lightweight (6 kB)
Powered by modern new Git feature (core.hooksPath)
Follows npm and Yarn best practices regarding autoinstall
User-friendly messages
Optional install
Like husky 4, supports
- macOS, Linux and Windows
- Git GUIs
- Custom directories
- Monorepos

Used by

The new husky is used by these awesome projects:

Articles

Usage

Already using husky? See Migrate from 4 to 7.

Automatic (recommended)

husky-init is a one-time command to quickly initialize a project with husky.

npx husky-init && npm install       # npm
npx husky-init && yarn              # Yarn 1
yarn dlx husky-init --yarn2 && yarn # Yarn 2

It will setup husky, modify package.json and create a sample pre-commit hook that you can edit. By default, it will run npm test when you commit.

To add another hook use husky add.

For example:

npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

Manual

Install

Install husky

npm install husky --save-dev

Enable Git hooks

npx husky install

To automatically have Git hooks enabled after install, edit package.json

npm set-script prepare "husky install"

You should have:

// package.json
{
  "scripts": {
    "prepare": "husky install"
  }
}

!> Yarn 2 doesn't support prepare lifecycle script, so husky needs to be installed differently (this doesn't apply to Yarn 1 though). See Yarn 2 install.

Create a hook

To add a command to a hook or create a new one, use husky add <file> [cmd] (don't forget to run husky install before).

npx husky add .husky/pre-commit "npm test"
git add .husky/pre-commit

Try to make a commit

git commit -m "Keep calm and commit"

If npm test command fails, your commit will be automatically aborted.

!> Using Yarn to run commands? There's an issue on Windows with Git Bash, see Yarn on Windows.

Uninstall

npm uninstall husky

Yarn 2

Install

Install husky

yarn add husky --dev
yarn add pinst --dev # ONLY if your package is not private

Enable Git hooks

yarn husky install

To automatically have Git hooks enabled after install, edit package.json

// package.json
{
  "private": true, // ← your package is private, you only need postinstall
  "scripts": {
    "postinstall": "husky install"
  }
}

!> if your package is not private and you're publishing it on a registry like npmjs.com, you need to disable postinstall script using pinst. Otherwise, postinstall will run when someone installs your package and result in an error.

// package.json
{
  "private": false, // ← your package is public
  "scripts": {
    "postinstall": "husky install",
    "prepublishOnly": "pinst --disable",
    "postpublish": "pinst --enable"
  }
}

Uninstall

Remove "postinstall": "husky install" from package.json and run:

yarn remove husky && git config --unset core.hooksPath

Recipes

Monorepo

It's recommended to add husky in root package.json. You can use tools like lerna and filters to only run scripts in packages that have been changed.

Custom directory

If you want to install husky in another directory, for example .config, you can pass it to install command. For example:

// package.json
{
  "scripts": {
    "prepare": "husky install .config/husky"
  }
}

Another case you may be in is if your package.json file and .git directory are not at the same level. For example, project/.git and project/front/package.json.

By design, husky install must be run in the same directory as .git, but you can change directory during prepare script and pass a subdirectory:

// package.json
{
  "scripts": {
    "prepare": "cd .. && husky install front/.husky"
  }
}

In your hooks, you'll also need to change directory:

# .husky/pre-commit
# ...
cd front
npm test

Bypass hooks

You can bypass pre-commit and commit-msg hooks using Git -n/--no-verify option:

git commit -m "yolo!" --no-verify

For Git commands that don't have a --no-verify option, you can use HUSKY environment variable:

HUSKY=0 git push # yolo!

Disable husky in CI/Docker

There's no right or wrong way to disable husky in CI/Docker context and is highly dependent on your use-case.

With npm

If you want to prevent husky from installing completely

npm ci --only=production --ignore-scripts

Alternatively, you can specifically disable prepare script with

npm set-script prepare ""
npm ci --only-production

With a custom script

You can create a custom JS script and conditionally require husky and install hooks.

"prepare": "node ./prepare.js"

// prepare.js
const isCi = process.env.CI !== undefined
if (!isCi) {
  require('husky').install()
}

With env variables

You can set HUSKY environment variable to 0 in your CI config file, to disable all hooks.

Alternatively, most Continuous Integration Servers set a CI environment variable. You can use it in your hooks to detect if it's running in a CI.

# .husky/pre-commit
# ...
[ -n "$CI" ] && exit 0

With is-ci

You can also use is-ci in your prepare script to conditionally install husky

npm install is-ci --save-dev

// package.json
{
  "scripts": {
    "prepare": "is-ci || husky install"
  }
}

Test hooks

If you want to test a hook, you can add exit 1 at the end of the script to abort git command.

# .husky/pre-commit
# ...
exit 1 # Commit will be aborted

Git-flow

If using git-flow you need to ensure your git-flow hooks directory is set to use Husky's (.husky by default).

git config gitflow.path.hooks .husky

Note:

If you are configuring git-flow after you have installed husky, the git-flow setup process will correctly suggest the .husky directory.
If you have set a custom directory for husky you need to specify that (ex. git config gitflow.path.hooks .config/husky)

To revert the git-flow hooks directory back to its default you need to reset the config to point to the default Git hooks directory.

git config gitflow.path.hooks .git/hooks

FAQ

Does it work on Windows?

Yes. When you install Git on Windows, it comes with the necessary software to run shell scripts.

Troubleshoot

Command not found

If you're running Git from an app and the command can be found in your terminal, this means that the PATH in your app is different from your terminal.

You can echo $PATH in your terminal and configure your app to use the same value.

If you've installed your command using brew, see the Homebrew FAQ to make your command available to your app.

Finally, if you're using a script for managing versions like nvm, n, rbenv, pyenv, ... you can use ~/.huskyrc to load the necessary before running hooks.

For example, for nvm that would be:

# ~/.huskyrc
# This loads nvm.sh and sets the correct PATH before running hook
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

Hooks not running

Ensure that you don't have a typo in your filename. For example, precommit or pre-commit.sh are invalid names. See Git hooks documentation for valid names.

Verify hooks permissions, they should be executable. This is automatically set when using husky add command but you can run chmod +x .husky/<hookname> to fix that.

Check that your version of Git is greater than 2.9.

Yarn on Windows

Git hooks may fail when using Yarn on Windows with Git Bash (stdin is not a tty). If you have users on Windows, it's highly recommended to add the following workaround.

Create .husky/common.sh:

command_exists () {
  command -v "$1" >/dev/null 2>&1
}

# Workaround for Windows 10, Git Bash and Yarn
if command_exists winpty && test -t 1; then
  exec < /dev/tty
fi

Source it in in places where Yarn is used to run commands:

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
. "$(dirname "$0")/common.sh"

yarn ...

Breaking changes

Environment variables:

HUSKY_SKIP_HOOKS becomes HUSKY.
HUSKY_SKIP_INSTALL is removed.
HUSKY_GIT_PARAMS is removed. Instead Git parameters should be used directly in scripts (e.g. $1).
PATH for locally installed tools is not automatically set anymore. You'll need to use your package manager to run them.

Migrate from v4 to v7

husky-4-to-7 CLI

See husky-4-to-7 CLI to quickly migrate from v4 to v7.

Package scripts

If you were calling package.json scripts using npm or yarn, you can simply copy your commands:

// .huskyrc.json (v4)
{
  "hooks": {
    "pre-commit": "npm test && npm run foo"
  }
}

# .husky/pre-commit (v7)
# ...
npm test
npm run foo

Locally installed binaries

If you were calling directly locally installed binaries, you need to run them via your package manager:

// .huskyrc.json (v4)
{
  "hooks": {
    "pre-commit": "jest"
  }
}

# .husky/pre-commit (v7)
# ...
npx --no-install jest
# or
yarn jest

HUSKY_GIT_PARAMS (i.e. commitlint, ...)

Previous HUSKY_GIT_PARAMS environment variable is replaced by native params $1, $2, etc.

// .huskyrc.json (v4)
{
  "hooks": {
    "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
  }
}

# .husky/commit-msg (v7)
# ...
npx --no-install commitlint --edit $1
# or
yarn commitlint --edit $1

License

MIT

Files

docs

Directory actions

More options

Directory actions

More options

Latest commit

History

docs

Folders and files

parent directory

README.md

Features

Used by

Articles

Usage

Automatic (recommended)

Manual

Install

Create a hook

Uninstall

Yarn 2

Install

Uninstall

Recipes

Monorepo

Custom directory

Bypass hooks

Disable husky in CI/Docker

With npm

With a custom script

With env variables

With is-ci

Test hooks

Git-flow

FAQ

Does it work on Windows?

Troubleshoot

Command not found

Hooks not running

Yarn on Windows

Breaking changes

Migrate from v4 to v7

husky-4-to-7 CLI

Package scripts

Locally installed binaries

HUSKY_GIT_PARAMS (i.e. commitlint, ...)

Sponsors

Companies

Individuals

License