githook-js

A minimal git hooks installer, with no runtime dependencies beyond js-yaml.

Installation

pnpm add -D githook-js
# or: npm install --save-dev githook-js

Then wire the githook-install binary into your setup so hooks stay installed automatically:

{
  "scripts": {
    "postinstall": "githook-install"
  }
}

Usage

githook-install installs git hooks into .git/hooks/ and marks them executable (chmod 0755). It's idempotent — it compares a SHA-256 hash of the source and installed copy and only touches files that changed, printing whether each hook was installed, updated, or already up to date.

Two sources are supported in the consuming project, checked in this order:

1. git_hooks.yml (preferred)

A Lefthook-style config at the project root. Each top-level key is a git hook name; each hook has a commands map of named steps, each with a run script and an optional glob that gates whether the step runs, based on the files changed in that hook's diff (staged files for pre-commit, the pushed range for pre-push):

pre-commit:
  commands:
    block-main-commit:
      run: |
        current_branch=$(git rev-parse --abbrev-ref HEAD)
        if [ "$current_branch" = "main" ]; then
          echo "❌ Error: Direct commits to the 'main' branch are blocked."
          exit 1
        fi
    lint-staged:
      glob: "*.{js,ts,vue}"
      run: pnpm exec eslint --fix $(git diff --cached --name-only --diff-filter=ACM -- '*.js' '*.ts' '*.vue')

githook-install compiles each hook's commands into a single generated script and installs it. To add a new hook or command, edit git_hooks.yml and commit it — no other changes are needed.

2. scripts/git-hooks/ (fallback)

Used only when git_hooks.yml does not exist. One plain executable script per hook, named after git's standard hook names (pre-push, pre-commit, commit-msg, etc.), copied verbatim into .git/hooks/. To add a new hook this way, drop a new executable script in this directory and commit it.