settings.toml

# HK Settings Registry
# This is an internal options registry used for codegen (not user-edited config).
# It defines all configuration options and their sources, merge policies, and documentation.

[all]
type = "bool"
default = false
sources.cli = ["--all"]
docs = """
Run on all files instead of just staged files.

When enabled, hk will run steps against all tracked files in the repository rather than only the
files currently staged in git. This is useful for running a full project-wide check or fix.

Example: `hk check --all` to check all files in the repository.
"""

[cache_dir]
type = "path"
sources.env = ["HK_CACHE_DIR"]
docs = """
Directory where hk stores cache files for improved performance.

Default location: `~/.cache/hk`

Cache includes tool binary locations, parsed configurations, and other performance optimizations.
"""

[default_branch]
type = "string"
sources.pkl = ["default_branch"]
docs = """
Specifies the preferred default branch to compare against when hk needs a reference
(e.g., suggestions in pre-commit warnings).
If unset or empty, hk attempts to detect it via `origin/HEAD`, the current branch's remote,
or falls back to `main`/`master` if they exist on the remote.

Both local branch names (e.g., `main`) and remote-qualified refs (e.g., `origin/main`) are supported.
"""

[env]
type = "map<string, string>"
sources.pkl = ["env"]
docs = """
Environment variables to set when running linter commands.

These variables are set before executing any step commands and are merged with step-level env settings.
"""

[check]
type = "bool"
default = false
sources.cli = ["--check", "-c"]
sources.env = ["HK_CHECK"]
sources.git = ["hk.check"]
docs = """
Forces hk to run only check commands (read-only) instead of fix commands.

This is the opposite of the `fix` setting. When enabled, hk will report issues without attempting to fix them.

Useful for CI environments where you want to verify code quality without making changes.
"""

[check_first]
type = "bool"
default = true
sources.env = ["HK_CHECK_FIRST"]
sources.git = ["hk.checkFirst"]
docs = """
If enabled, hk will run check commands first, then run fix commands only if the check fails when there are multiple linters with the same file in matching glob patterns.

The reason for this optimization is to maximize parallelization. We can have multiple check commands running in parallel against the same file without interference, but we can't have 2 fix commands potentially writing to the same file simultaneously.

If disabled, hk will use simpler logic that just runs fix commands in series in this situation.
"""

[display_skip_reasons]
type = "list<string>"
default = ["profile-not-enabled"]
sources.pkl = ["display_skip_reasons"]
sources.env = ["HK_DISPLAY_SKIP_REASONS"]
sources.git = ["hk.displaySkipReasons"]
docs = """
Controls which skip reasons are displayed when steps are skipped.

Available options:
- `all`: Show all skip reasons
- `none`: Hide all skip reasons
- `disabled-by-config`: Show when steps are skipped due to configuration
- `profile-not-enabled`: Show when steps are skipped due to missing profiles (default)

Example: `HK_DISPLAY_SKIP_REASONS=all` to see all skip reasons.
"""

[exclude]
type = "list<string>"
merge = "union"
sources.cli = ["--exclude", "-e"]
sources.env = ["HK_EXCLUDE"]
sources.git = ["hk.exclude"]
sources.pkl = ["exclude", "defaults.exclude"]
docs = """
Glob patterns to exclude from processing. These patterns are **unioned** with exclude patterns from other configuration sources (git config, user config, project config). Supports both directory names and glob patterns.

Examples:
- Exclude specific directories: `node_modules,dist`
- Exclude using glob patterns: `**/*.min.js,**/*.map`

All exclude patterns from different sources are combined.
"""

[fail_fast]
type = "bool"
default = true
sources.cli = ["--fail-fast", "--no-fail-fast"]
sources.env = ["HK_FAIL_FAST"]
sources.git = ["hk.failFast"]
sources.pkl = ["fail_fast", "defaults.fail_fast"]
docs = """
Controls whether hk aborts running steps after the first one fails.

When enabled (default), hk will stop execution immediately when a step fails, providing quicker feedback.
When disabled, hk will continue running all steps even if some fail, useful for seeing all issues at once.

Can be toggled with `--fail-fast` / `--no-fail-fast` CLI flags.
"""

[fix]
type = "bool"
default = true
sources.cli = ["--fix", "-f"]
sources.env = ["HK_FIX"]
sources.git = ["hk.fix"]
docs = """
Controls whether hk runs fix commands (that modify files) or check commands (read-only).

When enabled (default), runs fix commands to automatically resolve issues.
When disabled, only runs check commands to report issues without making changes.

Can be toggled with `--fix` / `--check` CLI flags.
"""

[hide_warnings]
type = "list<string>"
merge = "union"
sources.pkl = ["hide_warnings"]
sources.env = ["HK_HIDE_WARNINGS"]
sources.git = ["hk.hideWarnings"]
docs = """
Warning tags to suppress. Allows hiding specific warning messages that you don't want to see.

Available warning tags:
- `missing-profiles`: Suppresses warnings about steps being skipped due to missing profiles

Example: `HK_HIDE_WARNINGS=missing-profiles`

All hide configurations from different sources are **unioned** together.
"""

[hide_when_done]
type = "bool"
default = false
sources.env = ["HK_HIDE_WHEN_DONE"]
docs = """
Controls whether hk hides the progress output when the hook finishes successfully.

When enabled, successful runs will clear their output to reduce visual clutter.
Failed runs will always show their output regardless of this setting.
"""

[hkrc]
type = "path"
default = ".hkrc.pkl"
sources.cli = ["--hkrc"]
docs = """
**Deprecated:** Use `~/.config/hk/config.pkl` for global config or `hk.local.pkl` for per-project overrides.

Path to the user configuration file.

Default: `.hkrc.pkl` in the current directory or parent directories.

This file can override project-level settings and is useful for personal preferences.
This setting and the `--hkrc` flag will be removed in hk v2.
"""

[pkl_http_rewrite]
type = "string"
sources.env = ["HK_PKL_HTTP_REWRITE"]
docs = """
A value to provide `pkl`'s `--http-rewrite` flag when invoking `pkl`.

(`pkl` expects this in the form `http(s)://<FROM>/=http(s)://<TO>/`)ß
"""

[jobs]
type = "usize"
default = 0 # 0 means auto-detect from environment or CPU count
sources.cli = ["--jobs", "-j"]
sources.env = ["HK_JOBS", "HK_JOB"]
sources.git = ["hk.jobs"]
sources.pkl = ["jobs", "defaults.jobs"]
docs = """
The number of parallel processes that hk will use to execute steps concurrently. This affects performance by controlling how many linting/formatting tasks can run simultaneously.

Set to `0` (default) to auto-detect based on CPU cores.

Example usage:
- `hk check --jobs 4` - Run with 4 parallel jobs
- `HK_JOBS=8 hk fix` - Set via environment variable
"""
examples = ["hk check --jobs 4", "HK_JOBS=1 hk fix", "hk check -j 8"]
since = "1.0.0"

[json]
type = "bool"
default = false
sources.cli = ["--json"]
sources.env = ["HK_JSON"]
sources.git = ["hk.json"]
docs = """
Enables JSON output format for structured data.

When enabled, hk outputs machine-readable JSON instead of human-readable text.
Useful for integration with other tools or for programmatic processing of results.

Example: `hk check --json | jq '.steps[] | select(.failed)'`
"""

[libgit2]
type = "bool"
default = true
sources.env = ["HK_LIBGIT2"]
docs = """
Controls whether hk uses libgit2 (a Git library) or shells out to git CLI commands.

When enabled (default), uses libgit2 for better performance in most cases.
When disabled, uses git CLI commands which may provide better performance in some cases such as when using `fsmonitor` to watch for changes.
"""

[log_file]
type = "path"
sources.env = ["HK_LOG_FILE"]
docs = """
Path to the log file where hk writes detailed execution logs.

Default location: `~/.local/state/hk/hk.log`

Useful for debugging issues or keeping an audit trail of hook executions.
"""

[log_file_level]
type = "enum"
default = "info"
validate.enum = ["off", "error", "warn", "info", "debug", "trace"]
sources.env = ["HK_LOG_FILE_LEVEL"]
docs = """
Controls the verbosity of file logging output.

Uses the same levels as `log_level` but specifically for the log file.
Defaults to the same level as `log_level` if not specified.

This allows you to have different verbosity levels for console and file output.
"""

[log_level]
type = "enum"
default = "info"
validate.enum = ["off", "error", "warn", "info", "debug", "trace"]
sources.env = ["HK_LOG", "HK_LOG_LEVEL"]
docs = """
Controls the verbosity of console output.

Available levels (from least to most verbose):
- `off`: No logging
- `error`: Only errors
- `warn`: Errors and warnings
- `info`: Normal output (default)
- `debug`: Detailed debugging information
- `trace`: Very detailed trace information

Example: `HK_LOG_LEVEL=debug hk check`
"""

[mise]
type = "bool"
default = false
sources.env = ["HK_MISE"]
docs = """
Enables deep integration with [mise](https://mise.jdx.dev) for tool management.

When enabled:
- `hk install` will use `mise x` to execute hooks, ensuring mise tools are available without activation
- `hk init` will create a `mise.toml` file with hk configured
- Tool discovery will use mise shims automatically
"""

[no_progress]
type = "bool"
default = false
sources.cli = ["--no-progress"]
docs = """
Disables progress bars and real-time status updates.

When enabled, hk will use simpler text output instead of dynamic progress indicators.
Useful for CI environments or when output is being logged to a file.
"""

[profiles]
type = "list<string>"
sources.cli = ["--profile", "-p"]
sources.env = ["HK_PROFILE", "HK_PROFILES"]
sources.git = ["hk.profile"]
sources.pkl = ["profiles", "defaults.profiles"]
docs = """
Profiles to enable or disable. Profiles allow you to group steps that should run only in certain contexts (e.g., CI, slow tests).

Prefix with `!` to explicitly disable a profile.

Example usage:
- `HK_PROFILE=ci` - Enable the CI profile
- `HK_PROFILE=slow,ci` - Enable multiple profiles
- `--profile=!slow` - Explicitly disable the slow profile
"""

[quiet]
type = "bool"
default = false
sources.cli = ["--quiet", "-q"]
docs = """
Suppresses non-essential output.

When enabled, only errors and critical information will be displayed.
Useful for scripting or when you only care about the exit code.
"""

[silent]
type = "bool"
default = false
sources.cli = ["--silent"]
docs = """
Completely suppresses all output, including errors.

More extreme than `quiet` - absolutely no output will be displayed.
Useful when only the exit code matters.
"""

[skip_hooks]
type = "list<string>"
merge = "union"
sources.pkl = ["skip_hooks", "defaults.skip_hooks"]
sources.env = ["HK_SKIP_HOOK", "HK_SKIP_HOOKS"]
sources.git = ["hk.skipHooks", "hk.skipHook"]
docs = """
A list of hook names to skip entirely. This allows you to disable specific git hooks from running.

For example: `HK_SKIP_HOOK=pre-commit,pre-push` would skip running those hooks completely.

This is useful when you want to temporarily disable certain hooks while still keeping them configured in your `hk.pkl` file.
Unlike `skip_steps` which skips individual steps, this skips the entire hook and all its steps.

This setting can also be configured via:
- Git config: `git config hk.skipHook "pre-commit"`
- User config (`~/.config/hk/config.pkl`): `skip_hooks = List("pre-commit")`

**All skip configurations from different sources are unioned together.**
"""

[skip_steps]
type = "list<string>"
merge = "union"
sources.cli = ["--skip-step"]
sources.env = ["HK_SKIP_STEPS", "HK_SKIP_STEP"]
sources.git = ["hk.skipSteps", "hk.skipStep"]
sources.pkl = ["skip_steps", "defaults.skip_steps"]
docs = """
A list of step names to skip when running hooks. This allows you to bypass specific linting or formatting tasks.

For example: `HK_SKIP_STEPS=lint,test` would skip any steps named "lint" or "test".

This setting can also be configured via:
- Git config: `git config hk.skipSteps "step1,step2"`
- User config (`~/.config/hk/config.pkl`): `skip_steps = List("step1", "step2")`

**All skip configurations from different sources are unioned together.**
"""

[slow]
type = "bool"
default = false
sources.cli = ["--slow", "-s"]
docs = """
Enables the "slow" profile for running additional checks that may take longer.

This is a convenience flag equivalent to `--profile=slow`.

Useful for thorough checking in CI or before major releases.
"""

[stage]
type = "bool"
sources.cli = ["--stage", "--no-stage"]
sources.env = ["HK_STAGE"]
sources.git = ["hk.stage"]
sources.pkl = ["stage"]
docs = """
When specified, overrides the [hook's `stage` key](https://hk.jdx.dev/configuration.html#hooks-hook-stage-boolean).

This is useful when you want to manually review changes made by auto-fixers before including them in your commit.
"""

[stash]
type = "enum"
validate.enum = ["git", "patch-file", "none"]
sources.cli = ["--stash"]
sources.env = ["HK_STASH"]
sources.git = ["hk.stash"]
docs = """
Strategy for temporarily saving unstaged changes before running hooks that might modify files. This prevents conflicts between your working directory changes and automated fixes.

Available strategies:
- `git`: Use `git stash` to stash changes
- `patch-file`: Use hk-generated patch files (typically faster, avoids "index is locked" errors)
- `none`: No stashing (fastest, but may cause staging conflicts if fixes modify unstaged changes in the same file)
"""

[stash_untracked]
type = "bool"
default = true
sources.env = ["HK_STASH_UNTRACKED"]
sources.git = ["hk.stashUntracked"]
docs = """
Controls whether untracked files are included when stashing before running hooks.

When enabled (default), untracked files will be temporarily stashed along with tracked changes.
This ensures a clean working directory for hook execution.
"""

[stash_backup_count]
type = "usize"
default = 20
sources.env = ["HK_STASH_BACKUP_COUNT"]
sources.git = ["hk.stashBackupCount"]
sources.pkl = ["stash_backup_count"]
docs = """
Number of backup patch files to keep per repository when using git stash.

Each time git stash is used, hk creates a backup patch file in
$HK_STATE_DIR/patches/. This setting controls how many of these
backups are retained per repository (oldest are automatically deleted).

Set to 0 to disable patch backup creation entirely.

Default: 20
"""

[state_dir]
type = "path"
sources.env = ["HK_STATE_DIR"]
docs = """
Directory where hk stores persistent state files.

Default location: `~/.local/state/hk`

Includes logs, temporary patch files for stashing, and other state information.
"""

[summary_text]
type = "bool"
default = false
sources.env = ["HK_SUMMARY_TEXT"]
docs = """
Controls whether per-step output summaries are printed in plain text mode.

By default, summaries are only shown when hk is rendering progress bars (non-text mode).
Set to `true` to force summaries to appear in text mode, useful for CI environments.

Example: `HK_SUMMARY_TEXT=1 hk check`
"""

[terminal_progress]
type = "bool"
default = true
sources.env = ["HK_TERMINAL_PROGRESS"]
sources.git = ["hk.terminalProgress"]
sources.pkl = ["terminal_progress"]
docs = """
Enables or disables reporting progress via OSC sequences to compatible terminals.
"""

[timing_json]
type = "path"
sources.env = ["HK_TIMING_JSON"]
docs = """
Path to write a JSON timing report after a hook finishes. The report includes total wall time and per-step wall time, with overlapping intervals merged so time isn't double-counted across parallel step parts.

The `steps` field maps step names to objects containing:
- `wall_time_ms`: merged wall time in milliseconds
- `profiles` (optional): list of profiles required for that step

Example usage: `HK_TIMING_JSON=/tmp/hk-timing.json hk check`

Example output:
```json
{
  "total": { "wall_time_ms": 12456 },
  "steps": {
    "lint": { "wall_time_ms": 4321, "profiles": ["ci", "fast"] },
    "fmt": { "wall_time_ms": 2100 }
  }
}
```

When a hook-level `report` command is configured in `hk.pkl`, hk will set `HK_REPORT_JSON` to the same timing JSON content and execute the command after the hook finishes.
"""

[trace]
type = "enum"
default = "off"
validate.enum = ["off", "text", "json", "1", "true"]
sources.cli = ["--trace"]
sources.env = ["HK_TRACE"]
sources.git = ["hk.trace"]
docs = """
Enables tracing spans and performance diagnostics for detailed execution analysis.

Available formats:
- `off`: No tracing (default)
- `text`: Human-readable trace output
- `json`: Machine-readable JSON trace output
- `1` or `true`: Enable text tracing (aliases)

Useful for debugging performance issues or understanding execution flow.

Example: `HK_TRACE=text hk check` to see detailed execution traces.
"""

[walk_ignore]
type = "bool"
default = true
sources.env = ["HK_WALK_IGNORE"]
sources.git = ["hk.walkIgnore"]
sources.pkl = ["walk_ignore"]
docs = """
Controls whether hk respects .gitignore and other ignore files when walking directories.

When enabled (default), hk will skip files matching patterns in .gitignore, .ignore, and other
standard ignore files when discovering files for linting. This improves performance by not
processing generated files, build artifacts, or vendored dependencies.

When disabled, all files are included regardless of ignore patterns.

Example: `HK_WALK_IGNORE=0 hk check --all` to include all files.
"""

[verbose]
type = "u8"
default = 0
sources.cli = ["--verbose", "-v"]
docs = """
Controls the verbosity of output.

Can be specified multiple times to increase verbosity:
- `-v`: Basic verbose output
- `-vv`: More detailed output
- `-vvv`: Very detailed output

Example: `hk check -vv` for detailed debugging output.
"""

[warnings]
type = "list<string>"
sources.pkl = ["warnings"]
sources.env = ["HK_WARNINGS"]
sources.git = ["hk.warnings"]
docs = """
Warning tags to enable or show. Controls which warning messages are displayed during execution.
"""