A jj-native TUI for Jujutsu VCS

jk is a jj-native terminal UI for inspecting changes, previewing local mutations, capturing command output, and recovering through Jujutsu's operation log without losing terminal context.

Install

Install from Josh's Homebrew tap on macOS, or use cargo-binstall for prebuilt Rust release archives on macOS and Linux.

The manual covers the 0.3.0 source, including rebase, bookmarks, remotes, and workspace management. Installed releases may expose fewer commands; check jk --version.

Homebrew on macOS

brew trust --formula joshka/tap/jk
brew install joshka/tap/jk

The trust step follows the joshka/homebrew-tap install pattern.

cargo-binstall

cargo binstall jk

Uses the published jk binary archive when your platform is supported.

From source

cargo install jk --locked

Falls back to a normal crates.io build when you want Cargo to compile locally.

Workflow

Keep the jj TUI in place.

The first screen is the view you would reach for with jj log, kept open in a terminal you can refresh after another tool changes the repository. From there, jk opens focused views, prompts, and previews only when the workflow asks for them.

Inspect without losing place

Move from log to show, diff, status, or evolog, then return to the same selected change.

Preview before writing

Inspect operands and the exact jj command before confirming rebase, squash, restore, bookmarks, and remote operations.

Recover from operations

Command History and Operation Log keep command output, operation ids, undo, redo, and jj op views close by.

Design constraints

jj output first, interaction around it.

jk follows Jujutsu's command model and configuration first. It starts from the output you already trust: your revsets, templates, graph style, colors, and diff preferences. Interactivity should make that output easier to keep open, inspect, and act from.

The action menu names the affected object and distinguishes immediate actions from previews. Command History retains the executed command and diagnostics, while Operation Log provides the repository's recovery history.

Command fidelity

jk keeps rendered jj output as the source of truth, then adds navigation, previews, and recovery around it.

Presentation fidelity

Normal log and diff views preserve jj configuration for default commands, revsets, templates, graph style, colors, and diff formats.

Focused screens

The default stays compact: one primary view, with separate screens or overlays for details, diffs, prompts, and previews.

Safe recovery

The mutation loop keeps command history, operation log, undo, redo, and operation details beside every write.

Diff review

Review diffs without leaving jj output.

jk diff opens rendered jj diff output for the current change, one revision, or an explicit from/to range. Search works across rendered output; color-words diffs support file navigation, folding, and a file-list overlay. View Options select summary, stat, types, name-only, Git, or color-words output. Hunk navigation and the Git-format file list are known gaps documented in the manual.

Recent polish

Smoother log navigation in real jj workspaces.

Inspect sibling workspaces, refresh stale workspace metadata, and drill into elided graph lanes. The manual records the tested behavior and recovery paths, including the current automatic container-startup limitation.

Explicit workspace startup

Use jk -R default from an outer jj container. Automatic child-workspace detection has a known compatibility issue with jj 0.45.1.

Working-copy snapshots

Normal log loads and refreshes snapshot file edits like jj log. Run Options can skip the working-copy snapshot for one pending command.

Graph drill-in

Elided ~ rows drill into the graph lane they belong to, keep selection when returning, and keep inline expansion connected to the surrounding graph.

Short command targets

Navigation commands use shortened revision IDs while keeping full change IDs for selection and mark identity.

Usage

Current source workflows.

The 0.3.0 source includes rebase, whole-change squash and restore, bookmarks, remotes, and workspace management. The manual explains each action and its recovery path; your installed release may have a smaller command surface.

Usage guide Roadmap doc

Inspection

Enter, d, and v inspect the selected change; s shows working-copy status.

Diff review

Move by line and page, search rendered output, and navigate or fold files in color-words diffs. Switch formats with V; hunk navigation is a known gap.

Command mode

: runs direct jj commands, captures stdout/stderr, keeps failures inspectable, and records the command in history.

Safe previews

a opens the action menu. Rebase, squash, restore, bookmarks, and remote operations preview the command before execution; new, edit, undo, redo, and empty abandon run immediately.

Recovery

C opens Command History and o opens Operation Log or the operation created by a confirmed command.

Workspaces

W lists sibling jj workspaces, refreshes stale workspaces, and opens selected-workspace log/status/diff views.

Commands

CLI surface follows jj shapes.

Bare jk follows jj's configured default command when it is log-like enough for semantic navigation. Explicit commands keep canonical jj argument shapes visible so the TUI, command history, previews, and docs can all talk about the same command.

In the TUI, : runs direct jj commands and keeps output in Command History. The action menu distinguishes immediate actions from confirmations. New, Edit, Undo, Redo, and empty Abandon run immediately; command mode runs on Enter.

jk

Open the configured default jj command when it is log-like enough for navigation.

jk log

Open the explicit log path.

jk log -T <template>

Render with a selected jj log template while keeping semantic navigation stable.

jk diff -r <revision>

Inspect one revision using the canonical jj diff shape.

jk diff --from A --to B

Compare two revision trees using explicit --from and --to operands.

jk show <revision>

Inspect selected-change details with jj show output.

jk status

Inspect repository status without leaving the focused TUI flow.

jk workspaces

List sibling jj workspaces and open workspace-scoped log, status, and diff views.

jk -R /path/to/repo -n 20

Carry repository and limit context through generated jj commands.

Docs

Learn the current jk TUI.

Follow a task from its starting repository through the command, visible result, and recovery. The manual pairs source-checked instructions with recorded workflows and a searchable command reference for the 0.3.0 source surface.

README Read the manual Changelog

Release boundaries

Command History is in-memory for the active jk session.
Rebase, squash, restore, bookmarks, fetch, and workspace management have native workflows. Push is dry-run only.
Partial-change editing, native split, conflict resolution, and foreground tool handoff remain gaps.
Public media is generated from Betamax tapes so release images can be refreshed independently of source code.

Motivation

Keep your jj view in context.

jk starts from a common jj workflow: keep jj log visible while the repository changes somewhere else. Without a refreshable view, you quit the log, rerun it, and find your place again.

The TUI should still feel like jj. It should use your revsets, colors, templates, graph style, and output preferences instead of replacing them with a parallel display model. The first job is to keep configured command output on screen and make it easier to navigate.

That requirement keeps the layout small. jk starts from one compact view and adds detail when you ask for it: inline expansion, detail screens, overlays, prompts, and command previews. Split layouts can be useful, but the default should not require pane focus, pane resizing, or scanning several regions just to keep up with repository state.

The release snapshot proves that command-shaped model for inspection, command mode, command history, operation recovery, workspaces, and the first safe mutation previews. Larger workflows such as rebase, refs, remotes, and persistent history come after this baseline is shipped.

Media

Release media

These captures show the current release surface. Final public GIFs are generated from Betamax tapes so the README, crates.io, website, and release notes can reuse the same evidence.

Homepage workflow animation

jk-homepage-manual-v0.3.0-r3.gif

Open