kgit

kgit is a planned fast, Git-first terminal UI written in Rust. It takes inspiration from lazygit while prioritizing a polished interface, consistent Vim-style navigation, and optional visual enhancements provided by kterm.

Download v0.5.0

Download 0.5.0

The application will use the Git CLI as its source of truth instead of reimplementing Git. It will remain a normal VT application in every terminal; kterm's OSC extensions add rounded tabs, buttons, and scrollbars when the terminal advertises support.

Diffs are rendered by kgit rather than delegated to a pager. The built-in renderer combines unified and intraline change presentation with tree-sitter syntax highlighting, and can hide whitespace-only changes while reviewing. The UI adopts the terminal's configured palette by default. Catppuccin Mocha and six dark/light Everforest contrast variants are available as explicit fixed themes matching kvim and Kterm.

Product principles

Initial experience

The workspace has six top-level routes:

  1. Changes pairs the changed-path tree with its file diff.
  2. History pairs the commit graph with commit details and diffs.
  3. Branches, Tags, Remotes, and Stashes each expose a repository collection with a derived detail view.

Wide terminals show each route as a master/detail split. Narrow terminals show one level at a time: l opens detail and Esc or h returns to the route's master list. Enter opens Changes and History details, while repository collection routes keep their specific activation (for example, switching a branch or fetching a remote). 1 through 6, Tab/Shift-Tab, and gt/gT switch routes; [/] switch repository collection routes. Destructive or history-rewriting operations require an explicit confirmation that displays the Git command and affected scope.

A Nerd Font is expected for file, folder, and semantic status icons.

Hover guidance appears in a compact framed popup and fades after about two seconds without being renewed by movement over the same hint. Operation notices last about five seconds; ! / Info retains the latest notice's full text after it disappears. These notices stay nonmodal and restore the covered content on expiry.

File and hunk stage/unstage operations use compact progress frames showing only the affected count and current phase, followed by a short completion notice. Input stays blocked until Git and the repository refresh finish; errors retain their exact scope and diagnostics.

The detailed design is in docs/architecture.md. The dependency-ordered phases, deliverables, and completion gates are in docs/implementation-plan.md.

kgit must not depend on either project's internal crates. Shared behavior should be captured by kgit-owned interfaces and tests.

Development

The repository uses the stable Rust toolchain with Rustfmt and Clippy. Run the same checks used by CI from the repository root:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features

Windows MSVC release builds use a statically linked CRT through .cargo/config.toml; CI verifies that kgit.exe does not import VCRUNTIME140.dll.

Basic startup commands are:

cargo run -- --help
cargo run -- --version
cargo run -- --repo .

For input or layout diagnostics, set KGIT_LOG to an output file before launching. The log records raw mouse coordinates and event kinds, semantic hit target categories, divider capture transitions, rendered pane geometry, and reducer clamping without recording selected paths or ref names:

$env:KGIT_LOG = "$PWD\kgit-diagnostics.log"
cargo run --release -- --repo .
Remove-Item Env:KGIT_LOG
Select-String -Path .\kgit-diagnostics.log `
  -Pattern "terminal input|mouse event|preview divider|viewport layout"

The general diagnostic stream can include repository paths and Git failure messages, so review the file before sharing it.

kgit --repo <path> is the stable integration contract for terminals and editors. The path may be a repository root, a nested worktree directory, a linked worktree, a bare repository, or an existing directory outside Git. See installation and release packages, migration and rollback, the kvim parity matrix, and Phase 9 stress evidence.

The Changes pane discovers the enclosing worktree from the current directory or --repo, then shows independent index/worktree/conflict badges from porcelain v2 status. Use j/k, gg/G, and Ctrl-u/d to navigate, h/l or Enter to collapse/expand directories, / plus n/N to search, and r to refresh. Press s to stage paths with worktree changes or unstage index-only paths. Directory actions expand to the exact changed paths currently displayed and are passed to Git as bounded literal pathspec batches.

Press S in Changes or its diff to stage remaining changes, or unstage all when everything is staged, regardless of selection, collapsed folders, or search matches. If any stageable working-tree changes remain, kgit stages those modified, added, deleted, and untracked files from the current repository snapshot, fully staging partially staged files and preserving staged-only paths. Otherwise, it unstages all staged changes without modifying files on disk. A clean repository is unchanged. Ignored files are excluded. Submodule worktrees are not recursively staged, and internal submodule edits alone do not prevent unstaging the parent's changes; changed submodule commit pointers are staged normally. Wait for refresh to finish first. If any unresolved conflicts remain, the bulk action is refused: review and stage resolved files individually with s.

Editing changed files

Press E in Changes or its diff to edit one focused working-tree file. The clickable command bar includes Edit file when it fits; the ? palette exposes it at narrow sizes too. An active hunk selected with [/] or a hunk click supplies the destination, even when Changes still has focus. The editor opens at the first changed new-side line; deletion-only hunks use the nearest surviving boundary. Staged positions are mapped from the index into the file on disk. Stale or ambiguous positions are refused with a diagnostic and refresh, not guessed.

Configure the editor in user ~/.config/kgit/config.toml (or the selected user path described under Configuration and repository trust); Info shows the resolved configuration path. No editor is selected implicitly. For kvim 0.18.0 or newer:

[editor]
program = "kvim"
args = []
position = "kvim"

Kgit uses --goto <line> -- <file> when a hunk is active. A bounded version check rejects older kvim before sending positioning arguments. Ensure the configured executable is the updated kvim binary.

For older kvim, set position = "none" instead. none is the default and opens the file at the editor's normal destination. Kgit explicitly reports omitted hunk positioning on return.

For VS Code:

[editor]
program = "code"
args = []
position = "vscode"

Kgit adds --wait and, when a hunk is active, --goto <file>:<line>:1. Close the opened file in VS Code to return to kgit. On Windows, code.cmd and the full path to Code.exe are supported through VS Code's native Electron/JavaScript CLI; kgit never interpolates the filename into a shell command. Unsupported wrapper layouts are explicit errors.

program is one executable name or path, and args is an array of literal arguments, not a command string. The child runs from the repository root and inherits the terminal only after kgit releases its capabilities. Kgit waits, restores the terminal, discards buffered application input, and refreshes status and the selected diff, including after a nonzero editor exit. Editing never stages a file or writes an index/historical snapshot. Visual selection does not turn this into a batch action. Folders, missing files, symlink leaves, paths escaping the worktree, and active operations are refused. Repository configuration cannot contain [editor]; custom keymaps use file.edit.

Selecting and reviewing changes

Use v for a keyboard range and Space to toggle the current item. Shift-click extends a range, Ctrl-click toggles an item, and left-drag extends the same selection. These batch selections are available only for changed paths and exact actionable hunks. Scrollbar tracks page; scrollbar thumbs use pointer capture while dragging. Vim motions provide the equivalent keyboard scrolling.

The route detail view renders bounded diffs without an external pager. Use d to open it or switch index/worktree when both exist, i for unified/intraline presentation, o for patch/whole-file scope, w for exact/ignore-all-space review, z to toggle wrapped lines, and [/] for hunks in the visible file. Whole-file scope fills unchanged ranges from the complete new-side file while retaining removed rows at their hunk anchors; deleted files use the old side and opens at the first available hunk. Press s on an exact worktree hunk to stage it or on an exact index hunk to unstage it. kgit verifies baseline, index, and worktree identities, runs git apply --check, and then applies the generated patch. Whitespace-filtered or stale hunks are rejected and trigger an exact refresh.

The preview uses concise file and change labels instead of raw diff --git, index, path-marker, and @@ syntax. Old/new line-number columns distinguish removed and added rows without repeating - and + signs in the content gutter. Unified and intraline views retain syntax token colors. Intraline backgrounds never replace those foregrounds; if a concrete background would reduce token contrast below 4.5:1 (or below its already lower pane contrast), kgit restores the pane background and uses bold/underlined intraline emphasis instead, including visible underlines on changed spaces and tabs. The same emphasis is used when palette colors collapse to an identical background. Without concrete terminal palette values, and in ANSI-16 mode, added/removed gutters are green/red, content keeps the pane background, intraline ranges are bold/underlined. All colored themes use italic hunk selection so it does not hide fallback intraline emphasis. No-color keeps the old/new number columns and uses bold/underlined intraline, underlined search, and reversed hunk-selection cues.

Press D on exact tracked worktree hunks to discard only those hunks, on tracked worktree paths to discard the files, or on an entirely untracked path selection to clean it. The modal lists the operation and exact path/hunk scope; y/Enter confirms and n/Esc cancels. Hunk discard verifies the same baseline, index, and worktree identity immediately before a non-mutating patch check and reverse-applies the generated patch to the worktree only. The index is not changed. Whitespace-filtered, stale, non-actionable, untracked, and conflicted hunks are rejected. Empty untracked directories are not listed by Git and are not removed. Unresolved conflicts cannot be discarded as hunks or through the tracked-discard flow; stage a resolved file explicitly. Bare repositories, paths outside a repository, and repository access failures never permit mutation. Mutations are serialized per repository and are not cancellable after queueing, avoiding partial interruption between bounded Git operations.

Queued and running mutations and synchronization own a blocking progress popup with the operation, exact scope, current Git phase, and elapsed time. Background workers and rendering continue, but navigation, refresh, and other commands are blocked and are never replayed afterward. Successful operations close the popup only after the current HEAD/status refresh finishes. Fetch offers Esc / Cancel fetch once running; cancellation waits for Git's actual result and never implies rollback. Local mutations, rewrite replay/publication, pull, and push cannot be cancelled live. A conflicted rewrite closes the progress popup and returns to the existing recovery workflow; X still requests confirmed abort. Commit failures retain the submitted draft; dismiss the error to edit or retry. HEAD and staged scope are revalidated, never silently substituted.

There is no permanent status row. Repository/HEAD context lives in pane chrome, brief nonmodal notifications report results and refusals, and ! / Info opens full repository, configuration, and recovery details. The Alert indicator persists for configuration problems and unfinished recovery even after a notification expires. Notices themselves are clickable; their complete latest text remains available in Info. Mouse and keyboard trust actions use the same exact canonical repository path.

The current repository snapshot derives staged counts and commit eligibility. Press c to open the internal commit composer in Insert mode on its title field, with a separate wrapped body-description input. The composer provides Normal/Insert editing with i/a/A/I/o/O, h/j/k/l, w/b, 0/$, gg/G, x, D, and dd. Use Tab or Shift-Tab to switch inputs. Submit with Enter in Normal mode or Ctrl-Enter in Insert mode; q/Esc cancels from Normal mode before anything is queued. Empty messages are rejected. kgit passes the message through a securely created temporary file to git commit --file; repository hooks run normally, and bounded hook stderr is shown when a hook rejects the commit.

Press A for the distinct amend flow. kgit first confirms the exact current HEAD and that local history will be rewritten, then opens the composer. Detached HEAD commits are supported. Merge, rebase, cherry-pick, revert, and bisect metadata appears in Context. Only actions reported for the current state are offered: C continues, X aborts with confirmation, and Skip is available through the Repository ? palette and clickable command bar, with confirmation. S always means the bulk stage/unstage toggle, never Skip. Unmerged rows show available base/ours/theirs stages. Resolve conflicts in an external editor, stage the result with s, refresh, and then use the available continue action; kgit does not embed a merge editor.

History defaults to Current branch: commits reachable from the displayed HEAD, including merged history but excluding unrelated, unmerged branches. Press b in History, click the scope control in the pane header, or use ? to toggle All refs, the repository-wide graph. The scope is session-only and can be rebound with history.toggle-scope. Detached HEAD uses its captured commit; an unborn branch stays empty even when other branches have commits. Current-branch pages use one captured HEAD object ID until refresh, so branch movement cannot mix histories between pages. / searches the loaded commits in the active scope. Scope changes retain the selected commit when present and otherwise select the newest commit; they clear commit ranges and file expansion.

The History route loads Arc-backed commit summaries in bounded pages and keeps commit selection stable by full object ID. Full author/committer/body details load only for the selected commit. At most 2,000 summaries are retained; deeper history is reported as capped instead of growing without bound. Decorations, parents, roots, and merge lane transitions are shown deterministically. Vim motions, counts, gg/G, H/M/L, Ctrl-u/d, /, n/N, mouse row selection, the wheel, and the scrollbar all work on history. More commits load automatically near the end without duplicate rows. Press Enter to focus the selected commit diff. Press v, move to a second commit, and review that commit range through the same built-in diff viewport, syntax highlighting, whitespace toggle, search, and theme paths used for worktree diffs.

Remove a commit or its file contribution

In Current branch History, press D on a commit row to drop that commit, or expand it and press D on a file row to remove only that file's contribution. If the commit changes just one file, deleting its file contribution drops the entire commit instead of retaining an empty replacement. A rename counts as one file; in multi-file commits its removal includes both old and new paths. This discards the contribution entirely, not back into Changes, and replays every later commit through the displayed branch tip. Author/message metadata is retained; rewritten IDs, committer metadata, and signatures change. Other branches and tags are untouched. The key uses the existing configurable mutation.discard action.

The confirmation shows the branch, expected tip, target, file scope, and successor count. Replay runs in an isolated detached worktree; the original branch stays unchanged during preparation. Successful replay publishes automatically, without a review step or second confirmation. Publication still requires the original branch/tip and clean worktree to remain unchanged. Git 2.46+ is required. The initial scope supports only a linear, non-merge segment on the current named branch's first-parent chain, within 2,000 commits. Root commits, merged side-history commits, detached/unborn HEAD, dirty worktrees, All refs, folders, ranges, batches, and hunk surgery are refused.

If a successor conflicts, kgit displays the isolated workspace path. Resolve and stage files there, using an external editor and Git, then press C. Once all remaining successors replay successfully, publication is automatic. Do not resolve the rewrite in the original Changes worktree. Empty successors and empty resolutions retain their commits; successors cannot be skipped. X confirms abort and discards only the isolated workspace/resolutions. Unrelated mutations and synchronization are disabled while a session exists. You may quit while paused and reopen the original worktree to recover it.

The journal lives under the common Git directory's kgit-rewrite directory. Completed/aborted journals are archived; refs/kgit/rewrites/<session>/before retains the original tip, and /after retains a prepared result. Consequently, All refs may still display the old history. Invalid or foreign-worktree journals are reported explicitly and block mutations. Interrupted commits with ambiguous checkpoints are not replayed twice: inspect the retained workspace or abort and start a fresh plan. A failed/interrupted publication can leave HEAD detached; its outcome is reported as uncertain and rediscovered on refresh. C retries interrupted preparation/publication without requiring a loaded diff or another confirmation; the same publication safety checks still apply. Abort never automatically resets or checks out the original worktree.

Local remote-tracking reachability produces a shared-history warning, but that inventory can be stale. kgit never pushes a rewrite automatically; publishing remotely still requires the existing separately confirmed, explicit --force-with-lease workflow.

Branches, Tags, Remotes, and Stashes are direct routes. Use [/] to switch between them and / to search the active inventory. Branch rows show the current branch, upstream, and ahead/behind counts. On Branches, use a to create at the displayed HEAD object ID and x to request confirmed deletion. Creation uses --no-track, never forces, and fails atomically if the name already exists. Deletion first rejects symbolic local refs, branches checked out by any worktree, and tips not merged into current HEAD, then uses one git update-ref --stdin transaction to verify the checked HEAD OID and no-dereference delete the full ref at the displayed branch OID. It does not remove branch.* configuration because post-delete cleanup could race with a newly recreated branch of the same name.

Enter performs an exact named switch only with Git 2.46 or newer. kgit checks that capability, rejects symbolic local refs and branches checked out by another worktree, then switches detached to the displayed object ID. It atomically verifies the branch still has that ID and symbolically attaches HEAD with an update-ref --stdin transaction. If the branch moves between phases, kgit reports a safe partial outcome and leaves HEAD detached at the displayed commit. Older Git is refused without changing the worktree. Branch rename is intentionally unavailable because Git cannot atomically preserve its full rename/config/reflog semantics against the displayed object ID. Tags are browse-only; Enter previews the tagged commit.

Worktree occupancy is checked again as late as practical, including after the detached switch phase. Git cannot include every worktree's HEAD in the shared ref transaction, so a separate Git process can still race this best-effort check. Expected-OID and raw-ref updates remain atomic.

On Stashes, a creates a stash (including untracked files), Enter opens its details and diff, and e applies its full stash commit object ID. Use l or the disclosure glyph to expand a stash into its changed-file tree, and h to collapse it. Navigate the expanded folder/file rows with j/k; selecting a path scopes Preview to that path. p is a separately labeled safe apply-by-OID action that also retains the stash; it is not pop. Drop is unavailable. Each stash row keeps its selector for display and uses a globally unique duplicate-aware reflog fingerprint for selection, while apply never resolves a potentially moved selector.

The Remotes route shows redacted fetch/push URLs and configured-upstream ahead/behind state. Use f to fetch, p to pull only the configured upstream, and P to push. (p retains its stash-apply meaning while the Stashes tab is focused.) These synchronization commands are listed first in Help, and p/P remain visible in the bottom command bar (f is also shown there on Remotes). Ambiguous fetches open an explicit remote chooser.

P always opens a destination chooser for the current named branch. It preselects the configured upstream and lists bounded, locally cached remote-tracking branches plus a same-name creation target for each remote. Cached destinations are derived through each remote's configured fetch refspecs; ambiguous or non-branch mappings are omitted. Use Vim motions and counts, / with n/N, or the mouse to select a destination. Choosing a branch other than the configured upstream is a one-off push and does not rewrite branch configuration. When no upstream exists, choosing the same-name destination sets it after the explicit choice.

Background synchronization is bounded and never prompts for credentials. Synchronization remains disabled until remote discovery succeeds for the current repository generation and branch; refreshes and discovery failures discard the old remote/upstream inventory. Background SSH also receives OpenSSH batch mode so it cannot bypass Git's no-prompt policy through a TTY. Fetch progress is parsed from Git's progress stream, and Esc cancels a running fetch without reporting success. Pull and push are not cancellable after they start; process failures that cannot prove the result are reported as uncertain and trigger a refresh. Push uses porcelain output and explains rejected updates. Immediately before any background or interactive network Git, kgit revalidates the exact named, detached, or unborn HEAD identity. Normal and force-with-lease pushes also pin their source to that request's full commit OID; same-name upstream setup retains Git's branch-based --set-upstream behavior after the same identity check. All stored synchronization diagnostics redact URL userinfo, queries, and fragments.

After a non-fast-forward rejection, F opens a separate confirmation for --force-with-lease=<remote-ref>:<expected-remote-oid> for the exact selected destination; plain --force is never used. A fetched tracking OID is required. If background Git reports that credentials or explicit SSH host verification are required, I first rebuilds the exact request from the current generation, HEAD, and remote inventory, refusing a stale retry. It then explicitly releases the TUI terminal to Git and restores raw mode, alternate screen, cursor, and mouse capture afterward. Interactive Git stderr is continuously drained, bounded, and URL-sanitized before terminal display or storage; direct controlling-terminal prompts remain available. Interactive push porcelain and failure effects retain the same rejection, uncertainty, and refresh semantics as background synchronization.

Configuration and repository trust

kgit loads configuration in this order:

  1. built-in defaults;
  2. one user file, discovered as described below;
  3. .kgit.toml at the canonical repository root, only when that exact canonical root is allowlisted by the user file.

User-file discovery runs once at startup:

  1. KGIT_CONFIG selects an explicit file, without trying other locations.
  2. Otherwise, prefer $XDG_CONFIG_HOME/kgit/config.toml when XDG_CONFIG_HOME is a nonempty absolute directory, or ~/.config/kgit/config.toml when it is unset or empty. Relative XDG_CONFIG_HOME values are ignored with a visible warning.
  3. If that portable file is missing, retain an existing platform-native config. On Windows, this is %APPDATA%\kgit\config\config.toml; on macOS, it is ~/Library/Application Support/kgit/config.toml. Linux normally uses the same XDG/home path as the portable candidate.

If neither file exists, future trust/preview writes create the portable file. When both exist, only the portable file is loaded, and Info identifies the ignored native file. Settings and repository trust are never merged between user files. An invalid or unreadable preferred file is reported, not replaced by native settings. The selected path stays fixed for all reads and atomic trust/preview writes until kgit exits, even if that file is deleted or becomes unreadable. Another candidate can be selected only after a restart. Existing files are never moved or deleted automatically. To keep using a native file explicitly, point KGIT_CONFIG at it. Info always shows the selected user path.

Missing and invalid user configuration is shown in ! / Info with its source path; errors and untrusted repository configuration retain an Alert indicator. An invalid or unreadable user file is never overwritten by a trust action. An untrusted repository file is ignored in full and produces a visible source-aware notice. Press t or click Trust to atomically add only the displayed canonical root to [trust].repositories, then reload both layers (the clickable Trust exact repository control is in Info). Parent paths, glob patterns, manually listed symlink aliases, and local [trust] tables never confer trust. Repository config must be a regular, non-symlink .kgit.toml file.

Preview controls changed with i, o, w, and z are written atomically to the user-only [preview] table and restored on the next launch. An invalid or unreadable user file is never overwritten; kgit keeps the in-session toggle and shows the persistence failure instead.

The optional user-only [editor] table configures the E/file.edit handoff. See Editing changed files for kvim and VS Code examples and positioning compatibility. Repository editor overrides are rejected even when the repository is trusted.

[appearance]
theme = "terminal" # default; fixed themes are listed below
color-mode = "auto" # true-color, ansi-256, ansi-16, or no-color
# The compatibility spelling `true-color = "auto|always|never"` is also accepted.

[input]
mouse-capture = true
seamless-pane-controls = true

[preview]
layout = "unified" # unified or intraline
scope = "patch" # patch or whole-file
whitespace = "exact" # exact or ignore-all-space
word-wrap = false

[keymap]
"za" = "repository.refresh"
"<C-S-l>" = "pane.resize-right"

[trust]
repositories = ["C:\\exact\\canonical\\repository"]

Keymap values are stable action names rather than Rust enum names or shell commands. The supported groups are motion.*, pane.*, context.*, operation.*, selection.*, mutation.*, sync.*, diff.*, repository.refresh|info, search.*, palette.open, clipboard.copy, file.edit, and app.*. Diff controls include diff.toggle-layout, diff.toggle-whole-file, diff.toggle-whitespace, and diff.toggle-word-wrap. Sequences may contain bare characters and tokens such as <Esc>, <Space>, <C-h>, <C-S-l>, and <PageDown>. Unknown actions, malformed keys, normalized duplicates, ambiguous prefixes, and sequences longer than eight keys reject the complete source with its path and invalid value shown. Esc is reserved for cancel/step-back and cannot be overridden or used as a sequence prefix. Configured <S-Tab> is normalized to the runtime BackTab representation.

mutation.toggle-all is the configurable bulk stage/unstage action (default S), replacing the unreleased mutation.stage-all action name. operation.skip remains configurable but has no default direct shortcut. To restore the old shortcut explicitly, set "S" = "operation.skip" in [keymap].

terminal is the default theme. It uses terminal default/reset foreground and background colors plus the terminal's ANSI palette entries 0-15 for semantic accents, diffs, history, syntax, and icons. color-mode still controls color enablement. In Kterm true-color sessions, kgit also accepts the strict, bounded KTERM_PALETTE v1 export (1: followed by FG, BG, CURSOR, ACCENT, SURFACE, and ANSI0-ANSI15 as exactly 21 uppercase six-digit RGB fields). It uses those concrete anchors for subdued theme-aware diff, selection, status, command surfaces, and contrast-safe inactive frames. It chooses foregrounds by computed contrast, supporting both light and dark terminal themes. Malformed or unsupported exports are ignored. Outside true-color palette adoption, the terminal theme continues to use terminal defaults and ANSI entries 0-15, including the attribute-based diff fallback described above; NO_COLOR always wins.

catppuccin-mocha preserves the previous fixed RGB palette exactly and adapts it deterministically for true-color, ANSI-256, ANSI-16, and no-color output.

Everforest is available through six stable names: everforest-dark-hard, everforest-dark-medium, everforest-dark-soft, everforest-light-hard, everforest-light-medium, and everforest-light-soft. Each uses the corresponding fixed upstream foreground, accent, surface, semantic-tint, status-line, and ANSI palette. True-color uses those values directly; ANSI-256, ANSI-16, and no-color use the same deterministic degradation paths as Catppuccin. KTERM_PALETTE is consumed only by the terminal theme and never changes a fixed theme.

Kterm grid-shape records require concrete RGB values, so shapes remain enabled for fixed themes and for true-color terminal sessions with a valid KTERM_PALETTE; otherwise they are omitted. The complete VT interface remains visible.

Everforest palette data is derived from Everforest by sainnhe at commit 85a86eb62409e3ec88713bff3d1b9d7374e112e4, Copyright (c) 2019 sainnhe, and is used under the MIT License. See the complete local third-party notice; the pinned upstream license is also available.

Command palette, mouse, and kterm

Press ? for the contextual command palette. j/k selects and Enter runs a command; every command is clipped to one clickable row, including narrow screens. Right-click opens the same palette for the pointed pane. Hover updates only the status hint. Click, wheel, Shift-wheel, Shift/Ctrl selection, row drag, scrollbar track click, and captured thumb drag all resolve through the same typed actions as keyboard input. Mouse input waits for any worker-triggered frame so it never resolves against the preceding hit map.

Ctrl-h/j/k/l navigates kgit's visible pane grid. At an edge it asks kterm to continue when KTERM_PANE_NAVIGATION=1. Ctrl-Shift-h/j/k/l moves kgit's nearest bounded divider, then asks kterm to continue when KTERM_PANE_RESIZE=1. Claims occur only on the alternate screen and are balanced across suspend, interactive child handoff, panic, and exit. Before claiming, kgit capability-checks and pushes Kitty keyboard disambiguation (CSI > 1 u), then releases the claim and pops that stack entry in reverse order. On Windows, Crossterm's event backend cannot decode progressive keyboard input, so kgit leaves seamless pane controls unclaimed. Kterm's ConPTY transport continues to provide native key events independently.

In the wide layout, the master pane starts at the smallest width that fits its content, capped at half the workspace. Drag the divider to resize Preview, or use Shift-Left/Right. The Ctrl-Shift-h/j/k/l bindings remain available for seamless kterm pane resizing.

When kterm advertises KTERM_GRID_SHAPES=1, kgit draws its complete VT frame first and then adds bounded rounded tabs, buttons, focused surfaces, and scrollbar thumbs. It also publishes the repository directory, explicit y clipboard copies, and operation progress only to detected kterm sessions. Tiny or zero-sized shape targets are omitted. OSC 7 percent-encodes path bytes (including semicolons), while Windows OSC 9;9 is validated and bounded independently; unsupported metadata is omitted with a nonfatal status diagnostic. Shapes and progress are cleared on lifecycle transitions, and progress is cleared again after each terminal reacquire before its cache is reset. Generic terminals retain the full text controls, borders, scrollbars, status, and command palette.

The initial tree-sitter language inventory and its exact kvim parity source are documented in docs/syntax-language-parity.md.

Set KGIT_LOG to a file path to capture startup diagnostics. Diagnostics are disabled otherwise, so they never write into the terminal frame.