Announcement you can support the development of v4 major release on Open Collective and GitHub Sponsors ๐
See next branch. Feedback is welcome ๐
Git hooks made easy
Husky can prevent bad git commit
, git push
and more ๐ถ woof!
npm install husky --save-dev
// package.json
{
"husky": {
"hooks": {
"pre-commit": "npm test",
"pre-push": "npm test",
"...": "..."
}
}
}
git commit -m 'Keep calm and commit'
Existing hooks are kept. Requires Node >= 8.6.0
and Git >= 2.13.2
.
npm uninstall husky
Git hooks installed by husky will be removed.
Become a financial contributor and help us sustain our community. [Contribute]
Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]
- webpack
- babel
- create-react-app
- ... and many other awesome projects
- Upgrading from 0.14
- Supported hooks
- Access Git params and stdin
- Skip all hooks (rebase)
- Disable auto-install
- CI servers
- Monorepos
- Node version managers
- Local commands (~/.huskyrc)
- Debug
- Multiple commands
- Troubleshoot
Run husky-upgrade
to automatically upgrade your configuration:
npx --no-install husky-upgrade
You can also do it manually. Move your existing hooks to husky.hooks
field and use raw Git hooks names. Also, if you were using GIT_PARAMS
env variable, rename it to HUSKY_GIT_PARAMS
.
{
"scripts": {
- "precommit": "npm test",
- "commitmsg": "commitlint -E GIT_PARAMS"
},
+ "husky": {
+ "hooks": {
+ "pre-commit": "npm test",
+ "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
+ }
+ }
}
Starting with 1.0.0
, husky can be configured using .huskyrc
, .huskyrc.json
or .huskyrc.js
file.
// .huskyrc
{
"hooks": {
"pre-commit": "npm test"
}
}
Husky supports all Git hooks defined here. Server-side hooks (pre-receive
, update
and post-receive
) aren't supported.
Git hooks can get parameters via command-line arguments and stdin. Husky makes them accessible via HUSKY_GIT_PARAMS
and HUSKY_GIT_STDIN
environment variables.
"commit-msg": "echo $HUSKY_GIT_PARAMS"
During a rebase you may want to skip all hooks, you can use HUSKY_SKIP_HOOKS
environment variable.
HUSKY_SKIP_HOOKS=1 git rebase ...
If you don't want husky to automatically install Git hooks, simply set HUSKY_SKIP_INSTALL
environment variable.
HUSKY_SKIP_INSTALL=1 npm install
By default, Husky won't install on CI servers.
If you have a multi-package repository, it's recommended to use tools like lerna and have husky installed ONLY in the root package.json
to act as the source of truth.
Generally speaking, you should AVOID defining husky in multiple package.json
, as each package would overwrite previous husky installation.
.
โโโ root
โโโ .git
โโโ package.json ๐ถ # Add husky here
โโโ packages
โโโ A
โ โโโ package.json
โโโ B
โ โโโ package.json
โโโ C
โโโ package.json
// root/package.json
{
"private": true,
"devDependencies": {
"husky": "..."
},
"husky": {
"hooks": {
"pre-commit": "lerna run test"
}
}
}
If you're on Windows, husky will simply use the version installed globally on your system.
For macOS and Linux users:
- if you're running
git
commands in the terminal, husky will use the version defined in your shellPATH
. In other words, if you're anvm
user, husky will use the version that you've set withnvm
. - if you're using a GUI client and
nvm
, it may have a differentPATH
and not loadnvm
, in this case the highestnode
version installed bynvm
will usually be picked. You can also check~/.node_path
to see which version is used by GUIs and edit if you want to use something else.
Husky will source ~/.huskyrc
file if it exists before running hook scripts.
You can use it, for example, to load a node version manager or run some shell
commands before hooks.
# ~/.huskyrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
Use HUSKY_DEBUG=1
to log debug messages.
By design and just like scripts
defined in package.json
, husky will run hook scripts as a single command.
"pre-commit": "cmd && cmd"
That said, if you prefer to use an array, the recommended approach is to define them in .huskyrc.js
.
const tasks = arr => arr.join(' && ')
module.exports = {
'hooks': {
'pre-commit': tasks([
'cmd',
'cmd'
])
}
}
Tools like npm-run-all can help too.
Check if hooks were installed. Verify that .git/hooks/pre-commit
exists and have husky code. It should start with:
#!/bin/sh
# husky...
If not, you may have another Git hooks manager defined in your package.json
overwriting husky's hooks. Check also the output during install, you should see:
husky > Setting up git hooks
husky > Done
For a commit to be blocked, pre-commit
script must exit with a non-zero exit code. If you commit isn't blocked, check your script exit code.
Husky is fast and only adds a few tenth of seconds to commits (~0.3s
on a low-end PC). So it's most probably related to how many things are done during pre-commit
. You can often improve this by using cache on your tools (babel, eslint, ...) and using lint-staged.
To isolate your issue, you can also create a new repo:
mkdir foo && cd foo
git init && npm init -y
npm install husky --save-dev
# Add a failing pre-commit hook to your package.json:
# "pre-commit": "echo \"this should fail\" && exit 1"
# Make a commit
- pkg-ok - Prevents publishing a module with bad paths or incorrect line endings
- please-upgrade-node - Show a message to upgrade Node instead of a stacktrace in your CLIs
- pinst - dev only postinstall hook
People and companies supporting via Patreon: thanks
MIT