Skip to content

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

docs(list): note --full requirement on summary and main.diff JSON fields (#3224)

Maximilian Roosc3abee15efb5
diff --git a/docs/content/list.md b/docs/content/list.md
index 796fdbf89..12f5216e2 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -242,7 +242,7 @@ Query structured data with `--format=json`:
| `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 |
+| `summary` | string | LLM-generated branch summary; `--full` only, then 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`](@/config.md#wt-config-state-vars) (absent when empty) |
@@ -276,7 +276,7 @@ The five change flags map to the [Working tree](#working-tree) symbols (`renamed
|-------|------|-------------|
| `ahead` | number | Commits ahead of the default branch |
| `behind` | number | Commits behind the default branch |
-| `diff` | object | Lines changed vs the default branch: `{added, deleted}` |
+| `diff` | object | Lines changed vs the default branch: `{added, deleted}`; `--full` only |
### remote object
diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.md
index 00a5df036..7d81e6fcc 100644
--- a/skills/worktrunk/reference/list.md
+++ b/skills/worktrunk/reference/list.md
@@ -251,7 +251,7 @@ $ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
| `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 |
+| `summary` | string | LLM-generated branch summary; `--full` only, then 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`](https://worktrunk.dev/config/#wt-config-state-vars) (absent when empty) |
@@ -285,7 +285,7 @@ The five change flags map to the [Working tree](#working-tree) symbols (`renamed
|-------|------|-------------|
| `ahead` | number | Commits ahead of the default branch |
| `behind` | number | Commits behind the default branch |
-| `diff` | object | Lines changed vs the default branch: `{added, deleted}` |
+| `diff` | object | Lines changed vs the default branch: `{added, deleted}`; `--full` only |
### remote object
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 52c7a14b2..536357221 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -989,7 +989,7 @@ $ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
| `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 |
+| `summary` | string | LLM-generated branch summary; `--full` only, then 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`](@/config.md#wt-config-state-vars) (absent when empty) |
@@ -1023,7 +1023,7 @@ The five change flags map to the [Working tree](#working-tree) symbols (`renamed
|-------|------|-------------|
| `ahead` | number | Commits ahead of the default branch |
| `behind` | number | Commits behind the default branch |
-| `diff` | object | Lines changed vs the default branch: `{added, deleted}` |
+| `diff` | object | Lines changed vs the default branch: `{added, deleted}`; `--full` only |
### remote object
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 960fd2b66..4f1a3674d 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -318,7 +318,7 @@ Query structured data with --format=json:
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
+ summary string LLM-generated branch summary; --full only, then 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)
@@ -348,11 +348,11 @@ The five change flags map to the Working tree symbols (renamed and d
main object
- Field Type Description
- ────── ────── ─────────────────────────────────────────────────────
- ahead number Commits ahead of the default branch
- behind number Commits behind the default branch
- diff object Lines changed vs the default branch: {added, deleted}
+ Field Type Description
+ ────── ────── ──────────────────────────────────────────────────────────────────
+ ahead number Commits ahead of the default branch
+ behind number Commits behind the default branch
+ diff object Lines changed vs the default branch: {added, deleted}; --full only
remote object
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 8097bab8c..4356a949d 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
@@ -359,46 +359,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_reas string Why branch is integrated (see below)
- on
- 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); --full only, then absent
- when no PR/MR or branch workflow
- 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_rea string Why branch is integrated (see below)
+ son
+ 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); --full only, then absent
+ when no PR/MR or branch workflow
+ 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; --full only, then
+ 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
@@ -426,11 +426,12 @@ none of their own):
main object
- Field Type Description
- ────── ────── ─────────────────────────────────────────────────────
- ahead number Commits ahead of the default branch
- behind number Commits behind the default branch
- diff object Lines changed vs the default branch: {added, deleted}
+ Field Type Description
+ ────── ────── ────────────────────────────────────────────────────────────────
+ ahead number Commits ahead of the default branch
+ behind number Commits behind the default branch
+ diff object Lines changed vs the default branch: {added, deleted}; --full
+ only
remote object