husky/docs

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.

?> You're viewing documentation for husky v5, which is free to use in Open Source projects ❤️ and in early access for Sponsors 🎁. To use this new version at work, you can become a sponsor on GitHub Sponsors or Open Collective.

If you can't sponsor Husky, that's okay, husky v4 is free to use in any project.

Features

• Zero dependencies
• Lightweight
• Fast
• Supports macOS, Linux and Windows

Usage

Install

1. Install husky and pinst (optional)

# npm
npm install husky@next --save-dev
npm install pinst --save-dev # if your package is not private

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

2. Enable Git hooks

npx husky install
yarn husky install

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

// package.json
{
  "private": true,
  "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,
  "scripts": {
    "postinstall": "husky install",
    "prepublishOnly": "pinst --disable",
    "postpublish": "pinst --enable"
  }
}

Add a hook

To add a hook, you can use husky add <file> [cmd] (don't forget to run husky install before).

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

Try to make a commit

git commit -m "Keep calm and commit"

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

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": {
    "postinstall": "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 postinstall script and pass a subdirectory:

// package.json
{
  "scripts": {
    "postinstall": "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 hooks in CI

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

You can also use is-ci in your postinstall script to conditionnally install husky

npm install is-ci --save-dev

// package.json
{
  "scripts": {
    "postinstall": "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

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
. ~/.nvm/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.

Check 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.

Free for Open Source, early access for Sponsors

How it works?

• If you have an Open Source project, you're free to install or upgrade husky to v5 ❤️
• If you have a commercial project and are a Sponsor, you can start using v5 today at work 🎁

To acquire a proprietary-use license, simply go to GitHub Sponsors or Open Collective.

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 v5

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 (v5)
# ...
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 (v5)
# ...
npx --no-install jest
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 (v5)
# ...
npx --no-install commitlint --edit $1
# or
yarn commitlint --edit $1

Sponsors

Companies

Does your company use Husky? Ask your manager or marketing team if your company would be interested in supporting this project.

Individuals

Find Husky helpful? Become a backer and show your appreciation with a monthly donation on Open Collective. You can also tip with a one-time donation.

GitHub sponsors can be viewed on my profile. All past and current Open Collective sponsors can be viewed on Husky's Open Collective.

License

License Zero Parity 7.0.0 and MIT (contributions) with exception License Zero Patron 1.0.0.