introducing hk: git hook manager

[jdx]

hk is a brand new cli for git-hooks. I could have included this functionality into mise but decided it was unique enough to warrant a new CLI.

hk and mise pair very well together. While other git-hook managers typically will provide nascent functionality around things like dependencies (tools), parallel jobs (tasks), and env vars—these are obviously things mise already does very well. Using mise to install the linters and as a way to run complex tasks means hk itself is rather simple and focused on doing the following (in a pre-commit workflow):

• stash unstaged changes
• get list of files with staged modifications
• run steps in parallel if globs match staged files
• add any changed files from fix steps, e.g.: prettier -w (optional)
• unstash unstaged files

Within each step, you could run a mise task for the advanced workflows tasks provide.

hk is configured with pkl and a basic hk.pkl for a project looks like this:

amends "https://hk.jdx.dev/v0/hk.pkl"
import "https://hk.jdx.dev/v0/builtins.pkl"

`pre-commit` {
    // hooks can be manually defined
    ["eslint"] {
        // the files to run the hook on, if no files are matched, the hook 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 step
        run = "eslint {{files}}"
    }
    // hooks can also be specified with the builtins pkl library
    ["prettier"] = new builtins.Prettier {}
}

[minibikini]

Looks cool! I tried installing it using mise use hk (like the instructions say in the Getting Started guide), but ran into this error:

mise ERROR hk not found in mise tool registry
mise ERROR Run with --verbose or MISE_VERBOSE=1 for more information

[jdx]

it's brand new, is mise up to date?

[minibikini]

Oh, I thought it was up-to-date, but it looks like there's a newer version! 😊

2025.2.4 macos-arm64 (2025-02-14)
mise WARN  mise version 2025.2.6 available

All good now, thanks so much!

[jdx]

I just released hk 0.5.0 which is the first release that I think is ready for people to really start putting through its paces. https://github.com/jdx/hk/releases/tag/v0.5.0

[thoroc]

I appreciate the addition, BUT pkl file are an odd format coming from web development. I've used Husky, Lefthook and Pre-commit and this feels completely alien to me. Not to mention the vscode extension for the language support being outside the vscode marketplace or the required Java installation (thankfully mise supports that).

[jdx]

I'm very happy with pkl. It offloads a ton of features that I don't have to build into hk and comes with schema validation built in. It's also a lot more fun.

In terms of the ecosystem, it's obviously young. I'm sure that it'll be in the vscode marketplace soon enough and the java requirement will go away when there is a native rust library so these are temporary issues.

[stempler]

I must say it took a bit to get used to pkl but after getting familiar with it, it is really awesome. So easy to share common logic and configuration in a modular way.
If anyone is interested in an example - this is our repo with shared configuration for hk.

One thing I was wondering about though is that when using hk with mise, you always need to make sure that the tools required for the linter steps are configured in mise to have them available.

Would you see it as an option to include the possibility to in the steps define the configuration for the respective tool for mise, so that mise could pick that up?
I would imagine mise would include the tools required in the steps (possibly limiting to steps where related files are present in the repo) in mise install. If there is a configuration for the same tool in mise directly, that would have priority over the config from hk.
There could be an option in mise to enable this behavior.
Like this there wouldn't be the need to make sure manually that the mise and hk configuration are in sync.

Another possibility would be if mise would support pkl configuration, so it would be possible to import matching common configuration.
I guess a workaround for this would be having a pkl file that is rendered to toml (e.g. as mise.local.toml or similar).

[jdx]

could you use a prefix on the steps like mise x node@20 --?

[stempler]

Yes, sure. So simple and effective I did not come to my mind.

One downside though is that reusing builtins is harder, since commands need to be adapted and if a builtin changes the mechanism is prone to break.

---

In the meantime I had done an exercise to test the approach with generating a mise configuration from pkl. Which worked but is cumbersome due to the need to make sure the config is generated and mise install called afterwards to have the tools available.

In case that's interesting for you:

• pkl generating the mise tools config (adding a file to .config/mise/conf.d)
• tasks to generate and apply config
• steps defined with additional tool metadata

One advantage of that approach was that it also automatically adds hk as tool and makes sure that the version used is the same as the version of the hk pkl definitions that are used.

[jdx]

the point of prefix is specifically so you don't need to override the builtin scripts

[stempler]

Completely missed that option. That makes a lot more sense. Thanks a lot!