Getting Started

A tool for running hooks on files in a git repository.

DANGER

This is a work in progress. Everything about this project including the docs is probably going to change. You may encouter bugs that result in local data loss.

Installation

Use mise-en-place to install hk (you'll also need the pkl cli):

mise use hk pkl
hk --version

TIP

mise-en-place integrates well with hk. Features common in similar git-hook managers like dependency management, task dependencies, and env vars can be provided by mise.

See mise integration for more information.

Or install from source with cargo:

cargo install hk

Project Setup

Use hk generate to generate a hk.pkl file:

hk generate

hk.pkl

This will generate a hk.pkl file in the root of the repository, here's an example hk.pkl with eslint and prettier linters:

amends "package://github.com/jdx/hk/releases/download/v0.4.2/[email protected]#/Config.pkl"
import "package://github.com/jdx/hk/releases/download/v0.4.2/[email protected]#/builtins/prettier.pkl"

linters {
    // linters can be manually defined
    ["eslint"] {
        // the files to run the linter on, if no files are matched, the linter will be skipped
        // this will filter the staged files and return the subset matching these globs
        glob = new { "*.js"; "*.ts" }
        // a command that returns non-zero to fail the check
        check = "eslint {{files}}"
    }
    // linters can also be specified with the builtins pkl library
    ["prettier"] = new prettier.Prettier {}
}

hooks {
    ["pre-commit"] {
        ["fix"] = new Fix {}
    }
}

See configuration for more information on the hk.pkl file.

Usage

Inside a git repository with a hk.pkl file, run:

hk install

This will install the hooks for the repository like pre-commit and pre-push if they are defined in hk.pkl. Running git commit would now run the linters defined above in our example through the pre-commit hook.

core.hooksPath

As an alternative to using hk install, you can run git config --local core.hooksPath .hooks to use the hooks defined in the .hooks directory of the repository:

#!/bin/sh
hk run pre-commit

Running Hooks

To explicitly run the hooks without going through git, use the hk run command.

hk run pre-commit

This will run the pre-commit hook for the repository. This will run against all files that are staged for commit. To run against all files in the repository, use the --all flag.

hk run pre-commit --all

To run a specific linter, use the --linter flag.

hk run pre-commit --linter eslint