hk Release Notes

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

Original source Report a problem

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

Original source Report a problem

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

Original source Report a problem

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

Original source Report a problem

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

Original source Report a problem

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

Original source Report a problem

This release brings a more intuitive setup experience and some delightful quality-of-life improvements. The hk init command now auto-detects your project's tools and offers an interactive mode, making it easier than ever to get started. We've also added git worktree support for developers working across multiple branches simultaneously.

Highlights

Smarter Initialization (#656)

The hk init command has been significantly enhanced with auto-detection capabilities. It now scans your project to identify which linters and formatters you're using and can automatically configure them for you. An interactive mode lets you review and customize the detected configuration before committing to it.

Git Worktree Support (#651)

For developers who use git worktrees to work on multiple branches simultaneously, hk now properly supports this workflow. Hooks and configuration are correctly resolved regardless of which worktree you're working in.

Helpful Typo Suggestions (#654)

Made a typo in a command or step name? hk now offers "did you mean?" suggestions, helping you quickly recover from common mistakes without having to look up the correct spelling.

Haiku-Named Stash Backups (#655)

Stash patch backups now use memorable haiku-style names instead of cryptic identifiers. This makes it much easier to identify and manage your stashed changes when you need to recover them.

Internal Improvements

Migrated to xx utilities and removed unused dependencies, keeping the binary lean (#653)

For full documentation, visit hk.jdx.dev.

Changelog

1.35.0 - 2026-02-01

🚀 Features

• (init) add auto-detection and interactive mode by @jdx in #656
• (stash) use haiku names for stash patch backups by @jdx in #655
• add git worktree support by @jdx in #651
• add "did you mean?" suggestions for typos by @jdx in #654

🚜 Refactor

• use xx utilities and drop unused dependencies by @jdx in #653

Original source Report a problem

This release brings official Windows support to hk, expanding the tool's reach to developers on all major platforms. Whether you're running Windows, macOS, or Linux, hk now has you covered with tested, reliable git hook management and project linting.
We've also fixed an important networking issue that was affecting users in corporate environments with custom certificate authorities, ensuring HTTPS requests now properly use your system's trusted certificates.

Highlights

Windows Support (#648)

hk now includes Windows in its CI testing matrix, bringing first-class support for Windows developers. This means you can confidently use hk across your entire team regardless of operating system, making it easier to enforce consistent code quality standards in mixed-platform environments.

Bug Fixes

System CA Certificates for HTTPS (#650)

HTTPS requests now properly use your system's CA certificates instead of a bundled certificate store. This fix is particularly important for users behind corporate proxies or in environments with custom certificate authorities—hk will now respect your system's trusted certificates, eliminating connection failures when downloading tools or fetching remote configurations. Thanks to @lobaorn-bitso for this contribution!

Documentation

Clarified that the fix: commit type is specifically for CLI bug fixes, not for CI, docs, or infrastructure changes (#649)

For full documentation, visit hk.jdx.dev.

Changelog

1.34.0 - 2026-01-27

• 🚀 Features

  • add Windows CI testing and improve Windows support by @jdx in #648

• 🐛 Bug Fixes

  • use system CA certificates for HTTPS requests by @lobaorn-bitso in #650

• 📚 Documentation

  • clarify fix type is for CLI bugs only by @jdx in #649

• New Contributors

  • @lobaorn-bitso made their first contribution in #650

Original source Report a problem

🚀 Features

• add LLM-generated creative release titles by
  @jdx in
  #624
• add hook and step tera contexts by
  @thejcannon in
  #645

🐛 Bug Fixes

• strip LLM preamble from generated release notes by
  @jdx in
  #618
• start the job progress hidden by
  @thejcannon in
  #631
• default stage to for fix steps by
  @chadxz in
  #632
• remove verbose output from taplo by
  @vmeurisse in
  #364
• shfmt should use --apply-ignore by
  @thejcannon in
  #643
• Tell biome not to error on unmatched files by
  @thejcannon in
  #641

🚜 Refactor

• Add before/after variables to ruff_format.pkl tests by
  @thejcannon in
  #623
• test expectations into helpers by
  @thejcannon in
  #625
• Remove dead code in markdownlint tests by
  @thejcannon in
  #642

📚 Documentation

• improve CLAUDE.md with workspace structure and testing info by
  @jdx in
  #621
• Add linebreaks to shanty by
  @thejcannon in
  #626
• Fix condition docstring to use exec by
  @thejcannon in
  #630
• add conventional commit guidance to CLAUDE.md by
  @jdx in
  4d59edf

🧪 Testing

• markdownlint builtin by @thejcannon
  in #628
• gofmt by @thejcannon in
  #603

🔍 Other Changes

• improve release title format for robustness by
  @jdx in
  #639

📦️ Dependency Updates

• update jdx/mise-action digest to 6d1e696 by
  @renovate[bot] in
  #634
• update anthropics/claude-code-action digest to 8341a56 by
  @renovate[bot] in
  #633
• update actions/checkout action to v6 by
  @renovate[bot] in
  #635

New Contributors

• @vmeurisse made their first contribution in
  #364
• @chadxz made their first contribution in
  #632

Original source Report a problem

Highlights

This release brings a refreshed look to the hk documentation site with a new fishing hook logo, electric blue color scheme, and nautical-themed feature descriptions. We've also fixed an issue that caused commands like hk completion bash to fail when run in directories with invalid configuration files.

New branding and documentation refresh - The documentation site has been completely updated with a new fishing hook logo, electric blue color scheme, and improved homepage layout. The "Why Choose HK?" section now features nautical-themed descriptions that match the hook branding, with titles like "Shipshape," "Tackle Box," and "All Hands on Deck." Three new feature cards highlight Pkl Configuration, Mise Integration, and Parallel Execution. (#616, #617) by @jdx

Bug Fixes

Fixed completion and version commands in invalid config directories - Commands that don't need configuration (hk completion, hk usage, hk --version) now work even when run in a directory with an invalid hk.pkl file. This fixes Homebrew bottle test failures and improves the experience when setting up shell completions. (#615) by @jdx

Original source Report a problem