Skip to content

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

docs(list): align status-symbol tables with JSON by type (#3139)

Maximilian Roos61f3a296d9dd
diff --git a/docs/content/list.md b/docs/content/list.md
index d5ea17a59..aee840338 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -105,23 +105,25 @@ The leftmost column marks each row by physical presence, from most present to le
### CI status
-The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and Azure DevOps, `!3035` on GitLab — colored by pipeline status, or a bare `#` when no number is available (e.g. branch workflows without a PR/MR):
+The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and Azure DevOps, `!3035` on GitLab — colored by pipeline status, or a bare `#` when no number is available (e.g. branch workflows without a PR/MR). One color folds two JSON fields: green/blue/red/yellow/gray are `ci.status`; magenta/cyan are `ci.review_state`. The `Value` column is the matching JSON string from `--format=json`:
-| 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:#a0a'>#</span> magenta | Reviewer requested changes |
-| <span style='color:#0aa'>#</span> cyan | Review required, not yet given |
-| <span style='color:#a60'>#</span> yellow | Merge conflicts with base |
-| <span style='color:#888'>#</span> gray | No checks configured |
-| <span style='color:#a60'>⚠</span> yellow | Fetch error (rate limit, network) |
-| (blank) | No upstream or no PR/MR |
+| Indicator | Value | Meaning |
+|-----------|-------|---------|
+| <span style='color:#0a0'>#</span> green | `"passed"` | All checks passed |
+| <span style='color:#00a'>#</span> blue | `"running"` | Checks in progress |
+| <span style='color:#a00'>#</span> red | `"failed"` | One or more checks failed |
+| <span style='color:#a60'>#</span> yellow | `"conflicts"` | Merge conflicts with the target branch |
+| <span style='color:#888'>#</span> gray | `"no-ci"` | No PR/MR, or no checks configured |
+| <span style='color:#a60'>⚠</span> yellow | `"error"` | CI status could not be fetched (rate limit, network, etc.) |
+| <span style='color:#a0a'>#</span> magenta | `"changes_requested"` | A reviewer requested changes |
+| <span style='color:#0aa'>#</span> cyan | `"pending"` | A review is required (e.g. branch protection) but not yet given |
+| (blank) | `ci` absent | No upstream, or no PR/MR and no branch workflow |
-Review state merges into the same color where its required action ranks: changes-requested (magenta) outranks running checks — waiting can't clear it — while an outstanding required review (cyan) only recolors an otherwise green or quiet branch. Cool colors mean waiting, warm colors mean act. A PR with no review signal (no required reviewers and no reviews) keeps its plain CI color, and draft PRs appear dimmed.
+The two remaining `ci.review_state` values have no indicator of their own: `"draft"` only dims the cell and `"approved"` leaves the color unchanged.
-CI cells are clickable links to the PR or pipeline page, and appear dimmed when unpushed local changes make the status stale. PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches — visible with `--remotes` — get CI status detection. Results are cached for 30-60 seconds; use `wt config state` to view or clear.
+Color precedence resolves the fold: changes-requested (magenta) outranks running checks — waiting can't clear it — while an outstanding required review (cyan) only recolors an otherwise green or quiet branch. Cool colors mean waiting, warm colors mean act. An approved PR, or one with no review signal at all (no required reviewers and no reviews), keeps its plain `ci.status` color — `ci.review_state` is then `"approved"` or absent, respectively. GitLab MR data carries only `"pending"` and `"draft"` — no approved or changes-requested signal.
+
+CI cells are clickable links to the PR or pipeline page, and appear dimmed for a draft PR/MR (`"draft"`) or when unpushed local changes make the status stale (`ci.stale`). PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches — visible with `--remotes` — get CI status detection. Results are cached for 30-60 seconds; use `wt config state` to view or clear.
### LLM summaries
@@ -144,35 +146,62 @@ A column that renders empty for every row is dropped from the table. Templates,
## Status symbols
-The Status column has multiple subcolumns. Within each, only the first matching symbol is shown (listed in priority order):
-
-| Subcolumn | Symbol | Meaning |
-|-----------|--------|---------|
-| Working tree (1) | `+` | Staged files |
-| Working tree (2) | `!` | Modified files (unstaged) |
-| Working tree (3) | `?` | Untracked files |
-| Worktree | `✘` | Merge conflicts |
-| | `⤴` | Rebase in progress |
-| | `⤵` | Merge in progress |
-| | `/` | Branch without worktree |
-| | `⚑` | Branch-worktree mismatch (branch name doesn't match worktree path) |
-| | `⊟` | Prunable (directory missing) |
-| | `⊞` | Locked worktree |
-| Default branch | `^` | Is the default branch |
-| | `∅` | Orphan branch (no common ancestor with the default branch) |
-| | `✗` | Would conflict if merged to the default branch; with `--full`, includes uncommitted changes |
-| | `_` | Same commit as the default branch, clean |
-| | `–` | Same commit as the default branch, uncommitted changes |
-| | `⊂` | Content [integrated](@/remove.md#branch-cleanup) into the default branch or target |
-| | `↕` | Diverged from the default branch |
-| | `↑` | Ahead of the default branch |
-| | `↓` | Behind the default branch |
-| Remote | `\|` | In sync with remote |
-| | `⇅` | Diverged from remote |
-| | `⇡` | Ahead of remote |
-| | `⇣` | Behind remote |
-
-Rows are dimmed when [safe to delete](@/remove.md#branch-cleanup) (`_` same commit with clean working tree or `⊂` content integrated).
+The Status column packs several subcolumns, left to right, each mapping to a field in `--format=json`. Working-tree flags are independent and co-occur — any combination shows at once. The other subcolumns are mutually exclusive: each shows a single symbol, the highest-priority state in top-to-bottom table order, and is blank when nothing applies.
+
+### Working tree
+
+Independent flags from `git status`; several can show at once (e.g. `+!?`). Each maps to a boolean in the `working_tree` object:
+
+| Symbol | working_tree | Meaning |
+|--------|--------------|---------|
+| `+` | `staged` | Staged files |
+| `!` | `modified` | Modified files (unstaged) |
+| `?` | `untracked` | Untracked files |
+
+`working_tree` also reports `renamed` and `deleted`, which have no dedicated symbol in the column.
+
+### Worktree
+
+An in-progress git operation, a worktree-location attribute, or a branch with no worktree. One symbol shows, highest priority first (`✘ > ⤴ > ⤵ > ⚑ > ⊟ > ⊞ > /`):
+
+| Symbol | JSON | Meaning |
+|--------|------|---------|
+| `✘` | `operation_state` `"conflicts"` | Merge conflicts |
+| `⤴` | `operation_state` `"rebase"` | Rebase in progress |
+| `⤵` | `operation_state` `"merge"` | Merge in progress |
+| `⚑` | `worktree.state` `"branch_worktree_mismatch"` | Branch name doesn't match the worktree path |
+| `⊟` | `worktree.state` `"prunable"` | Prunable (worktree directory missing) |
+| `⊞` | `worktree.state` `"locked"` | Locked worktree |
+| `/` | `kind` `"branch"` | Branch without a worktree (no `worktree` object) |
+
+### Default branch
+
+The single highest-priority state describing the branch's relation to the default branch; blank when none applies (a normal up-to-date branch). Each symbol is one `main_state` value:
+
+| Symbol | main_state | Meaning |
+|--------|------------|---------|
+| `^` | `"is_main"` | The main worktree (the repo's home worktree) |
+| `∅` | `"orphan"` | No common ancestor with the default branch |
+| `✗` | `"would_conflict"` | Merging into the default branch would conflict (simulated with `git merge-tree`); with `--full`, the check includes uncommitted changes |
+| `_` | `"empty"` | Same commit as the default branch, working tree clean — safe to remove; row dimmed |
+| `–` | `"same_commit"` | Same commit as the default branch, but with uncommitted changes |
+| `⊂` | `"integrated"` | Content [integrated](@/remove.md#branch-cleanup) into the default branch or merge target via different history; the matching check is in `integration_reason`; row dimmed |
+| `↕` | `"diverged"` | Both ahead of and behind the default branch |
+| `↑` | `"ahead"` | Has commits the default branch doesn't |
+| `↓` | `"behind"` | Missing commits the default branch has |
+
+Rows are dimmed when [safe to delete](@/remove.md#branch-cleanup) — `_` (`"empty"`) or `⊂` (`"integrated"`).
+
+### Remote
+
+Relation to the tracking branch, derived from the `remote.ahead` / `remote.behind` counts; blank when there is no upstream:
+
+| Symbol | remote | Meaning |
+|--------|--------|---------|
+| `\|` | `ahead` 0, `behind` 0 | In sync with remote |
+| `⇡` | `ahead` > 0 | Ahead of remote |
+| `⇣` | `behind` > 0 | Behind remote |
+| `⇅` | `ahead` > 0, `behind` > 0 | Diverged from remote |
### Placeholder symbols
@@ -201,7 +230,7 @@ Query structured data with `--format=json`:
| `working_tree` | object | Working tree state (see below) |
| `main_state` | string | Relation to the default branch (see below) |
| `integration_reason` | string | Why branch is integrated (see below) |
-| `operation_state` | string | `"conflicts"`, `"rebase"`, or `"merge"`; absent when clean |
+| `operation_state` | string | `"conflicts"`, `"rebase"`, or `"merge"` (see [Worktree](#worktree)); absent when clean |
| `main` | object | Relationship to the default branch (see below); absent when is_main |
| `remote` | object | Tracking branch info (see below); absent when no tracking |
| `worktree` | object | Worktree metadata (see below) |
@@ -230,6 +259,8 @@ Query structured data with `--format=json`:
### working_tree object
+The five change flags map to the [Working tree](#working-tree) symbols (`renamed` and `deleted` have none of their own):
+
| Field | Type | Description |
|-------|------|-------------|
| `staged` | boolean | Has staged files |
@@ -249,6 +280,8 @@ Query structured data with `--format=json`:
### remote object
+`ahead` / `behind` drive the [Remote](#remote) divergence symbol:
+
| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Remote name (e.g., `"origin"`) |
@@ -258,9 +291,11 @@ Query structured data with `--format=json`:
### worktree object
+Present only for worktree-kind items. `state` is the worktree-location attribute — see [Worktree](#worktree) for its symbols:
+
| Field | Type | Description |
|-------|------|-------------|
-| `state` | string | `"no_worktree"`, `"branch_worktree_mismatch"`, `"prunable"`, `"locked"` (absent when normal) |
+| `state` | string | `"branch_worktree_mismatch"`, `"prunable"`, or `"locked"` (absent when normal) |
| `reason` | string | Reason for locked/prunable state |
| `detached` | boolean | HEAD is detached |
@@ -293,23 +328,23 @@ Top-level `repo` describes the local checkout's repository as derived from the p
### main_state values
-These values describe the relation to the default branch.
-
-`"is_main"` `"orphan"` `"would_conflict"` `"empty"` `"same_commit"` `"integrated"` `"diverged"` `"ahead"` `"behind"`
+The single highest-priority state describing the branch's relation to the default branch; absent when none applies (a normal up-to-date branch). Each value is one Default-branch symbol — see [Default branch](#default-branch) for the symbol and the full meaning of each value (`"is_main"`, `"orphan"`, `"would_conflict"`, `"empty"`, `"same_commit"`, `"integrated"`, `"diverged"`, `"ahead"`, `"behind"`).
### integration_reason values
-When `main_state == "integrated"`: `"ancestor"` `"trees-match"` `"no-added-changes"` `"merge-adds-nothing"` `"patch-id-match"`
-
-### ci.status values
-
-`"passed"` `"running"` `"failed"` `"conflicts"` `"no-ci"` `"error"`
+Set only when `main_state == "integrated"` (the `⊂` symbol), recording which check matched. Checks run cheapest-first and the first match wins. JSON-only — every reason renders as the same `⊂`:
-### ci.review_state values
+| Value | Meaning |
+|-------|---------|
+| `"ancestor"` | Branch HEAD is an ancestor of the default branch, which has moved past it |
+| `"no-added-changes"` | The three-dot diff (`main...branch`) is empty — no file changes beyond the merge-base |
+| `"trees-match"` | Different history, but the branch's tree is identical to the default branch's |
+| `"merge-adds-nothing"` | The branch has changes, but merging them leaves the default branch's tree unchanged (e.g. a squash merge where the target advanced on other files) |
+| `"patch-id-match"` | The branch's squashed diff matches a single commit on the default branch (e.g. a GitHub/GitLab squash merge) |
-`"approved"` `"changes_requested"` `"pending"` `"draft"`
+### ci.status and ci.review_state values
-The vocabulary matches Claude Code's statusline `pr.review_state` field. `"pending"` means a review is required (e.g. branch protection) but not yet given; a PR with no review signal at all has no `review_state`. GitLab reports only `"pending"` and `"draft"` — MR list data carries no approved or changes-requested signal.
+The [CI status](#ci-status) section above is the single source for both fields: the table maps each colored value, and the notes below it cover `"draft"` and `"approved"`. `ci.status` is one of `"passed"`, `"running"`, `"failed"`, `"conflicts"`, `"no-ci"`, `"error"`; `ci.review_state` is one of `"changes_requested"`, `"pending"`, `"draft"`, `"approved"`, absent when the forge reports no review signal. The vocabulary matches Claude Code's statusline `pr.review_state` field.
Missing a field that would be generally useful? [Open an issue](https://github.com/max-sixty/worktrunk/issues).
diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.md
index cbddd5e1a..13e4ae53d 100644
--- a/skills/worktrunk/reference/list.md
+++ b/skills/worktrunk/reference/list.md
@@ -94,23 +94,25 @@ The leftmost column marks each row by physical presence, from most present to le
### CI status
-The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and Azure DevOps, `!3035` on GitLab — colored by pipeline status, or a bare `#` when no number is available (e.g. branch workflows without a PR/MR):
+The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and Azure DevOps, `!3035` on GitLab — colored by pipeline status, or a bare `#` when no number is available (e.g. branch workflows without a PR/MR). One color folds two JSON fields: green/blue/red/yellow/gray are `ci.status`; magenta/cyan are `ci.review_state`. The `Value` column is the matching JSON string from `--format=json`:
-| Indicator | Meaning |
-|-----------|---------|
-| `#` green | All checks passed |
-| `#` blue | Checks running |
-| `#` red | Checks failed |
-| `#` magenta | Reviewer requested changes |
-| `#` cyan | Review required, not yet given |
-| `#` yellow | Merge conflicts with base |
-| `#` gray | No checks configured |
-| `⚠` yellow | Fetch error (rate limit, network) |
-| (blank) | No upstream or no PR/MR |
+| Indicator | Value | Meaning |
+|-----------|-------|---------|
+| `#` green | `"passed"` | All checks passed |
+| `#` blue | `"running"` | Checks in progress |
+| `#` red | `"failed"` | One or more checks failed |
+| `#` yellow | `"conflicts"` | Merge conflicts with the target branch |
+| `#` gray | `"no-ci"` | No PR/MR, or no checks configured |
+| `⚠` yellow | `"error"` | CI status could not be fetched (rate limit, network, etc.) |
+| `#` magenta | `"changes_requested"` | A reviewer requested changes |
+| `#` cyan | `"pending"` | A review is required (e.g. branch protection) but not yet given |
+| (blank) | `ci` absent | No upstream, or no PR/MR and no branch workflow |
-Review state merges into the same color where its required action ranks: changes-requested (magenta) outranks running checks — waiting can't clear it — while an outstanding required review (cyan) only recolors an otherwise green or quiet branch. Cool colors mean waiting, warm colors mean act. A PR with no review signal (no required reviewers and no reviews) keeps its plain CI color, and draft PRs appear dimmed.
+The two remaining `ci.review_state` values have no indicator of their own: `"draft"` only dims the cell and `"approved"` leaves the color unchanged.
-CI cells are clickable links to the PR or pipeline page, and appear dimmed when unpushed local changes make the status stale. PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches — visible with `--remotes` — get CI status detection. Results are cached for 30-60 seconds; use `wt config state` to view or clear.
+Color precedence resolves the fold: changes-requested (magenta) outranks running checks — waiting can't clear it — while an outstanding required review (cyan) only recolors an otherwise green or quiet branch. Cool colors mean waiting, warm colors mean act. An approved PR, or one with no review signal at all (no required reviewers and no reviews), keeps its plain `ci.status` color — `ci.review_state` is then `"approved"` or absent, respectively. GitLab MR data carries only `"pending"` and `"draft"` — no approved or changes-requested signal.
+
+CI cells are clickable links to the PR or pipeline page, and appear dimmed for a draft PR/MR (`"draft"`) or when unpushed local changes make the status stale (`ci.stale`). PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches — visible with `--remotes` — get CI status detection. Results are cached for 30-60 seconds; use `wt config state` to view or clear.
### LLM summaries [experimental]
@@ -129,35 +131,62 @@ A column that renders empty for every row is dropped from the table. Templates,
## Status symbols
-The Status column has multiple subcolumns. Within each, only the first matching symbol is shown (listed in priority order):
-
-| Subcolumn | Symbol | Meaning |
-|-----------|--------|---------|
-| Working tree (1) | `+` | Staged files |
-| Working tree (2) | `!` | Modified files (unstaged) |
-| Working tree (3) | `?` | Untracked files |
-| Worktree | `✘` | Merge conflicts |
-| | `⤴` | Rebase in progress |
-| | `⤵` | Merge in progress |
-| | `/` | Branch without worktree |
-| | `⚑` | Branch-worktree mismatch (branch name doesn't match worktree path) |
-| | `⊟` | Prunable (directory missing) |
-| | `⊞` | Locked worktree |
-| Default branch | `^` | Is the default branch |
-| | `∅` | Orphan branch (no common ancestor with the default branch) |
-| | `✗` | Would conflict if merged to the default branch; with `--full`, includes uncommitted changes |
-| | `_` | Same commit as the default branch, clean |
-| | `–` | Same commit as the default branch, uncommitted changes |
-| | `⊂` | Content [integrated](https://worktrunk.dev/remove/#branch-cleanup) into the default branch or target |
-| | `↕` | Diverged from the default branch |
-| | `↑` | Ahead of the default branch |
-| | `↓` | Behind the default branch |
-| Remote | `\|` | In sync with remote |
-| | `⇅` | Diverged from remote |
-| | `⇡` | Ahead of remote |
-| | `⇣` | Behind remote |
-
-Rows are dimmed when [safe to delete](https://worktrunk.dev/remove/#branch-cleanup) (`_` same commit with clean working tree or `⊂` content integrated).
+The Status column packs several subcolumns, left to right, each mapping to a field in `--format=json`. Working-tree flags are independent and co-occur — any combination shows at once. The other subcolumns are mutually exclusive: each shows a single symbol, the highest-priority state in top-to-bottom table order, and is blank when nothing applies.
+
+### Working tree
+
+Independent flags from `git status`; several can show at once (e.g. `+!?`). Each maps to a boolean in the `working_tree` object:
+
+| Symbol | working_tree | Meaning |
+|--------|--------------|---------|
+| `+` | `staged` | Staged files |
+| `!` | `modified` | Modified files (unstaged) |
+| `?` | `untracked` | Untracked files |
+
+`working_tree` also reports `renamed` and `deleted`, which have no dedicated symbol in the column.
+
+### Worktree
+
+An in-progress git operation, a worktree-location attribute, or a branch with no worktree. One symbol shows, highest priority first (`✘ > ⤴ > ⤵ > ⚑ > ⊟ > ⊞ > /`):
+
+| Symbol | JSON | Meaning |
+|--------|------|---------|
+| `✘` | `operation_state` `"conflicts"` | Merge conflicts |
+| `⤴` | `operation_state` `"rebase"` | Rebase in progress |
+| `⤵` | `operation_state` `"merge"` | Merge in progress |
+| `⚑` | `worktree.state` `"branch_worktree_mismatch"` | Branch name doesn't match the worktree path |
+| `⊟` | `worktree.state` `"prunable"` | Prunable (worktree directory missing) |
+| `⊞` | `worktree.state` `"locked"` | Locked worktree |
+| `/` | `kind` `"branch"` | Branch without a worktree (no `worktree` object) |
+
+### Default branch
+
+The single highest-priority state describing the branch's relation to the default branch; blank when none applies (a normal up-to-date branch). Each symbol is one `main_state` value:
+
+| Symbol | main_state | Meaning |
+|--------|------------|---------|
+| `^` | `"is_main"` | The main worktree (the repo's home worktree) |
+| `∅` | `"orphan"` | No common ancestor with the default branch |
+| `✗` | `"would_conflict"` | Merging into the default branch would conflict (simulated with `git merge-tree`); with `--full`, the check includes uncommitted changes |
+| `_` | `"empty"` | Same commit as the default branch, working tree clean — safe to remove; row dimmed |
+| `–` | `"same_commit"` | Same commit as the default branch, but with uncommitted changes |
+| `⊂` | `"integrated"` | Content [integrated](https://worktrunk.dev/remove/#branch-cleanup) into the default branch or merge target via different history; the matching check is in `integration_reason`; row dimmed |
+| `↕` | `"diverged"` | Both ahead of and behind the default branch |
+| `↑` | `"ahead"` | Has commits the default branch doesn't |
+| `↓` | `"behind"` | Missing commits the default branch has |
+
+Rows are dimmed when [safe to delete](https://worktrunk.dev/remove/#branch-cleanup) — `_` (`"empty"`) or `⊂` (`"integrated"`).
+
+### Remote
+
+Relation to the tracking branch, derived from the `remote.ahead` / `remote.behind` counts; blank when there is no upstream:
+
+| Symbol | remote | Meaning |
+|--------|--------|---------|
+| `\|` | `ahead` 0, `behind` 0 | In sync with remote |
+| `⇡` | `ahead` > 0 | Ahead of remote |
+| `⇣` | `behind` > 0 | Behind remote |
+| `⇅` | `ahead` > 0, `behind` > 0 | Diverged from remote |
### Placeholder symbols
@@ -210,7 +239,7 @@ $ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
| `working_tree` | object | Working tree state (see below) |
| `main_state` | string | Relation to the default branch (see below) |
| `integration_reason` | string | Why branch is integrated (see below) |
-| `operation_state` | string | `"conflicts"`, `"rebase"`, or `"merge"`; absent when clean |
+| `operation_state` | string | `"conflicts"`, `"rebase"`, or `"merge"` (see [Worktree](#worktree)); absent when clean |
| `main` | object | Relationship to the default branch (see below); absent when is_main |
| `remote` | object | Tracking branch info (see below); absent when no tracking |
| `worktree` | object | Worktree metadata (see below) |
@@ -239,6 +268,8 @@ $ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
### working_tree object
+The five change flags map to the [Working tree](#working-tree) symbols (`renamed` and `deleted` have none of their own):
+
| Field | Type | Description |
|-------|------|-------------|
| `staged` | boolean | Has staged files |
@@ -258,6 +289,8 @@ $ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
### remote object
+`ahead` / `behind` drive the [Remote](#remote) divergence symbol:
+
| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Remote name (e.g., `"origin"`) |
@@ -267,9 +300,11 @@ $ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
### worktree object
+Present only for worktree-kind items. `state` is the worktree-location attribute — see [Worktree](#worktree) for its symbols:
+
| Field | Type | Description |
|-------|------|-------------|
-| `state` | string | `"no_worktree"`, `"branch_worktree_mismatch"`, `"prunable"`, `"locked"` (absent when normal) |
+| `state` | string | `"branch_worktree_mismatch"`, `"prunable"`, or `"locked"` (absent when normal) |
| `reason` | string | Reason for locked/prunable state |
| `detached` | boolean | HEAD is detached |
@@ -302,23 +337,23 @@ Top-level `repo` describes the local checkout's repository as derived from the p
### main_state values
-These values describe the relation to the default branch.
-
-`"is_main"` `"orphan"` `"would_conflict"` `"empty"` `"same_commit"` `"integrated"` `"diverged"` `"ahead"` `"behind"`
+The single highest-priority state describing the branch's relation to the default branch; absent when none applies (a normal up-to-date branch). Each value is one Default-branch symbol — see [Default branch](#default-branch) for the symbol and the full meaning of each value (`"is_main"`, `"orphan"`, `"would_conflict"`, `"empty"`, `"same_commit"`, `"integrated"`, `"diverged"`, `"ahead"`, `"behind"`).
### integration_reason values
-When `main_state == "integrated"`: `"ancestor"` `"trees-match"` `"no-added-changes"` `"merge-adds-nothing"` `"patch-id-match"`
-
-### ci.status values
-
-`"passed"` `"running"` `"failed"` `"conflicts"` `"no-ci"` `"error"`
+Set only when `main_state == "integrated"` (the `⊂` symbol), recording which check matched. Checks run cheapest-first and the first match wins. JSON-only — every reason renders as the same `⊂`:
-### ci.review_state values
+| Value | Meaning |
+|-------|---------|
+| `"ancestor"` | Branch HEAD is an ancestor of the default branch, which has moved past it |
+| `"no-added-changes"` | The three-dot diff (`main...branch`) is empty — no file changes beyond the merge-base |
+| `"trees-match"` | Different history, but the branch's tree is identical to the default branch's |
+| `"merge-adds-nothing"` | The branch has changes, but merging them leaves the default branch's tree unchanged (e.g. a squash merge where the target advanced on other files) |
+| `"patch-id-match"` | The branch's squashed diff matches a single commit on the default branch (e.g. a GitHub/GitLab squash merge) |
-`"approved"` `"changes_requested"` `"pending"` `"draft"`
+### ci.status and ci.review_state values
-The vocabulary matches Claude Code's statusline `pr.review_state` field. `"pending"` means a review is required (e.g. branch protection) but not yet given; a PR with no review signal at all has no `review_state`. GitLab reports only `"pending"` and `"draft"` — MR list data carries no approved or changes-requested signal.
+The [CI status](#ci-status) section above is the single source for both fields: the table maps each colored value, and the notes below it cover `"draft"` and `"approved"`. `ci.status` is one of `"passed"`, `"running"`, `"failed"`, `"conflicts"`, `"no-ci"`, `"error"`; `ci.review_state` is one of `"changes_requested"`, `"pending"`, `"draft"`, `"approved"`, absent when the forge reports no review signal. The vocabulary matches Claude Code's statusline `pr.review_state` field.
Missing a field that would be generally useful? Open an issue at https://github.com/max-sixty/worktrunk.
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 374510ca1..91983c1d7 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -804,23 +804,25 @@ The leftmost column marks each row by physical presence, from most present to le
### CI status
-The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and Azure DevOps, `!3035` on GitLab — colored by pipeline status, or a bare `#` when no number is available (e.g. branch workflows without a PR/MR):
+The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and Azure DevOps, `!3035` on GitLab — colored by pipeline status, or a bare `#` when no number is available (e.g. branch workflows without a PR/MR). One color folds two JSON fields: green/blue/red/yellow/gray are `ci.status`; magenta/cyan are `ci.review_state`. The `Value` column is the matching JSON string from `--format=json`:
-| Indicator | Meaning |
-|-----------|---------|
-| `#` green | All checks passed |
-| `#` blue | Checks running |
-| `#` red | Checks failed |
-| `#` magenta | Reviewer requested changes |
-| `#` cyan | Review required, not yet given |
-| `#` yellow | Merge conflicts with base |
-| `#` gray | No checks configured |
-| `⚠` yellow | Fetch error (rate limit, network) |
-| (blank) | No upstream or no PR/MR |
+| Indicator | Value | Meaning |
+|-----------|-------|---------|
+| `#` green | `"passed"` | All checks passed |
+| `#` blue | `"running"` | Checks in progress |
+| `#` red | `"failed"` | One or more checks failed |
+| `#` yellow | `"conflicts"` | Merge conflicts with the target branch |
+| `#` gray | `"no-ci"` | No PR/MR, or no checks configured |
+| `⚠` yellow | `"error"` | CI status could not be fetched (rate limit, network, etc.) |
+| `#` magenta | `"changes_requested"` | A reviewer requested changes |
+| `#` cyan | `"pending"` | A review is required (e.g. branch protection) but not yet given |
+| (blank) | `ci` absent | No upstream, or no PR/MR and no branch workflow |
-Review state merges into the same color where its required action ranks: changes-requested (magenta) outranks running checks — waiting can't clear it — while an outstanding required review (cyan) only recolors an otherwise green or quiet branch. Cool colors mean waiting, warm colors mean act. A PR with no review signal (no required reviewers and no reviews) keeps its plain CI color, and draft PRs appear dimmed.
+The two remaining `ci.review_state` values have no indicator of their own: `"draft"` only dims the cell and `"approved"` leaves the color unchanged.
-CI cells are clickable links to the PR or pipeline page, and appear dimmed when unpushed local changes make the status stale. PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches — visible with `--remotes` — get CI status detection. Results are cached for 30-60 seconds; use `wt config state` to view or clear.
+Color precedence resolves the fold: changes-requested (magenta) outranks running checks — waiting can't clear it — while an outstanding required review (cyan) only recolors an otherwise green or quiet branch. Cool colors mean waiting, warm colors mean act. An approved PR, or one with no review signal at all (no required reviewers and no reviews), keeps its plain `ci.status` color — `ci.review_state` is then `"approved"` or absent, respectively. GitLab MR data carries only `"pending"` and `"draft"` — no approved or changes-requested signal.
+
+CI cells are clickable links to the PR or pipeline page, and appear dimmed for a draft PR/MR (`"draft"`) or when unpushed local changes make the status stale (`ci.stale`). PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches — visible with `--remotes` — get CI status detection. Results are cached for 30-60 seconds; use `wt config state` to view or clear.
### LLM summaries [experimental]
@@ -839,35 +841,62 @@ A column that renders empty for every row is dropped from the table. Templates,
## Status symbols
-The Status column has multiple subcolumns. Within each, only the first matching symbol is shown (listed in priority order):
-
-| Subcolumn | Symbol | Meaning |
-|-----------|--------|---------|
-| Working tree (1) | `+` | Staged files |
-| Working tree (2) | `!` | Modified files (unstaged) |
-| Working tree (3) | `?` | Untracked files |
-| Worktree | `✘` | Merge conflicts |
-| | `⤴` | Rebase in progress |
-| | `⤵` | Merge in progress |
-| | `/` | Branch without worktree |
-| | `⚑` | Branch-worktree mismatch (branch name doesn't match worktree path) |
-| | `⊟` | Prunable (directory missing) |
-| | `⊞` | Locked worktree |
-| Default branch | `^` | Is the default branch |
-| | `∅` | Orphan branch (no common ancestor with the default branch) |
-| | `✗` | Would conflict if merged to the default branch; with `--full`, includes uncommitted changes |
-| | `_` | Same commit as the default branch, clean |
-| | `–` | Same commit as the default branch, uncommitted changes |
-| | `⊂` | Content [integrated](@/remove.md#branch-cleanup) into the default branch or target |
-| | `↕` | Diverged from the default branch |
-| | `↑` | Ahead of the default branch |
-| | `↓` | Behind the default branch |
-| Remote | `\|` | In sync with remote |
-| | `⇅` | Diverged from remote |
-| | `⇡` | Ahead of remote |
-| | `⇣` | Behind remote |
-
-Rows are dimmed when [safe to delete](@/remove.md#branch-cleanup) (`_` same commit with clean working tree or `⊂` content integrated).
+The Status column packs several subcolumns, left to right, each mapping to a field in `--format=json`. Working-tree flags are independent and co-occur — any combination shows at once. The other subcolumns are mutually exclusive: each shows a single symbol, the highest-priority state in top-to-bottom table order, and is blank when nothing applies.
+
+### Working tree
+
+Independent flags from `git status`; several can show at once (e.g. `+!?`). Each maps to a boolean in the `working_tree` object:
+
+| Symbol | working_tree | Meaning |
+|--------|--------------|---------|
+| `+` | `staged` | Staged files |
+| `!` | `modified` | Modified files (unstaged) |
+| `?` | `untracked` | Untracked files |
+
+`working_tree` also reports `renamed` and `deleted`, which have no dedicated symbol in the column.
+
+### Worktree
+
+An in-progress git operation, a worktree-location attribute, or a branch with no worktree. One symbol shows, highest priority first (`✘ > ⤴ > ⤵ > ⚑ > ⊟ > ⊞ > /`):
+
+| Symbol | JSON | Meaning |
+|--------|------|---------|
+| `✘` | `operation_state` `"conflicts"` | Merge conflicts |
+| `⤴` | `operation_state` `"rebase"` | Rebase in progress |
+| `⤵` | `operation_state` `"merge"` | Merge in progress |
+| `⚑` | `worktree.state` `"branch_worktree_mismatch"` | Branch name doesn't match the worktree path |
+| `⊟` | `worktree.state` `"prunable"` | Prunable (worktree directory missing) |
+| `⊞` | `worktree.state` `"locked"` | Locked worktree |
+| `/` | `kind` `"branch"` | Branch without a worktree (no `worktree` object) |
+
+### Default branch
+
+The single highest-priority state describing the branch's relation to the default branch; blank when none applies (a normal up-to-date branch). Each symbol is one `main_state` value:
+
+| Symbol | main_state | Meaning |
+|--------|------------|---------|
+| `^` | `"is_main"` | The main worktree (the repo's home worktree) |
+| `∅` | `"orphan"` | No common ancestor with the default branch |
+| `✗` | `"would_conflict"` | Merging into the default branch would conflict (simulated with `git merge-tree`); with `--full`, the check includes uncommitted changes |
+| `_` | `"empty"` | Same commit as the default branch, working tree clean — safe to remove; row dimmed |
+| `–` | `"same_commit"` | Same commit as the default branch, but with uncommitted changes |
+| `⊂` | `"integrated"` | Content [integrated](@/remove.md#branch-cleanup) into the default branch or merge target via different history; the matching check is in `integration_reason`; row dimmed |
+| `↕` | `"diverged"` | Both ahead of and behind the default branch |
+| `↑` | `"ahead"` | Has commits the default branch doesn't |
+| `↓` | `"behind"` | Missing commits the default branch has |
+
+Rows are dimmed when [safe to delete](@/remove.md#branch-cleanup) — `_` (`"empty"`) or `⊂` (`"integrated"`).
+
+### Remote
+
+Relation to the tracking branch, derived from the `remote.ahead` / `remote.behind` counts; blank when there is no upstream:
+
+| Symbol | remote | Meaning |
+|--------|--------|---------|
+| `\|` | `ahead` 0, `behind` 0 | In sync with remote |
+| `⇡` | `ahead` > 0 | Ahead of remote |
+| `⇣` | `behind` > 0 | Behind remote |
+| `⇅` | `ahead` > 0, `behind` > 0 | Diverged from remote |
### Placeholder symbols
@@ -920,7 +949,7 @@ $ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
| `working_tree` | object | Working tree state (see below) |
| `main_state` | string | Relation to the default branch (see below) |
| `integration_reason` | string | Why branch is integrated (see below) |
-| `operation_state` | string | `"conflicts"`, `"rebase"`, or `"merge"`; absent when clean |
+| `operation_state` | string | `"conflicts"`, `"rebase"`, or `"merge"` (see [Worktree](#worktree)); absent when clean |
| `main` | object | Relationship to the default branch (see below); absent when is_main |
| `remote` | object | Tracking branch info (see below); absent when no tracking |
| `worktree` | object | Worktree metadata (see below) |
@@ -949,6 +978,8 @@ $ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
### working_tree object
+The five change flags map to the [Working tree](#working-tree) symbols (`renamed` and `deleted` have none of their own):
+
| Field | Type | Description |
|-------|------|-------------|
| `staged` | boolean | Has staged files |
@@ -968,6 +999,8 @@ $ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
### remote object
+`ahead` / `behind` drive the [Remote](#remote) divergence symbol:
+
| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Remote name (e.g., `"origin"`) |
@@ -977,9 +1010,11 @@ $ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
### worktree object
+Present only for worktree-kind items. `state` is the worktree-location attribute — see [Worktree](#worktree) for its symbols:
+
| Field | Type | Description |
|-------|------|-------------|
-| `state` | string | `"no_worktree"`, `"branch_worktree_mismatch"`, `"prunable"`, `"locked"` (absent when normal) |
+| `state` | string | `"branch_worktree_mismatch"`, `"prunable"`, or `"locked"` (absent when normal) |
| `reason` | string | Reason for locked/prunable state |
| `detached` | boolean | HEAD is detached |
@@ -1012,23 +1047,23 @@ Top-level `repo` describes the local checkout's repository as derived from the p
### main_state values
-These values describe the relation to the default branch.
-
-`"is_main"` `"orphan"` `"would_conflict"` `"empty"` `"same_commit"` `"integrated"` `"diverged"` `"ahead"` `"behind"`
+The single highest-priority state describing the branch's relation to the default branch; absent when none applies (a normal up-to-date branch). Each value is one Default-branch symbol — see [Default branch](#default-branch) for the symbol and the full meaning of each value (`"is_main"`, `"orphan"`, `"would_conflict"`, `"empty"`, `"same_commit"`, `"integrated"`, `"diverged"`, `"ahead"`, `"behind"`).
### integration_reason values
-When `main_state == "integrated"`: `"ancestor"` `"trees-match"` `"no-added-changes"` `"merge-adds-nothing"` `"patch-id-match"`
-
-### ci.status values
-
-`"passed"` `"running"` `"failed"` `"conflicts"` `"no-ci"` `"error"`
+Set only when `main_state == "integrated"` (the `⊂` symbol), recording which check matched. Checks run cheapest-first and the first match wins. JSON-only — every reason renders as the same `⊂`:
-### ci.review_state values
+| Value | Meaning |
+|-------|---------|
+| `"ancestor"` | Branch HEAD is an ancestor of the default branch, which has moved past it |
+| `"no-added-changes"` | The three-dot diff (`main...branch`) is empty — no file changes beyond the merge-base |
+| `"trees-match"` | Different history, but the branch's tree is identical to the default branch's |
+| `"merge-adds-nothing"` | The branch has changes, but merging them leaves the default branch's tree unchanged (e.g. a squash merge where the target advanced on other files) |
+| `"patch-id-match"` | The branch's squashed diff matches a single commit on the default branch (e.g. a GitHub/GitLab squash merge) |
-`"approved"` `"changes_requested"` `"pending"` `"draft"`
+### ci.status and ci.review_state values
-The vocabulary matches Claude Code's statusline `pr.review_state` field. `"pending"` means a review is required (e.g. branch protection) but not yet given; a PR with no review signal at all has no `review_state`. GitLab reports only `"pending"` and `"draft"` — MR list data carries no approved or changes-requested signal.
+The [CI status](#ci-status) section above is the single source for both fields: the table maps each colored value, and the notes below it cover `"draft"` and `"approved"`. `ci.status` is one of `"passed"`, `"running"`, `"failed"`, `"conflicts"`, `"no-ci"`, `"error"`; `ci.review_state` is one of `"changes_requested"`, `"pending"`, `"draft"`, `"approved"`, absent when the forge reports no review signal. The vocabulary matches Claude Code's statusline `pr.review_state` field.
Missing a field that would be generally useful? Open an issue at https://github.com/max-sixty/worktrunk.
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 340a4e495..7a1b5b7a4 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -164,23 +164,26 @@ The leftmost column marks each row by physical presence, from most present to le
CI status
-The CI column shows the branch's open PR/MR — #3035 on GitHub, Gitea, and Azure DevOps, !3035 on GitLab — colored by pipeline status, or a bare # when no number is available (e.g. branch workflows without a PR/MR):
+The CI column shows the branch's open PR/MR — #3035 on GitHub, Gitea, and Azure DevOps, !3035 on GitLab — colored by pipeline status, or a bare # when no number is available (e.g. branch workflows without a PR/MR). One color folds two JSON fields: green/blue/red/yellow/gray are ci.status; magenta/cyan are ci.review_state. The Value column is the matching JSON string from --format=json:
- Indicator Meaning
- ───────── ─────────────────────────────────
- # green All checks passed
- # blue Checks running
- # red Checks failed
- # magenta Reviewer requested changes
- # cyan Review required, not yet given
- # yellow Merge conflicts with base
- # gray No checks configured
- ⚠ yellow Fetch error (rate limit, network)
- (blank) No upstream or no PR/MR
+ Indicator Value Meaning
+ ───────── ─────────────────── ───────────────────────────────────────────────────────────────
+ # green "passed" All checks passed
+ # blue "running" Checks in progress
+ # red "failed" One or more checks failed
+ # yellow "conflicts" Merge conflicts with the target branch
+ # gray "no-ci" No PR/MR, or no checks configured
+ ⚠ yellow "error" CI status could not be fetched (rate limit, network, etc.)
+ # magenta "changes_requested" A reviewer requested changes
+ # cyan "pending" A review is required (e.g. branch protection) but not yet given
+ (blank) ci absent No upstream, or no PR/MR and no branch workflow
-Review state merges into the same color where its required action ranks: changes-requested (magenta) outranks running checks — waiting can't clear it — while an outstanding required review (cyan) only recolors an otherwise green or quiet branch. Cool colors mean waiting, warm colors mean act. A PR with no review signal (no required reviewers and no reviews) keeps its plain CI color, and draft PRs appear dimmed.
+The two remaining ci.review_state values have no indicator of their own: "draft" only dims the cell and "approved" leaves the color unchanged.
-CI cells are clickable links to the PR or pipeline page, and appear dimmed when unpushed local changes make the status stale. PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches — visible with --remotes — get CI status detection. Results are cached for 30-60 seconds; use wt config state to view or clear.
+Color precedence resolves the fold: changes-requested (magenta) outranks running checks — waiting can't clear it — while an outstanding required review (cyan) only recolors an otherwise green or quiet branch. Cool colors mean waiting, warm colors mean act. An approved PR, or one with no review signal at all (no required reviewers and no reviews), keeps its plain ci.status color — ci.review_state is then "approved" or absent, respectively. GitLab MR data carries only "pending" and "draft" — no
+approved or changes-requested signal.
+
+CI cells are clickable links to the PR or pipeline page, and appear dimmed for a draft PR/MR ("draft") or when unpushed local changes make the status stale (ci.stale). PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches — visible with --remotes — get CI status detection. Results are cached for 30-60 seconds; use wt config state to view or clear.
LLM summaries [experimental]
@@ -197,35 +200,62 @@ A column that renders empty for every row is dropped from the table. Templates,
Status symbols
-The Status column has multiple subcolumns. Within each, only the first matching symbol is shown (listed in priority order):
-
- Subcolumn Symbol Meaning
- ──────────────── ────── ─────────────────────────────────────────────────────────────────────────────────────────
- Working tree (1) + Staged files
- Working tree (2) ! Modified files (unstaged)
- Working tree (3) ? Untracked files
- Worktree ✘ Merge conflicts
- ⤴ Rebase in progress
- ⤵ Merge in progress
- / Branch without worktree
- ⚑ Branch-worktree mismatch (branch name doesn't match worktree path)
- ⊟ Prunable (directory missing)
- ⊞ Locked worktree
- Default branch ^ Is the default branch
- ∅ Orphan branch (no common ancestor with the default branch)
- ✗ Would conflict if merged to the default branch; with --full, includes uncommitted changes
- _ Same commit as the default branch, clean
- – Same commit as the default branch, uncommitted changes
- ⊂ Content integrated into the default branch or target
- ↕ Diverged from the default branch
- ↑ Ahead of the default branch
- ↓ Behind the default branch
- Remote | In sync with remote
- ⇅ Diverged from remote
- ⇡ Ahead of remote
- ⇣ Behind remote
-
-Rows are dimmed when safe to delete (_ same commit with clean working tree or ⊂ content integrated).
+The Status column packs several subcolumns, left to right, each mapping to a field in --format=json. Working-tree flags are independent and co-occur — any combination shows at once. The other subcolumns are mutually exclusive: each shows a single symbol, the highest-priority state in top-to-bottom table order, and is blank when nothing applies.
+
+Working tree
+
+Independent flags from git status; several can show at once (e.g. +!?). Each maps to a boolean in the working_tree object:
+
+ Symbol working_tree Meaning
+ ────── ──────────── ─────────────────────────
+ + staged Staged files
+ ! modified Modified files (unstaged)
+ ? untracked Untracked files
+
+working_tree also reports renamed and deleted, which have no dedicated symbol in the column.
+
+Worktree
+
+An in-progress git operation, a worktree-location attribute, or a branch with no worktree. One symbol shows, highest priority first (✘ > ⤴ > ⤵ > ⚑ > ⊟ > ⊞ > /):
+
+ Symbol JSON Meaning
+ ────── ───────────────────────────────────────── ──────────────────────────────────────────────
+ ✘ operation_state "conflicts" Merge conflicts
+ ⤴ operation_state "rebase" Rebase in progress
+ ⤵ operation_state "merge" Merge in progress
+ ⚑ worktree.state "branch_worktree_mismatch" Branch name doesn't match the worktree path
+ ⊟ worktree.state "prunable" Prunable (worktree directory missing)
+ ⊞ worktree.state "locked" Locked worktree
+ / kind "branch" Branch without a worktree (no worktree object)
+
+Default branch
+
+The single highest-priority state describing the branch's relation to the default branch; blank when none applies (a normal up-to-date branch). Each symbol is one main_state value:
+
+ Symbol main_state Meaning
+ ────── ──────────────── ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ ^ "is_main" The main worktree (the repo's home worktree)
+ ∅ "orphan" No common ancestor with the default branch
+ ✗ "would_conflict" Merging into the default branch would conflict (simulated with git merge-tree); with --full, the check includes uncommitted changes
+ _ "empty" Same commit as the default branch, working tree clean — safe to remove; row dimmed
+ – "same_commit" Same commit as the default branch, but with uncommitted changes
+ ⊂ "integrated" Content integrated into the default branch or merge target via different history; the matching check is in integration_reason; row dimmed
+ ↕ "diverged" Both ahead of and behind the default branch
+ ↑ "ahead" Has commits the default branch doesn't
+ ↓ "behind" Missing commits the default branch has
+
+Rows are dimmed when safe to delete — _ ("empty") or ⊂ ("integrated").
+
+Remote
+
+Relation to the tracking branch, derived from the remote.ahead / remote.behind counts; blank when there is no upstream:
+
+ Symbol remote Meaning
+ ────── ───────────────────── ────────────────────
+ | ahead 0, behind 0 In sync with remote
+ ⇡ ahead > 0 Ahead of remote
+ ⇣ behind > 0 Behind remote
+ ⇅ ahead > 0, behind > 0 Diverged from remote
Placeholder symbols
@@ -276,7 +306,7 @@ Query structured data with --format=json:
working_tree object Working tree state (see below)
main_state string Relation to the default branch (see below)
integration_reason string Why branch is integrated (see below)
- operation_state string "conflicts", "rebase", or "merge"; absent when clean
+ operation_state string "conflicts", "rebase", or "merge" (see Worktree); absent when clean
main object Relationship to the default branch (see below); absent when is_main
remote object Tracking branch info (see below); absent when no tracking
worktree object Worktree metadata (see below)
@@ -305,6 +335,8 @@ Query structured data with --format=json:
working_tree object
+The five change flags map to the Working tree symbols (renamed and deleted have none of their own):
+
Field Type Description
───────── ─────── ───────────────────────────────────────
staged boolean Has staged files
@@ -324,6 +356,8 @@ Query structured data with --format=json:
remote object
+ahead / behind drive the Remote divergence symbol:
+
Field Type Description
────── ────── ────────────────────────────
name string Remote name (e.g., "origin")
@@ -333,11 +367,13 @@ Query structured data with --format=json:
worktree object
- Field Type Description
- ──────── ─────── ────────────────────────────────────────────────────────────────────────────────────
- state string "no_worktree", "branch_worktree_mismatch", "prunable", "locked" (absent when normal)
- reason string Reason for locked/prunable state
- detached boolean HEAD is detached
+Present only for worktree-kind items. state is the worktree-location attribute — see Worktree for its symbols:
+
+ Field Type Description
+ ──────── ─────── ────────────────────────────────────────────────────────────────────────
+ state string "branch_worktree_mismatch", "prunable", or "locked" (absent when normal)
+ reason string Reason for locked/prunable state
+ detached boolean HEAD is detached
ci object
@@ -368,23 +404,23 @@ Top-level repo describes the local checkout's repository as derived from
main_state values
-These values describe the relation to the default branch.
-
-"is_main" "orphan" "would_conflict" "empty" "same_commit" "integrated" "diverged" "ahead" "behind"
+The single highest-priority state describing the branch's relation to the default branch; absent when none applies (a normal up-to-date branch). Each value is one Default-branch symbol — see Default branch for the symbol and the full meaning of each value ("is_main", "orphan", "would_conflict", "empty", "same_commit", "integrated", "diverged", "ahead", "behind").
integration_reason values
-When main_state == "integrated": "ancestor" "trees-match" "no-added-changes" "merge-adds-nothing" "patch-id-match"
-
-ci.status values
-
-"passed" "running" "failed" "conflicts" "no-ci" "error"
+Set only when main_state == "integrated" (the ⊂ symbol), recording which check matched. Checks run cheapest-first and the first match wins. JSON-only — every reason renders as the same ⊂:
-ci.review_state values
+ Value Meaning
+ ──────────────────── ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ "ancestor" Branch HEAD is an ancestor of the default branch, which has moved past it
+ "no-added-changes" The three-dot diff (main...branch) is empty — no file changes beyond the merge-base
+ "trees-match" Different history, but the branch's tree is identical to the default branch's
+ "merge-adds-nothing" The branch has changes, but merging them leaves the default branch's tree unchanged (e.g. a squash merge where the target advanced on other files)
+ "patch-id-match" The branch's squashed diff matches a single commit on the default branch (e.g. a GitHub/GitLab squash merge)
-"approved" "changes_requested" "pending" "draft"
+ci.status and ci.review_state values
-The vocabulary matches Claude Code's statusline pr.review_state field. "pending" means a review is required (e.g. branch protection) but not yet given; a PR with no review signal at all has no review_state. GitLab reports only "pending" and "draft" — MR list data carries no approved or changes-requested signal.
+The CI status section above is the single source for both fields: the table maps each colored value, and the notes below it cover "draft" and "approved". ci.status is one of "passed", "running", "failed", "conflicts", "no-ci", "error"; ci.review_state is one of "changes_requested", "pending", "draft", "approved", absent when the forge reports no review signal. The vocabulary matches Claude Code's statusline pr.review_state field.
Missing a field that would be generally useful? Open an issue at https://github.com/max-sixty/worktrunk.
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
index a7808d5ae..365ff9392 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
@@ -180,33 +180,42 @@ least:
The CI column shows the branch's open PR/MR — #3035 on GitHub, Gitea, and Azure
DevOps, !3035 on GitLab — colored by pipeline status, or a bare # when no number
- is available (e.g. branch workflows without a PR/MR):
-
- Indicator Meaning
- ───────── ─────────────────────────────────
- # green All checks passed
- # blue Checks running
- # red Checks failed
- # magenta Reviewer requested changes
- # cyan Review required, not yet given
- # yellow Merge conflicts with base
- # gray No checks configured
- ⚠ yellow Fetch error (rate limit, network)
- (blank) No upstream or no PR/MR
-
-Review state merges into the same color where its required action ranks:
-changes-requested (magenta) outranks running checks — waiting can't clear it —
-while an outstanding required review (cyan) only recolors an otherwise green or
-quiet branch. Cool colors mean waiting, warm colors mean act. A PR with no
-review signal (no required reviewers and no reviews) keeps its plain CI color,
-and draft PRs appear dimmed.
-
-CI cells are clickable links to the PR or pipeline page, and appear dimmed when
-unpushed local changes make the status stale. PRs/MRs are checked first, then
-branch workflows/pipelines for branches with an upstream. Local-only branches
-show blank; remote-only branches — visible with --remotes — get CI status
-detection. Results are cached for 30-60 seconds; use wt config state to view or
-clear.
+ is available (e.g. branch workflows without a PR/MR). One color folds two JSON
+fields: green/blue/red/yellow/gray are ci.status; magenta/cyan are
+ci.review_state. The Value column is the matching JSON string from
+--format=json:
+
+ Indicator Value Meaning
+ ───────── ─────────────────── ────────────────────────────────────────────────
+ # green "passed" All checks passed
+ # blue "running" Checks in progress
+ # red "failed" One or more checks failed
+ # yellow "conflicts" Merge conflicts with the target branch
+ # gray "no-ci" No PR/MR, or no checks configured
+ ⚠ yellow "error" CI status could not be fetched (rate limit,
+ network, etc.)
+ # magenta "changes_requested" A reviewer requested changes
+ # cyan "pending" A review is required (e.g. branch protection)
+ but not yet given
+ (blank) ci absent No upstream, or no PR/MR and no branch workflow
+
+The two remaining ci.review_state values have no indicator of their own: "draft"
+ only dims the cell and "approved" leaves the color unchanged.
+
+Color precedence resolves the fold: changes-requested (magenta) outranks running
+ checks — waiting can't clear it — while an outstanding required review (cyan)
+only recolors an otherwise green or quiet branch. Cool colors mean waiting, warm
+ colors mean act. An approved PR, or one with no review signal at all (no
+required reviewers and no reviews), keeps its plain ci.status color —
+ci.review_state is then "approved" or absent, respectively. GitLab MR data
+carries only "pending" and "draft" — no approved or changes-requested signal.
+
+CI cells are clickable links to the PR or pipeline page, and appear dimmed for a
+ draft PR/MR ("draft") or when unpushed local changes make the status stale
+(ci.stale). PRs/MRs are checked first, then branch workflows/pipelines for
+branches with an upstream. Local-only branches show blank; remote-only branches
+— visible with --remotes — get CI status detection. Results are cached for 30-60
+ seconds; use wt config state to view or clear.
LLM summaries [experimental]
@@ -229,40 +238,82 @@ widths, and drop priority: custom columns config.
Status symbols
-The Status column has multiple subcolumns. Within each, only the first matching
-symbol is shown (listed in priority order):
-
- Subcolumn Symbol Meaning
- ──────────────── ────── ──────────────────────────────────────────────────────
- Working tree (1) + Staged files
- Working tree (2) ! Modified files (unstaged)
- Working tree (3) ? Untracked files
- Worktree ✘ Merge conflicts
- ⤴ Rebase in progress
- ⤵ Merge in progress
- / Branch without worktree
- ⚑ Branch-worktree mismatch (branch name doesn't match
- worktree path)
- ⊟ Prunable (directory missing)
- ⊞ Locked worktree
- Default branch ^ Is the default branch
- ∅ Orphan branch (no common ancestor with the default
- branch)
- ✗ Would conflict if merged to the default branch; with
- --full, includes uncommitted changes
- _ Same commit as the default branch, clean
- – Same commit as the default branch, uncommitted changes
- ⊂ Content integrated into the default branch or target
- ↕ Diverged from the default branch
- ↑ Ahead of the default branch
- ↓ Behind the default branch
- Remote | In sync with remote
- ⇅ Diverged from remote
- ⇡ Ahead of remote
- ⇣ Behind remote
-
-Rows are dimmed when safe to delete (_ same commit with clean working tree or ⊂
-content integrated).
+The Status column packs several subcolumns, left to right, each mapping to a
+field in --format=json. Working-tree flags are independent and co-occur — any
+combination shows at once. The other subcolumns are mutually exclusive: each
+shows a single symbol, the highest-priority state in top-to-bottom table order,
+and is blank when nothing applies.
+
+Working tree
+
+Independent flags from git status; several can show at once (e.g. +!?). Each
+maps to a boolean in the working_tree object:
+
+ Symbol working_tree Meaning
+ ────── ──────────── ─────────────────────────
+ + staged Staged files
+ ! modified Modified files (unstaged)
+ ? untracked Untracked files
+
+working_tree also reports renamed and deleted, which have no dedicated symbol in
+ the column.
+
+Worktree
+
+An in-progress git operation, a worktree-location attribute, or a branch with no
+ worktree. One symbol shows, highest priority first (✘ > ⤴ > ⤵ > ⚑ > ⊟ > ⊞ > /):
+
+ Symbol JSON Meaning
+ ────── ───────────────────────────────────────── ─────────────────────────────
+ ✘ operation_state "conflicts" Merge conflicts
+ ⤴ operation_state "rebase" Rebase in progress
+ ⤵ operation_state "merge" Merge in progress
+ ⚑ worktree.state "branch_worktree_mismatch" Branch name doesn't match the
+ worktree path
+ ⊟ worktree.state "prunable" Prunable (worktree directory
+ missing)
+ ⊞ worktree.state "locked" Locked worktree
+ / kind "branch" Branch without a worktree (no
+ worktree object)
+
+Default branch
+
+The single highest-priority state describing the branch's relation to the
+default branch; blank when none applies (a normal up-to-date branch). Each
+symbol is one main_state value:
+
+ Symb main_state Meaning
+ ol
+ ──── ────────── ──────────────────────────────────────────────────────────────
+ ^ "is_main" The main worktree (the repo's home worktree)
+ ∅ "orphan" No common ancestor with the default branch
+ ✗ "would_con Merging into the default branch would conflict (simulated with
+ flict" git merge-tree); with --full, the check includes uncommitted
+ changes
+ _ "empty" Same commit as the default branch, working tree clean — safe
+ to remove; row dimmed
+ – "same_comm Same commit as the default branch, but with uncommitted
+ it" changes
+ ⊂ "integrate Content integrated into the default branch or merge target via
+ d" different history; the matching check is in integration_reason
+ ; row dimmed
+ ↕ "diverged" Both ahead of and behind the default branch
+ ↑ "ahead" Has commits the default branch doesn't
+ ↓ "behind" Missing commits the default branch has
+
+Rows are dimmed when safe to delete — _ ("empty") or ⊂ ("integrated").
+
+Remote
+
+Relation to the tracking branch, derived from the remote.ahead / remote.behind
+counts; blank when there is no upstream:
+
+ Symbol remote Meaning
+ ────── ───────────────────── ────────────────────
+ | ahead 0, behind 0 In sync with remote
+ ⇡ ahead > 0 Ahead of remote
+ ⇣ behind > 0 Behind remote
+ ⇅ ahead > 0, behind > 0 Diverged from remote
Placeholder symbols
@@ -307,45 +358,46 @@ Query structured data with --format=json:
Fields:
- Field Type Description
- ────────────────── ─────────── ───────────────────────────────────────────────
- branch string/null Branch name (null for detached HEAD)
- path string Worktree path (absent for branches without
- worktrees)
- kind string "worktree" or "branch"
- commit object Commit info (see below)
- working_tree object Working tree state (see below)
- main_state string Relation to the default branch (see below)
- integration_reason string Why branch is integrated (see below)
- operation_state string "conflicts", "rebase", or "merge"; absent when
- clean
- main object Relationship to the default branch (see below);
- absent when is_main
- remote object Tracking branch info (see below); absent when
- no tracking
- worktree object Worktree metadata (see below)
- is_main boolean Is the main worktree
- is_current boolean Is the current worktree
- is_previous boolean Previous worktree from wt switch
- ci object CI status (see below); absent when no CI
- repo_url string Repository web URL derived from the primary
- remote; absent when the remote URL cannot be
- parsed
- repo object Structured repository metadata (see below);
- includes remote
- url string Dev server URL from project config; absent when
- not configured
- url_active boolean Whether the URL's port is listening; absent
- when not configured
- summary string LLM-generated branch summary; absent when not
- configured or no summary
- statusline string Pre-formatted status with ANSI colors
- symbols string Raw status symbols without colors (e.g., "!?↓")
- vars object Per-branch variables from wt config state vars
- (absent when empty)
- columns object Rendered custom column values keyed by header;
- empty cells omitted (absent when none
- configured)
+ Field Type Description
+ ───────────────── ─────────── ────────────────────────────────────────────────
+ branch string/null Branch name (null for detached HEAD)
+ path string Worktree path (absent for branches without
+ worktrees)
+ kind string "worktree" or "branch"
+ commit object Commit info (see below)
+ working_tree object Working tree state (see below)
+ main_state string Relation to the default branch (see below)
+ integration_reaso string Why branch is integrated (see below)
+ n
+ operation_state string "conflicts", "rebase", or "merge" (see
+ Worktree); absent when clean
+ main object Relationship to the default branch (see below);
+ absent when is_main
+ remote object Tracking branch info (see below); absent when no
+ tracking
+ worktree object Worktree metadata (see below)
+ is_main boolean Is the main worktree
+ is_current boolean Is the current worktree
+ is_previous boolean Previous worktree from wt switch
+ ci object CI status (see below); absent when no CI
+ repo_url string Repository web URL derived from the primary
+ remote; absent when the remote URL cannot be
+ parsed
+ repo object Structured repository metadata (see below);
+ includes remote
+ url string Dev server URL from project config; absent when
+ not configured
+ url_active boolean Whether the URL's port is listening; absent when
+ not configured
+ summary string LLM-generated branch summary; absent when not
+ configured or no summary
+ statusline string Pre-formatted status with ANSI colors
+ symbols string Raw status symbols without colors (e.g., "!?↓")
+ vars object Per-branch variables from wt config state vars
+ (absent when empty)
+ columns object Rendered custom column values keyed by header;
+ empty cells omitted (absent when none
+ configured)
Commit object
@@ -359,6 +411,9 @@ Query structured data with --format=json:
working_tree object
+The five change flags map to the Working tree symbols (renamed and deleted have
+none of their own):
+
Field Type Description
───────── ─────── ───────────────────────────────────────
staged boolean Has staged files
@@ -378,6 +433,8 @@ Query structured data with --format=json:
remote object
+ahead / behind drive the Remote divergence symbol:
+
Field Type Description
────── ────── ────────────────────────────
name string Remote name (e.g., "origin")
@@ -387,10 +444,13 @@ Query structured data with --format=json:
worktree object
+Present only for worktree-kind items. state is the worktree-location attribute —
+ see Worktree for its symbols:
+
Field Type Description
──────── ─────── ─────────────────────────────────────────────────────────────
- state string "no_worktree", "branch_worktree_mismatch", "prunable",
- "locked" (absent when normal)
+ state string "branch_worktree_mismatch", "prunable", or "locked" (absent
+ when normal)
reason string Reason for locked/prunable state
detached boolean HEAD is detached
@@ -431,28 +491,40 @@ primary remote. ci.repo describes the repository targeted by the PR/MR U
main_state values
-These values describe the relation to the default branch.
-
-"is_main" "orphan" "would_conflict" "empty" "same_commit" "integrated"
-"diverged" "ahead" "behind"
+The single highest-priority state describing the branch's relation to the
+default branch; absent when none applies (a normal up-to-date branch). Each
+value is one Default-branch symbol — see Default branch for the symbol and the
+full meaning of each value ("is_main", "orphan", "would_conflict", "empty",
+"same_commit", "integrated", "diverged", "ahead", "behind").
integration_reason values
-When main_state == "integrated": "ancestor" "trees-match" "no-added-changes"
-"merge-adds-nothing" "patch-id-match"
-
-ci.status values
-
-"passed" "running" "failed" "conflicts" "no-ci" "error"
-
-ci.review_state values
-
-"approved" "changes_requested" "pending" "draft"
-
-The vocabulary matches Claude Code's statusline pr.review_state field. "pending"
- means a review is required (e.g. branch protection) but not yet given; a PR
-with no review signal at all has no review_state. GitLab reports only "pending"
-and "draft" — MR list data carries no approved or changes-requested signal.
+Set only when main_state == "integrated" (the ⊂ symbol), recording which check
+matched. Checks run cheapest-first and the first match wins. JSON-only — every
+reason renders as the same ⊂:
+
+ Value Meaning
+ ────────────── ───────────────────────────────────────────────────────────────
+ "ancestor" Branch HEAD is an ancestor of the default branch, which has
+ moved past it
+ "no-added-chan The three-dot diff (main...branch) is empty — no file changes
+ ges" beyond the merge-base
+ "trees-match" Different history, but the branch's tree is identical to the
+ default branch's
+ "merge-adds-no The branch has changes, but merging them leaves the default
+ thing" branch's tree unchanged (e.g. a squash merge where the target
+ advanced on other files)
+ "patch-id-matc The branch's squashed diff matches a single commit on the
+ h" default branch (e.g. a GitHub/GitLab squash merge)
+
+ci.status and ci.review_state values
+
+The CI status section above is the single source for both fields: the table maps
+ each colored value, and the notes below it cover "draft" and "approved".
+ci.status is one of "passed", "running", "failed", "conflicts", "no-ci",
+"error"; ci.review_state is one of "changes_requested", "pending", "draft",
+"approved", absent when the forge reports no review signal. The vocabulary
+matches Claude Code's statusline pr.review_state field.
Missing a field that would be generally useful? Open an issue at
https://github.com/max-sixty/worktrunk.