hunk

The hunk watch implementation has transitioned from a 250ms polling mechanism to an evented Chokidar-based hybrid observer.

Key Performance Differences:

• Idle Overhead: The evented mode significantly reduces Git subprocess invocations and CPU consumption during idle periods. While the old polling version averaged ~13 Git calls per second, the evented version averages ~0.35 calls per second (primarily via a 10s safety poll).
• Startup Time: Startup performance remains identical (~1.7s) between both versions, as both are dominated by the initial git diff load cost.
• Refresh Latency: The evented mode provides sub-second passive refresh latency for various file operations:
  • Simple tracked-file write: ~340ms
  • Atomic temp-file + rename: ~418ms
  • Large 241-line diff update: ~406ms
  • New untracked file creation: ~682ms

Components accept HunkDiffFileInput objects. You can create these using several methods depending on your source data:

From before/after contents

Use parseDiffFromFile to generate metadata from two versions of a file, then wrap it in createHunkDiffFile.

import { createHunkDiffFile, parseDiffFromFile } from "hunkdiff/opentui";

const file = createHunkDiffFile({
  id: "example",
  metadata: parseDiffFromFile(beforeFile, afterFile, { context: 3 }, true),
  path: "example.ts",
  language: "typescript",
});

From unified diff text

Use createHunkDiffFilesFromPatch for a quick way to generate multiple files from a single patch string.

import { createHunkDiffFilesFromPatch } from "hunkdiff/opentui";

const files = createHunkDiffFilesFromPatch(patchText, "example:patch");

To review the current state of your repository, including both tracked changes and untracked files, run hunk diff from within the repository.

If you only want to see tracked changes, use the --exclude-untracked flag.

While inside the Hunk interface, use these keybindings for navigation and layout:

• ] : Jump to the next hunk.
• . : Jump to the next file.
• 1, 2, or 0 : Switch between split, stack, or responsive auto layout.
• q : Quit Hunk.

To run Hunk on Windows:

• Ensure Node.js 18 or newer is installed and available on your PATH.
• Use a modern Windows terminal.
• Note on Shells: Git Bash, PowerShell, and other shells have different quoting rules for commands. When using multi-line shell examples, you may need to adapt the quoting to match your specific environment.

STML (Small Terminal Markup Language) allows rendering HTML-like markup (boxes, gauges, lists, etc.) in the terminal.

Requirements:

1. The session must have been launched with the --experimental flag.
2. hunk session context --json must list stml in experimentalFeatures.

Usage:

• Use the --markup <stml> flag in comment add or the markup field in comment apply payloads.
• Use hunk markup guide to learn syntax and width rules.
• Use hunk markup render - --width <width> to preview markup, where <width> is provided by noteMarkupWidth in the session context.

To automatically open Hunk when running git diff or git show, set Hunk as your Git pager.

Option 1: Global configuration

git config --global core.pager "hunk pager"

Option 2: Git config file

[core]
    pager = hunk pager

Option 3: Opt-in aliases (keeps default pager for standard commands)

git config --global alias.hdiff "-c core.pager=\"hunk pager\" diff"
git config --global alias.hshow "-c core.pager=\"hunk pager\" show"

Note: Untracked files are only auto-included in Hunk's own hunk diff sessions. When using the Git pager, Git determines the patch contents, so untracked files will not appear.

To use the reusable terminal diff components, install hunkdiff along with its peer dependencies @opentui/core, @opentui/react, and react.

npm i hunkdiff @opentui/core@^0.4.2 @opentui/react@^0.4.2 react

Hunk distinguishes between two types of extensions, both using the same per-extension API and registry:

• User extensions: Loaded at interactive-app startup. These are subject to discovery, trust gating, and can be disabled using the --no-extensions flag.
• Bundled extensions: Compiled into the binary and located in src/extensions/default/. These are implicitly trusted and remain loaded even with --no-extensions.

Extension ID Rules: An extension ID is the namespace for its commands (<extensionId>.<commandId>), sidebar views (<extensionId>:<viewId>), and configuration ([extension.<id>]).

• IDs must match the regex: /^[A-Za-z0-9][A-Za-z0-9_-]*$/.
• Reserved IDs (like hunk or bundled VCS backends) cannot be used.
• Dots or colons are not allowed in the ID itself to prevent ambiguity in composed IDs.