A small feature release: Bazel users get first-class buildifier built-ins, and hk's auto-batching is now smart enough to leave steps alone when their commands don't actually reference the file list.

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.

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.

Highlights

• 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