v1.56.0: Offline Pkl evaluation and configurable output

This release adds a persistent Pkl package cache with offline evaluation, pinact v4 support, a configurable failed-command output file, and a handful of fixes for binary files, builtin argument handling, worktrees, annotated tags, and step conditions.

Added

• Persistent Pkl package cache and offline mode (@jdx) #1199. Pkl packages are now persisted (by default under the platform cache directory as pklr), so a package downloaded during any prior evaluation stays available even after hk's resolved-config cache is invalidated by a config edit, upgrade, or cache cleanup. This prevents local commits from being blocked when a registry is unreachable. Two new environment variables control the behavior: HK_PKL_CACHE_DIR overrides the cache location, and HK_PKL_OFFLINE=1 disables all network access, failing fast with the missing package URL and cache path instead of hitting the network. Both are read from the environment before hk.pkl is evaluated. Addresses discussion #1198.

• pinact v3 and v4 builtins (@risu729) #1195. The pinact and pinact_update builtins now track the latest major version (currently v4.1.1) and use the v4-native --verify-comment flag. New pinact_v3 and pinact_update_v3 alternatives are available for projects still on pinact v3, without requiring changes to step names.

  // pinact v4 (default)
  ["pinact"] = Builtins.pinact
  // pinact v3
  ["pinact"] = Builtins.pinact_v3

• Configurable failed-command output file (@signadou) #1204. The full output of failed commands is written to a log file whose location can now be set with HK_OUTPUT_FILE. It defaults to ~/.local/state/hk/output.log, and nested paths are created as needed. Closes #1201.

• allow_binary step option in Pkl (@jdx) #1190. The allow_binary step option is now declared in the Step schema, so configs can opt into processing binary files (which are filtered out by default). The Rust file filter already honored the flag, but there was previously no valid way to set it from hk.pkl. Addresses discussion #1189.

Fixed

• Preserve file argument boundaries in builtins (@jdx) #1194. Around 100 additional builtins (including ruff_format) were migrated from shell-string commands to structured argv lists so file paths keep their literal argument boundaries and compose cleanly with list prefix values. Shell-dependent builtins (pipes, redirects, substitutions, loops) are intentionally left as shell strings. Relates to discussion #1174. See Breaking Changes below.

• Scoped steps in linked worktrees (@jdx) #1200. When Git supplied only GIT_DIR, nested Git commands in scoped subproject steps treated the step's subdirectory as the worktree root, misaligning index paths with filesystem paths. hk now sets GIT_WORK_TREE to the resolved repository root and preserves GIT_INDEX_FILE, so scoped steps continue to inspect the index being committed. Fixes #1138.

• Pushing annotated tags through pre-push (@jdx) #1197. Pushing an annotated tag failed because its OID identifies a tag object, which libgit2's merge-base calculation rejects. hk now peels both ends of a ref range to commits before computing merge bases and trees. Fixes discussion #1196.

• Step condition compatibility with expr v2 (@jdx) #1212. Upgrading the expression engine to expr-lang v2 would have rejected raw newlines inside quoted condition strings that v1 accepted (Pkl decodes \n before hk evaluates a condition). A compatibility layer now escapes raw CR/LF characters only inside interpreted quoted strings, leaving backtick strings, comments, and escapes untouched, so existing step and job conditions keep working.

Breaking Changes

• Builtins migrated to structured argv in #1194 now require list-form prefixes instead of shell-string prefixes:

  prefix = List("mise", "x", "--")

New Contributors

• @signadou made their first contribution in #1204

Full Changelog: v1.55.0...v1.56.0

💚 Sponsor hk

hk is maintained by @jdx, an open source developer for entire.io, the title sponsor of the jdx.dev open source tools including mise, aube, 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 jdx.dev. Sponsorships are what keep hk moving and the project independent.