Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: improve wt list docs with colored CI dots and progressive display

Maximilian Roosc8c49a63e6aa
diff --git a/README.md b/README.md
index d805b0f41..b7f7abe11 100644
--- a/README.md
+++ b/README.md
@@ -835,6 +835,8 @@ Global Options:
Show all worktrees with their status. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
+The table renders progressively: branch names, paths, and commit hashes appear immediately, then status, divergence, and other columns fill in as background git operations complete. CI status (with `--full`) requires network requests and may take longer.
+
```
### Examples
@@ -863,46 +865,12 @@ Output as JSON for scripting:
wt list --format=json
```
-### Status Symbols
-
-Symbols appear in the Status column in this order:
-
-**Working tree state:**
-- `+` — Staged files
-- `!` — Modified files (unstaged)
-- `?` — Untracked files
-- `✖` — Merge conflicts
-- `↻` — Rebase in progress
-- `⋈` — Merge in progress
-
-**Branch state:**
-- `⊘` — Would conflict if merged to main (`--full` only)
-- `≡` — Matches main (identical contents)
-- `_` — No commits (empty branch)
-
-**Divergence from main:**
-- `↑` — Ahead of main
-- `↓` — Behind main
-- `↕` — Diverged from main
-
-**Remote tracking:**
-- `⇡` — Ahead of remote
-- `⇣` — Behind remote
-- `⇅` — Diverged from remote
-
-**Other:**
-- `⎇` — Branch without worktree
-- `⌫` — Prunable (directory missing)
-- `⊠` — Locked worktree
-
-Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).
-
### Columns
| Column | Shows |
|--------|-------|
| Branch | Branch name |
-| Status | Compact symbols (see above) |
+| Status | Compact symbols (see below) |
| HEAD± | Uncommitted changes: +added -deleted lines |
| main↕ | Commits ahead/behind main |
| main…± | Line diffs in commits ahead of main (`--full`) |
@@ -914,13 +882,44 @@ Rows are dimmed when the branch has no marginal contribution (`≡` matches main
| Message | Last commit message (truncated) |
The CI column shows GitHub/GitLab pipeline status:
-- `●` green — All checks passed
-- `●` blue — Checks running
-- `●` red — Checks failed
-- `●` yellow — Merge conflicts with base
-- `●` gray — No checks configured
-- blank — No PR/MR found
-- dimmed — Stale (unpushed local changes)
+
+| Indicator | Meaning |
+|-----------|---------|
+| `●` green | All checks passed |
+| `●` blue | Checks running |
+| `●` red | Checks failed |
+| `●` yellow | Merge conflicts with base |
+| `●` gray | No checks configured |
+| blank | No PR/MR found |
+
+Any CI dot appears dimmed when there are unpushed local changes (stale status).
+
+### Status Symbols
+
+Symbols appear in the Status column in this order:
+
+| Category | Symbol | Meaning |
+|----------|--------|---------|
+| Working tree | `+` | Staged files |
+| | `!` | Modified files (unstaged) |
+| | `?` | Untracked files |
+| | `✖` | Merge conflicts |
+| | `↻` | Rebase in progress |
+| | `⋈` | Merge in progress |
+| Branch state | `⊘` | Would conflict if merged to main (`--full` only) |
+| | `≡` | Matches main (identical contents) |
+| | `_` | No commits (empty branch) |
+| Divergence | `↑` | Ahead of main |
+| | `↓` | Behind main |
+| | `↕` | Diverged from main |
+| Remote | `⇡` | Ahead of remote |
+| | `⇣` | Behind remote |
+| | `⇅` | Diverged from remote |
+| Other | `⎇` | Branch without worktree |
+| | `⌫` | Prunable (directory missing) |
+| | `⊠` | Locked worktree |
+
+Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).
### JSON Output
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index f5367c1d9..ffa50f7e2 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -95,7 +95,7 @@ When adding new positioned elements:
## Command Documentation
-Command pages (e.g., `switch.md`, `merge.md`) are **generated from the CLI source code**.
+Command pages (e.g., `switch.md`, `merge.md`, `list.md`) are **generated from the CLI source code**. The **entire file** is generated — manual edits will be overwritten.
### Generation Mechanism
@@ -106,16 +106,16 @@ wt <command> --help-page > docs/content/<command>.md
```
The output combines:
-1. **Zola frontmatter** - title, weight, group metadata
-2. **Conceptual documentation** - from `after_long_help` in `src/cli.rs`
-3. **Command Reference section** - the standard `--help` output
+1. **Zola frontmatter** — title, weight, group metadata
+2. **Conceptual documentation** — from `after_long_help` in `src/cli.rs`
+3. **Command Reference section** — the standard `--help` output
### Editing Command Docs
**To update command documentation, edit `src/cli.rs`**, not the markdown files directly.
-- **Conceptual content** - Edit the `after_long_help` attribute on the command
-- **Usage/options/examples** - Edit the clap attributes (`about`, `long_about`, doc comments on args)
+- **Conceptual content** — Edit the `after_long_help` attribute on the command
+- **Usage/options/examples** — Edit the clap attributes (`about`, `long_about`, doc comments on args)
After editing, run the sync test (which auto-updates out-of-sync pages):
@@ -123,7 +123,33 @@ After editing, run the sync test (which auto-updates out-of-sync pages):
cargo test --test integration test_command_pages_are_in_sync
```
-The generated files contain this warning comment:
+### CLI and Web Compatibility
+
+Content in `after_long_help` must work in **both** the terminal (`--help`) and the web docs:
+
+- **Tables** — Work in both. Prefer tables over bullet lists for structured data.
+- **Markdown links** — Work in both (`[text](/path/)`)
+- **Code blocks** — Work in both
+- **Raw HTML** — Avoid. Renders as raw text in terminal help.
+
+### Post-Processing for Web Docs
+
+The `--help-page` generator in `src/main.rs` applies post-processing to transform CLI-friendly content into web-friendly HTML:
+
+| CLI Source | Web Output |
+|------------|------------|
+| `` ```console `` | `` ```bash `` |
+| `` `●` green `` | `<span style='color:#0a0'>●</span> green` |
+| `` `●` blue `` | `<span style='color:#00a'>●</span> blue` |
+| `` `●` red `` | `<span style='color:#a00'>●</span> red` |
+| `` `●` yellow `` | `<span style='color:#a60'>●</span> yellow` |
+| `` `●` gray `` | `<span style='color:#888'>●</span> gray` |
+
+To add web-only styling for new content, edit `colorize_ci_status_for_html()` in `src/main.rs` — not the markdown files.
+
+Similarly, `md_help::colorize_status_symbols()` applies ANSI colors for terminal `--help` output.
+
+The generated files contain this warning comment in the Command Reference section:
```html
<!-- ⚠️ AUTO-GENERATED from `wt <command> --help-page` — edit cli.rs to update -->
```
diff --git a/docs/content/list.md b/docs/content/list.md
index 588928ed7..4921eec01 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -8,6 +8,8 @@ group = "Commands"
Show all worktrees with their status. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
+The table renders progressively: branch names, paths, and commit hashes appear immediately, then status, divergence, and other columns fill in as background git operations complete. CI status (with `--full`) requires network requests and may take longer.
+
## Examples
List all worktrees:
@@ -34,46 +36,12 @@ Output as JSON for scripting:
wt list --format=json
```
-## Status Symbols
-
-Symbols appear in the Status column in this order:
-
-**Working tree state:**
-- `+` — Staged files
-- `!` — Modified files (unstaged)
-- `?` — Untracked files
-- `✖` — Merge conflicts
-- `↻` — Rebase in progress
-- `⋈` — Merge in progress
-
-**Branch state:**
-- `⊘` — Would conflict if merged to main (`--full` only)
-- `≡` — Matches main (identical contents)
-- `_` — No commits (empty branch)
-
-**Divergence from main:**
-- `↑` — Ahead of main
-- `↓` — Behind main
-- `↕` — Diverged from main
-
-**Remote tracking:**
-- `⇡` — Ahead of remote
-- `⇣` — Behind remote
-- `⇅` — Diverged from remote
-
-**Other:**
-- `⎇` — Branch without worktree
-- `⌫` — Prunable (directory missing)
-- `⊠` — Locked worktree
-
-Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).
-
## Columns
| Column | Shows |
|--------|-------|
| Branch | Branch name |
-| Status | Compact symbols (see above) |
+| Status | Compact symbols (see below) |
| HEAD± | Uncommitted changes: +added -deleted lines |
| main↕ | Commits ahead/behind main |
| main…± | Line diffs in commits ahead of main (`--full`) |
@@ -85,13 +53,44 @@ Rows are dimmed when the branch has no marginal contribution (`≡` matches main
| Message | Last commit message (truncated) |
The CI column shows GitHub/GitLab pipeline status:
-- `●` green — All checks passed
-- `●` blue — Checks running
-- `●` red — Checks failed
-- `●` yellow — Merge conflicts with base
-- `●` gray — No checks configured
-- blank — No PR/MR found
-- dimmed — Stale (unpushed local changes)
+
+| Indicator | Meaning |
+|-----------|---------|
+| <span style='color:#0a0'>●</span> green | All checks passed |
+| <span style='color:#00a'>●</span> blue | Checks running |
+| <span style='color:#a00'>●</span> red | Checks failed |
+| <span style='color:#a60'>●</span> yellow | Merge conflicts with base |
+| <span style='color:#888'>●</span> gray | No checks configured |
+| blank | No PR/MR found |
+
+Any CI dot appears dimmed when there are unpushed local changes (stale status).
+
+## Status Symbols
+
+Symbols appear in the Status column in this order:
+
+| Category | Symbol | Meaning |
+|----------|--------|---------|
+| Working tree | `+` | Staged files |
+| | `!` | Modified files (unstaged) |
+| | `?` | Untracked files |
+| | `✖` | Merge conflicts |
+| | `↻` | Rebase in progress |
+| | `⋈` | Merge in progress |
+| Branch state | `⊘` | Would conflict if merged to main (`--full` only) |
+| | `≡` | Matches main (identical contents) |
+| | `_` | No commits (empty branch) |
+| Divergence | `↑` | Ahead of main |
+| | `↓` | Behind main |
+| | `↕` | Diverged from main |
+| Remote | `⇡` | Ahead of remote |
+| | `⇣` | Behind remote |
+| | `⇅` | Diverged from remote |
+| Other | `⎇` | Branch without worktree |
+| | `⌫` | Prunable (directory missing) |
+| | `⊠` | Locked worktree |
+
+Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).
## JSON Output
diff --git a/src/cli.rs b/src/cli.rs
index c9c2a358d..59bcc9163 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -823,6 +823,8 @@ Toggle between views with number keys:
#[command(
after_long_help = r#"Show all worktrees with their status. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
+The table renders progressively: branch names, paths, and commit hashes appear immediately, then status, divergence, and other columns fill in as background git operations complete. CI status (with `--full`) requires network requests and may take longer.
+
## Examples
List all worktrees:
@@ -849,46 +851,12 @@ Output as JSON for scripting:
wt list --format=json
```
-## Status Symbols
-
-Symbols appear in the Status column in this order:
-
-**Working tree state:**
-- `+` — Staged files
-- `!` — Modified files (unstaged)
-- `?` — Untracked files
-- `✖` — Merge conflicts
-- `↻` — Rebase in progress
-- `⋈` — Merge in progress
-
-**Branch state:**
-- `⊘` — Would conflict if merged to main (`--full` only)
-- `≡` — Matches main (identical contents)
-- `_` — No commits (empty branch)
-
-**Divergence from main:**
-- `↑` — Ahead of main
-- `↓` — Behind main
-- `↕` — Diverged from main
-
-**Remote tracking:**
-- `⇡` — Ahead of remote
-- `⇣` — Behind remote
-- `⇅` — Diverged from remote
-
-**Other:**
-- `⎇` — Branch without worktree
-- `⌫` — Prunable (directory missing)
-- `⊠` — Locked worktree
-
-Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).
-
## Columns
| Column | Shows |
|--------|-------|
| Branch | Branch name |
-| Status | Compact symbols (see above) |
+| Status | Compact symbols (see below) |
| HEAD± | Uncommitted changes: +added -deleted lines |
| main↕ | Commits ahead/behind main |
| main…± | Line diffs in commits ahead of main (`--full`) |
@@ -900,13 +868,44 @@ Rows are dimmed when the branch has no marginal contribution (`≡` matches main
| Message | Last commit message (truncated) |
The CI column shows GitHub/GitLab pipeline status:
-- `●` green — All checks passed
-- `●` blue — Checks running
-- `●` red — Checks failed
-- `●` yellow — Merge conflicts with base
-- `●` gray — No checks configured
-- blank — No PR/MR found
-- dimmed — Stale (unpushed local changes)
+
+| Indicator | Meaning |
+|-----------|---------|
+| `●` green | All checks passed |
+| `●` blue | Checks running |
+| `●` red | Checks failed |
+| `●` yellow | Merge conflicts with base |
+| `●` gray | No checks configured |
+| blank | No PR/MR found |
+
+Any CI dot appears dimmed when there are unpushed local changes (stale status).
+
+## Status Symbols
+
+Symbols appear in the Status column in this order:
+
+| Category | Symbol | Meaning |
+|----------|--------|---------|
+| Working tree | `+` | Staged files |
+| | `!` | Modified files (unstaged) |
+| | `?` | Untracked files |
+| | `✖` | Merge conflicts |
+| | `↻` | Rebase in progress |
+| | `⋈` | Merge in progress |
+| Branch state | `⊘` | Would conflict if merged to main (`--full` only) |
+| | `≡` | Matches main (identical contents) |
+| | `_` | No commits (empty branch) |
+| Divergence | `↑` | Ahead of main |
+| | `↓` | Behind main |
+| | `↕` | Diverged from main |
+| Remote | `⇡` | Ahead of remote |
+| | `⇣` | Behind remote |
+| | `⇅` | Diverged from remote |
+| Other | `⎇` | Branch without worktree |
+| | `⌫` | Prunable (directory missing) |
+| | `⊠` | Locked worktree |
+
+Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).
## JSON Output
diff --git a/src/main.rs b/src/main.rs
index 1865df141..aec742257 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -186,9 +186,13 @@ fn handle_help_page(args: &[String]) {
// Get the after_long_help content
// Transform ```console to ```bash for Zola compatibility
+ // Add HTML colors for CI status dots
let after_help = sub
.get_after_long_help()
- .map(|s| s.to_string().replace("```console\n", "```bash\n"))
+ .map(|s| {
+ let text = s.to_string().replace("```console\n", "```bash\n");
+ colorize_ci_status_for_html(&text)
+ })
.unwrap_or_default();
// Get the help reference block
@@ -275,6 +279,21 @@ fn handle_help_page(args: &[String]) {
println!("```");
}
+/// Add HTML color spans for CI status dots in help page output.
+///
+/// Transforms plain text like "`●` green" into colored HTML spans for web rendering.
+/// This is the web-docs counterpart to md_help::colorize_status_symbols() which
+/// produces ANSI codes for terminal output.
+fn colorize_ci_status_for_html(text: &str) -> String {
+ text
+ // CI status colors (in table cells)
+ .replace("`●` green", "<span style='color:#0a0'>●</span> green")
+ .replace("`●` blue", "<span style='color:#00a'>●</span> blue")
+ .replace("`●` red", "<span style='color:#a00'>●</span> red")
+ .replace("`●` yellow", "<span style='color:#a60'>●</span> yellow")
+ .replace("`●` gray", "<span style='color:#888'>●</span> gray")
+}
+
/// Enhance clap errors with command-specific hints, then exit.
///
/// For `wt switch` missing the branch argument, adds hints about shortcuts.
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index d21a1ef09..e3a352d4b 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -59,6 +59,8 @@ Usage: wt list [OPTIONS]
Show all worktrees with their status. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
+The table renders progressively: branch names, paths, and commit hashes appear immediately, then status, divergence, and other columns fill in as background git operations complete. CI status (with --full) requires network requests and may take longer.
+
Examples
List all worktrees:
@@ -77,46 +79,12 @@ Output as JSON for scripting:
wt list --format=json
-Status Symbols
-
-Symbols appear in the Status column in this order:
-
-Working tree state:
-- + — Staged files
-- ! — Modified files (unstaged)
-- ? — Untracked files
-- ✖ — Merge conflicts
-- ↻ — Rebase in progress
-- ⋈ — Merge in progress
-
-Branch state:
-- ⊘ — Would conflict if merged to main (--full only)
-- ≡ — Matches main (identical contents)
-- _ — No commits (empty branch)
-
-Divergence from main:
-- ↑ — Ahead of main
-- ↓ — Behind main
-- ↕ — Diverged from main
-
-Remote tracking:
-- ⇡ — Ahead of remote
-- ⇣ — Behind remote
-- ⇅ — Diverged from remote
-
-Other:
-- ⎇ — Branch without worktree
-- ⌫ — Prunable (directory missing)
-- ⊠ — Locked worktree
-
-Rows are dimmed when the branch has no marginal contribution (≡ matches main or _ no commits).
-
Columns
| Column | Shows |
|--------|-------|
| Branch | Branch name |
-| Status | Compact symbols (see above) |
+| Status | Compact symbols (see below) |
| HEAD± | Uncommitted changes: +added -deleted lines |
| main↕ | Commits ahead/behind main |
| main…± | Line diffs in commits ahead of main (--full) |
@@ -128,13 +96,44 @@ Rows are dimmed when the branch has no marginal contribution (≡ matche
| Message | Last commit message (truncated) |
The CI column shows GitHub/GitLab pipeline status:
-- ● green — All checks passed
-- ● blue — Checks running
-- ● red — Checks failed
-- ● yellow — Merge conflicts with base
-- ● gray — No checks configured
-- blank — No PR/MR found
-- dimmed — Stale (unpushed local changes)
+
+| Indicator | Meaning |
+|-----------|---------|
+| ● green | All checks passed |
+| ● blue | Checks running |
+| ● red | Checks failed |
+| ● yellow | Merge conflicts with base |
+| ● gray | No checks configured |
+| blank | No PR/MR found |
+
+Any CI dot appears dimmed when there are unpushed local changes (stale status).
+
+Status Symbols
+
+Symbols appear in the Status column in this order:
+
+| Category | Symbol | Meaning |
+|----------|--------|---------|
+| Working tree | + | Staged files |
+| | ! | Modified files (unstaged) |
+| | ? | Untracked files |
+| | ✖ | Merge conflicts |
+| | ↻ | Rebase in progress |
+| | ⋈ | Merge in progress |
+| Branch state | ⊘ | Would conflict if merged to main (--full only) |
+| | ≡ | Matches main (identical contents) |
+| | _ | No commits (empty branch) |
+| Divergence | ↑ | Ahead of main |
+| | ↓ | Behind main |
+| | ↕ | Diverged from main |
+| Remote | ⇡ | Ahead of remote |
+| | ⇣ | Behind remote |
+| | ⇅ | Diverged from remote |
+| Other | ⎇ | Branch without worktree |
+| | ⌫ | Prunable (directory missing) |
+| | ⊠ | Locked worktree |
+
+Rows are dimmed when the branch has no marginal contribution (≡ matches main or _ no commits).
JSON Output