hk

Unlike other tools (like lefthook in parallel mode, which can suffer from race conditions when linters touch overlapping files), hk runs linters in parallel safely by using file-level read/write locks.

hk avoids write locks and race conditions through several mechanisms depending on the linter:

This coordination allows hk to handle overlapping globs (e.g., a linter targeting *.js and another targeting **/*) without the corruption or race conditions seen in tools that lack file-level coordination.

A Group is a collection of steps executed in parallel. It acts as a synchronization point: all steps in the group must finish before subsequent steps or groups can start.

Note: Groups are a simple way to manage order, but for complex dependencies, use read/write locks or the depends property.

Group Inheritance

Steps inside a group inherit certain settings from the group if they do not define them themselves. Values are overridden, not merged.

hooks {
    ["pre-commit"] {
        steps {
            ["build"] = new Group {
                steps = new Mapping<String, Step> {
                    ["ts"] = new Step { fix = "tsc -b" }
                    ["rs"] = new Step { fix = "cargo build" }
                }
            }
            ["lint"] = new Group {
                steps = new Mapping<String, Step> {
                    ["prettier"] = new Step { check = "prettier --check {{files}}" }
                    ["eslint"] = new Step { check = "eslint {{files}}" }
                }
            }
        }
    }
}

Unlike pre-commit or prek, which download and execute code from external third-party git repositories, hk uses a local, transparent plugin model based on Pkl configuration.

hk builtins are hosted within the hk repository as Pkl files. When you use a builtin, you are importing a configuration that defines how to invoke linters already installed on your system. This allows you to audit exactly what a hook does by reading its Pkl definition.

Example of a Pkl builtin definition:

// This is an entire hk builtin.
prettier = new Config.Step {
  glob = List("**/*.js", "**/*.ts", "**/*.css", "**/*.json", "**/*.md")
  check = "prettier --check {{ files }}"
  check_list_files = "prettier --list-different {{ files }}"
  fix = "prettier --write {{ files }}"
}

// This is an entire hk builtin. That's it.
prettier = new Config.Step {
  glob = List("**/*.js", "**/*.ts", "**/*.css", "**/*.json", "**/*.md")
  check = "prettier --check {{ files }}"
  check_list_files = "prettier --list-different {{ files }}"
  fix = "prettier --write {{ files }}"
}

Unlike many hook managers that run tasks sequentially or risk race conditions during parallel execution, hk uses a file-level read/write locking mechanism. This allows multiple linters to run in parallel safely.

• Read Locks: Used when a linter only checks files without modifying them (e.g., using --list-different or --diff modes).
• Write Locks: An exclusive lock is acquired when a linter needs to modify files (e.g., prettier --write).
• Optimization: hk avoids unnecessary write locks by leveraging linter capabilities like ruff --diff or prettier --list-different. If a linter lacks these capabilities (like eslint), hk falls back to a write lock on all its targeted files, while other linters targeting different files continue to run in parallel.
• check_first feature: For linters that don't support diff/list modes, you can use check_first to run a check first, and only run the fix command if the check fails.