simple-git-hooks

To remove the package and all existing git hooks:

• pnpm: pnpm uninstall simple-git-hooks (This also removes the hooks).
• npm/others: npm uninstall simple-git-hooks (This removes the package but not the hooks). To remove hooks manually, run:

  node node_modules/simple-git-hooks/uninstall.js

Skip installation

If you want to prevent hooks from being installed during npm install (e.g., in CI environments), set the SKIP_INSTALL_SIMPLE_GIT_HOOKS environment variable:

export SKIP_INSTALL_SIMPLE_GIT_HOOKS=1
npm install simple-git-hooks --save-dev

Skip execution for a single command

Use the standard git --no-verify (or -n) flag to bypass hooks for a specific operation:

git commit -m "message" --no-verify

Skip execution for the entire session

Set the SKIP_SIMPLE_GIT_HOOKS environment variable to bypass all associated hooks for all subsequent Git commands in the current terminal session:

export SKIP_SIMPLE_GIT_HOOKS=1

To use simple-git-hooks in your project, follow these steps:

1. Install as a dev dependency:

   npm install simple-git-hooks --save-dev

2. Configure your hooks in package.json.
3. Run the CLI to apply the hooks:

   npx simple-git-hooks

4. (Recommended) Add it to your prepare script to ensure hooks are installed automatically when dependencies are installed:

   {
     "scripts": {
       "prepare": "existing-command && simple-git-hooks"
     }
   }

Whenever you modify your git hook configuration, you must manually run the CLI to update the actual git hooks in your .git directory.

Run the following command from the root of your project:

• npm: npx simple-git-hooks
• yarn 2+: yarn dlx simple-git-hooks
• yarn 1: ynpx simple-git-hooks

Instead of using package.json, you can use external configuration files. If an external file is present, the package.json configuration will be ignored. Supported files include .simple-git-hooks.cjs, .simple-git-hooks.js, .simple-git-hooks.mjs, simple-git-hooks.cjs, simple-git-hooks.js, simple-git-hooks.mjs, .simple-git-hooks.json, or simple-git-hooks.json.

To install hooks from a specific custom configuration file, use: npx simple-git-hooks ./my-config.js.

CommonJS Example

module.exports = {
  "pre-commit": "npx lint-staged",
  "pre-push": "npm run format",
};

ES Modules Example

export default {
  "pre-commit": "npx lint-staged",
  "pre-push": "npm run format",
};

JSON Example

{
  "pre-commit": "npx lint-staged",
  "pre-push": "npm run format"
}

If you use a node version manager (like nvm, nodenv, or mise) and encounter npx: command not found in a GUI client (like VSCode or GitKraken), you need to provide the path to your node binaries via an init script.

1. Create an init script at ~/.simple-git-hooks.rc containing the necessary path exports. For example, for mise:

   export PATH="$HOME/.local/share/mise/shims:$PATH"

2. Set the SIMPLE_GIT_HOOKS_RC environment variable to point to this file. On macOS, you can add this to your ~/.zshenv:

   export SIMPLE_GIT_HOOKS_RC="$HOME/.simple-git-hooks.rc"

Use setHooksFromConfig to parse your configuration and install the corresponding git hooks into your .git/hooks directory. The function automatically detects the project root and handles the creation/replacement of hook files.

Configuration Sources: The function searches for configuration in the following order:

1. A custom file path provided as the second argument.
2. .simple-git-hooks.cjs
3. .simple-git-hooks.js
4. .simple-git-hooks.mjs
5. simple-git-hooks.cjs
6. simple-git-hooks.js
7. simple-git-hooks.mjs
8. .simple-git-hooks.json
9. simple-git-hooks.json
10. The simple-git-hooks key in package.json.

Options:

• projectRootPath: The absolute path to the project root (defaults to process.cwd()).
• argv: An array of command line arguments (defaults to process.argv).

Returns: A Promise that resolves to an object: { isHookChanged: boolean }.

You can prevent the installation of hooks by setting the SKIP_INSTALL_SIMPLE_GIT_HOOKS environment variable to 1 or true. This is useful in CI/CD environments or specific development workflows where you want to avoid modifying the .git directory.

Use the skipInstall() function to check if this condition is met.

Use removeHooks to delete all git hooks that were installed by simple-git-hooks. It uses the same configuration discovery logic as setHooksFromConfig to determine which hooks to remove, while respecting the preserveUnused option if present in your config.

Parameters:

• projectRootPath: The absolute path to the project root (defaults to process.cwd()).

Returns: A Promise that resolves when hooks are removed.

When defining your configuration, you can use the following option:

• preserveUnused: An array of hook names (e.g., ['pre-commit']) or a boolean. If set, any git hooks present in the .git/hooks directory that are not defined in your configuration will be left untouched instead of being deleted.

The following are the supported git hook names that can be used in your configuration file:

applypatch-msg
pre-applypatch
post-applypatch
pre-commit
pre-merge-commit
prepare-commit-msg
commit-msg
post-commit
pre-rebase
post-checkout
post-merge
pre-push
pre-receive
update
proc-receive
post-receive
post-update
reference-transaction
push-to-checkout
pre-auto-gc
post-rewrite
sendemail-validate
fsmonitor-watchman
p4-changelist
p4-prepare-changelist
p4-post-changelist
p4-pre-submit
post-index-change