hk Updates & Release Notes

A feature-and-fix release: hooks can now target staged files without touching your worktree, hk install cooperates with global installs, and three separate stash/merge bugs that could clobber fixer output or staged deletions are fixed.

Added

--staged flag for hk run, check, fix, and hook subcommands (@jdx) #950. Runs hooks against the staged file set while leaving unstaged and untracked changes alone — no stash, no worktree mutation. It conflicts with --all and --stash, and forces StashMethod::None even when the hook config opts into stashing. Fixes #940.

hk run pre-commit --staged
hk fix --staged

hk install skips when hk is configured globally (@jdx) #934. If any hook.hk-* entry exists in ~/.gitconfig, hk install is a no-op and additionally cleans up stale per-repo hooks left behind from a prior install, so the global install is the single source of truth and hk doesn't fire twice per event. Pass --force-local to install per-repo hooks anyway. This means postinstall workarounds like git config --get-regexp hook.hk- || hk install can now be replaced with a plain hk install. Closes #933.

Named template variables for post-checkout hooks (@jdx) #951. Steps can now reference prev_head, new_head, and is_branch_checkout (a real boolean, mapped from git's 1/0 flag) instead of having to parse the combined hook_args string. docs/hooks.md documents the per-hook variables for prepare-commit-msg, commit-msg, and post-checkout.

oxfmt builtin (@hituzi-no-sippo) #914. Adds oxfmt as a builtin formatter for JS/TS, JSON, YAML, and TOML.

Vite+ builtin (@hituzi-no-sippo) #913. Adds Vite+ as a builtin formatter/linter for JavaScript/TypeScript.

oxlint builtin upgrades (@hituzi-no-sippo) #911. Adds --deny-warnings so violations exit non-zero, extends the file glob to .vue, .svelte, .astro, .mjs, .cjs, .mts, and .cts, and registers oxlint config files as project indicators so the builtin is auto-suggested.

Fixed

pre-push ref filter was inverted (@jdx) #932. The filter was checking the local sha for all-zeros (a deletion) when the intent was to check the remote sha (a new branch). Two visible consequences:

First push of a new branch was dropped and fell through to resolving refs/remotes/origin/HEAD, which often failed with Failed to parse reference: refs/remotes/origin/HEAD (likely the root cause of #172).

Branch deletions were kept and triggered linting against the deleted ref.

The filter now drops only deletions, falls back to the real remote-tracking branch (or Git::resolve_default_branch()) for new-branch pushes, and uses a new git::is_zero_sha() helper that works for both SHA-1 and SHA-256 repos.

hk install --global now uses absolute paths (@jdx) #939. Global hook commands previously assumed hk/mise were on PATH when git invoked the hook, which broke in environments with a sanitized PATH. The installer now resolves hk (or mise) to an absolute path at install time (using ~/ when home-relative and quoting otherwise), and --mise global installs use mise x hk -- hk so the hk tool is requested explicitly. Global installs also pick hook events from the project's hk.pkl when present. Fixes #937.

fail_on_fix no longer loses fixer output through stash = "git" (@jdx) #909. git stash show --name-only can list staged files stored in the stash commit that were not part of the unstaged set being restored, so the manual unstash could rewrite a staged-only file and discard the fixer's output that should remain visible as an unstaged diff. hk now tracks the exact path set selected for stashing and filters restore to that set. Follow-up to the fail_on_fix fix in v1.44.3.

Staged deletions survive pop_stash (@jdx) #927. pop_stash() walked every path returned by git stash show --name-only and wrote a merged blob to disk, even for paths the user had staged for deletion with git rm. After the commit, the deleted file reappeared on disk as untracked. hk now queries git diff --cached --diff-filter=D before unstashing and skips those paths. Fixes #926.

Fixer tail-line deletions are preserved across three-way merge (@jdx) #931. In merge.rs::diff_hunks, when the LCS walk consumed other entirely after a matching line, a pure tail deletion of base[i..n] was dropped, so three_way_merge_hunks silently copied the removed lines back in. The classic symptom: a fixer that strips trailing blank lines, applied to a file where you have an unrelated unstaged change in the middle, would have its trailing-line cleanup silently undone. Fixes #929.

check_diff failures get accurate fix suggestions (@jdx) #949. When a step defined both check_diff and check_list_files, the "To fix, run" hint always parsed output with the list-files parser regardless of which check actually ran. hk now passes the executed command into collect_fix_suggestion and dispatches to the diff parser for check_diff output, so the suggested files match the real failure. Fixes #942.

Full Changelog: v1.45.0...v1.46.0

💚 Sponsor hk

hk is developed by @jdx at en.dev — a small independent studio behind developer tools like mise, aube, hk, and more. Work on hk is funded by sponsorships.

If hk has sped up your pre-commit loop or made linting feel less painful, please consider sponsoring at en.dev. Sponsorships are what keep hk moving and the project independent.

Added

buildifier_format and buildifier_lint built-ins (@plx) #896. Two new built-ins for Bazel projects, modeled on buf_format / buf_lint. They cover BUILD, BUILD.bazel, WORKSPACE, WORKSPACE.bazel, MODULE.bazel, *.bzl, *.star, and *.sky files, and ship with the usual project-indicator metadata so they're auto-suggested for Bazel repos.

import "package://github.com/jdx/hk/releases/download/v1.45.0/[email protected]#/Builtins.pkl"

hooks {
["pre-commit"] {
steps = new {
["buildifier-format"] = Builtins.buildifier_format
["buildifier-lint"] = Builtins.buildifier_lint
}
}
}

Fixed

Auto-batching no longer splits jobs whose command doesn't reference {{files}} (@jdx) #901. Previously, hk decided whether to split a step into multiple ARG_MAX-safe batches purely from the size of the file-list expansion. On Windows — where ARG_MAX falls back to 128KB — a step like:

local vscodeCommitHint = new Step {
exclusive = true
check = "echo If you see this message in a pop-up, the pre-commit steps failed."
}

…against a ~20K-file repo would be fanned out into ~29 jobs, printing the message 29 times even though the command never used {{files}}. Auto-batching now happens at execution time with the full tera context available, renders the real run command for each candidate batch, and only splits when the rendered command exceeds the safe limit. Byte estimation is kept as a fallback if rendering fails. The split path also now correctly preserves check_first and workspace_indicator across batches (the old code dropped them with a TODO).

Documentation

The README now credits Namespace for providing CI runners for hk (@jdx) #895.

New Contributors

@plx made their first contribution in #896

Full Changelog: v1.44.3...v1.45.0

💚 Sponsor hk

hk is developed by @jdx at en.dev — a small independent studio behind developer tools like mise, aube, hk, and more. Work on hk is funded by sponsorships.

If hk has sped up your pre-commit loop or made linting feel less painful, please consider sponsoring at en.dev. Sponsorships are what keep hk moving and the project independent.

A small patch release fixing two notable rough edges: fail_on_fix=true no longer silently re-stages the fixer's output over your git add, and hk's text-mode progress output is finally readable in CI logs.

Fixed

• fail_on_fix=true no longer overwrites your staged changes with the fix (@jdx) #892. Previously, when a hook had fail_on_fix = true, the step's auto-staging would silently merge the fixer's output into the index over your explicit git add choices. After the failed commit, the fix was no longer visible as an unstaged change for review, and a re-commit would silently succeed with the fix baked in — defeating the entire point of fail_on_fix. should_stage is now forced off for RunType::Fix runs when fail_on_fix is set, so the fixer's output stays in the worktree as an unstaged change for you to inspect, and the commit keeps failing until you accept it. Fixes #888.

• Text-mode progress output is usable in CI again (@jdx) #890. hk's output in GitHub Actions and other piped-stderr environments was a mess: raw [9A[80D[0J cursor-control escapes leaked into the log, every status change was duplicated, failure stderr was suppressed, and a step matching hundreds of files dumped ~4KB of paths into every progress line. This release fixes the lot:

  • Bumps clx to 2.0.1, which makes refresh_once() a no-op in text mode (no more leaked UI escape codes) and dedupes consecutive identical job lines per job.
  • Failure summaries are now emitted in text mode by default. Successful steps stay quiet (their output already streamed during execution), but failed steps get a full diagnostic block at the end so you can see the failure in one place. HK_SUMMARY_TEXT=1 still forces every step's summary to print.
  • Per-step progress messages are bounded. A new display-only tera context truncates files / workspace_files to first_file … when more than one file matches, and the rendered message itself is capped at 2048 printable chars (ANSI-aware). The execution command is rendered against the full file list as before — only the human-readable progress line is truncated.
  • Stops truncating text-mode messages at 60 chars. The previous truncate_text filter clamped to term_width - 20, which is 60 in non-TTY environments — exactly enough to hide the diagnostic detail you actually need to debug a CI failure.

A typical dbg step matching 98 .rs files now reads:

dbg – 98 files – **/*.rs – ! rg -e 'dbg!' bin/generate_docs.rs …

instead of unrolling all 98 paths on every prop update.

Full Changelog: v1.44.2...v1.44.3

💚 Sponsor hk

hk is developed by @jdx at en.dev — a small independent studio behind developer tools like mise, aube, hk, and more. Work on hk is funded by sponsorships.

If hk has sped up your pre-commit loop or made linting feel less painful, please consider sponsoring at en.dev. Sponsorships are what keep hk moving and the project independent.

A small patch release focused on two HK_PKL_BACKEND=pklr rough edges: edits to hk.pkl are now picked up immediately, and loading Builtins.pkl no longer spams deprecation warnings on every run.

Fixed

hk.pkl edits are now picked up under HK_PKL_BACKEND=pklr (@jdx) #879. The two pkl backends return different things from analyze_imports — the pkl CLI happens to include the source file in resolvedImports, but pklr only returns transitive import URIs. As a result, with pklr the main hk.pkl was missing from the config cache's fresh_files, so edits didn't invalidate the cache and hk kept reusing the stale Config until you ran hk cache clear. The main config path is now always added to fresh_files. Fixes #877.

No more pklr deprecation warnings on every Builtins.pkl load (@jdx) #880. Previously, every invocation under HK_PKL_BACKEND=pklr printed:

[pklr] WARNING: property 'check_byte_order_marker' is deprecated
[pklr] WARNING: property 'fix_byte_order_marker' is deprecated

…even when your hk.pkl didn't reference those aliases. This release bumps pklr to 0.4.2 (which evaluates @Deprecated lazily, on field access) and reworks Builtins.pkl so its own internal bindings no longer touch the deprecated aliases at load time. The migration nudge still fires if you explicitly reference Builtins.check_byte_order_marker or Builtins.fix_byte_order_marker. Fixes #878.

Mobile docs banner layout (@jdx) #865, #867. At <=640px, the banner now stacks the message and "Read more" link vertically, with the close button pinned to the top-right corner instead of floating in the middle of the taller stacked layout.

Documentation

The VitePress site nav now surfaces the current release version (parsed from Cargo.toml) and a GitHub star counter, matching the mise and aube docs (@jdx) #872.

Full Changelog: v1.44.1...v1.44.2

💚 Sponsor hk

hk is developed by @jdx at en.dev — a small independent studio behind developer tools like mise, aube, hk, and more. Work on hk is funded by sponsorships.

If hk has sped up your pre-commit loop or made linting feel less painful, please consider sponsoring at en.dev. Sponsorships are what keep hk moving and the project independent.

A small patch release fixing two rough edges introduced with the v1.44.0 global-hooks work: post-commit and pre-rebase now have proper hk run subcommands, and HK_STASH_UNTRACKED=false finally skips the untracked-file scan (not just the stash), which makes hk usable on YADM-style dotfile repos where GIT_WORK_TREE is $HOME.

Fixed

hk run post-commit and hk run pre-rebase are now first-class subcommands (@jdx) #858. Both events are written by hk install, but previously fell through to the generic other handler — so they didn't show up in hk run --help and their arguments got mixed into the positional file collector, occasionally producing confusing Usage: hk run --from-ref <FROM_REF> [FILES]... errors during git rebase. pre-rebase now has a typed <upstream> [branch] signature matching git's spec, and post-commit is a proper no-args handler.

HK_STASH_UNTRACKED=false now also skips the untracked scan in git status (@jdx) #861. Before this, the flag only suppressed stashing — hk still ran git status --untracked-files=all on every invocation, which could take tens of seconds and emit hundreds of megabytes of output when GIT_WORK_TREE points at a large directory like $HOME (as in YADM). Both the libgit2 and shell-git code paths now honor the setting, so large-worktree users can opt out of the scan entirely. Fixes #860.

export HK_STASH_UNTRACKED=false
hk check --all # no longer scans the entire worktree for untracked files

Documentation

Getting-started docs now lead with hk install --global as the recommended setup path, since the --from-hook short-circuit added in v1.44.0 makes it safe to enable once per machine (@jdx) #855.

Added a dismissible cross-site announcement banner to hk.jdx.dev, with an optional expires field so banners auto-hide on their own (@jdx) #857, #862.

Full Changelog: v1.44.0...v1.44.1

💚 Sponsor hk

hk is developed by @jdx at en.dev — a small independent studio behind developer tools like mise, aube, hk, and more. Work on hk is funded by sponsorships.

If hk has sped up your pre-commit loop or made linting feel less painful, please consider sponsoring at en.dev. Sponsorships are what keep hk moving and the project independent.

Highlights

This release is all about understanding and controlling where hk runs. hk check --plan lets you dry-run a hook and see exactly which steps would execute and why, hk install --global registers hk against every repo on your machine using Git 2.54's new config-based hooks, and bare-repo dotfile managers like YADM are now supported via GIT_DIR/GIT_WORK_TREE.

• hk check --plan / --why / --json — dry-run any hook to see which steps would run, which would skip, and why, with JSON output for tooling
• hk install --global — install hooks once in ~/.gitconfig and have hk apply to every repo (Git 2.54+)
• Bare-repo dotfile support — hk now respects GIT_DIR and GIT_WORK_TREE, so YADM and similar setups work out of the box
• New cocogitto_commit_msg builtin for Conventional Commits validation

Added

hk check --plan / -P, --why [STEP] / -W, --json / -J

You can now dry-run a hook to see what hk would do without executing any commands. --plan prints the parallel groups, matched file counts, and included/skipped steps with reasons; --why drills into the skip reasons for every step (or a specific one); --json emits the plan as structured JSON for tooling. (@jdx) #848

$ hk check --plan
Plan: check
Run type: check
[parallel group] group_0
○ actionlint (no files matched filters)
✓ cargo-fmt (6 files matched)
○ cargo-clippy (required profile(s) not enabled: slow)
✓ cargo-check (6 files matched)

The planner reuses hk's real job-building and skip-evaluation logic, so the plan accurately reflects what would happen — including filter matches, profile gating, condition evaluation, dependsOn, and --step/--skip-step selections. It never executes step commands.

Git 2.54 config-based hook installation with --global

On Git 2.54+, hk install now writes config-based hooks (hook.hk-<event>.command / .event) instead of shell shims in .git/hooks/. The hooks directory is left untouched, and hk composes cleanly with other hook managers. Use --legacy to force the old shim behavior; older Git falls back automatically. (@jdx) #853

More importantly, hk install --global writes those entries to your ~/.gitconfig so hk runs in every repository on your machine:

$ hk install --global

In repos without an hk.pkl (or without a matching event), the invocation is a silent no-op via a new hidden hk run --from-hook flag — install once, forget, and repos that don't use hk are unaffected. hk uninstall now cleans up both script shims and config entries regardless of current Git version, and hk uninstall --global removes the global entries.

GIT_DIR / GIT_WORK_TREE support for bare-repo dotfile managers

hk now honors these environment variables during repository discovery, so it works with YADM and similar bare-repo dotfile setups where there is no .git directory in the work tree. When libgit2 opens a bare repo, hk falls back to shell git for status/diff operations (libgit2 refuses those on bare repos). As a bonus, hk builtins no longer loads project settings, so it runs outside a repo instead of panicking. Fixes #831. (@jdx) #847

cocogitto_commit_msg builtin

A new builtin linter that validates commit messages against the Conventional Commits spec using cocogitto's cog verify. Uses the {{commit_msg_file}} template variable, making it a drop-in for the commit-msg hook. (@hituzi-no-sippo) #838

Fixed

Text progress in CI

Some CI systems allocate a pseudo-TTY, which made console::user_attended_stderr() report an interactive stderr while the log collector stripped cursor-control escapes and recorded spinner frames as noisy log rows. hk now detects CI environments via is_ci and forces clx progress into text mode, while leaving local interactive behavior unchanged. (@jdx) #845

Changed

Bumped communique to 1.0.1 (#850) and updated clx to v2 (#836).

Full Changelog: v1.43.0...v1.44.0

💚 Sponsor hk

hk is developed by @jdx at en.dev — a small independent studio behind developer tools like mise, aube, hk, and more. Work on hk is funded by sponsorships.

If hk has sped up your pre-commit loop or made linting feel less painful, please consider sponsoring at en.dev. Sponsorships are what keep hk moving and the project independent.

This release adds {{ hook_stdin }} for forwarding git hook stdin to step commands (completing git-lfs support started in v1.42.0), introduces a built-in harper grammar checker, and ships Linux musl binaries for Alpine and other musl-based distributions.

Highlights

• {{ hook_stdin }} template variable completes git-lfs pre-push support -- LFS objects are now properly uploaded during git push
• harper-cli builtin adds grammar checking as a first-class linter
• Linux musl release binaries for Alpine and other musl-based distros
• hk is back on crates.io -- installable via cargo install hk again

Added

{{ hook_stdin }} template variable: Step commands can now receive the raw stdin that git passes to hook scripts via the stdin field. This is essential for git lfs pre-push, which needs the ref data piped through stdin to know which LFS objects to upload. Without this, git lfs pre-push would silently succeed but upload nothing, causing the remote to reject the push. The variable is available in pre-push and post-rewrite hooks. (@JohanLorenzo) #825

hooks {
["pre-push"] {
steps {
["git-lfs"] {
check = "git lfs pre-push {{ hook_args }}"
stdin = "{{ hook_stdin }}"
}
}
}
}

For pre-push, {{ hook_stdin }} contains the ref lines that git pipes in (e.g., refs/heads/main <local-sha> refs/heads/main <remote-sha>). For post-rewrite, it contains the old/new SHA mapping lines. When stdin is a terminal (no piped data), it expands to an empty string.

Built-in harper and harper_commit_message linter steps: harper-cli is now available as a builtin linter for grammar checking prose and documentation. The harper step runs against text files, while harper_commit_message checks commit messages. (@hituzi-no-sippo) #714

Linux musl release binaries: Pre-built binaries for x86_64-unknown-linux-musl and aarch64-unknown-linux-musl are now included in releases, making hk easy to install on Alpine Linux and other musl-based distributions. (@jdx) #829

hk is published to crates.io again: The crate had been stuck at v1.10.1 since August 2025 after the publish step was accidentally dropped during a build system migration. Starting with this release, cargo install hk will get the latest version. (@jdx) #830

New Contributors

@hituzi-no-sippo made their first contribution in #714

Full Changelog: v1.42.0...v1.43.0

This release adds a new {{ hook_args }} template variable for forwarding git hook arguments to downstream commands, and fixes a Windows-specific bug where {{files}} expansion silently broke file-based checks.

Added

{{ hook_args }} template variable: Step commands can now access the arguments that git passes to hook scripts via {{ hook_args }}. This is essential for tools like git-lfs, whose hooks (post-checkout, post-merge, pre-push) require the original positional arguments from git to function correctly. Without this, commands like git lfs post-checkout would fail with "This should be run through Git's post-checkout hook." (@JohanLorenzo) #807

hooks {
["post-checkout"] {
steps {
["git-lfs"] { check = "git lfs post-checkout {{ hook_args }}" }
}
}
["post-merge"] {
steps {
["git-lfs"] { check = "git lfs post-merge {{ hook_args }}" }
}
}
["pre-push"] {
steps {
["git-lfs"] { check = "git lfs pre-push {{ hook_args }}" }
}
}
}

The variable is populated for all hook types: pre-push gets <remote-name> <remote-url>, commit-msg gets the message file path, post-checkout gets <prev-head> <new-head> <is-branch>, and so on. For hooks that receive no arguments (like pre-commit), it expands to an empty string.

First-class post-checkout, post-merge, and post-rewrite hooks: These three hook types now have dedicated subcommands (hk run post-checkout, hk run post-merge, hk run post-rewrite) with proper argument parsing, rather than being handled as generic hooks. (@JohanLorenzo) #807

Fixed

{{files}} expansion on Windows no longer silently breaks checks: On Windows, Rust's Command::arg applies MSVCRT-style argv escaping that collides with cmd.exe's own quoting rules. This caused the already-quoted {{files}} payload to reach tools with literal " characters embedded in arguments. Tools like ruff, biome, and others would silently exit 0 while processing zero files, making hk report success on broken invocations. The fix switches the Windows cmd.exe /c code path to use raw_arg, passing the rendered command string verbatim so cmd.exe can parse its own quoting without Rust interference. This also affects {{workspace_files}}. (@jdx) #824

New Contributors

@JohanLorenzo made their first contribution in #807

Full Changelog: v1.41.1...v1.42.0

A patch release focused on fixing hook failure output. Previously, failing steps could produce duplicated or missing diagnostic output depending on the combination of output_summary, check_first, and fail_fast settings. These fixes ensure that failure output is shown exactly once, includes both stdout and stderr so no diagnostics are lost, and preserves the configured summary label.

Fixed

• No more duplicate output on failure: The end-of-run error handler was reprinting the first failing step's output after the per-step summary had already displayed it. This caused confusing duplication and misattribution -- for example, one tool's errors could appear to be part of another tool's section. The redundant handle_script_failed output has been removed. (@nkakouros) #784

• Combined output shown for failed steps: When a step fails, hk now shows combined stdout+stderr output regardless of the output_summary setting (unless set to "hide"). Previously, if output_summary was set to "stderr" but the tool wrote diagnostics to stdout (as eslint, flake8, prettier, and many others do), those diagnostics were invisible in the failure summary. (@nkakouros) #772

• Configured output summary label preserved on failure: The combined-output-on-failure fix from #772 was changing the summary header from the configured label (e.g., lint stderr:) to lint combined:. The label now matches the configured output_summary value while still using combined content underneath. (@jdx) #808

• check_first diagnostics preserved when cancelled by fail_fast: For steps using check_diff or check_list_files with check_first, diagnostic output from the check phase was lost if another step failed first and triggered fail_fast cancellation before the fix phase could run. The check output is now saved so it appears in the summary. (@nkakouros) #784

New Contributors

• @jhult made their first contribution in #805

Full Changelog: v1.41.0...v1.41.1

This release adds support for per-worktree git hook configurations, fixes the global config path to consistently use XDG_CONFIG_HOME across all platforms, and resolves a common issue where Go package-level analysis tools would fail in multi-package projects.

Added

Per-worktree hook support: When extensions.worktreeConfig is enabled and a per-worktree core.hooksPath is set, hk install and hk uninstall now respect that worktree-local directory instead of always using the shared hooks directory. This allows different worktrees to have independent hook configurations without conflicting with each other. (@nkakouros) #789

# Enable per-worktree config in the main repo
git config extensions.worktreeConfig true
# In each worktree, point hooks to a worktree-local directory
cd /path/to/worktree
git config --worktree core.hooksPath "$(git rev-parse --git-dir)/hooks"
hk install

Fixed

Config path now uses XDG_CONFIG_HOME on all platforms: Previously, hk used dirs::config_dir() which resolves to ~/Library/Application Support/ on macOS, meaning the documented path ~/.config/hk/config.pkl would not be found. hk now uses $XDG_CONFIG_HOME (defaulting to ~/.config) on all platforms, consistent with mise and matching what the documentation describes. (@fukuchancat) #801

Go package-level builtins work in multi-package projects: Seven Go analysis builtins (go_vet, golangci_lint, go_sec, go_vuln_check, staticcheck, revive, err_check) now use workspace_indicator = "go.mod" and run ./... from the module root instead of passing individual file paths. This fixes the "named files must all be in one directory" error that occurred when staged .go files spanned multiple packages -- a Go toolchain constraint that affects any tool built on go/packages. File-level formatters (go_fmt, go_fumpt, go_imports, go_lines) are unchanged. (@jdx) #803

Breaking Changes

macOS config path changed: On macOS, hk now looks for global config at ~/.config/hk/config.pkl instead of ~/Library/Application Support/hk/config.pkl. If you had a config file at the old macOS-specific path, move it to ~/.config/hk/config.pkl (or set HK_CONFIG_DIR to point to your preferred location). This was never documented or intended behavior.

New Contributors

@fukuchancat made their first contribution in #801

Full Changelog: v1.40.0...v1.41.0

This release introduces an experimental pure-Rust Pkl evaluator (pklr) as an opt-in backend, adds a required field for steps that need specific environment variables, and expands the builtins library with five new linter/scanner configurations. It also fixes an important staging bug where hk fix could inadvertently stage pre-existing untracked files.

Highlights

Experimental pklr backend: Set HK_PKL_BACKEND=pklr to evaluate .pkl config files using a built-in Rust evaluator instead of shelling out to the pkl CLI. This eliminates the pkl binary dependency entirely. Proxy, CA certificate, and HTTP rewrite settings are forwarded automatically. Note: pklr is experimental and may not support every pkl feature yet.

required field for steps: Steps can now declare environment variables that must be present for the step to run. If any are missing, the step is gracefully skipped with a clear message. This is designed for builtins like addlicense where running without user-provided configuration would produce incorrect results.

Five new builtins: google_java_format, dclint, gitleaks, betterleaks, and mdschema join the built-in linter registry.

Staging correctness fix: hk fix no longer stages untracked files that existed before the hook ran -- only files newly created by fixers are staged.

Added

pklr Pkl backend: A pure-Rust Pkl evaluator is now available as an opt-in alternative to the external pkl CLI. Enable it with HK_PKL_BACKEND=pklr. Supports proxy settings, custom CA certificates via HK_PKL_CA_CERTIFICATES, and HTTP rewrites via HK_PKL_HTTP_REWRITE. (@jdx) #768, #769

export HK_PKL_BACKEND=pklr
hk run check # no pkl CLI needed

required field on steps: Declare environment variables that must be set for a step to run. If any are missing, the step is skipped with a message like skipped: missing required environment variable(s): LICENSE_FILE. Variables can be satisfied by the process environment, the global env block, or the step's own env block. (@timothysparg) #785

["addlicense"] {
required = List("LICENSE_FILE")
check = "addlicense --check -f $LICENSE_FILE {{files}}"
fix = "addlicense -f $LICENSE_FILE {{files}}"
}

To see skip messages for missing required env vars, add "missing-required-env" to display_skip_reasons.

google_java_format builtin: Format Java files using google-java-format. Matches **/*.java. (@timothysparg) #777

dclint builtin: Lint and fix Docker Compose files using dclint. Auto-detected via compose.yml, docker-compose.yml, and variants. (@timothysparg) #779

gitleaks builtin: Scan for secrets in Git repositories using gitleaks. Auto-detected via .gitleaks.toml. (@hituzi-no-sippo) #749

betterleaks builtin: Scan for secrets using betterleaks. Auto-detected via .gitleaks.toml or .betterleaks.toml. (@hituzi-no-sippo) #750

mdschema builtin: Validate Markdown documents against schemas using mdschema. Auto-detected via .mdschema.yml. (@hituzi-no-sippo) #748

Changed

exclude defaults to List(): The exclude field on steps now defaults to an empty list instead of null. This means you no longer need the null-coalescing operator when extending exclusions in Pkl configs. (@timothysparg) #781

// Before (required null check)
exclude = (Builtins.actionlint.exclude ?? List()) + List("**/ignored-dir/**")
// After (just concatenate)
exclude = Builtins.actionlint.exclude + List("**/ignored-dir/**")

Fixed

Pre-existing untracked files no longer staged by hk fix: When using the default stage=<JOB_FILES> behavior, untracked files that existed before the hook started are no longer added to the git index. Only files newly created by fixers during the run are staged. Explicit stage globs still opt into staging all matching untracked files. (@jdx) #788

Pkl package URIs use correct versioned format: Documentation and error messages now use the correct versioned Pkl package URI format (/releases/download/vX.Y.Z/[email protected]) instead of invalid /latest/ paths. Error messages also now dynamically reflect the running hk version. (@jdx) #770

New Contributors

@timothysparg made their first contribution in #777

Full Changelog: v1.39.0...v1.40.0

This release adds four new builtin linter/formatter configurations, introduces corporate proxy support for Pkl config loading, and fixes several important correctness issues -- most notably binary file corruption during the stash/unstash cycle and broken hooks in git worktrees.

Highlights

Binary file preservation in stash: Binary files (images, compiled assets, etc.) were silently corrupted to 0 bytes when hk stashed and unstashed changes during pre-commit hooks with partial staging. This is now fixed with binary-safe blob handling.

Git worktree support: The commit-msg and prepare-commit-msg hooks now resolve file paths correctly in git worktrees, where .git is a file pointing to the main repo rather than a directory.

Four new builtins: just_format, knip, knip_strict, and contextlint join the growing library of built-in linter configurations.

Corporate proxy support: The new HK_PKL_CA_CERTIFICATES env var lets hk work behind SSL-intercepting proxies without manual workarounds.

Added

just_format builtin: Format Justfiles using just --fmt. Matches **/justfile and **/*.just globs. (@matdibu) #729

knip and knip_strict builtins: Find unused files, dependencies, and exports in JavaScript/TypeScript projects using Knip. The knip_strict variant enables --strict (implies --production) for stricter analysis. (@hituzi-no-sippo) #713

contextlint builtin: Rule-based linting for structured Markdown documents using contextlint. Automatically detected via contextlint.config.json. (@hituzi-no-sippo) #747

HK_PKL_CA_CERTIFICATES env var: Pass a custom CA certificates file to Pkl via --ca-certificates, enabling hk to work in corporate environments with SSL-intercepting proxies. (@jdx) #760

export HK_PKL_CA_CERTIFICATES=/path/to/ca-bundle.pem

Fixed

Binary files preserved during stash/unstash: Binary files (PNG, JPG, etc.) were silently corrupted to 0 bytes during the stash/unstash cycle when committing with partial staged changes. The root cause was that git_read_raw() converted blob output to a UTF-8 string, which fails silently for binary content. Binary files are now detected and restored directly from raw bytes, bypassing the text merge path. (@jdx) #759

Commit message hooks work in git worktrees: In git worktrees, .git is a file (not a directory), so the .git/COMMIT_EDITMSG path passed by git to commit-msg and prepare-commit-msg hooks would fail with "Not a directory". hk now resolves these paths through the actual git directory. (@jdx) #761

Batch splitting honored in workspace jobs: When both workspace_indicator and batch = true were set, the batch splitting logic was bypassed entirely, producing one large job per workspace. Files are now properly chunked into parallel jobs within each workspace. (@jdx) #757

trailing-whitespace --fix handles CRLF correctly: The fix and check modes used BufReader::lines() which silently strips \r from CRLF line endings, making carriage returns invisible to detection. This is now consistent with --diff mode, which already handled CRLF correctly. (@jdx) #758

Regex patterns no longer break config cache: Regex() file patterns caused "failed to parse cache file" warnings on subsequent runs because the serde discriminator field was skipped during serialization. (@jdx) #740

nixfmt gracefully skips on Windows: Since nixfmt doesn't support Windows, the builtin now cleanly no-ops on that platform instead of failing. (@azais-corentin) #741

New Contributors

@azais-corentin made their first contribution in #741

Full Changelog: v1.38.0...v1.39.0

A small release that adds a new fail_on_fix hook option for workflows that want fixes applied but commits blocked, along with correctness improvements to several built-in linter configurations.

Added

• fail_on_fix hook option: Hooks can now set fail_on_fix = true to fail when fix commands actually modify files. This is designed for stage = false pre-commit workflows where you want fixers to apply changes but block the commit so you can review and stage them manually. Defaults to false to preserve existing behavior. (@jdx) #725

hooks {
["pre-commit"] {
fix = true
stage = false
fail_on_fix = true
steps = linters
}
}

Fixed

Cleaner builtin linter configs: Removed redundant check commands from black, ruff_format, and taplo_format builtins where check_diff already covers all issues. Removed check_diff from the ruff builtin because ruff check --diff can exit 0 even when non-fixable issues exist, which caused hk to incorrectly skip the fix step. Thanks @nkakouros! #726

Full Changelog

v1.37.0...v1.38.0

Highlights

This release overhauls global configuration handling, adds hook-level environment variables, and fixes several correctness issues in check/fix workflows.

• Overhauled global config (hkrc) -- The global user configuration has been significantly reworked. hk now supports the full Config.pkl format in hkrc files (not just UserConfig.pkl), fixing a panic when using the documented example with hooks and steps. The recommended config location is now ~/.config/hk/config.pkl, with clear "project wins" merge semantics. The legacy .hkrc.pkl paths and --hkrc flag are deprecated and will be removed in v2. Thanks @ivy! #710
• Hook-level env support -- Hooks can now define environment variables that are automatically passed to all their steps, reducing duplication when multiple steps need the same variables. Step-level env takes precedence over hook-level env. #709
• check_diff correctness in check mode -- Previously, steps with check_diff defined would always run the diff command first, even in check mode. This could hide non-auto-fixable errors when the diff command exited 0. The diff-first shortcut is now gated to fix mode only. Thanks @nkakouros! #717
• Added
  • Hook-level env: Define environment variables once per hook instead of repeating them on every step. Step-level env takes precedence when both define the same variable. (@jdx) #709
  • hooks {
    ["pre-push"] {
    env {
    ["HK_PROFILES"] = "types"
    }
    steps = linters
    }
    }
  • Go-style diff parsing: hk now correctly handles unified diffs where the --- line has a .orig suffix (common with Go tools like gofmt -d). (@jdx, co-authored by @thejcannon) #704
  • XDG config directory support: Global configuration can now be placed at ~/.config/hk/config.pkl (or a custom path via HK_CONFIG_DIR). (@ivy) #710
  • Config precedence documentation: A clear precedence table and hkrc merge semantics are now documented, covering built-in defaults through CLI flags. (@ivy) #701 #710
• Fixed
  • end-of-file-fixer now enforces that files end with exactly one trailing newline, matching pre-commit-hooks behavior. Previously it would add a missing newline but leave multiple trailing newlines untouched. (@jdx) #708
  • pre-commit with stash no longer passes untracked files to linters as input. Untracked files were incorrectly included in the unstaged files set, causing them to be processed during hk run pre-commit. Thanks @nkakouros! #716
  • check_diff in check mode no longer silently swallows errors. When a step defines check_diff, hk previously ran the diff command first in all modes. If the diff command exited 0 (no auto-fixable issues), non-auto-fixable violations detected by the regular check command were hidden. The diff-first shortcut is now only used in fix mode. Thanks @nkakouros! #717
  • hkrc format support: Global config files can now use the full Config.pkl format with hooks containing steps that have check, fix, and glob fields. Previously this caused a panic because hk always deserialized hkrc as UserConfig. (@ivy) #710
  • hkrc discovery path: Default hkrc discovery now correctly checks ~/.hkrc.pkl and ~/.config/hk/config.pkl, instead of only looking for .hkrc.pkl relative to the current directory. (@ivy) #710
  • --all flag documentation now correctly describes what the flag does. Thanks @nkakouros! #715
• Deprecated
  • .hkrc.pkl and --hkrc flag are deprecated and will be removed in hk v2. Use ~/.config/hk/config.pkl for global configuration or hk.local.pkl in the project root for per-project overrides. Deprecation warnings are shown when legacy paths are used. #710

New Contributors

• @ivy made their first contribution in #701
• @nkakouros made their first contribution in #716

Full Changelog: v1.36.0...v1.37.0

Highlights

• New --pr flag for checking PR-changed files — You can now run hk check --pr to automatically check only the files that have changed in your current pull request compared to the base branch. This makes it easy to run targeted checks during code review without processing your entire codebase. #660
• New tmpdir step option — Steps can now specify tmpdir = true to run in an isolated temporary directory, useful for tools that need a clean working environment. Thanks @thejcannon! #663
• ty builtin — Added support for ty, Astral's new Python type checker. Thanks @joonas! #566
• New Built-in Linters
  • Thanks to @matdibu for contributing five new builtins:
  • cmake_format — Format CMake files #672
  • deadnix — Find unused code in Nix files #670
  • hclfmt — Format HCL/Terraform files #675
  • nil — Nix language server for diagnostics #669
  • nixf_diagnose — Additional Nix diagnostics #671
  • The ruff_format and tombi builtins now use --quiet mode for cleaner output. #667 #676

Bug Fixes

• typos now respects exclusions when using --force-exclude — Thanks @CallumKerson! #659
• check-case-conflict no longer reports false positives from duplicate file entries — Thanks @safinn! #678
• yamllint now runs in strict mode for more reliable error detection #673
• Fixed ignore patterns not being respected when recursing into directories — Thanks @thejcannon! #661
• Fixed Nix flake builds when git submodules are included — Thanks @jeffutter! #681
• New Contributors
• Welcome to our new contributors! 🎉
• @jeffutter
• @matdibu
• @safinn
• @CallumKerson

Full documentation: https://hk.jdx.dev/ Changelog

1.36.0 - 2026-02-09

🚀 Features

• (cmake_format) init by @matdibu in #672
• (deadnix) init by @matdibu in #670
• (hclfmt) init by @matdibu in #675
• (nil) init by @matdibu in #669
• (nixf_diagnose) init by @matdibu in #671
• (ruff_format) use --quiet by @matdibu in #667
• ( Tomb i ) use --quiet by @matdibu in #676
• add ty builtin by @joonas in #566
• add --pr shortcut flag for checking PR-changed files by @jdx in #660
• add tmpdir step test option by @thejcannon in #663

🐛 Bug Fixes

• (bultins) respect typos exclusions with --force-exclude by @CallumKerson in #659
• (docs) escape angle brackets in --pr flag description by @jdx in #666
• (docs) use valid
  tags instead of
  in sea shanty by @jdx in 12e17f8
• (go_fumpt) comment out broken check by @matdibu in #668
• (yamllint) enable strict mode by @matdibu in #673
• respect ignore when recursing by @thejcannon in #661
• Deduplicate files in check-case-conflict to prevent false positives by @safinn in #678
• Fix building of nix flake wiwth the inclusion of git subomdules by @jeffutter in #681

🛡️ Security

• add tone calibration to release notes prompt by @jdx in #679
• add opengraph meta tags by @jdx in #685

🔍 Other Changes

• Use tmpdir for the tests by @thejcannon in #677

📦️ Dependency Updates

• lock file maintenance by @renovate[bot] in #658
• update anthropics/claude-code-action digest to b113f49 by @renovate[bot] in #684
• update actions/checkout digest to de0fac2 by @renovate[bot] in #683

New Contributors

• @jeffutter made their first contribution in #681
• @matdibu made their first contribution in #673
• @safinn made their first contribution in #678
• @CallumKerson made their first contribution in #659