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.mdindex 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 Outputdiff --git a/docs/CLAUDE.md b/docs/CLAUDE.mdindex 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.mdindex 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.+## ExamplesList 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 Outputdiff --git a/src/cli.rs b/src/cli.rsindex 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.+## ExamplesList 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 Outputdiff --git a/src/main.rs b/src/main.rsindex 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 dotslet 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.snapindex 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: [1m[36mwt list[0m [36m[OPTIONS][0mShow 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 [2m--full[0m) requires network requests and may take longer.+[32mExamples[0mList all worktrees:@@ -77,46 +79,12 @@ Output as JSON for scripting:[2mwt list --format=json[0m-[32mStatus Symbols[0m--Symbols appear in the Status column in this order:--[1mWorking tree state:[0m-- [2m+[0m — Staged files-- [2m![0m — Modified files (unstaged)-- [2m?[0m — Untracked files-- [2m✖[0m — Merge conflicts-- [2m↻[0m — Rebase in progress-- [2m⋈[0m — Merge in progress--[1mBranch state:[0m-- [2m⊘[0m — Would conflict if merged to main ([2m--full[0m only)-- [2m≡[0m — Matches main (identical contents)-- [2m_[0m — No commits (empty branch)--[1mDivergence from main:[0m-- [2m↑[0m — Ahead of main-- [2m↓[0m — Behind main-- [2m↕[0m — Diverged from main--[1mRemote tracking:[0m-- [2m⇡[0m — Ahead of remote-- [2m⇣[0m — Behind remote-- [2m⇅[0m — Diverged from remote--[1mOther:[0m-- [2m⎇[0m — Branch without worktree-- [2m⌫[0m — Prunable (directory missing)-- [2m⊠[0m — Locked worktree--Rows are dimmed when the branch has no marginal contribution ([2m≡[0m matches main or [2m_[0m no commits).-[32mColumns[0m| 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 ([2m--full[0m) |@@ -128,13 +96,44 @@ Rows are dimmed when the branch has no marginal contribution ([2m≡[0m matche| Message | Last commit message (truncated) |The CI column shows GitHub/GitLab pipeline status:-- [2m●[0m green — All checks passed-- [2m●[0m blue — Checks running-- [2m●[0m red — Checks failed-- [2m●[0m yellow — Merge conflicts with base-- [2m●[0m gray — No checks configured-- blank — No PR/MR found-- dimmed — Stale (unpushed local changes)++| Indicator | Meaning |+|-----------|---------|+| [2m●[0m green | All checks passed |+| [2m●[0m blue | Checks running |+| [2m●[0m red | Checks failed |+| [2m●[0m yellow | Merge conflicts with base |+| [2m●[0m gray | No checks configured |+| blank | No PR/MR found |++Any CI dot appears dimmed when there are unpushed local changes (stale status).++[32mStatus Symbols[0m++Symbols appear in the Status column in this order:++| Category | Symbol | Meaning |+|----------|--------|---------|+| Working tree | [2m+[0m | Staged files |+| | [2m![0m | Modified files (unstaged) |+| | [2m?[0m | Untracked files |+| | [2m✖[0m | Merge conflicts |+| | [2m↻[0m | Rebase in progress |+| | [2m⋈[0m | Merge in progress |+| Branch state | [2m⊘[0m | Would conflict if merged to main ([2m--full[0m only) |+| | [2m≡[0m | Matches main (identical contents) |+| | [2m_[0m | No commits (empty branch) |+| Divergence | [2m↑[0m | Ahead of main |+| | [2m↓[0m | Behind main |+| | [2m↕[0m | Diverged from main |+| Remote | [2m⇡[0m | Ahead of remote |+| | [2m⇣[0m | Behind remote |+| | [2m⇅[0m | Diverged from remote |+| Other | [2m⎇[0m | Branch without worktree |+| | [2m⌫[0m | Prunable (directory missing) |+| | [2m⊠[0m | Locked worktree |++Rows are dimmed when the branch has no marginal contribution ([2m≡[0m matches main or [2m_[0m no commits).[32mJSON Output[0m