Skip to content

jk manual

UX findings

Known limitations and proposed changes for jk 0.3.0.

These findings describe the 0.3.0 source with jj 0.45.1. Each includes the observed behavior, available recovery, and a proposed change with acceptance criteria. Evidence identifies code inspection and recorded reproductions separately.

The proposed changes have not been implemented.

  1. UX-01 · Foreground terminal tools have no handoff lifecycle
  2. UX-02 · Push preview cannot complete publication
  3. UX-03 · File and hunk navigation cannot select mutation content
  4. UX-04 · Operand previews require matching hashes to hidden context
  5. UX-05 · Abandon diff overrides jj format and styles
  6. UX-06 · Modal backgrounds retain active cursor emphasis
  7. UX-07 · Rebase search cannot find destinations outside the current log
  8. UX-08 · Operation inspection errors are hidden
  9. UX-09 · Command mode returns to stale repository content
  10. UX-10 · Workspace failure discards the retry draft
  11. UX-11 · Bookmark action mode is invisible
  12. UX-12 · Workspace inspection does not label arbitrary command scope
  13. UX-13 · Retry editing requires deleting the command tail
  14. UX-14 · Bookmark mutation success has no factual completion cue
  15. UX-15 · Captured output clips the execution command and long lines
  16. UX-16 · Escape quits inspection instead of returning
  17. UX-17 · Diff navigation requires incompatible file and hunk headers
  18. UX-18 · Container startup misses current jj no-working-copy output

Foreground terminal tools have no handoff lifecycle

UX-01 · P2 support boundary

User concern: Finish or reshape work without losing repository context.

Operation
commit, split, absorb, resolve, describe, external command
Interaction
Enter a command that needs an editor, interactive selector, or merge tool.
Observed result
Captured execution closes stdin and pipes output; there is no foreground-terminal handoff. Long commands block input; separate-window GUI tools are a different execution case.
Current recovery
Use an explicitly noninteractive command, or exit jk and run the tool, then reopen and verify.
Proposed improvement

Add one foreground tool handoff lifecycle and separate cancellable captured execution.

Acceptance criteria

  • Restore terminal/input on success, failure, cancellation, and missing executable.
  • Record exact repository/command and exit or interruption status.
  • Refresh affected state even when a tool changes the repository before failing.
  • Prove selected and remaining content for interactive split.
Evidence and review status

Push preview cannot complete publication

UX-02 · P2 support boundary

User concern: Publish the bookmark just reviewed.

Operation
git push --dry-run; git push
Interaction
Choose a bookmark and remote, review and execute push dry-run.
Observed result
Dry-run cannot publish, and :git push is rejected. Publication requires re-entering the reviewed bookmark and remote through ! or a shell.
Current recovery
Cancel before dry-run or leave the native flow to publish; verify remote refs afterward.
Proposed improvement

Keep bookmark, remote, and proposal through a distinct publish confirmation and result.

Acceptance criteria

  • Dry-run and cancellation leave the disposable remote unchanged.
  • Confirmation publishes exactly the selected bookmark.
  • Changed local/remote state refreshes the proposal.
  • Rejection retains useful context; remote recovery is not labeled local Undo.
Evidence and review status

File and hunk navigation cannot select mutation content

UX-03 · P2 support boundary

User concern: Move or discard one part of a change.

Operation
squash, restore, commit, split
Interaction
Inspect a file or hunk, then open squash or restore.
Observed result
Native mutations affect whole changes/all paths; navigation does not select mutation content.
Current recovery
Cancel and use explicit noninteractive filesets or an external interactive jj tool; inspect and Undo a completed mistake.
Proposed improvement

Share explicit content selection across commit/split and squash/restore, including message choice.

Acceptance criteria

  • Show selected content and content left behind.
  • Assert exact content for mixed files, multiple hunks, rename/deletion, and conflicts.
  • Empty selection and cancellation mutate nothing.
  • Unselected bytes remain unchanged; Undo restores the prior result.
Evidence and review status

Operand previews require matching hashes to hidden context

UX-04 · P2 confirmed

User concern: Confirm which work will move and where.

Operation
rebase, squash, restore, ordered parent/comparison operands
Interaction
Choose roles and review the exact command, including at 60 columns.
Observed result
Preview roles use full commit IDs without descriptions; compact rebase controls show unexplained key lists. After multi-parent New, the cursor moves to the new working copy but the parent marks remain; another New reuses those parents.
Current recovery
Cancel, inspect the changes, and reopen with the intended roles.
Proposed improvement

Show change IDs and descriptions beside source/destination roles. Expand compact role controls at narrow widths and label order where it changes the command.

Acceptance criteria

  • Identify source, destination, scope, and ordering from the active surface.
  • Review all nine rebase forms at 60 columns.
  • Distinguish similarly described changes and ordered marks.
  • Never silently truncate operative identities or command text.
  • After multi-parent New, make the operands of another immediate New clear; choose and verify an explicit policy for retaining or clearing marks.
Evidence and review status

Abandon diff overrides jj format and styles

UX-05 · P2 confirmed

User concern: Inspect content before abandoning using familiar jj output.

Operation
abandon; diff
Interaction
Open View diff from the abandon confirmation.
Observed result
The query forces Git format and color never; jk repaints plus/minus lines and wraps patch lines.
Current recovery
Return to the decision and cancel to inspect in the normal Diff view.
Proposed improvement

Reuse the normal diff presentation contract or scoped Diff view that returns to the same decision.

Acceptance criteria

  • Honor custom colors and non-Git default format.
  • Preserve long code lines with navigation rather than prose wrapping.
  • Return to the same cancel-default decision after scrolling.
  • Compare pixels and styled spans at light/dark/narrow sizes.
Evidence and review status

Modal backgrounds retain active cursor emphasis

UX-06 · P3 confirmed

User concern: Know where the next key will go.

Operation
modal selection, confirmation, description, Run Options
Interaction
Open a dialog over the log.
Observed result
The graph cursor and dialog focus both look active; only the dialog receives input.
Current recovery
Escape returns to the preserved graph selection; routing still targets the active mode.
Proposed improvement

Render overlay backgrounds as inactive while retaining marks, cursor location, and jj colors.

Acceptance criteria

  • Only the active surface uses focus styling.
  • Retain actual graph context and opaque filled dialog.
  • Compare help/actions/describe/abandon/rebase/options/previews at dark/light/narrow sizes.
Evidence and review status

Rebase search cannot find destinations outside the current log

UX-07 · P2 source confirmed

User concern: Move work onto a revision hidden by the current filter or limit.

Operation
rebase
Interaction
Open the destination chooser and search for a missing revision.
Observed result
Only loaded log candidates are searched; no distinct candidate can prevent opening; multiple marks are rejected.
Current recovery
Cancel, widen the log revset/limit, restore source selection, and reopen.
Proposed improvement

Retain frozen source roles while resolving an explicit destination or a broader search.

Acceptance criteria

  • Resolve destinations hidden by revset and log limit.
  • Distinguish invalid, missing, and ambiguous expressions.
  • Preserve input and source selection after failure.
  • Explain search Escape versus dialog Escape.
Evidence and review status

Operation inspection errors are hidden

UX-08 · P2 source confirmed

User concern: Understand why an operation detail did not open.

Operation
op show, op diff
Interaction
Open an operation from operation log or Command History while jj lookup fails.
Observed result
The error becomes AppTransition::Continue with no visible failure.
Current recovery
Inspect Command History for the failed lookup; correct the cause and retry.
Proposed improvement

Surface the attempted operation and diagnostic while retaining selection and a retry path.

Acceptance criteria

  • Fixture failure remains visible on every caller surface.
  • Preserve full stderr in history/details.
  • Retry opens the intended operation without changing selection.
  • Operation inspection from Command History remains usable with a stale on-disk working copy, or reports its failure in that view without silently updating the working copy.
Evidence and review status

Command mode returns to stale repository content

UX-09 · P2 source confirmed

User concern: Verify the command just completed.

Operation
arbitrary jj mutations and external commands
Interaction
Run a noninteractive mutation, then return from captured output.
Observed result
RefreshPlan::None leaves the prior view unchanged; command-output refresh gives a Command History limitation.
Current recovery
Return to the repository view and explicitly refresh before making another decision.
Proposed improvement

Refresh after command return or mark affected views stale with one direct repository refresh action.

Acceptance criteria

  • Verify describe, commit, duplicate, restore, and external file-edit results against jj.
  • Refresh partial-effect failures as well as success.
  • Retain captured output and operation links.
  • Preserve read-only command navigation.
Evidence and review status

Workspace failure discards the retry draft

UX-10 · P2 runtime and source confirmed

User concern: Correct a path or name without reentering the form.

Operation
workspace add, workspace rename
Interaction
Submit an existing destination or colliding name, then try to correct it.
Observed result
A failed add or rename discards the draft and shows only the first error line. Workspace confirmation uses y to execute, while other command previews use y to copy.
Current recovery
Reopen add/rename and re-enter the intended path/name. For the full diagnostic, open Command History, press Home to select the latest failed command, then Enter; initial selection may be an earlier operation-bearing success.
Proposed improvement

Retain the editable draft and diagnostics after failure; apply a consistent confirmation key contract.

Acceptance criteria

  • Failed add/rename retain editable input and complete diagnostics.
  • A copy key cannot unexpectedly execute another preview.
  • Preserve selected workspace after failure.
  • Opening error details selects the failed command rather than an earlier successful command with an operation ID.
Evidence and review status

Bookmark action mode is invisible

UX-11 · P2 runtime and source confirmed

User concern: Discover actions available on the current bookmark screen.

Operation
bookmark and remote actions
Interaction
Open B, then a; attempt to use the displayed bookmark screen.
Observed result
Bookmarks uses Workspaces context and lacks action-menu overlay rendering; the hidden action mode intercepts keys. Native ? help has a separate route and renders correctly.
Current recovery
Close the menu and use the direct bookmark keys.
Proposed improvement

Render a bookmark-specific action menu with the correct executable action set and safety cues.

Acceptance criteria

  • The action-menu overlay becomes visibly active when opened; retain the working native ? help.
  • Every shown bookmark action routes to implemented bookmark/remote behavior.
  • No workspace-only entries appear in bookmark help/actions.
  • Actual Workspaces help and actions remain correct.
Evidence and review status

Workspace inspection does not label arbitrary command scope

UX-12 · P1 runtime and source confirmed

User concern: Avoid changing a different working copy from the one being inspected.

Operation
arbitrary jj mutation or executable from sibling workspace inspection
Interaction
Inspect sibling status, then enter :describe -m changed @.
Observed result
The command still targets the startup repository while the screen shows sibling workspace content. The prompt omits the execution repository. The corrected CI recording proves default changes, scratch stays unchanged, and native Undo restores default exactly.
Current recovery
Verify execution repository before running; inspect operation history and Undo in the affected repository if needed.
Proposed improvement

Show execution workspace/repository before every arbitrary command; retain startup scope or provide an explicit scoped handoff.

Acceptance criteria

  • Two sibling fixture workspaces have distinct working-copy descriptions.
  • Prompt, command, output, history, and actual changed working copy agree.
  • Exercise log/status/diff entry points and relative paths through !.
  • Never silently switch execution policy based on the view.
Evidence and review status

Retry editing requires deleting the command tail

UX-13 · P3 source confirmed

User concern: Correct one operand in a failed command.

Operation
command editing and retry
Interaction
Open edit from captured output and try to move to a middle operand.
Observed result
Input supports append, Backspace, and clear-all; cursor and word movement are ignored.
Current recovery
Backspace through the suffix or Ctrl-u and reenter the command.
Proposed improvement

Reuse a cursor-based text input model with word movement, deletion, Unicode, and horizontal scrolling.

Acceptance criteria

  • Change a middle operand without changing the suffix.
  • Retry preserves original input.
  • Assert exact argument vector after Unicode editing and scrolling.
Evidence and review status

Bookmark mutation success has no factual completion cue

UX-14 · P3 source confirmed

User concern: Know whether the bookmark changed.

Operation
bookmark create, move, delete
Interaction
Confirm the mutation and return to the refreshed list.
Observed result
Success refreshes without showing prepared success_message; status clears unless selection disappeared.
Current recovery
Compare the target/list and inspect Command History.
Proposed improvement

Show the bookmark/target result, preserve useful selection, and link Command History.

Acceptance criteria

  • Verify create in a long list, move, and delete.
  • Separate command success from subsequent refresh failure.
  • Keep concise feedback visible without obscuring repository content.
Evidence and review status

Captured output clips the execution command and long lines

UX-15 · P2 runtime and source confirmed

User concern: Inspect the full command and diagnostic before deciding what to do next.

Operation
Captured jj or external command; command-history details
Interaction
Run or inspect a command with a long repository path or quoted operands.
Observed result
Long repository paths hide the command and operands beyond the right edge. Rendered output has vertical scrolling only; the full command remains available through Command History copy or edit/retry.
Current recovery
Copy the recorded command from Command History, or edit/retry to retain the original arguments; recorded data is intact.
Proposed improvement

Wrap command metadata or make it scrollable, and provide an explicit full-text or horizontal navigation path for raw output.

Acceptance criteria

  • Show the whole execution command with long paths and quoted operands at 60 and 104 columns.
  • Preserve stdout/stderr/code whitespace while making long lines inspectable.
  • Copy exact arguments and exclude chrome.
Evidence and review status

Escape quits inspection instead of returning

UX-16 · P2 runtime confirmed

User concern: Return from command output or nested inspection without losing navigation context.

Operation
captured jj/external command and workspace/operation inspection
Interaction
Press Escape after reading output, using the same key that dismisses a prompt or preview.
Observed result
The shared key mapping treats Escape as Quit; static rendered, workspace and operation views propagate it to application exit. Backspace pops one view. Failed recordings caught unintended exit before recovery.
Current recovery
Reopen jk and reconstruct the view stack; use Backspace to return one level while the application is still open.
Proposed improvement

Adopt one visible back/cancel contract for nested views, reserving an explicit quit action for leaving the application. Preserve appropriate prompt cancellation and top-level exit behavior.

Acceptance criteria

  • From nested output, history details, workspace status/log/diff and operation show/diff, the displayed Back key returns exactly one level without quitting.
  • Prompt cancel and preview cancel leave repository state unchanged.
  • An explicit Quit key remains available and is distinguished from Back in help/footer.
  • Capture a command failure, return to its origin, retry, and verify recovery without restarting jk.
Evidence and review status

Diff navigation requires incompatible file and hunk headers

UX-17 · P2 runtime and source confirmed

User concern: Navigate the files and hunks visible in the patch.

Operation
diff file listing, file jumps/folds, hunk jumps/folds
Interaction
Open a real --git diff and its file picker, or try hunk navigation on real --color-words output.
Observed result
The Git patch is populated but the file dialog says No files in this diff. File parsing recognizes color-words headers only; hunk parsing then requires @@ inside recognized sections. Git provides @@ without recognized file headers, and color-words provides file headers without @@. The recording that claimed successful hunk folding lacked a folded marker and is rejected as tutorial evidence.
Current recovery
Use color-words for supported file navigation/folding, scroll/search raw Git output, and inspect hunks outside the advertised navigation until the parser is corrected.
Proposed improvement

Build file/hunk navigation from a format-aware structure covering actual jj output, or derive semantic anchors separately while retaining the chosen patch rendering. Disable or explain unsupported controls rather than reporting an empty file set.

Acceptance criteria

  • Use unmodified real jj --git and --color-words output fixtures; avoid synthetic mixed-format headers.
  • List and jump among multiple files for each supported format, including renames and binary changes.
  • Hunk navigation/folding reaches distinct real hunks and visibly preserves context; formats without hunk anchors clearly state the limit.
  • Switch format and refresh while preserving valid selection; no populated patch is described as having no files.
Evidence and review status

Container startup misses current jj no-working-copy output

UX-18 · P2 runtime and source confirmed

User concern: Start jk from a shared repository container and inspect its default child workspace.

Operation
startup repository resolution
Interaction
Run bare jk in a no-working-copy container with a default child using tested jj 0.45.1.
Observed result
With jj 0.45.1, status prints "No working copy." but the resolver matches "No working copy" without the period. It skips child selection. Explicit -R default works.
Current recovery
Run jk -R default from the container or change into the intended child workspace before launching.
Proposed improvement

Detect the no-working-copy state through a stable structured capability when available; otherwise normalize the specific supported diagnostic conservatively and preserve other errors.

Acceptance criteria

  • Exercise actual jj 0.45.1 output with trailing punctuation and supported older variants.
  • A default child is chosen deterministically; fallback child selection is verified when no default exists.
  • An explicit -R remains authoritative.
  • Unrelated jj errors never trigger silent selection of another repository.
  • Capture startup from container and child plus a mutation-scope assertion in the resolved workspace.
Evidence and review status