hk

https://hk.jdx.dev/
Admin
hk is a fast, powerful, and flexible git hook manager for modern development workflows with...
Tokens:27,209
Snippets:315
Trust Score:7.3
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install hk CLI

Source: https://hk.jdx.dev/getting_started

Methods to install the hk tool using various package managers or source compilation.

```shell
mise use hk pkl
hk --version
```

```shell
cargo install hk
```

```shell
brew install hk
```

```shell
aqua g -i jdx/hk
```

--------------------------------

### Initialize hk Project

Source: https://hk.jdx.dev/getting_started

Generates a default hk.pkl configuration file in the root of the current repository.

```shell
hk init
```

--------------------------------

### Install and Run Hooks

Source: https://hk.jdx.dev/getting_started

Commands to register hooks into the git repository and manually trigger specific hooks.

```shell
hk install
```

```shell
hk run pre-commit
```

--------------------------------

### Define hooks and linters in hk.pkl

Source: https://hk.jdx.dev/getting_started

Example configuration file using Pkl to define linters like eslint and prettier, and hook stages like pre-commit.

```pkl
amends "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Config.pkl"
import "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Builtins.pkl"

local linters = new Mapping<String, Step> {
    ["eslint"] {
        glob = List("*.js", "*.ts")
        check = "eslint {{files}}"
    }
    ["prettier"] = Builtins.prettier
    ["prettier-yaml"] = (Builtins.prettier) {
        glob = List("*.yaml", "*.yml")
    }
}

hooks {
    ["pre-commit"] {
        fix = true
        stash = "git"
        steps {
            ["prelint"] {
                check = "mise run prelint"
                exclusive = true
            }
            ...linters
            ["postlint"] {
                check = "mise run postlint"
                exclusive = true
            }
        }
    }
}
```

--------------------------------

### Install pkl CLI via mise

Source: https://hk.jdx.dev/pkl_introduction.html

Command to install the pkl CLI tool globally using the mise version manager.

```shell
mise use -g pkl
```

--------------------------------

### Basic hk.pkl Configuration Example

Source: https://hk.jdx.dev/configuration.html

This example demonstrates a basic `hk.pkl` file structure. It imports the base configuration, defines custom linters using a mapping, and sets up pre-commit and pre-push hooks. The `amends` directive is crucial for extending the base configuration.

```pkl
amends "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Config.pkl"
import "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Builtins.pkl"

local linters = new Mapping<String, Step> {
    // linters can be manually defined
    ["eslint"] {
        // the files to run the linter on, if no files are matched, the linter will be skipped
        // this will filter the staged files and return the subset matching these globs
        glob = List("*.js", "*.ts")
        // the command to run that makes no changes
        check = "eslint {{files}}"
        // the command to run that fixes the files (used by default)
        fix = "eslint --fix {{files}}"
        // optional: files matching these globs will be staged after fix modifies them
        // defaults to the step's glob when staging is enabled, so usually not needed
        // stage = List("*.js", "*.ts")
    }
    // linters can also be specified with the Builtins pkl library
    ["prettier"] = Builtins.prettier
}

hooks {
    ["pre-commit"] {
        fix = true       // runs the fix step to make modifications
        stash = "git"    // stashes unstaged changes before running fix steps
        steps = linters
    }
    ["pre-push"] {
        steps = linters
    }
    // "fix" and "check" are special steps for `hk fix` and `hk check` commands
    ["fix"] {
        fix = true
        steps = linters
    }
    ["check"] {
        steps = linters
        // optional: run a report after the hook finishes; HK_REPORT_JSON contains timing JSON
        report = #"node scripts/upload-timings.js <<<\"$HK_REPORT_JSON\""
    }
}

```

--------------------------------

### Define pkl mappings

Source: https://hk.jdx.dev/pkl_introduction.html

Example of creating a mapping (key-value pairs) in pkl.

```pkl
my_mapping = new Mapping<String, String> {
  ["key"] = "value"
}
```

--------------------------------

### Initialize and Install hk with mise

Source: https://hk.jdx.dev/mise_integration.html

Commands to initialize a project with mise support or install hooks that utilize mise for environment execution. These commands ensure tools are correctly managed and accessible within the hook execution context.

```shell
export HK_MISE=1
hk init --mise
hk install --mise
```

--------------------------------

### Debugging Configuration and Git Hooks

Source: https://hk.jdx.dev/logging.html

Examples for troubleshooting configuration loading, dry-run validation, and git hook execution issues.

```bash
# Validate configuration with verbose output
hk validate -v

# Check which steps would run
HK_LOG=debug hk check --dry-run

# Test hooks directly with debug output
HK_LOG=debug hk run pre-commit

# Check hook installation
hk install --verbose
```

--------------------------------

### Define basic pkl types

Source: https://hk.jdx.dev/pkl_introduction.html

Examples of defining basic data types in pkl, including strings, numbers, booleans, and lists.

```pkl
my_string = "hello"
my_number = 1
my_boolean = true
list_of_strings = List("a", "b", "c")
```

--------------------------------

### Define Step Tests with Lifecycle Hooks

Source: https://hk.jdx.dev/configuration.html

Shows how to define self-contained tests for steps, including setup via 'write' or 'before' hooks, execution modes, and validation using 'expect' and 'after' hooks.

```pkl
hooks {
  ["check"] {
    steps {
      ["prettier"] {
        check = "prettier --check {{ files }}"
        fix = "prettier --write {{ files }}"
        tests {
          ["formats json via fix"] {
            run = "fix"
            write { ["{{tmp}}/a.json"] = "{\"b\":1}" }
            expect { files { ["{{tmp}}/a.json"] = "{\n  \"b\": 1\n}\n" } }
          }
          ["check shows output"] {
            run = "check"
            files = List("{{tmp}}/a.json")
            env { ["FOO"] = "bar" }
            expect { stdout = "prettier" }
          }
          ["before generates file, after verifies contents"] {
            run = "fix"
            before = #"printf '{"b":1}' > {{tmp}}/raw.json"#
            files = List("{{tmp}}/raw.json")
            after = #"grep -q '"b": 1' {{tmp}}/raw.json"#
            expect { files { ["{{tmp}}/raw.json"] = "{\n  \"b\": 1\n}\n" } }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Execute HK Tests via CLI

Source: https://hk.jdx.dev/configuration.html

Provides common command-line interface examples for running, filtering, and listing tests within the HK framework.

```bash
hk test                 # all tests
hk test --step prettier # only prettier's tests
hk test --name formats json via fix
hk test --list          # list without running
```

--------------------------------

### Configure Step Exclusivity

Source: https://hk.jdx.dev/configuration.html

When set to true, the step waits for all previous steps to finish before starting, effectively isolating the execution.

```pkl
hooks {
    ["pre-commit"] {
        steps {
            ["prelint"] {
                exclusive = true
                check = "mise run prelint"
            }
            ["postlint"] {
                exclusive = true
                check = "mise run postlint"
            }
        }
    }
}
```

--------------------------------

### Skip Steps and Hooks in Bash

Source: https://hk.jdx.dev/glossary.html

Provides examples for bypassing specific steps or entire hooks during execution using environment variables.

```bash
# Skip specific steps
HK_SKIP_STEPS=lint,test hk run pre-commit

# Skip entire hooks
HK_SKIP_HOOK=pre-commit,pre-push git commit
```

--------------------------------

### Configure Global Hooks and Linters with hkrc

Source: https://hk.jdx.dev/configuration.html

Example of defining global linters and hooks in the hkrc configuration file, which are merged into project-level configurations.

```pkl
amends "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Config.pkl"
import "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Builtins.pkl"

local linters {
    ["prettier"] = Builtins.prettier
    ["eslint"] {
        glob = List("*.js", "*.ts")
        check = "eslint {{files}}"
        fix = "eslint --fix {{files}}"
    }
}

hooks {
    ["pre-commit"] {
        fix = true
        steps = linters
    }
}
```

--------------------------------

### Configure Monorepo Linting and Hooks with Pkl

Source: https://hk.jdx.dev/reference/examples/monorepo.html

This Pkl configuration defines groups for frontend, backend, and infrastructure tasks, applying specific linters and formatters to each. It demonstrates how to use shared mappings and hooks to automate pre-commit and check workflows across a multi-language project.

```pkl
amends "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Config.pkl"
import "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Builtins.pkl"

local frontend = new Group {
  steps {
    ["prettier"] = (Builtins.prettier) {
      dir = "frontend"
      batch = true
    }
    ["eslint"] = (Builtins.eslint) {
      dir = "frontend"
      batch = true
    }
    ["stylelint"] = (Builtins.stylelint) {
      glob = List("frontend/**/*.css", "frontend/**/*.scss")
    }
  }
}

local backend = new Group {
  steps {
    ["cargo_fmt"] = (Builtins.cargo_fmt) {
      workspace_indicator = "Cargo.toml"
      dir = "backend"
    }
    ["cargo_clippy"] = (Builtins.cargo_clippy) {
      workspace_indicator = "Cargo.toml"
      dir = "backend"
    }
    ["cargo_check"] = (Builtins.cargo_check) {
      dir = "backend"
      profiles = List("ci", "full")
    }
  }
}

local infrastructure = new Group {
  steps {
    ["terraform"] = (Builtins.terraform) {
      glob = List("infrastructure/**/*.tf")
    }
    ["tflint"] = (Builtins.tf_lint) {
      glob = List("infrastructure/**/*.tf")
    }
  }
}

local shared = new Mapping<String, Step> {
  ["markdown"] = (Builtins.markdown_lint) {
    glob = List("**/*.md")
    exclude = List("**/node_modules/**", "**/target/**")
  }
  ["yaml"] = (Builtins.yamllint) {
    glob = List("**/*.yaml", "**/*.yml")
    exclude = List("**/node_modules/**")
  }
}

hooks {
  ["pre-commit"] {
    fix = true
    stash = "git"
    steps {
      ["frontend"] = frontend
      ["backend"] = backend
      ["infrastructure"] = infrastructure
      ...shared
    }
  }
  ["check"] {
    steps {
      ["frontend"] = frontend
      ["backend"] = backend
      ["infrastructure"] = infrastructure
      ...shared
    }
  }
}
```

--------------------------------

### hk.local.pkl for Local Overrides

Source: https://hk.jdx.dev/configuration.html

This example shows how to use `hk.local.pkl` to override or extend configurations defined in the main `hk.pkl`. It assumes the `hk.pkl` is in the same directory and uses `amends` to apply local changes, such as adding a custom step to the pre-commit hook.

```pkl
amends "./hk.pkl"
import "./hk.pkl" as repo_config

hooks = (repo_config.hooks) {
    ["pre-commit"] {
        (steps) {
            ["custom-step"] = new Step {
                // ...
            }
        }
    }
}

```

--------------------------------

### Configuring Warning Categories in hk.pkl (Pkl)

Source: https://hk.jdx.dev/environment_variables.html

Illustrates how to opt-in to specific warning categories within the hk configuration file (hk.pkl or .hkrc.pkl). This example shows how to enable 'missing-profiles' warnings.

```pkl
warnings = List("missing-profiles")
```

--------------------------------

### Specify Files for Steps using Glob Patterns

Source: https://hk.jdx.dev/configuration.html

Defines the files a specific step should operate on using glob patterns, single patterns, or regular expressions. If no patterns are provided, the step runs unconditionally. Examples show list of globs, single glob, and regex for file matching.

```pkl
// Glob patterns
["prettier"] {
    glob = List("*.js", "*.ts")
    check = "prettier --check {{files}}"
}

// Single glob pattern
["eslint"] {
    glob = "*.js"
    check = "eslint {{files}}"
}

// Regex pattern for complex matching
["config-lint"] {
    glob = Types.Regex(#"^(config|settings).*\.(json|yaml|yml)$"#)
    check = "config-lint {{files}}"
}
```

--------------------------------

### Enable Mise Integration

Source: https://hk.jdx.dev/configuration.html

Enables deep integration with `mise` for tool management. When active, `hk install` uses `mise x` for hook execution, `hk init` creates a `mise.toml` file, and tool discovery automatically uses `mise` shims.

```shell
# Enable mise integration
export HK_MISE=true
```

--------------------------------

### Define Check Command for Steps

Source: https://hk.jdx.dev/configuration.html

Specifies a command to run for checking files without modifying them. This command should return a non-zero exit code if errors are found. Examples show a simple string command and a `Script` object for OS-specific commands.

```pkl
hooks {
    ["pre-commit"] {
        ["prettier"] {
            check = "prettier --check {{files}}"
        }
    }
}

If you want to use a different check command for different operating systems, you can define a Script instead of a String:
pkl
hooks {
    ["pre-commit"] {
        ["prettier"] {
            check = new Script {
                linux = "prettier --check {{files}}"
                macos = "prettier --check {{files}}"
                windows = "prettier --check {{files}}"
                other = "prettier --check {{files}}"
            }
        }
    }
}
```

--------------------------------

### Define Hooks in Pkl

Source: https://hk.jdx.dev/glossary.html

Configures git hooks or custom commands to trigger a collection of steps. This example shows a pre-commit hook with auto-fixing and stashing enabled.

```pkl
hooks {
  ["pre-commit"] {
    fix = true
    stash = "git"
    steps = linters
  }
}
```

--------------------------------

### Define Environment Variables in mise.toml

Source: https://hk.jdx.dev/mise_integration.html

Example of defining environment variables within a mise.toml file to be utilized by hooks. This provides a centralized way to manage configuration settings for project tasks.

```toml
[env]
PRETTIER_CONFIG = ".prettierrc.json"
```

--------------------------------

### Filter Step Files by Type

Source: https://hk.jdx.dev/configuration.html

Filters files for a step based on their type (e.g., 'python', 'shell', 'json') using extension, shebang, or content detection. This allows for more precise filtering than globs alone. Examples show matching by single type, multiple types, and combining with glob patterns.

```pkl
// Match Python files by extension AND shebang (including extensionless scripts)
["black"] {
    types = List("python")
    fix = "black {{files}}"
}

// Match shell scripts by extension or shebang
["shellcheck"] {
    types = List("shell")
    check = "shellcheck {{files}}"
}

// Match multiple types (OR logic)
["format-scripts"] {
    types = List("python", "shell", "ruby")
    fix = "format-script {{files}}"
}

// Combine types with glob patterns for more precise filtering
["format-src-python"] {
    glob = "src/**/*"  // Only files in src/
    types = List("python")  // That are Python files
    fix = "black {{files}}"
}
```

--------------------------------

### Use local variables and classes

Source: https://hk.jdx.dev/pkl_introduction.html

Shows how to define local variables to avoid exporting unexpected fields and how to instantiate classes provided by the configuration.

```pkl
local my_step = new LinterStep {
  check = "make lint"
}
```

--------------------------------

### Define pkl lists and listings

Source: https://hk.jdx.dev/pkl_introduction.html

Demonstrates the difference between simple lists and complex listings for structured collections.

```pkl
my_list = List("a", "b", "c")

my_listing = new Listing<Step> {
  new LinterStep {
    check = "make lint"
  }
  new LinterStep {
    check = "make format"
  }
}
```

--------------------------------

### PKL Imports

Source: https://hk.jdx.dev/pkl_introduction.html

Illustrates how to import code from other PKL files, both local and remote. This allows for code sharing and modularity across different configuration files.

```pkl
import "./extra.pkl"
# do something with `extra`

import "https://example.com/remote.pkl"
# do something with `remote`
```

--------------------------------

### Evaluate pkl configuration

Source: https://hk.jdx.dev/pkl_introduction.html

Command to evaluate a pkl file and output the resulting configuration structure, useful for debugging.

```shell
pkl eval hk.pkl
```

--------------------------------

### Configure hk via Git

Source: https://hk.jdx.dev/configuration.html

Demonstrates how to manage hk settings using git config, including setting parallel jobs, disabling fail-fast, and managing list-based configurations like profiles and exclude patterns.

```bash
# Set number of parallel jobs
git config --local hk.jobs 5

# Disable fail-fast behavior
git config --local hk.failFast false

# Add profiles
git config --local hk.profile slow
git config --local --add hk.profile fast

# Add exclude patterns (union semantics)
git config --local hk.exclude "node_modules"
git config --local --add hk.exclude "**/*.min.js"

# Skip specific steps
git config --local hk.skipSteps "slow-test,flaky-test"

# Skip entire hooks
git config --local hk.skipHook "pre-push"

# Configure warnings
git config --local hk.warnings "missing-profiles"
git config --local hk.hideWarnings "missing-profiles"
```

--------------------------------

### Format Nixpkgs with nixpkgs-fmt

Source: https://hk.jdx.dev/builtins.html

Formats Nix expressions used in Nixpkgs according to the Nixpkgs style guide. It can check for formatting compliance or format files.

```shell
nixpkgs-fmt --check {{ files }}
```

```shell
nixpkgs-fmt {{ files }}
```

--------------------------------

### Lint Python with Flake8

Source: https://hk.jdx.dev/builtins.html

Uses Flake8 to check Python code for style guide violations and programming errors. It combines PyFlakes, pycodestyle, and McCabe.

```shell
flake8 {{ files }}
```

--------------------------------

### PKL Comments

Source: https://hk.jdx.dev/pkl_introduction.html

Demonstrates different ways to add comments in PKL files. Includes single-line, multi-line, and documentation comments. These comments are ignored by the PKL interpreter.

```pkl
// This is a comment
/*
This is a multi-line comment
*/
/// This is a doc comment (not used by hk at least today)
```

--------------------------------

### Suppressing Warnings with HK_HIDE_WARNINGS (Bash)

Source: https://hk.jdx.dev/environment_variables.html

Shows how to use the HK_HIDE_WARNINGS environment variable to suppress specific warning messages during hk execution. This example demonstrates hiding 'missing-profiles' warnings.

```bash
HK_HIDE_WARNINGS=missing-profiles hk check
```

--------------------------------

### Define Custom Linters and Hooks in Pkl

Source: https://hk.jdx.dev/reference/examples/custom-linters.html

Demonstrates how to define custom linting steps including SQL formatters, platform-specific security scanners, and workspace-aware build tools. It also shows how to integrate these custom steps with built-in linters and configure pre-commit hooks.

```pkl
amends "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Config.pkl"
import "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Builtins.pkl"

local custom_linters = new Mapping<String, Step> {
  ["sql_formatter"] {
    glob = List("**/*.sql")
    exclude = List("**/migrations/**")
    check = "sql-formatter --check {{files}}"
    fix = "sql-formatter --write {{files}}"
    batch = true
  }

  ["security_scan"] {
    check = new Script {
      linux = "security-scanner-linux --scan {{files}}"
      macos = "security-scanner-mac --scan {{files}}"
      windows = "security-scanner.exe /scan {{files}}"
    }
    condition = "test -f .security-config.yml"
    exclusive = true
  }

  ["custom_build"] {
    workspace_indicator = "build.toml"
    check = "cd {{workspace}} && custom-build check"
    fix = "cd {{workspace}} && custom-build fix"
    check_diff = "cd {{workspace}} && custom-build diff"
  }

  ["migrate"] {
    glob = List("**/migrations/*.sql")
    check = "migrate validate {{files}}"
    fix = "migrate apply {{files}}"
    interactive = true
  }

  ["custom_validator"] {
    glob = List("**/*.custom")
    check = "validator {{files}}"
    fix = "validator --fix {{files}}"

    tests {
      ["validates correct syntax"] {
        run = "check"
        write {
          ["{{tmp}}/test.custom"] = #"valid content"#
        }
        files = List("{{tmp}}/test.custom")
        expect {
          code = 0
        }
      }
    }
  }
}

hooks {
  ["pre-commit"] {
    fix = true
    stash = "patch-file"
    steps = custom_linters
  }
}
```

--------------------------------

### Configure hk via Pkl

Source: https://hk.jdx.dev/configuration.html

Shows how to define user-specific defaults in the ~/.config/hk/config.pkl file using the Pkl configuration language.

```pkl
amends "package://github.com/jdx/hk/releases/latest/hk#/Config.pkl"

jobs = 4
fail_fast = false
exclude = List("node_modules", "dist", "build")
skip_steps = List("slow-test")
skip_hooks = List("pre-push")
```

--------------------------------

### Configure Step Environment Variables

Source: https://hk.jdx.dev/configuration.html

Demonstrates how to define environment variables for a specific step using a Pkl Mapping. These variables are merged with global environment settings during execution.

```pkl
local linters = new Mapping<String, Step> {
    ["prettier"] {
        env {
            ["NODE_ENV"] = "production"
        }
    }
}
```

--------------------------------

### Tool Configuration and Customization via Pkl

Source: https://hk.jdx.dev/builtins.html

Demonstrates how to configure built-in tools by overriding properties, adding dependencies, setting workspace indicators, and defining custom linting/formatting steps.

```pkl
["prettier"] = (Builtins.prettier) {
  glob = List("src/**/*.js", "src/**/*.ts")
  batch = false
  env {
    ["PRETTIER_CONFIG"] = ".prettierrc.json"
  }
}

["eslint"] = (Builtins.eslint) {
  depends = "prettier"
}

["cargo_clippy"] = (Builtins.cargo_clippy) {
  workspace_indicator = "Cargo.toml"
  check = "cargo clippy --manifest-path {{workspace}}/Cargo.toml"
}

["mypy"] = (Builtins.mypy) {
  profiles = List("python")
}

["custom-tool"] {
  glob = List("*.custom")
  check = "custom-tool --check {{files}}"
  fix = "custom-tool --fix {{files}}"
  batch = true
}
```

--------------------------------

### Define Hook Environment Variables (.env)

Source: https://hk.jdx.dev/configuration.html

Maps environment variables for a specific hook. These variables are merged into each step's environment, with step-level variables taking precedence. Example shows setting HK_PROFILES for a pre-push hook.

```pkl
hooks {
  ["pre-push"] {
    env {
      ["HK_PROFILES"] = "types"
    }
    steps = linters
  }
}
```

--------------------------------

### Amend pkl objects

Source: https://hk.jdx.dev/pkl_introduction.html

Demonstrates how to reuse and modify (amend) existing objects in pkl to reduce duplication.

```pkl
local make_lint = new LinterStep {
  check = "make lint"
}
local linters = new Mapping<String, Step> {
  ["make-lint"] = (make_lint) {
    dir = "proj_a"
  }
  ["make-lint"] = (make_lint) {
    dir = "proj_b"
  }
}
```

--------------------------------

### Generate Performance Timing Reports

Source: https://hk.jdx.dev/logging.html

Demonstrates how to generate and view performance timing reports in JSON format to identify bottlenecks in execution steps.

```bash
# Write timing report to a file
HK_TIMING_JSON=/tmp/timing.json hk check

# View the report
cat /tmp/timing.json | jq .
```

--------------------------------

### Enable Tracing and Performance Diagnostics

Source: https://hk.jdx.dev/logging.html

Shows how to enable tracing for execution analysis, including outputting to JSONL format for programmatic processing.

```bash
# Enable tracing with console output
hk check --trace

# Enable tracing via environment variable
HK_TRACE=1 hk check

# Enable tracing with JSON output
HK_TRACE=json hk check > trace.jsonl
hk check --trace --json > trace.jsonl
```

--------------------------------

### Configure Hook Failure on Fixes (fail_on_fix)

Source: https://hk.jdx.dev/configuration.html

Determines if a hook should fail when fix commands modify files. Defaults to false. Setting this to true is useful for pre-commit hooks to allow fixes but block commits for manual review. Example shows fail_on_fix set to true for a pre-commit hook.

```pkl
hooks {
  ["pre-commit"] {
    fix = true
    stage = false
    fail_on_fix = true
    steps = linters
  }
}
```

--------------------------------

### Configure File Exclusion Patterns in Pkl

Source: https://hk.jdx.dev/configuration.html

Demonstrates how to define global exclude patterns using strings, lists, or regex to skip specific files or directories during processing.

```pkl
// Exclude specific directories
exclude = List("node_modules", "dist", "build")

// Exclude using glob patterns
exclude = List("**/*.min.js", "**/*.map", "**/vendor/**")

// Single pattern
exclude = "node_modules"

// Exclude using regex pattern (for complex matching)
exclude = Regex(#".*\.(test|spec)\.(js|ts)$"#)
```

--------------------------------

### Configure commit-msg hook to validate commit message format

Source: https://hk.jdx.dev/hooks.html

This PKL configuration sets up the 'commit-msg' hook. It includes a 'validate-commit-msg' step that uses 'grep' to check if the commit message starts with a valid prefix (e.g., 'fix:', 'feat:', 'chore:'). If the format is invalid, the command exits with a status code of 1, failing the commit.

```pkl
hooks {
    ["commit-msg"] {
        steps {
            ["validate-commit-msg"] {
                check = "grep -q '^(fix|feat|chore):' {{commit_msg_file}} || exit 1"
            }
        }
    }
}
```

--------------------------------

### `hk run pre-commit` Command

Source: https://hk.jdx.dev/cli/run/pre-commit.html

Sets up git hooks to run hk on specified files or all files. Supports various flags for controlling the execution, such as checking, fixing, excluding, and staging.

```APIDOC
## `hk run pre-commit` Command

### Description
Sets up git hooks to run hk on specified files or all files. Supports various flags for controlling the execution, such as checking, fixing, excluding, and staging.

### Method
`RUN` (This is a command-line tool, not a typical HTTP method)

### Endpoint
`hk run pre-commit [FLAGS] [FILES]…`

### Arguments
#### `[FILES]…`
* **Type**: string array
* **Description**: Run on specific files.

### Flags
#### `-a, --all`
* **Type**: boolean
* **Description**: Run on all files instead of just staged files.

#### `-c, --check`
* **Type**: boolean
* **Description**: Run check command instead of fix command.

#### `-e, --exclude <EXCLUDE>`
* **Type**: string array
* **Description**: Exclude files that otherwise would have been selected.

#### `-f, --fix`
* **Type**: boolean
* **Description**: Run fix command instead of check command (this is the default behavior unless HK_FIX=0).

#### `-g, --glob <GLOB>`
* **Type**: string array
* **Description**: Run on files that match these glob patterns.

#### `-P, --plan`
* **Type**: boolean
* **Description**: Print the plan instead of running the hook.

#### `-S, --step <STEP>`
* **Type**: string array
* **Description**: Run only specific step(s).

#### `--fail-fast`
* **Type**: boolean
* **Description**: Abort on first failure.

#### `--from-ref <FROM_REF>`
* **Type**: string
* **Description**: Start reference for checking files (requires --to-ref).

#### `--no-fail-fast`
* **Type**: boolean
* **Description**: Continue on failures (opposite of --fail-fast).

#### `--no-stage`
* **Type**: boolean
* **Description**: Disable auto-staging of fixed files.

#### `--pr`
* **Type**: boolean
* **Description**: Check only files changed in the current PR/branch (shortcut for --from-ref DEFAULT_BRANCH --to-ref HEAD).

#### `--skip-step <STEP>`
* **Type**: string array
* **Description**: Skip specific step(s).

#### `--stage`
* **Type**: boolean
* **Description**: Enable auto-staging of fixed files.

#### `--stash <STASH>`
* **Type**: string
* **Description**: Stash method to use for git hooks.
* **Choices**: `git`, `patch-file`, `none`

#### `--stats`
* **Type**: boolean
* **Description**: Display statistics about files matching each step.

#### `--to-ref <TO_REF>`
* **Type**: string
* **Description**: End reference for checking files (requires --from-ref).

### Request Example
```bash
hk run pre-commit --all --fix
```

### Response
(This command typically provides output to the console indicating the status of the pre-commit hooks, rather than a structured JSON response.)

#### Success Response
(Output indicating successful execution of pre-commit hooks or no issues found.)

#### Response Example
```text
Running pre-commit hooks...
All checks passed.
```
```

--------------------------------

### CLI Command: hk run

Source: https://hk.jdx.dev/cli/run.html

Executes a hook with specified flags and subcommands to manage file processing, linting, or git hooks.

```APIDOC
## [CLI] hk run

### Description
Runs a hook based on the provided subcommand and flags. It supports running on specific files, glob patterns, or git-based references.

### Method
CLI Execution

### Endpoint
hk run [FLAGS] [FILES]… <SUBCOMMAND>

### Parameters
#### Arguments
- **[FILES]** (list) - Optional - Run on specific files.

#### Flags
- **-a, --all** (boolean) - Optional - Run on all files instead of just staged files.
- **-c, --check** (boolean) - Optional - Run check command instead of fix command.
- **-e, --exclude** (string) - Optional - Exclude files that otherwise would have been selected.
- **-f, --fix** (boolean) - Optional - Run fix command instead of check command.
- **-g, --glob** (string) - Optional - Run on files that match these glob patterns.
- **-P, --plan** (boolean) - Optional - Print the plan instead of running the hook.
- **-S, --step** (string) - Optional - Run only specific step(s).
- **--fail-fast** (boolean) - Optional - Abort on first failure.
- **--stash** (string) - Optional - Stash method to use (Choices: git, patch-file, none).

### Subcommands
- **commit-msg** - Run commit-msg hook.
- **pre-commit** - Run pre-commit hook.
- **pre-push** - Run pre-push hook.
- **prepare-commit-msg** - Run prepare-commit-msg hook.

### Request Example
hk run --fix --all pre-commit

### Response
#### Success Response (0)
- **stdout** (string) - Execution output and statistics.
```

--------------------------------

### Configure Log File Output

Source: https://hk.jdx.dev/logging.html

Explains how to redirect logs to a specific file path and set a dedicated log level for file output using environment variables.

```bash
# Change the log file location
HK_LOG_FILE=/tmp/my-hk.log hk check

# Set a different log level for the file
HK_LOG_FILE_LEVEL=trace hk check
```

--------------------------------

### Enable plain text summary output

Source: https://hk.jdx.dev/environment_variables.html

Forces the display of per-step output summaries in plain text mode. By default, these summaries are restricted to progress bar rendering modes.

```bash
HK_SUMMARY_TEXT=1 hk check
```

--------------------------------

### Format Go Code with gofumpt

Source: https://hk.jdx.dev/builtins.html

Applies a more opinionated formatting to Go source files than gofmt. It aims for stricter code style adherence.

```shell
gofumpt -w {{ files }}
```

--------------------------------

### Configure Stdin Input

Source: https://hk.jdx.dev/configuration.html

Sends template-expanded strings to the command's stdin. Useful for tools that accept file lists via stdin.

```pkl
local linters = new Mapping<String, Step> {
    ["hungry-command"] {
        stdin = " {{ files_list | join(sep='\n') }}"
        check = "xargs my-command"
    }
}
```

--------------------------------

### Organize Steps into Groups in Pkl

Source: https://hk.jdx.dev/glossary.html

Demonstrates hierarchical organization of tasks by grouping related steps together. This is useful for managing logical divisions like frontend or backend tasks.

```pkl
steps {
  ["frontend"] = new Group {
    steps {
      ["prettier"] = Builtins.prettier
      ["eslint"] = Builtins.eslint
    }
  }
}
```

--------------------------------

### Skip Specific Steps

Source: https://hk.jdx.dev/configuration.html

A list of step names to skip when running hooks. This allows bypassing specific tasks like linting or formatting. Configuration can be provided via CLI, environment variables, Git config, or Pkl files, and all sources are unioned.

```shell
# Skip steps named 'lint' and 'test'
export HK_SKIP_STEPS=lint,test

# Skip a step via CLI
# hk --skip-step lint <command>

# Skip steps via Git config
# git config hk.skipSteps "step1,step2"
```

--------------------------------

### Access Git Status in Conditions and Templates

Source: https://hk.jdx.dev/configuration.html

Demonstrates how to use the git object to filter execution based on staged file states in Pkl conditions and Tera templates.

```pkl
// Run only if there are any staged files
condition = "git.staged_files != []"

// Run only if a Cargo.toml file is staged
condition = #"any(git.staged_files, {hasSuffix(#, "Cargo.toml")})"#

// Diff-filter approximations
// Added or Renamed (AR):
condition = "(git.staged_added_files != []) || (git.staged_renamed_files != [])"

// Renamed or Deleted (RD):
condition = "(git.staged_renamed_files != []) || (git.staged_deleted_files != [])"
```

```tera
check = "echo staged: {{ git.staged_files }}"
```

--------------------------------

### Execute mise Tasks in hk.pkl

Source: https://hk.jdx.dev/mise_integration.html

Demonstrates how to invoke mise tasks within an hk.pkl configuration file. This allows developers to use mise's task runner features like dependency management and parallel execution within hook steps.

```pkl
amends "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Config.pkl"

`pre-commit` {
    ["prelint"] {
        check = "mise run prelint"
        exclusive = true
    }
}
```

--------------------------------

### Manage Execution Profiles in Pkl

Source: https://hk.jdx.dev/configuration.html

Shows how to enable or disable specific execution profiles, such as CI environments or slow tests, using list syntax.

```pkl
profiles = List("ci", "slow")
profiles = List("!slow")  // explicitly disable
```

--------------------------------

### Configure Built-in Linters in pkl

Source: https://hk.jdx.dev/builtins.html

Demonstrates how to import and apply built-in linters within an hk.pkl configuration file. It shows the standard implementation for pre-commit hooks and how to override default linter settings.

```pkl
amends "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Config.pkl"
import "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Builtins.pkl"

hooks {
  ["pre-commit"] {
    steps {
      ["prettier"] = Builtins.prettier
      ["eslint"] = Builtins.eslint
    }
  }
}
```

```pkl
["prettier"] = (Builtins.prettier) {
  batch = false  // Override the default batch setting
  glob = List("*.js", "*.ts")  // Override file patterns
}
```

--------------------------------

### Enable Batch Processing for ESLint

Source: https://hk.jdx.dev/configuration.html

Configures the 'eslint' linter to process files in batches. Setting 'batch = true' allows for parallel processing of files, which can significantly speed up linting for single-threaded tools like ESLint.

```pkl
local linters = new Mapping<String, Step> {
    ["eslint"] {
        batch = true
    }
}
```

--------------------------------

### Define Linting Steps in Pkl

Source: https://hk.jdx.dev/glossary.html

Configures an individual linting step with file globbing, check/fix commands, and dependencies. This is the fundamental unit of work in hk.

```pkl
steps {
  ["eslint"] {
    glob = List("*.js", "*.ts")
    check = "eslint {{files}}"
    fix = "eslint --fix {{files}}"
    depends = List("prettier")  // Run after prettier
  }
}
```

--------------------------------

### Set Working Directory for ESLint

Source: https://hk.jdx.dev/configuration.html

Specifies that the 'eslint' linter should run within the 'frontend' directory. This is useful when linters need to be executed from a specific subdirectory within the project structure.

```pkl
local linters = new Mapping<String, Step> {
    ["eslint"] = (Builtins.eslint) {
        dir = "frontend"
    }
}
```

--------------------------------

### Configure Output Summary

Source: https://hk.jdx.dev/configuration.html

Determines which output streams (stdout, stderr, combined, or hidden) are captured and displayed at the end of the hook run.

```pkl
hooks {
  ["check"] {
    steps {
      ["lint"] {
        check = "eslint {{files}}"
        output_summary = "combined"
      }
      ["format"] {
        check = "prettier --check {{files}}"
        output_summary = "stdout"
      }
      ["quiet-step"] {
        check = "echo noisy && echo warn 1>&2"
        output_summary = "hide"
      }
    }
  }
}
```

--------------------------------

### Dump Configuration to TOML

Source: https://hk.jdx.dev/cli/config/dump.html

Prints the merged configuration settings of the hk project in TOML format. This command aggregates settings from CLI flags, environment variables, git config, user config, and project config. Use the --format flag to specify TOML output.

```bash
hk config dump --format toml

```

--------------------------------

### Configure Step Dependencies in Pkl

Source: https://hk.jdx.dev/glossary.html

Defines how to set prerequisites for a step using the depends property. This ensures specific tasks complete before the current step executes.

```pkl
steps {
  ["typecheck"] {
    depends = List("lint", "format")  // Wait for lint and format to complete
    check = "tsc --noEmit"
  }
}
```

--------------------------------

### Define Dependency for Prettier Step

Source: https://hk.jdx.dev/configuration.html

Specifies that the 'prettier' step must complete before the 'eslint' step can run. This is managed within a 'pre-commit' hook configuration, ensuring a specific execution order for linters.

```pkl
hooks {
    ["pre-commit"] {
        steps {
            ["prettier"] {
                depends = List("eslint")
            }
        }
    }
}
```

--------------------------------

### Manage Global Hook Preferences

Source: https://hk.jdx.dev/configuration.html

Methods for adding global steps, skipping project steps via git config or environment variables, and overriding project configurations locally.

```pkl
// ~/.config/hk/config.pkl
amends "package://github.com/jdx/hk/releases/latest/hk#/Config.pkl"

hooks {
    ["pre-commit"] {
        steps {
            ["gitleaks"] { check = "gitleaks git --staged" }
        }
    }
}
```

```bash
# Skip a step permanently in this repo
git config --local hk.skipSteps "slow-linter,noisy-formatter"

# Skip for one run
HK_SKIP_STEPS=slow-linter hk run pre-commit
```

```pkl
// hk.local.pkl  (add to .gitignore)
amends "./hk.pkl"
import "./hk.pkl" as upstream

hooks = (upstream.hooks) {
    ["pre-commit"] {
        steps {
            // keep only the steps you want
            ["gitleaks"] = upstream.hooks["pre-commit"].steps["gitleaks"]
        }
    }
}
```

--------------------------------

### Lint and Format Python with Ruff

Source: https://hk.jdx.dev/builtins.html

High-performance Python linting and formatting using Ruff. Supports force-exclusion and automatic fixing.

```bash
ruff check --force-exclude {{ files }}
ruff check --force-exclude --fix {{ files }}
ruff format --quiet --force-exclude --diff {{ files }}
ruff format --quiet --force-exclude {{ files }}
```

--------------------------------

### Check Go Dependencies for Vulnerabilities with govulncheck

Source: https://hk.jdx.dev/builtins.html

Scans Go projects for known vulnerabilities in dependencies. It helps ensure the project is using secure versions of its libraries.

```shell
govulncheck {{ files }}
```

--------------------------------

### Enable Execution Tracing

Source: https://hk.jdx.dev/configuration.html

Enables performance diagnostics and tracing spans. Supports text or JSON output formats for debugging execution flow.

```bash
HK_TRACE=text hk check
```

--------------------------------

### Configure pre-commit hook with cargo-fmt and cargo-clippy

Source: https://hk.jdx.dev/hooks.html

This snippet configures the 'pre-commit' hook using PKL. It includes steps for 'cargo-fmt' and 'cargo-clippy', both set to 'check_first = true' for safety. 'cargo-fmt' checks and formats Rust code, while 'cargo-clippy' checks and fixes Rust code with specific allowances for dirty and staged files.

```pkl
hooks {
    fix = true
    ["pre-commit"] {
        steps {
            ["cargo-fmt"] {
                glob = "*.rs"
                check_first = true
                check = "cargo fmt --check"
                fix = "cargo fmt"
            }
            ["cargo-clippy"] {
                glob = "*.rs"
                check_first = true
                check = "cargo clippy"
                fix = "cargo clippy --fix --allow-dirty --allow-staged"
            }
        }
    }
}
```

--------------------------------

### Configure Log Levels via CLI and Environment Variables

Source: https://hk.jdx.dev/logging.html

Demonstrates how to adjust logging verbosity using command-line flags like -v and -vv, or by setting the HK_LOG environment variable to levels such as debug or trace.

```bash
# Show debug output
hk check -v
hk fix --verbose

# Show trace output
hk check -vv

# Set log level via environment variable
HK_LOG=debug hk check
HK_LOG=trace hk fix
export HK_LOG=debug
```

--------------------------------

### Check Nix Language with nil

Source: https://hk.jdx.dev/builtins.html

Runs diagnostics on Nix language files, specifically checking for warnings and errors. The `--deny-warnings` flag ensures that warnings are treated as failures.

```shell
nil diagnostics --deny-warnings {{ files }}
```

--------------------------------

### Setting Environment Variables in hk.pkl

Source: https://hk.jdx.dev/configuration.html

This snippet illustrates how to define environment variables within `hk.pkl` that can be used to configure linters or other tools run by hk. The `env` block allows for key-value pairs of strings.

```pkl
env {
    ["NODE_ENV"] = "production"
}

```

--------------------------------

### Inspect hk Configuration

Source: https://hk.jdx.dev/configuration.html

Provides commands to debug and view the effective configuration, including dumping all merged settings and checking source precedence.

```bash
# Show effective configuration (all sources merged)
hk config dump

# Get a specific configuration value
hk config get exclude
hk config get skip_steps

# Show configuration source precedence
hk config sources
```

--------------------------------

### Define Hooks and Stash Behavior in Pkl

Source: https://hk.jdx.dev/configuration.html

Configures individual git hooks with specific fix and stash settings, demonstrating the use of boolean shorthands and explicit mapping values.

```pkl
hooks {
  ["pre-commit"] {
    fix = true
    stash = true        // boolean shorthand for git
    steps = linters
  }

  ["fix"] {
    fix = true
    stash = "none"      // disable stashing
    steps = linters
  }
}
```

--------------------------------

### Configure Interactive Mode

Source: https://hk.jdx.dev/configuration.html

Connects stdin/stdout/stderr directly to the hk execution, implying exclusive execution.

```pkl
local linters = new Mapping<String, Step> {
    ["show-warning"] {
        interactive = true
        check = "echo warning && read -p 'Press Enter to continue'"
    }
}
```

--------------------------------

### Configure JavaScript/TypeScript development hooks using Pkl

Source: https://hk.jdx.dev/reference/examples/javascript-project.html

This Pkl configuration defines environment variables and a suite of development tools including Prettier, ESLint, and TSC. It establishes hooks for pre-commit, pre-push, and manual check/fix tasks to ensure code quality and consistency.

```pkl
amends "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Config.pkl"
import "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Builtins.pkl"

env {
  ["NODE_ENV"] = "development"
}

local linters = new Mapping<String, Step> {
  ["prettier"] = (Builtins.prettier) {
    batch = true
    depends = List("eslint")
  }
  ["eslint"] = (Builtins.eslint) {
    batch = true
  }
  ["tsc"] = (Builtins.tsc) {
    stomp = true
  }
}

hooks {
  ["pre-commit"] {
    fix = true
    stash = "git"
    steps = linters
  }
  ["pre-push"] {
    steps = linters
  }
  ["check"] {
    steps = linters
  }
  ["fix"] {
    fix = true
    steps = linters
  }
}
```

--------------------------------

### Set Prefix for ESLint Command Execution

Source: https://hk.jdx.dev/configuration.html

Configures the 'eslint' linter to be executed with a specific prefix, 'npm run'. This is useful for tools that require a specific command structure to be invoked, such as running scripts defined in a project's 'package.json'.

```pkl
local linters = new Mapping<String, Step> {
    ["eslint"] {
        prefix = "npm run"
    }
}
```

--------------------------------

### Configure File Exclusions

Source: https://hk.jdx.dev/configuration.html

Filters out specific files from a step using glob or regex patterns. Regex patterns follow Rust syntax.

```pkl
["prettier"] {
    glob = List("**/*.yaml")
    exclude = List("*.test.yaml", "*.fixture.yaml")
    check = "prettier --check {{files}}"
}

["linter"] {
    glob = List("**/*")
    exclude = Types.Regex(#"""
(?x)
^(vendor|dist|build)/.*$|
.*\.(min|bundle)\.(js|css)$|
.*\.generated\.(ts|js)$
"""#)
    check = "custom-lint {{files}}"
}
```
Tokens:
Raw