Git Hooks Automation skill for Claude Code

# Git hook configurations

Read this when writing the actual config file. Versions below are placeholders on
purpose: run `pre-commit autoupdate` (or check each project's releases) and pin the
current tags; never leave `rev: main` or `latest`.

## pre-commit (multi-language, Python-installed)

```yaml
# .pre-commit-config.yaml
default_install_hook_types: [pre-commit, commit-msg, pre-push]
default_stages: [pre-commit]
fail_fast: false
exclude: '^(vendor/|third_party/|.*\.min\.js$)'
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: vX.Y.Z
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-json
      - id: check-merge-conflict
      - id: check-added-large-files
        args: [--maxkb=500]
      - id: detect-private-key
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: vX.Y.Z
    hooks:
      - id: ruff-check
        args: [--fix]
      - id: ruff-format
  - repo: https://github.com/gitleaks/gitleaks
    rev: vX.Y.Z
    hooks:
      - id: gitleaks
  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: vX.Y.Z
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]
  - repo: local
    hooks:
      - id: mypy
        name: mypy
        entry: uv run mypy
        language: system
        types: [python]
        pass_filenames: false
        stages: [pre-push]          # slower check: run on push, not every commit
```

Notes:
- Older ruff-pre-commit releases name the lint hook `ruff` instead of `ruff-check`;
  match the hook id to the pinned rev.
- `language: system` uses tools already installed (fast, but not isolated); use it for
  project-managed tools run via `uv run`, `npx`, `go run`.
- Commands: `pre-commit install` (honors `default_install_hook_types`),
  `pre-commit run --all-files`, `pre-commit run <id> --files a.py`,
  `pre-commit autoupdate`, `SKIP=mypy git commit ...`, `pre-commit gc`.
- `prek` is a compatible, faster reimplementation that reads the same config file; it
  can replace the `pre-commit` binary if install speed matters.

## lefthook (single binary, any language, parallel)

```yaml
# lefthook.yml
pre-commit:
  parallel: true
  commands:
    format-js:
      glob: "*.{js,ts,tsx,json,css,md}"
      run: npx prettier --write {staged_files}
      stage_fixed: true
    lint-js:
      glob: "*.{js,ts,tsx}"
      run: npx eslint --fix {staged_files}
      stage_fixed: true
    go-fmt:
      glob: "*.go"
      run: gofmt -l -w {staged_files}
      stage_fixed: true
    secrets:
      run: gitleaks git --pre-commit --staged --redact --no-banner
commit-msg:
  commands:
    conventional:
      run: npx --no -- commitlint --edit {1}
pre-push:
  parallel: true
  commands:
    typecheck:
      run: npx tsc --noEmit
    test:
      run: npm test
```

Notes:
- Install: `npm i -D lefthook` (adds a postinstall that runs `lefthook install`), or
  `brew install lefthook && lefthook install`.
- `{staged_files}`, `{push_files}`, `{all_files}`, `{1}` (first hook argument, the
  commit message file for commit-msg).
- `stage_fixed: true` re-adds files the command modified.
- Local overrides (not committed): `lefthook-local.yml`. Skip: `LEFTHOOK=0 git commit`
  or `LEFTHOOK_EXCLUDE=test git push`.
- Run manually: `lefthook run pre-commit --all-files`.
- gitleaks flags changed in v8.19 (`git`/`dir` subcommands replaced `detect`/`protect`);
  confirm with `gitleaks git --help` for your installed version.

## husky + lint-staged (JavaScript repos)

```bash
npm i -D husky lint-staged
npx husky init          # creates .husky/pre-commit and adds "prepare": "husky" to package.json
```

```sh
# .husky/pre-commit  (plain shell; husky v9 needs no shebang boilerplate)
npx lint-staged
```

```sh
# .husky/commit-msg
npx --no -- commitlint --edit "$1"
```

```json
// package.json (excerpt)
{
  "scripts": { "prepare": "husky" },
  "lint-staged": {
    "*.{ts,tsx,js}": ["eslint --fix --max-warnings=0", "prettier --write"],
    "*.{json,md,css,yml}": "prettier --write"
  }
}
```

Notes:
- lint-staged stashes unstaged changes, runs tasks on staged content, re-adds fixed
  files, and restores on failure.
- Disable in CI or for a command: `HUSKY=0`. In CI, `prepare` runs on `npm ci`;
  husky skips installing when there is no `.git` directory.
- Do not run `tsc` in lint-staged on individual files (it ignores tsconfig); run the
  project typecheck in pre-push or CI.

## commitlint

```js
// commitlint.config.js
export default { extends: ['@commitlint/config-conventional'] };
```

## CI job (run the same checks; hooks are bypassable)

```yaml
# GitHub Actions
jobs:
  hooks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - uses: pre-commit/[email protected]      # runs pre-commit run --all-files with caching
```

For lefthook: `npx lefthook run pre-commit --all-files` (and `pre-push` checks as
separate CI steps). For husky repos: run `npx lint-staged --diff="origin/main...HEAD"`
or simply the full lint/format/test commands.

## Secret scanning in history (one-off audit)

```bash
gitleaks git --redact -v .            # whole history of the current repo
trufflehog git file://. --only-verified
```

If a real secret is found: rotate it first (revocation is what protects you), then
decide with the user whether to rewrite history (see git-history-surgery).