hk v2 breaking-change rollout

[jdx]

hk v2 will include a coordinated set of breaking changes. I’d really appreciate feedback on the direction, especially on anything that feels surprising, unclear, or unnecessarily difficult to migrate.

I don't do big breaking changes like this in CLIs very often at all, but early design decisions have come home to roost, and I think one big break—this likely would be the only big change to the design ever—is necessary. The goal is to address those design issues together so hk has a cleaner, more consistent foundation going forward, rather than asking users to work through a series of smaller breaking changes over time.

Major changes at a glance

Define shared steps once

In v1, the same steps often had to be repeated across hooks:

hooks {
  ["check"] {
    steps {
      ["prettier"] = Builtins.prettier
    }
  }
  ["fix"] {
    fix = true
    steps {
      ["prettier"] = Builtins.prettier
    }
  }
  ["pre-commit"] {
    fix = true
    steps {
      ["prettier"] = Builtins.prettier
    }
  }
}

In v2, top-level steps automatically create the usual check, fix, and pre-commit behavior:

steps {
  ["prettier"] = Builtins.prettier
}

You can still define explicit hooks when you need to override those defaults, and enabled = false disables an implicit hook.

Configure builtins through stable factories

Default builtin references stay the same:

["prettier"] = Builtins.prettier

Special-purpose builtin names become options on the main builtin. For example:

// v1
["gitleaks"] = Builtins.gitleaks_staged
["knip"] = Builtins.knip_strict
["pinact"] = Builtins.pinact_v3

// v2
["gitleaks"] = (Builtins.gitleaks) {
  staged = true
}
["knip"] = (Builtins.knip) {
  strict = true
}
["pinact"] = (Builtins.pinact) {
  version = "3"
}

Generic step customization moves under step, leaving room for builtin-specific options:

// v1
["prettier"] = (Builtins.prettier) {
  batch = false
}

// v2
["prettier"] = (Builtins.prettier) {
  step {
    batch = false
  }
}

Stage fixes only when intended

In v2, pre-commit continues to fix and stage changes by default. Manual hk fix and other hooks leave changes unstaged unless requested:

hk fix          # fixes files but leaves them unstaged
hk fix --stage  # fixes and stages them

A step-level stage pattern now filters which paths are staged; it no longer turns staging on by itself.

Use the canonical config and command names

v1	v2
hk.toml, hk.yaml, hk.yml, or hk.json	hk.pkl
project .hkrc.pkl	hk.local.pkl
~/.hkrc.pkl	~/.config/hk/config.pkl
--hkrc <PATH>	the XDG or project-local config path
UserConfig.pkl	Config.pkl
environment { ... }	env { ... }
hk generate	hk init
HK_PKL_BACKEND	remove it; hk always uses its built-in pklr evaluator

Removed v1 entry points will produce targeted migration errors rather than failing without context.

Implementation

The implementation is split across a few stacked PRs, which are intended to merge in this order:

1. #1253 — feat(builtins)!: expose configurable builtin factories
2. #1255 — feat(config)!: add shared top-level steps
3. #1256 — feat(hook)!: make staging contextual
4. #1257 — refactor(config)!: remove deprecated v1 interfaces
5. #1270 — refactor(config)!: remove pkl CLI fallback

hk install --legacy will remain supported because it controls Git-hook installation compatibility, not v1 configuration compatibility.

If you use hk today, please share your thoughts below. Feedback on the proposed syntax, migration pain points, error messages, or anything else that would make this transition friendlier would be especially helpful.

Release sequencing

For maintainers: all breaking PRs should merge in order before the release-plz v2 release PR. Feature branches will not set 2.0.0; release-plz will derive the major release from the Conventional Commit ! titles.

AI-assisted — Tool: Codex; model: unavailable/unavailable; version: unavailable.

[risu729]

I maintain a shared Pkl preset (risu729/hk-config) that wraps the builtins catalog for my repos, and migrated it against the branch schemas to see how the changes hold up in practice: risu729/hk-config#83. Overall the direction is great — the implicit check/fix/pre-commit hooks matched the hook boilerplate my preset generated (including stash = git on pre-commit) so exactly that I could delete the helper that existed only to produce it. Findings, each checked against the branch code:

Bug: top-level steps rejects builtin factories

Introduced in #1255: top-level steps is typed Mapping<String, Step | Group> while Hook.steps and Group.steps in the same file use StepDefinition. So the headline example fails typecheck:

steps {
  ["prettier"] = Builtins.prettier // Expected value of type `Step | Group`, but got type `Builtins#Prettier`
}

Reproduced by evaluating a config against pkl/Config.pkl from refactor/remove-v1-interfaces plus a Builtins.pkl stub in the generated factory shape. steps: Mapping<String, StepDefinition | Group> fixes it.

Overlook: migration hints don't cover the renamed builtin factories

The hint mechanism in config.rs (scanning the config source and Pkl stderr on eval failure) gives targeted guidance for check_byte_order_marker/fix_byte_order_marker, UserConfig.pkl, Types.Regex, etc. — but not for gitleaks_staged, knip_strict, pinact_v3, or pinact_update_v3, the four renames this discussion announces. Those currently surface as a bare Pkl "Cannot find property" error. Adding them to the hint list (with the factory-option replacement, e.g. (Builtins.gitleaks) { staged = true }) would make test/v2_migration_errors.bats coverage match the announcement.

Small builtin fix while breaking anyway: pinact glob misses root action.yml

pinact's glob = List(".github/workflows/*", "*/action.*"): since step globs are built without literal_separator, * crosses directories and nested metadata like .github/actions/setup/action.yml already matches — but a root-level action.yml (standalone action repos) never does, because the pattern requires a / before action.. **/action.* covers both.

Suggestion: a convention for strictness options

knip.strict and pinact.version establish factory options nicely. It would help preset authors if common strictness toggles became factory options too (e.g. zizmor --pedantic, hadolint --failure-threshold): today the only way to get them is replacing the command under step { … }, which also downgrades the v2 structured CommandSpec (argv + effect metadata) back to an opaque shell string. A loose convention — strict: Boolean wherever the tool has a pedantic/strict mode — would keep those overrides declarative and preserve the effect metadata.

Docs suggestion

The factory-option + step { … } interaction is the main thing preset authors will reach for, e.g.:

["pinact"] = (Builtins.pinact) {
  version = "3"
  step { glob = List(".github/workflows/*", "**/action.*") }
}

I verified Pkl's late binding makes the step amend apply on top of the version-selected step, but that's non-obvious enough to deserve an explicit example in the migration doc.

AI-assisted — Tool: Claude Code; model: anthropic/claude-fable-5; version: 2.1.241.

[risu729]

I'm sorry, I didn't mean to post this. They're just nitpicks, and I don't think they will affect the design. I'll create a PR later for the pinact point, but the others don't need fixes right now.

Aside from them, what do you think about dropping Apple pkl CLI support? I don't think we need it, maybe for testing, but not for users.

[jdx]

we could probably drop it

[EgoMaw]

I think top level steps can introduce some confusion if its not clearly conveyed what hooks they create.

Builtins having options instead of duplicating them for specific flows is a welcomed change.
And to expand further, would that open the road for passing our own arguments over whatever the builtin currently passes, in the future?

[jdx]

I think top level steps can introduce some confusion if its not clearly conveyed what hooks they create.

this is mostly sugar to permit simpler configs. I'm still unsure myself since it might just be sweeping complexity under the rug.

Builtins having options instead of duplicating them for specific flows is a welcomed change.

yeah, the builtin function change is the biggest change here and also probably the most necessary. We've started to add variants like _v3 and _staged but the second we want more than 1 option that model is going to fall over since _v3_staged is going to cause obvious problems. That hasn't occurred yet but it's obvious to me it will happen.

And to expand further, would that open the road for passing our own arguments over whatever the builtin currently passes, in the future?

yes but you don't need this change for that, you could write your own pkl to do that today