Modern, type-safe git hooks manager for Node.js
- π Zero dependencies - Lightweight and fast
- π¦ TypeScript native - Full type safety out of the box
- π― Simple API - Register and run hooks with minimal boilerplate
- π§ Cross-platform - Works on Windows, macOS, and Linux
- β‘ Modern Node.js - Built for Node.js 18+
- π Parallel execution - Run multiple commands concurrently
- π¨ Styled output - Optional pretty tables with
--styledflag - β Ignore patterns - Skip files matching patterns
- β Configuration validation - Built-in config checker
npm install --save-dev git-hooks-cli # or yarn add -D git-hooks-cli # or pnpm add -D git-hooks-cli
import { createHookRunner, GIT_HOOKS } from 'git-hooks-cli' // Create a hook runner const runner = createHookRunner() // Register a pre-commit hook runner.register({ name: 'pre-commit', command: 'npm run lint', }) // Run the hook await runner.run('pre-commit', ['file1.ts', 'file2.ts'])
For beautiful table output, use the --styled flag:
# Simple output (zero dependencies) git-hooks list # Styled output (requires cli-table-modern) git-hooks list --styled
Simple output:
β pre-commit
β pre-push
Styled output (with --styled):
ββββββββββββ¬ββββββββββββ¬ββββββββββββββ
β Enabled β Hook β Command β
ββββββββββββΌββββββββββββΌββββββββββββββ€
β β β pre-commit β npm run lint β
β β β pre-push β npm run testβ
ββββββββββββ΄ββββββββββββ΄ββββββββββββββ
The --styled flag uses cli-table-modern for pretty output. It is lazily loaded β cli-table-modern is only downloaded when you use --styled, keeping your bundle zero-dependency by default.
Creates a new HookRunner instance.
import { createHookRunner } from 'git-hooks-cli' const runner = createHookRunner()
Register a new hook.
runner.register({ name: 'pre-commit', command: 'npm run lint', args: ['--fix'], condition: (files) => files.some(f => f.endsWith('.ts')), parallel: false, })
Execute a registered hook.
const success = await runner.run('pre-commit', ['src/index.ts'])
List all registered hooks.
const hooks = runner.list() console.log(hooks)
Remove a registered hook.
runner.unregister('pre-commit')
Clear all registered hooks.
runner.clear()
// Enable parallel execution runner.parallelExec(true) // Set ignore patterns runner.ignore(['dist/', 'node_modules/']) / Enable colored output runner.useColors(true)
This package provides a CLI tool for managing git hooks:
# Install the CLI globally npm install -g git-hooks-cli # Use npx to run directly npx git-hooks # Or use the local installation after npm install ./node_modules/.bin/git-hooks install
| Command | Description |
|---|---|
git-hooks install [hook-name] |
Install git hooks from config |
git-hooks uninstall [hook-name] |
Remove installed hooks |
git-hooks list |
List configured hooks |
git-hooks list --styled |
List hooks with pretty table output |
git-hooks status |
Show installed vs configured hooks |
git-hooks check |
Validate configuration |
git-hooks run <hook-name> |
Run a hook manually |
Configure hooks in package.json:
{
"name": "my-project",
"git-hooks": {
"pre-commit": "npm run lint",
"pre-push": "npm run test"
}
}Or in .git-hookrc:
{
"pre-commit": "npm run lint",
"pre-push": "npm run test"
}Simple array format:
{
"git-hooks": {
"pre-commit": ["npm run lint", "npm run typecheck", "npm run test"]
}
}With parallel execution:
{
"git-hooks": {
"pre-commit": {
"run": ["lint", "typecheck"],
"parallel": true
}
}
}With ignore patterns:
{
"git-hooks": {
"pre-commit": {
"run": "npm run test",
"ignore": ["dist/", "node_modules/", "*.log"]
}
}
}Cross-platform with npm scripts:
{
"scripts": {
"lint": "eslint src/",
"test": "jest",
"typecheck": "tsc --noEmit"
},
"git-hooks": {
"pre-commit": ["lint", "typecheck"],
"pre-push": "test"
}
}All standard git hooks are supported:
| Hook | Description |
|---|---|
pre-commit |
Before a commit is created |
prepare-commit-msg |
After prepare-message but before editor |
commit-msg |
After commit message is set |
post-commit |
After a commit is created |
pre-push |
Before pushing to remote |
post-merge |
After a merge completes |
pre-rebase |
Before a rebase starts |
| And more... |
See the Git hooks documentation for the full list.
runner.register({ name: 'pre-commit', command: 'npm run lint && npm run typecheck', })
runner.register({ name: 'pre-commit', command: 'npm run test', condition: (files) => files.some(f => f.includes('test')), })
runner.parallelExec(true) runner.register({ name: 'pre-commit', command: 'npm run lint && npm run typecheck', parallel: true, })
runner.register({ name: 'pre-commit', command: 'npx lint-staged', })
{
"git-hooks": {
"pre-commit": ["lint", "test"]
},
"scripts": {
"lint": "eslint src/",
"test": "jest"
}
}| Variable | Description |
|---|---|
CI |
Enable CI mode (silent installation) |
GIT_HOOKS_SILENT |
Silent installation mode |
GIT_HOOKS_NO_COLOR |
Disable colored output |
NO_COLOR |
Standard no-color flag |
Contributions are welcome! Feel free to open issues or submit pull requests on GitHub.
If you're a maintainer considering rolling similar functionality into your core package, I'm happy to point users your direction instead. Open an issue to discuss.
MIT License - see LICENSE for details.
- Inspired by the original git-hooks package
- Built for the modern Node.js ecosystem