lefthook

Lefthook Git Hooks Standard

Canonical git-hooks setup using lefthook. Keep hooks thin by delegating every command to a mise run task, so local hooks and CI run the exact same checks. Lefthook decides when to run; mise owns what each command does.

Principles

• pre-commit (fast): format staged files, then run the static checks and secret scan.
• pre-push (slower): the test suite.
• post-commit (optional): repair state the commit itself invalidated — for a repo that deploys a binary built from its own sources, rebuild and redeploy it here, guarded so it only fires when the commit touched a real build input. Git ignores this hook's exit status, so it reports without ever blocking a commit.
• Delegate, don't duplicate: every command is a thin mise run <task>; the command name mirrors the task (format:go → mise run format:go). Tasks are owned by the language stack (go-stack, python-stack) — see the mise skill.
• Staged formatters, whole-tree checks: formatters take {staged_files} and restage their fixes (stage_fixed: true); check/test take no files so they always run on the whole tree — "run everything before commit/push".
• Clean output: suppress version headers and successful commands to keep commits quiet and distraction-free.

Setup

1. Add lefthook using mise (Go: go-stack; Python: python-stack).
2. Create lefthook.yml at the repo root (template below).
3. Install the hooks: lefthook install (wired into mise run install).

Template

pre-commit:
  parallel: false
  commands:
    format:dprint:
      glob: "*.{json,md,toml,yaml,yml}"
      priority: 10
      run: mise run format:dprint {staged_files}
      stage_fixed: true
    format:<lang>: # one per language: format:go / format:python / format:templ ...
      glob: "*.<ext>"
      priority: 10
      run: mise run format:<lang> {staged_files}
      stage_fixed: true
    check:leaks: # staged secret scan — history-mode gitleaks in `check` can't gate the incoming commit
      priority: 20
      run: mise run check:leaks --staged
    check:
      priority: 30
      run: mise run check
pre-push:
  commands:
    test:
      run: mise run test