hk - Git Hook Manager

Overview

hk is a fast git hook manager by jdx (author of mise). Uses pkl configuration language. Provides 90+ built-in linters.

Docs: https://hk.jdx.dev/ GitHub: https://github.com/jdx/hk

Detection

Identify which hook manager a project uses:

| File | Hook Manager | |------|--------------| | hk.pkl | hk | | lefthook.yml | lefthook | | .husky/ directory | husky | | .pre-commit-config.yaml | pre-commit (python) |

Key Commands

hk init              # Create initial hk.pkl
hk install           # Set up git hooks
hk check             # Run checks manually (read-only)
hk fix               # Auto-fix issues
hk builtins          # List available builtins
hk validate          # Validate config
hk config dump       # Show effective configuration

Core Concepts

• Hooks: Git hook types (pre-commit, commit-msg, pre-push)
• Steps: Named units of work within hooks
• Builtins: Pre-configured linters (90+) via Builtins.pkl
• Profiles: Enable/disable groups of steps (--profile slow)

Configuration

When editing hk.pkl, read hk-pkl-reference.md in this skill directory for structure and examples.

Built-in Linters

When looking up builtins, read builtins-reference.md in this skill directory. Or run hk builtins for the live list.

Finding Help

Stable reference: Read the reference files in this skill directory when needed.

Latest docs:

npx @mdream/crawl https://hk.jdx.dev/ --output /tmp/hk-docs

GitHub issues:

gh issue list -R jdx/hk                    # List open issues
gh search issues --repo jdx/hk "error"     # Search issues
gh issue view 123 -R jdx/hk                # View specific issue

Troubleshooting

Hook not running:

hk install        # Reinstall hooks
cat .git/hooks/pre-commit  # Verify hook calls hk

Step skipped:

hk check -v       # Verbose output shows skip reasons
hk config dump    # Check effective configuration

Validate config:

hk validate       # Check hk.pkl syntax