docs: add /diff command and auto theme detection documentation#4699
Merged
Conversation
added 2 commits
June 2, 2026 17:31
Add section 1.8 documenting the /diff interactive diff viewer, including source picker (Current + per-turn diffs), keyboard shortcuts, dialog example, and non-interactive mode output format. Also add /diff entry to the 1.2 Interface and Workspace Control table.
Document the 'auto' theme setting and its detection fallback chain (COLORFGBG → OSC 11 → macOS system appearance → default dark), including notes for tmux/SSH environments.
Contributor
📋 Review SummaryThis PR adds documentation for the 🔍 General Feedback
🎯 Specific Feedback🔵 Low
✅ Highlights
|
Contributor
Code Coverage Summary
CLI Package - Full Text ReportCore Package - Full Text ReportFor detailed HTML reports, please see the 'coverage-reports-22.x-ubuntu-latest' artifact from the main CI run. |
Collaborator
|
Thanks for the PR, @BZ-D! Template: the body uses Direction: solid. Approach: scope feels right. Two features, two doc sections, no overreach. Nothing to cut. Moving on to code review. 🔍 中文说明感谢贡献，@BZ-D！ 模板： PR body 用了 方向： 没问题。 方案： 范围合理，两个功能各补一节，没有多余的东西。 进入代码审查 🔍 — Qwen Code · qwen3.7-max |
Collaborator
|
Code review: The docs are well-structured and the content matches the code. The auto theme detection section accurately describes the async fallback chain (COLORFGBG → OSC 11 → macOS → default dark) — verified against One accuracy fix needed: the Section renumbering (1.8→1.9→1.10→1.11) is correct. The Testing: Docs-only PR, no functional changes. Before/After: N/A. 中文说明代码审查： 文档结构好，内容与代码一致。Auto theme detection 部分准确描述了异步回退链（COLORFGBG → OSC 11 → macOS → default dark），已对照 需要修一个准确性问题： 章节重新编号（1.8→1.9→1.10→1.11）正确。 测试： 纯文档 PR，无功能变更。Before/After: N/A。 — Qwen Code · qwen3.7-max |
Collaborator
|
Overall this is a clean docs PR that fills a real gap — The one blocker is the checkpointing default: saying "on by default" when it's actually off will send users down a confusing path ("I have per-turn diffs but no checkpointing?"). Once that's flipped to "off by default" (or "disabled by default"), this is good to merge. 中文说明整体来说这是一个干净的文档 PR，填补了真实的空白—— 唯一的卡点是 checkpointing 默认值：写 "on by default" 但实际是关的，会让用户困惑（"我有 per-turn diffs 但没有 checkpointing？"）。改成 "off by default" 或 "disabled by default" 之后就可以 merge 了。 — Qwen Code · qwen3.7-max |
pomelo-nwu
requested changes
Jun 2, 2026
pomelo-nwu
left a comment
Collaborator
There was a problem hiding this comment.
Needs the checkpointing default fix — see notes above. Once that's flipped, LGTM. 🙏
Checkpointing defaults to false, not true. Updated from "on by default" to "disabled by default" per reviewer feedback.
pomelo-nwu
previously approved these changes
Jun 2, 2026
doudouOUC
reviewed
Jun 2, 2026
doudouOUC
left a comment
Collaborator
There was a problem hiding this comment.
Documentation is well-structured overall. Found two factual inaccuracies that should be fixed before merging (non-interactive mode behavior and file checkpointing default), plus a few smaller items.
Comment on lines
+254
to
+263
| **Non-interactive mode:** | ||
|
|
||
| In headless (`--prompt`) or non-interactive contexts, `/diff` prints a plain-text summary of the working tree vs HEAD. Per-turn navigation is not available. | ||
|
|
||
| ``` | ||
| 3 files changed, +45 / -12 | ||
| +30 -8 src/utils/parser.ts | ||
| +12 -2 src/utils/parser.test.ts | ||
| +3 -2 README.md | ||
| ``` |
Collaborator
There was a problem hiding this comment.
This section describes a feature that doesn't exist. In nonInteractiveCliCommands.ts:128-131, all dialog commands (including /diff) are uniformly rejected with:
Dialog 'diff' cannot be opened in non-interactive mode.
The plain-text fallback described here is not implemented. This will mislead users trying to use /diff in CI pipelines or scripts.
Suggestion: either remove this section entirely, or replace it with a note that /diff is only available in interactive mode.
Collaborator
There was a problem hiding this comment.
My mistake — verified that /diff does have a plain-text fallback in non-interactive mode. The docs are accurate here, no change needed.
|
|
||
| The file list displays per-file stats (lines added/removed) with tags for special states (`new`, `deleted`, `untracked`, `binary`, `truncated`, `oversized`). Press Enter on a file to view its inline diff with syntax-highlighted hunks. | ||
|
|
||
| Per-turn diffs require [file checkpointing](./checkpointing) to be enabled (disabled by default). When checkpointing is off, only the "Current" source is available. |
Collaborator
There was a problem hiding this comment.
Two issues here:
-
"disabled by default" is incorrect.
fileCheckpointingEnableddefaults totruein interactive CLI mode (config.ts:1067-1069:!params.sdkMode && (params.interactive ?? false)). So per-turn diffs work out of the box for most users. -
The link points to a different feature.
./checkpointingdocuments the/restorecheckpoint system (controlled bygeneral.checkpointing.enabled, which IS disabled by default). That's a separate mechanism fromfileCheckpointingEnabledwhich controls per-turn diffs.
Suggestion: change to something like "Per-turn diffs require file checkpointing, which is enabled by default in interactive mode."
Collaborator
There was a problem hiding this comment.
Fixed in fc9c529 — "(on by default in interactive mode)" is accurate now. The ./checkpointing link is slightly off-target (that page covers /restore checkpoints, not fileCheckpointingEnabled), but it's the closest docs page available, so fine to keep.
| | `/clear` | Clear terminal screen content | `/clear` (shortcut: `Ctrl+L`) | | ||
| | `/context` | Show context window usage breakdown | `/context` | | ||
| | → `detail` | Show per-item context usage breakdown | `/context detail` | | ||
| | `/diff` | Open an interactive diff viewer showing uncommitted changes and per-turn diffs. Use ←/→ to switch between current git diff and individual conversation turns, ↑/↓ to browse files | `/diff` | |
Collaborator
There was a problem hiding this comment.
Nit: this description is much longer than every other entry in the table (~170 chars vs ~40 chars for others), which makes the table very wide and hard to read in rendered markdown. The keyboard shortcut details are already covered in section 1.8 below.
Suggestion: shorten to something like Open interactive diff viewer for uncommitted and per-turn changes
|
|
||
| | Priority | Method | Platform | How it works | | ||
| | -------- | ----------------------- | ---------- | ---------------------------------------------------------------------------------------------------- | | ||
| | 1 | `COLORFGBG` | All | Reads the `COLORFGBG` environment variable (set by terminals like iTerm2, rxvt, Konsole) | |
Collaborator
There was a problem hiding this comment.
Nit: the code comment in detect-terminal-theme.ts:178 lists COLORFGBG as set by "rxvt, xterm, iTerm2, Konsole" — xterm is missing from this list.
| | `↑` / `↓` | Navigate file list | | ||
| | `j` / `k` | Navigate file list (vim-style) | | ||
| | Enter | View inline diff for selected file | | ||
| | `←` / Esc | Return to file list from inline diff view | |
Collaborator
There was a problem hiding this comment.
Nit: DiffDialog.tsx:181 also handles backspace for returning from detail view. Consider adding it: `←` / Backspace / Esc
File checkpointing (used by per-turn diffs and /rewind) defaults to enabled in interactive mode. Session checkpointing (/restore) is the one that defaults to disabled. Corrected the description accordingly.
pomelo-nwu
approved these changes
Jun 2, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/diffcommand documentation tocommands.md— interactive diff viewer with per-turn navigation, keyboard shortcuts, dialog example, and non-interactive mode outputthemes.md—"auto"setting, detection fallback chain (COLORFGBG → OSC 11 → macOS system appearance → default dark), and tmux/SSH notesTest plan
/diffsection renders correctly in the docs sitecommands.mdis consistent after insertion