--- title: Config reference description: Exhaustive generated reference for Hunk TOML keys, defaults, aliases, and layering. editUrl: true head: [] template: doc sidebar: hidden: false attrs: {} pagefind: true draft: false --- Hunk reads TOML preferences from the user config and an optional repository config. This reference is generated from the same catalog that `src/core/run/config.ts` uses to parse preference keys. ## Resolution and scope Layers apply from lowest to highest precedence: 1. built-in defaults 2. user config top-level keys, then the matching command table, then `[pager]` when pager chrome is active 3. repository `.hunk/config.toml` top-level keys, matching command table, and pager table 4. explicit CLI options The user path is `$XDG_CONFIG_HOME/hunk/config.toml` when configured. Otherwise Hunk uses `$HOME/.config/hunk/config.toml` or `%USERPROFILE%/.config/hunk/config.toml`; if none of those environment variables are set, no user config is loaded. Custom theme tables are root-only; preference keys may appear at top level, in a command table, or in `[pager]`. ## Preference keys **`mode`** Choose responsive, side-by-side, or stacked diff layout. - **Type:** string - **Accepted:** `auto`, `split`, or `stack` - **Built-in default:** `auto` --- **`cursor_line`** Mark the current line as a full-row highlight or on its line number. `off` restores plain `j`/`k` scrolling. - **Type:** string - **Accepted:** `row`, `number`, or `off` - **Built-in default:** `row` --- **`vcs`** Select the version-control adapter explicitly. An explicit id outranks detection; an id no loaded backend owns falls back to detection with a startup notice. - **Type:** string - **Accepted:** `git`, `jj`, `sl`, or an id a loaded extension backend registers - **Built-in default:** detected from the checkout (Git fallback) --- **`theme`** Select the active color theme. - **Type:** string - **Accepted:** a built-in theme id or `custom` - **Built-in default:** `github-dark-default` --- **`watch`** Reload supported review inputs when their source changes. - **Type:** boolean - **Accepted:** `true` or `false` - **Built-in default:** `false` --- **`exclude_untracked`** Hide untracked files from working-tree reviews. - **Type:** boolean - **Accepted:** `true` or `false` - **Built-in default:** `false` --- **`line_numbers`** Show old and new line-number columns. - **Type:** boolean - **Accepted:** `true` or `false` - **Built-in default:** `true` --- **`tab_width`** Set terminal-cell tab stops used for display and wrapping. - **Type:** integer - **Accepted:** 1 through 16 - **Built-in default:** `4` --- **`wrap_lines`** Wrap long diff lines instead of keeping one visual row. - **Type:** boolean - **Accepted:** `true` or `false` - **Built-in default:** `false` --- **`hunk_headers`** Show hunk metadata rows in the review stream. - **Type:** boolean - **Accepted:** `true` or `false` - **Built-in default:** `true` --- **`menu_bar`** Show the top application menu bar. - **Type:** boolean - **Accepted:** `true` or `false` - **Built-in default:** `true` --- **`sidebar`** Show the files pane if it fits, keep it closed, or let the responsive layout decide. Pager sessions always open with the files pane closed. - **Type:** string or boolean - **Accepted:** `"auto"`, `true`, or `false` - **Built-in default:** `auto` --- **`agent_notes`** Show agent notes when a review opens. - **Type:** boolean - **Accepted:** `true` or `false` - **Built-in default:** `false` --- **`copy_decorations`** Include diff signs and line numbers in copied selections. - **Type:** boolean - **Accepted:** `true` or `false` - **Built-in default:** `false` --- **`prompt_save_view_preferences`** Ask before discarding view changes that can be persisted. - **Type:** boolean - **Accepted:** `true` or `false` - **Built-in default:** `true` --- **`transparent_background`** Let the terminal background show through Hunk surfaces. - **Type:** boolean - **Accepted:** `true` or `false` - **Built-in default:** `false` - **Aliases:** `transparentBackground` (deprecated) --- **`color_moved`** Enable moved-line coloring when the renderer supports it. - **Type:** boolean - **Accepted:** `true` or `false` - **Built-in default:** — ## Command tables | Table | Applies to | | -------------- | ------------------------------------------------- | | `[vcs]` | working-tree and target reviews (`hunk diff`) | | `[show]` | commit and target display reviews (`hunk show`) | | `[stash-show]` | stash reviews (`hunk stash show`) | | `[diff]` | two-file comparisons (`hunk diff `) | | `[patch]` | patch-file reviews (`hunk patch`) | | `[difftool]` | Git difftool pair reviews (`hunk difftool`) | `[pager]` is an additional overlay for any review opened with pager-style chrome. It is applied after the matching command table in the same file. ## Custom themes Set `theme = "custom"` and add a root `[custom_theme]` table. `custom_theme.base` accepts one of these built-in ids and defaults to `github-dark-default` when layered custom themes need a base: - `andromeeda` - `aurora-x` - `ayu-dark` - `ayu-light` - `ayu-mirage` - `catppuccin-frappe` - `catppuccin-latte` - `catppuccin-macchiato` - `catppuccin-mocha` - `dark-plus` - `dracula` - `dracula-soft` - `everforest-dark` - `everforest-light` - `github-dark` - `github-dark-default` - `github-dark-dimmed` - `github-dark-high-contrast` - `github-light` - `github-light-default` - `github-light-high-contrast` - `gruvbox-dark-hard` - `gruvbox-dark-medium` - `gruvbox-dark-soft` - `gruvbox-light-hard` - `gruvbox-light-medium` - `gruvbox-light-soft` - `horizon` - `horizon-bright` - `houston` - `kanagawa-dragon` - `kanagawa-lotus` - `kanagawa-wave` - `laserwave` - `light-plus` - `material-theme` - `material-theme-darker` - `material-theme-lighter` - `material-theme-ocean` - `material-theme-palenight` - `min-dark` - `min-light` - `monokai` - `night-owl` - `night-owl-light` - `nord` - `one-dark-pro` - `one-light` - `plastic` - `poimandres` - `red` - `rose-pine` - `rose-pine-dawn` - `rose-pine-moon` - `slack-dark` - `slack-ochin` - `snazzy-light` - `solarized-dark` - `solarized-light` - `synthwave-84` - `tokyo-night` - `vesper` - `vitesse-black` - `vitesse-dark` - `vitesse-light` These deprecated IDs remain accepted by `theme` and `custom_theme.base`, then normalized to their replacements: | Legacy ID | Replacement | | ---------- | ---------------------- | | `graphite` | `github-dark-default` | | `midnight` | `github-dark-dimmed` | | `paper` | `github-light-default` | | `ember` | `dark-plus` | | `zenburn` | `everforest-dark` | `custom_theme.label` accepts a non-empty string. Every semantic color below accepts a six-digit `#rrggbb` value: | Key | Description | | ---------------------------------- | ------------------------------------------------ | | `custom_theme.background` | Override the background semantic color. | | `custom_theme.panel` | Override the panel semantic color. | | `custom_theme.panelAlt` | Override the panelAlt semantic color. | | `custom_theme.border` | Override the border semantic color. | | `custom_theme.accent` | Override the accent semantic color. | | `custom_theme.accentMuted` | Override the accentMuted semantic color. | | `custom_theme.text` | Override the text semantic color. | | `custom_theme.muted` | Override the muted semantic color. | | `custom_theme.addedBg` | Override the addedBg semantic color. | | `custom_theme.removedBg` | Override the removedBg semantic color. | | `custom_theme.movedAddedBg` | Override the movedAddedBg semantic color. | | `custom_theme.movedRemovedBg` | Override the movedRemovedBg semantic color. | | `custom_theme.contextBg` | Override the contextBg semantic color. | | `custom_theme.addedContentBg` | Override the addedContentBg semantic color. | | `custom_theme.removedContentBg` | Override the removedContentBg semantic color. | | `custom_theme.contextContentBg` | Override the contextContentBg semantic color. | | `custom_theme.addedSignColor` | Override the addedSignColor semantic color. | | `custom_theme.removedSignColor` | Override the removedSignColor semantic color. | | `custom_theme.lineNumberBg` | Override the lineNumberBg semantic color. | | `custom_theme.lineNumberFg` | Override the lineNumberFg semantic color. | | `custom_theme.selectedHunk` | Override the selectedHunk semantic color. | | `custom_theme.badgeAdded` | Override the badgeAdded semantic color. | | `custom_theme.badgeRemoved` | Override the badgeRemoved semantic color. | | `custom_theme.badgeNeutral` | Override the badgeNeutral semantic color. | | `custom_theme.fileNew` | Override the fileNew semantic color. | | `custom_theme.fileDeleted` | Override the fileDeleted semantic color. | | `custom_theme.fileRenamed` | Override the fileRenamed semantic color. | | `custom_theme.fileModified` | Override the fileModified semantic color. | | `custom_theme.fileUntracked` | Override the fileUntracked semantic color. | | `custom_theme.noteBorder` | Override the noteBorder semantic color. | | `custom_theme.noteBackground` | Override the noteBackground semantic color. | | `custom_theme.noteTitleBackground` | Override the noteTitleBackground semantic color. | | `custom_theme.noteTitleText` | Override the noteTitleText semantic color. | ### Syntax scopes `[custom_theme.syntax_scopes]` accepts arbitrary non-empty Shiki/TextMate scope names as TOML keys and six-digit hex colors as values. These exact scope overrides are the preferred syntax customization API. The deprecated `[custom_theme.syntax]` table remains accepted for one compatibility window with these semantic keys: `custom_theme.syntax.default`, `custom_theme.syntax.keyword`, `custom_theme.syntax.string`, `custom_theme.syntax.comment`, `custom_theme.syntax.number`, `custom_theme.syntax.function`, `custom_theme.syntax.property`, `custom_theme.syntax.type`, `custom_theme.syntax.variable`, `custom_theme.syntax.operator`, `custom_theme.syntax.punctuation`. Hunk normalizes them into exact scope overrides and emits a startup notice. ### Named themes Declare any number of additional themes as `[themes.]` tables. Each one accepts exactly the keys `[custom_theme]` accepts, plus the id in the table name, and is selectable with `theme = ""` or `--theme `. Ids are lowercase words separated by `-` or `_`; ids belonging to built-in themes, to `auto`, or to the `custom_theme` table are skipped with a startup notice. `[custom_theme]` itself keeps the id `custom`. Same-id tables merge field by field across the user and repository layers, with the repository layer winning. ## Extensions `[extensions]` controls which user extensions load. It is root-only and does not accept command or `[pager]` overrides. | Key | Type | Accepted | Built-in default | Description | | -------------------- | ---------------- | ----------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------- | | `extensions.enabled` | boolean | `true` or `false` | `true` | Load user extensions. `--no-extensions` forces this off for one run, and bundled VCS backends stay loaded either way. | | `extensions.paths` | array of strings | entry file or directory paths | `[]` | Extension entry points loaded at startup. Paths a repository config contributes are trust-gated before they run. | Repository `.hunk/config.toml` paths are kept separate from user paths: Hunk prompts for trust before executing repository-declared extension code, and `--no-extensions` disables user extensions entirely for one run. Each extension reads its own settings from a `[extension.]` table. Hunk does not interpret those keys; it passes the table through to the extension. Repository tables merge over user tables key by key, and Hunk emits a startup notice naming every extension whose settings the repository overrides.