Skip to content

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

feat: improve `wt list` help docs and update shell completion snapshots

Maximilian Roos8062f85c0623
diff --git a/.claude-plugin/skills/worktrunk/reference/README.md b/.claude-plugin/skills/worktrunk/reference/README.md
index c3a2f1cb9..9e86c4957 100644
--- a/.claude-plugin/skills/worktrunk/reference/README.md
+++ b/.claude-plugin/skills/worktrunk/reference/README.md
@@ -615,32 +615,20 @@ Order: `?!+»✘ ✖⚠≡∅ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠`
**JSON OUTPUT:**
-Use `--format=json` for structured data. Each object contains two status maps:
-
-**`status` (variant names for querying):**
-- `branch_state`: "" | "Conflicts" | "MergeTreeConflicts" | "MatchesMain" | "NoCommits"
-- `git_operation`: "" | "Rebase" | "Merge"
-- `worktree_attrs`: object (worktrees only) with:
- - `locked`: null | "reason string"
- - `prunable`: null | "reason string"
-- `main_divergence`: "" | "Ahead" | "Behind" | "Diverged"
-- `upstream_divergence`: "" | "Ahead" | "Behind" | "Diverged"
-- `working_tree`: object with booleans
- - `untracked`: boolean - untracked files present
- - `modified`: boolean - unstaged changes
- - `staged`: boolean - staged changes
- - `renamed`: boolean - renamed files
- - `deleted`: boolean - deleted files
-- `user_status`: string (optional) - custom status from git config
-
-**`status_symbols` (display symbols for rendering):**
-- `branch_state`: "" | "✖" | "⚠" | "≡" | "∅"
-- `git_operation`: "" | "↻" | "⋈"
-- `worktree_attrs`: "⎇" (branch) | "⌫" (prunable) | "⊠" (locked) | ""
-- `main_divergence`: "" | "↑" | "↓" | "↕"
-- `upstream_divergence`: "" | "⇡" | "⇣" | "⇅"
-- `working_tree`: string - combination of "?!+»✘"
-- `user_status`: string (optional) - same as status.user_status
+Use `--format=json` for structured data. Each object contains two status maps
+with the same fields in the same order as STATUS SYMBOLS above:
+
+**`status`** - variant names for querying:
+- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans
+- `branch_state`: `""` | `"Conflicts"` | `"MergeTreeConflicts"` | `"MatchesMain"` | `"NoCommits"`
+- `git_operation`: `""` | `"Rebase"` | `"Merge"`
+- `main_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
+- `upstream_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
+- `user_status`: string (optional)
+
+**`status_symbols`** - Unicode symbols for display (same fields, plus `worktree_attrs`: ⎇/⌫/⊠)
+
+Note: `locked` and `prunable` are top-level fields on worktree objects, not in status.
**Query examples:**
@@ -648,17 +636,17 @@ Use `--format=json` for structured data. Each object contains two status maps:
# Find worktrees with conflicts
jq '.[] | select(.status.branch_state == "Conflicts")'
-# Find locked worktrees
-jq '.[] | select(.status.worktree_attrs.locked != null)'
-
# Find worktrees with untracked files
-jq '.[] | select(.status.working_tree.untracked == true)'
+jq '.[] | select(.status.working_tree.untracked)'
# Find worktrees in rebase or merge
jq '.[] | select(.status.git_operation != "")'
# Get branches ahead of main
jq '.[] | select(.status.main_divergence == "Ahead")'
+
+# Find locked worktrees
+jq '.[] | select(.locked != null)'
```
</details>
diff --git a/README.md b/README.md
index c3a2f1cb9..9e86c4957 100644
--- a/README.md
+++ b/README.md
@@ -615,32 +615,20 @@ Order: `?!+»✘ ✖⚠≡∅ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠`
**JSON OUTPUT:**
-Use `--format=json` for structured data. Each object contains two status maps:
-
-**`status` (variant names for querying):**
-- `branch_state`: "" | "Conflicts" | "MergeTreeConflicts" | "MatchesMain" | "NoCommits"
-- `git_operation`: "" | "Rebase" | "Merge"
-- `worktree_attrs`: object (worktrees only) with:
- - `locked`: null | "reason string"
- - `prunable`: null | "reason string"
-- `main_divergence`: "" | "Ahead" | "Behind" | "Diverged"
-- `upstream_divergence`: "" | "Ahead" | "Behind" | "Diverged"
-- `working_tree`: object with booleans
- - `untracked`: boolean - untracked files present
- - `modified`: boolean - unstaged changes
- - `staged`: boolean - staged changes
- - `renamed`: boolean - renamed files
- - `deleted`: boolean - deleted files
-- `user_status`: string (optional) - custom status from git config
-
-**`status_symbols` (display symbols for rendering):**
-- `branch_state`: "" | "✖" | "⚠" | "≡" | "∅"
-- `git_operation`: "" | "↻" | "⋈"
-- `worktree_attrs`: "⎇" (branch) | "⌫" (prunable) | "⊠" (locked) | ""
-- `main_divergence`: "" | "↑" | "↓" | "↕"
-- `upstream_divergence`: "" | "⇡" | "⇣" | "⇅"
-- `working_tree`: string - combination of "?!+»✘"
-- `user_status`: string (optional) - same as status.user_status
+Use `--format=json` for structured data. Each object contains two status maps
+with the same fields in the same order as STATUS SYMBOLS above:
+
+**`status`** - variant names for querying:
+- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans
+- `branch_state`: `""` | `"Conflicts"` | `"MergeTreeConflicts"` | `"MatchesMain"` | `"NoCommits"`
+- `git_operation`: `""` | `"Rebase"` | `"Merge"`
+- `main_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
+- `upstream_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
+- `user_status`: string (optional)
+
+**`status_symbols`** - Unicode symbols for display (same fields, plus `worktree_attrs`: ⎇/⌫/⊠)
+
+Note: `locked` and `prunable` are top-level fields on worktree objects, not in status.
**Query examples:**
@@ -648,17 +636,17 @@ Use `--format=json` for structured data. Each object contains two status maps:
# Find worktrees with conflicts
jq '.[] | select(.status.branch_state == "Conflicts")'
-# Find locked worktrees
-jq '.[] | select(.status.worktree_attrs.locked != null)'
-
# Find worktrees with untracked files
-jq '.[] | select(.status.working_tree.untracked == true)'
+jq '.[] | select(.status.working_tree.untracked)'
# Find worktrees in rebase or merge
jq '.[] | select(.status.git_operation != "")'
# Get branches ahead of main
jq '.[] | select(.status.main_divergence == "Ahead")'
+
+# Find locked worktrees
+jq '.[] | select(.locked != null)'
```
</details>
diff --git a/src/cli.rs b/src/cli.rs
index f45194e0d..c5d1d1816 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -115,11 +115,11 @@ pub enum OutputFormat {
#[command(styles = help_styles())]
pub struct Cli {
/// Change working directory
- #[arg(short = 'C', global = true, value_name = "path")]
+ #[arg(short = 'C', global = true, value_name = "path", display_order = 100)]
pub directory: Option<std::path::PathBuf>,
/// Show commands and debug info
- #[arg(long, short = 'v', global = true)]
+ #[arg(long, short = 'v', global = true, display_order = 101)]
pub verbose: bool,
/// Use internal mode (outputs directives for shell wrapper)
@@ -256,7 +256,7 @@ pub enum StandaloneCommand {
verify: bool,
},
- /// Push changes to target branch
+ /// Push changes to local target branch
///
/// Automatically stashes non-conflicting edits in the target worktree before
/// the push and restores them afterward so other agents' changes stay intact.
@@ -370,16 +370,7 @@ Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat
},
/// List worktrees and optionally branches
- #[command(after_long_help = "## OPERATION
-
-Displays worktrees in a table format with status information, commit details, and optional branch listings.
-
-- **By default:** Shows only worktrees
-- **With `--branches`:** Includes branches without worktrees
-- **With `--full`:** Adds CI status, conflict detection, and detailed diffs
-- **With `--format=json`:** Outputs structured JSON for scripting
-
-## COLUMNS
+ #[command(after_long_help = "## COLUMNS
- **Branch:** Branch name
- **Status:** Quick status symbols (see STATUS SYMBOLS below)
@@ -429,52 +420,40 @@ Order: `?!+»✘ ✖⚠≡∅ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠`
## JSON OUTPUT
-Use `--format=json` for structured data. Each object contains two status maps:
-
-**`status` (variant names for querying):**
-- `branch_state`: \"\" | \"Conflicts\" | \"MergeTreeConflicts\" | \"MatchesMain\" | \"NoCommits\"
-- `git_operation`: \"\" | \"Rebase\" | \"Merge\"
-- `worktree_attrs`: object (worktrees only) with:
- - `locked`: null | \"reason string\"
- - `prunable`: null | \"reason string\"
-- `main_divergence`: \"\" | \"Ahead\" | \"Behind\" | \"Diverged\"
-- `upstream_divergence`: \"\" | \"Ahead\" | \"Behind\" | \"Diverged\"
-- `working_tree`: object with booleans
- - `untracked`: boolean - untracked files present
- - `modified`: boolean - unstaged changes
- - `staged`: boolean - staged changes
- - `renamed`: boolean - renamed files
- - `deleted`: boolean - deleted files
-- `user_status`: string (optional) - custom status from git config
-
-**`status_symbols` (display symbols for rendering):**
-- `branch_state`: \"\" | \"✖\" | \"⚠\" | \"≡\" | \"∅\"
-- `git_operation`: \"\" | \"↻\" | \"⋈\"
-- `worktree_attrs`: \"⎇\" (branch) | \"⌫\" (prunable) | \"⊠\" (locked) | \"\"
-- `main_divergence`: \"\" | \"↑\" | \"↓\" | \"↕\"
-- `upstream_divergence`: \"\" | \"⇡\" | \"⇣\" | \"⇅\"
-- `working_tree`: string - combination of \"?!+»✘\"
-- `user_status`: string (optional) - same as status.user_status
+Use `--format=json` for structured data. Each object contains two status maps
+with the same fields in the same order as STATUS SYMBOLS above:
+
+**`status`** - variant names for querying:
+- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans
+- `branch_state`: `\"\"` | `\"Conflicts\"` | `\"MergeTreeConflicts\"` | `\"MatchesMain\"` | `\"NoCommits\"`
+- `git_operation`: `\"\"` | `\"Rebase\"` | `\"Merge\"`
+- `main_divergence`: `\"\"` | `\"Ahead\"` | `\"Behind\"` | `\"Diverged\"`
+- `upstream_divergence`: `\"\"` | `\"Ahead\"` | `\"Behind\"` | `\"Diverged\"`
+- `user_status`: string (optional)
+
+**`status_symbols`** - Unicode symbols for display (same fields, plus `worktree_attrs`: ⎇/⌫/⊠)
+
+Note: `locked` and `prunable` are top-level fields on worktree objects, not in status.
**Query examples:**
# Find worktrees with conflicts
jq '.[] | select(.status.branch_state == \"Conflicts\")'
- # Find locked worktrees
- jq '.[] | select(.status.worktree_attrs.locked != null)'
-
# Find worktrees with untracked files
- jq '.[] | select(.status.working_tree.untracked == true)'
+ jq '.[] | select(.status.working_tree.untracked)'
# Find worktrees in rebase or merge
jq '.[] | select(.status.git_operation != \"\")'
# Get branches ahead of main
- jq '.[] | select(.status.main_divergence == \"Ahead\")'")]
+ jq '.[] | select(.status.main_divergence == \"Ahead\")'
+
+ # Find locked worktrees
+ jq '.[] | select(.locked != null)'")]
List {
- /// Output format
- #[arg(long, value_enum, default_value = "table")]
+ /// Output format (table, json)
+ #[arg(long, value_enum, default_value = "table", hide_possible_values = true)]
format: OutputFormat,
/// Include branches without worktrees
@@ -482,16 +461,11 @@ Use `--format=json` for structured data. Each object contains two status maps:
branches: bool,
/// Show CI, conflicts, diffs
- ///
- /// Adds CI column, main…± diffs, and conflict detection (merge-tree + network).
- #[arg(long, verbatim_doc_comment)]
+ #[arg(long)]
full: bool,
- /// Progressive rendering
- ///
- /// Use --progressive or --no-progressive to force rendering mode.
- /// Default: auto (enabled for TTY, disabled for pipes).
- #[arg(long, overrides_with = "no_progressive", verbatim_doc_comment)]
+ /// Force progressive (or --no-progressive)
+ #[arg(long, overrides_with = "no_progressive")]
progressive: bool,
/// Force buffered rendering
@@ -601,33 +575,20 @@ wt remove @ # Remove current worktree
/// Remove worktree and branch
#[command(after_long_help = r#"## OPERATION
-**Remove Current Worktree** (no arguments):
-- Requires clean working tree (no uncommitted changes)
-- If in worktree: removes it and switches to main worktree
-- If in main worktree: switches to default branch (e.g., `main`)
-- If already on default branch in main: does nothing
-
-**Remove Specific Worktree** (by name):
-- Requires target worktree has clean working tree
-- Removes specified worktree(s) and associated branches
-- If removing current worktree, switches to main first
-- Can remove multiple worktrees in one command
-
-**Remove Multiple Worktrees:**
-- When removing multiple, current worktree is removed last
-- Prevents deleting directory you're currently in
-- Each worktree must have clean working tree
-
-**Removal Process** (by default):
-1. **Validates** worktree has no uncommitted changes
-2. **Changes directory** (if removing current worktree)
-3. **Spawns background removal process** (non-blocking)
- - Directory deletion happens in background
- - Git worktree metadata removed in background
- - Branch deletion in background (uses `git branch -d`, safe delete)
- - Logs: `.git/wt-logs/{branch}-remove.log`
-4. **Returns immediately** so you can continue working
- - Use `--no-background` for foreground removal (blocking)
+Removes worktree directory, git metadata, and branch. Requires clean working tree.
+
+**No arguments** (remove current):
+- Removes current worktree and switches to main worktree
+- In main worktree: switches to default branch
+
+**By name** (remove specific):
+- Removes specified worktree(s) and branches
+- Current worktree removed last (switches to main first)
+
+**Background removal** (default):
+- Returns immediately so you can continue working
+- Logs: `.git/wt-logs/{branch}-remove.log`
+- Use `--no-background` for foreground (blocking)
## EXAMPLES
@@ -679,58 +640,24 @@ wt remove # (when already in main worktree)
},
/// Merge worktree into target branch
- #[command(long_about = r#"Merge worktree into target branch
-
-## OPERATION
-
-The merge operation follows a strict order designed for **fail-fast execution**:
-
-1. **Validate branches**
- Verifies current branch exists (not detached HEAD) and determines target branch
- (defaults to repository's default branch).
-
-2. **Auto-commit uncommitted changes**
- If working tree has uncommitted changes, stages changes and commits with LLM-generated
- message. By default stages all changes (`git add -A`). Use `--tracked-only` to stage only
- tracked files (`git add -u`).
-
-3. **Squash commits** (default)
- By default, counts commits since merge base with target branch. When multiple
- commits exist, squashes them into one with LLM-generated message. Skip squashing
- with `--no-squash`.
-
- A safety backup is created before squashing if there are working tree changes.
- Recover with: `git reflog show refs/wt-backup/<branch>`
+ #[command(after_long_help = r#"## OPERATION
-4. **Rebase onto target**
- Rebases current branch onto target branch. Detects conflicts and aborts if found.
- This fails fast before running expensive checks.
+Commit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks
-5. **Run pre-merge commands**
- Runs commands from project config's `[pre-merge-command]` after rebase completes.
- These receive `{{ target }}` placeholder for the target branch. Commands run sequentially
- and any failure aborts the merge immediately. Skip with `--no-verify`.
+**Commit**: Uncommitted changes are staged and committed with LLM-generated message.
+Use `--tracked-only` to stage only tracked files.
-6. **Push to target**
- Fast-forward pushes to target branch. Rejects non-fast-forward pushes (ensures
- linear history). Temporarily stashes non-conflicting local edits in the target
- worktree so they don't block the push, then restores them after success.
+**Squash**: Multiple commits are squashed into one with LLM-generated message.
+Skip with `--no-squash`. Safety backup: `git reflog show refs/wt-backup/<branch>`
-7. **Clean up worktree and branch**
- Removes current worktree, deletes the branch, and switches main worktree to target
- branch if needed. Skip removal with `--no-remove`.
+**Rebase**: Branch is rebased onto target. Conflicts abort the merge immediately.
-8. **Run post-merge commands**
- Runs commands from project config's `[post-merge-command]` in the destination worktree
- after cleanup. These receive `{{ target }}` placeholder. Commands run sequentially,
- failures are logged but don't abort. Skip with `--no-verify`.
+**Hooks**: Pre-merge commands run after rebase (failures abort). Post-merge commands
+run after cleanup (failures logged). Skip all with `--no-verify`.
-## HOOKS
+**Push**: Fast-forward push to local target branch. Non-fast-forward pushes are rejected.
-The `--no-verify` flag skips all project hooks:
-- Pre-commit hooks (before committing working tree changes)
-- Pre-merge hooks (after rebase, before push)
-- Post-merge hooks (after cleanup)
+**Cleanup**: Worktree and branch are removed. Skip with `--no-remove`.
## EXAMPLES
diff --git a/src/commands/list/model.rs b/src/commands/list/model.rs
index 28f8be1c6..b5930e6a9 100644
--- a/src/commands/list/model.rs
+++ b/src/commands/list/model.rs
@@ -688,26 +688,30 @@ impl WorkingTreeChanges {
}
/// Status variant names (for queryability)
+///
+/// Field order matches display order in STATUS SYMBOLS: working_tree → branch_state → ...
#[derive(Debug, Clone, serde::Serialize)]
struct QueryableStatus {
+ working_tree: WorkingTreeChanges,
branch_state: &'static str,
git_operation: &'static str,
main_divergence: &'static str,
upstream_divergence: &'static str,
- working_tree: WorkingTreeChanges,
#[serde(skip_serializing_if = "Option::is_none")]
user_status: Option<String>,
}
/// Status symbols (for display)
+///
+/// Field order matches display order in STATUS SYMBOLS: working_tree → branch_state → ...
#[derive(Debug, Clone, serde::Serialize)]
struct DisplaySymbols {
+ working_tree: String,
branch_state: String,
git_operation: String,
- worktree_attrs: String,
main_divergence: String,
upstream_divergence: String,
- working_tree: String,
+ worktree_attrs: String,
#[serde(skip_serializing_if = "Option::is_none")]
user_status: Option<String>,
}
@@ -750,21 +754,21 @@ impl serde::Serialize for StatusSymbols {
};
let queryable_status = QueryableStatus {
+ working_tree: WorkingTreeChanges::from_symbols(&self.working_tree),
branch_state: branch_state_variant,
git_operation: git_operation_variant,
main_divergence: main_divergence_variant,
upstream_divergence: upstream_divergence_variant,
- working_tree: WorkingTreeChanges::from_symbols(&self.working_tree),
user_status: self.user_status.clone(),
};
let display_symbols = DisplaySymbols {
+ working_tree: self.working_tree.clone(),
branch_state: self.branch_state.to_string(),
git_operation: self.git_operation.to_string(),
- worktree_attrs: self.item_attrs.clone(),
main_divergence: self.main_divergence.to_string(),
upstream_divergence: self.upstream_divergence.to_string(),
- working_tree: self.working_tree.clone(),
+ worktree_attrs: self.item_attrs.clone(),
user_status: self.user_status.clone(),
};
diff --git a/tests/snapshots/integration__integration_tests__help__help_beta.snap b/tests/snapshots/integration__integration_tests__help__help_beta.snap
index cbff00f89..491dcb91d 100644
--- a/tests/snapshots/integration__integration_tests__help__help_beta.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_beta.snap
@@ -20,7 +20,7 @@ Commands:
run-hook Run project hook
commit Commit changes with LLM-generated message
squash Squash commits with LLM-generated message
- push Push changes to target branch
+ push Push changes to local target branch
rebase Rebase onto target
ask-approvals Store approvals in config
clear-approvals Clear approved commands from config
diff --git a/tests/snapshots/integration__integration_tests__help__help_init.snap b/tests/snapshots/integration__integration_tests__help__help_init.snap
index b41d0696a..69d8a324e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_init.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_init.snap
@@ -17,14 +17,14 @@ wt-init - Generate shell integration code
Usage: wt init [OPTIONS] <SHELL>
Options:
- -C <path>
- Change working directory
-
--command-name <COMMAND_NAME>
Command name
[default: wt]
+ -C <path>
+ Change working directory
+
-v, --verbose
Show commands and debug info
diff --git a/tests/snapshots/integration__integration_tests__help__help_list.snap b/tests/snapshots/integration__integration_tests__help__help_list.snap
index 2f6718887..45e0b8060 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list.snap
@@ -1,6 +1,5 @@
---
source: tests/integration_tests/help.rs
-assertion_line: 16
info:
program: wt
args:
@@ -18,49 +17,29 @@ wt-list - List worktrees and optionally branches
Usage: wt list [OPTIONS]
Options:
- -C <path>
- Change working directory
-
- --format <FORMAT>
- Output format
-
- Possible values:
- - table: Human-readable table format
- - json: JSON output
-
- [default: table]
+ --format <FORMAT>
+ Output format (table, json)
+
+ [default: table]
--branches
Include branches without worktrees
- -v, --verbose
- Show commands and debug info
+ --full
+ Show CI, conflicts, diffs
- --full
- Show CI, conflicts, diffs
-
- Adds CI column, main…± diffs, and conflict detection (merge-tree +
-network).
+ --progressive
+ Force progressive (or --no-progressive)
- --progressive
- Progressive rendering
-
- Use --progressive or --no-progressive to force rendering mode.
- Default: auto (enabled for TTY, disabled for pipes).
+ -C <path>
+ Change working directory
+
+ -v, --verbose
+ Show commands and debug info
-h, --help
Print help (see a summary with '-h')
-OPERATION
-
-Displays worktrees in a table format with status information, commit details,
-and optional branch listings.
-
-- By default: Shows only worktrees
-- With --branches: Includes branches without worktrees
-- With --full: Adds CI status, conflict detection, and detailed diffs
-- With --format=json: Outputs structured JSON for scripting
-
COLUMNS
- Branch: Branch name
@@ -114,44 +93,31 @@ Rows are dimmed when no unique work (≡ matches main OR ∅ no commits).
JSON OUTPUT
-Use --format=json for structured data. Each object contains two status maps:
+Use --format=json for structured data. Each object contains two status maps
+with the same fields in the same order as STATUS SYMBOLS above:
-status (variant names for querying):
+status - variant names for querying:
+- working_tree: {untracked, modified, staged, renamed, deleted} booleans
- branch_state: "" | "Conflicts" | "MergeTreeConflicts" | "MatchesMain" |
"NoCommits"
- git_operation: "" | "Rebase" | "Merge"
-- worktree_attrs: object (worktrees only) with:
- - locked: null | "reason string"
- - prunable: null | "reason string"
- main_divergence: "" | "Ahead" | "Behind" | "Diverged"
- upstream_divergence: "" | "Ahead" | "Behind" | "Diverged"
-- working_tree: object with booleans
- - untracked: boolean - untracked files present
- - modified: boolean - unstaged changes
- - staged: boolean - staged changes
- - renamed: boolean - renamed files
- - deleted: boolean - deleted files
-- user_status: string (optional) - custom status from git config
-
-status_symbols (display symbols for rendering):
-- branch_state: "" | "✖" | "⚠" | "≡" | "∅"
-- git_operation: "" | "↻" | "⋈"
-- worktree_attrs: "⎇" (branch) | "⌫" (prunable) | "⊠" (locked) | ""
-- main_divergence: "" | "↑" | "↓" | "↕"
-- upstream_divergence: "" | "⇡" | "⇣" | "⇅"
-- working_tree: string - combination of "?!+»✘"
-- user_status: string (optional) - same as status.user_status
+- user_status: string (optional)
+
+status_symbols - Unicode symbols for display (same fields, plus worktree_attrs:
+⎇/⌫/⊠)
+
+Note: locked and prunable are top-level fields on worktree objects, not in
+status.
Query examples:
# Find worktrees with conflicts
jq '.[] | select(.status.branch_state == "Conflicts")'
- # Find locked worktrees
- jq '.[] | select(.status.worktree_attrs.locked != null)'
-
# Find worktrees with untracked files
- jq '.[] | select(.status.working_tree.untracked == true)'
+ jq '.[] | select(.status.working_tree.untracked)'
# Find worktrees in rebase or merge
jq '.[] | select(.status.git_operation != "")'
@@ -159,4 +125,7 @@ Query examples:
# Get branches ahead of main
jq '.[] | select(.status.main_divergence == "Ahead")'
+ # Find locked worktrees
+ jq '.[] | select(.locked != null)'
+
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge.snap b/tests/snapshots/integration__integration_tests__help__help_merge.snap
index 1a0a4be54..660887ffb 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge.snap
@@ -14,99 +14,15 @@ success: true
exit_code: 0
----- stdout -----
wt-merge - Merge worktree into target branch
-
-OPERATION
-
-The merge operation follows a strict order designed for fail-fast execution:
-
-1. Validate branches
- Verifies current branch exists (not detached HEAD) and determines target
-branch
- (defaults to repository's default branch).
-
-2. Auto-commit uncommitted changes
- If working tree has uncommitted changes, stages changes and commits with
-LLM-generated
- message. By default stages all changes (git add -A). Use --tracked-only to
-stage only
- tracked files (git add -u).
-
-3. Squash commits (default)
- By default, counts commits since merge base with target branch. When multiple
- commits exist, squashes them into one with LLM-generated message. Skip
-squashing
- with --no-squash.
-
- A safety backup is created before squashing if there are working tree
-changes.
- Recover with: git reflog show refs/wt-backup/<branch>
-
-4. Rebase onto target
- Rebases current branch onto target branch. Detects conflicts and aborts if
-found.
- This fails fast before running expensive checks.
-
-5. Run pre-merge commands
- Runs commands from project config's [pre-merge-command] after rebase
-completes.
- These receive {{ target }} placeholder for the target branch. Commands run
-sequentially
- and any failure aborts the merge immediately. Skip with --no-verify.
-
-6. Push to target
- Fast-forward pushes to target branch. Rejects non-fast-forward pushes
-(ensures
- linear history). Temporarily stashes non-conflicting local edits in the
-target
- worktree so they don't block the push, then restores them after success.
-
-7. Clean up worktree and branch
- Removes current worktree, deletes the branch, and switches main worktree to
-target
- branch if needed. Skip removal with --no-remove.
-
-8. Run post-merge commands
- Runs commands from project config's [post-merge-command] in the destination
-worktree
- after cleanup. These receive {{ target }} placeholder. Commands run
-sequentially,
- failures are logged but don't abort. Skip with --no-verify.
-
-HOOKS
-
-The --no-verify flag skips all project hooks:
-- Pre-commit hooks (before committing working tree changes)
-- Pre-merge hooks (after rebase, before push)
-- Post-merge hooks (after cleanup)
-
-EXAMPLES
-
-Basic merge to main:
-wt merge
-
-Merge without squashing:
-wt merge --no-squash
-
-Keep worktree after merging:
-wt merge --no-remove
-
-Skip all hooks:
-wt merge --no-verify
Usage: wt merge [OPTIONS] [TARGET]
Options:
- -C <path>
- Change working directory
-
--no-squash
Skip commit squashing
--no-commit
Skip commit, squash, and rebase
- -v, --verbose
- Show commands and debug info
-
--no-remove
Keep worktree after merge
@@ -119,7 +35,47 @@ Options:
--tracked-only
Stage tracked files only
+ -C <path>
+ Change working directory
+
+ -v, --verbose
+ Show commands and debug info
+
-h, --help
Print help (see a summary with '-h')
+OPERATION
+
+Commit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks
+
+Commit: Uncommitted changes are staged and committed with LLM-generated message.
+Use --tracked-only to stage only tracked files.
+
+Squash: Multiple commits are squashed into one with LLM-generated message.
+Skip with --no-squash. Safety backup: git reflog show refs/wt-backup/<branch>
+
+Rebase: Branch is rebased onto target. Conflicts abort the merge immediately.
+
+Hooks: Pre-merge commands run after rebase (failures abort). Post-merge commands
+run after cleanup (failures logged). Skip all with --no-verify.
+
+Push: Fast-forward push to local target branch. Non-fast-forward pushes are
+rejected.
+
+Cleanup: Worktree and branch are removed. Skip with --no-remove.
+
+EXAMPLES
+
+Basic merge to main:
+wt merge
+
+Merge without squashing:
+wt merge --no-squash
+
+Keep worktree after merging:
+wt merge --no-remove
+
+Skip all hooks:
+wt merge --no-verify
+
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove.snap b/tests/snapshots/integration__integration_tests__help__help_remove.snap
index 1a498758f..fba4c1769 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove.snap
@@ -17,53 +17,41 @@ wt-remove - Remove worktree and branch
Usage: wt remove [OPTIONS] [WORKTREES]...
Options:
- -C <path>
- Change working directory
-
--no-delete-branch
Keep branch after removal
-D, --force-delete
Delete unmerged branches
- -v, --verbose
- Show commands and debug info
-
--no-background
Run removal in foreground
+ -C <path>
+ Change working directory
+
+ -v, --verbose
+ Show commands and debug info
+
-h, --help
Print help (see a summary with '-h')
OPERATION
-Remove Current Worktree (no arguments):
-- Requires clean working tree (no uncommitted changes)
-- If in worktree: removes it and switches to main worktree
-- If in main worktree: switches to default branch (e.g., main)
-- If already on default branch in main: does nothing
-
-Remove Specific Worktree (by name):
-- Requires target worktree has clean working tree
-- Removes specified worktree(s) and associated branches
-- If removing current worktree, switches to main first
-- Can remove multiple worktrees in one command
-
-Remove Multiple Worktrees:
-- When removing multiple, current worktree is removed last
-- Prevents deleting directory you're currently in
-- Each worktree must have clean working tree
-
-Removal Process (by default):
-1. Validates worktree has no uncommitted changes
-2. Changes directory (if removing current worktree)
-3. Spawns background removal process (non-blocking)
- - Directory deletion happens in background
- - Git worktree metadata removed in background
- - Branch deletion in background (uses git branch -d, safe delete)
- - Logs: .git/wt-logs/{branch}-remove.log
-4. Returns immediately so you can continue working
- - Use --no-background for foreground removal (blocking)
+Removes worktree directory, git metadata, and branch. Requires clean working
+tree.
+
+No arguments (remove current):
+- Removes current worktree and switches to main worktree
+- In main worktree: switches to default branch
+
+By name (remove specific):
+- Removes specified worktree(s) and branches
+- Current worktree removed last (switches to main first)
+
+Background removal (default):
+- Returns immediately so you can continue working
+- Logs: .git/wt-logs/{branch}-remove.log
+- Use --no-background for foreground (blocking)
EXAMPLES
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch.snap b/tests/snapshots/integration__integration_tests__help__help_switch.snap
index 903e32164..e3d57b009 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch.snap
@@ -20,15 +20,9 @@ Options:
-c, --create
Create a new branch
- -C <path>
- Change working directory
-
-b, --base <BASE>
Base branch (defaults to default branch)
- -v, --verbose
- Show commands and debug info
-
-x, --execute <EXECUTE>
Execute command after switching
@@ -38,6 +32,12 @@ Options:
--no-verify
Skip all project hooks
+ -C <path>
+ Change working directory
+
+ -v, --verbose
+ Show commands and debug info
+
-h, --help
Print help (see a summary with '-h')
diff --git a/tests/snapshots/integration__integration_tests__init__init_fish.snap b/tests/snapshots/integration__integration_tests__init__init_fish.snap
index 4dc4ded3f..f562a9236 100644
--- a/tests/snapshots/integration__integration_tests__init__init_fish.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_fish.snap
@@ -19,7 +19,7 @@ info:
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpmxQ2Xu/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpDJ4JgG/test-config.toml
---
success: true
exit_code: 0
@@ -238,7 +238,7 @@ complete -c wt -n "__fish_wt_using_subcommand beta; and not __fish_seen_subcomma
complete -c wt -n "__fish_wt_using_subcommand beta; and not __fish_seen_subcommand_from run-hook commit squash push rebase ask-approvals clear-approvals select" -f -a "run-hook" -d 'Run project hook'
complete -c wt -n "__fish_wt_using_subcommand beta; and not __fish_seen_subcommand_from run-hook commit squash push rebase ask-approvals clear-approvals select" -f -a "commit" -d 'Commit changes with LLM-generated message'
complete -c wt -n "__fish_wt_using_subcommand beta; and not __fish_seen_subcommand_from run-hook commit squash push rebase ask-approvals clear-approvals select" -f -a "squash" -d 'Squash commits with LLM-generated message'
-complete -c wt -n "__fish_wt_using_subcommand beta; and not __fish_seen_subcommand_from run-hook commit squash push rebase ask-approvals clear-approvals select" -f -a "push" -d 'Push changes to target branch'
+complete -c wt -n "__fish_wt_using_subcommand beta; and not __fish_seen_subcommand_from run-hook commit squash push rebase ask-approvals clear-approvals select" -f -a "push" -d 'Push changes to local target branch'
complete -c wt -n "__fish_wt_using_subcommand beta; and not __fish_seen_subcommand_from run-hook commit squash push rebase ask-approvals clear-approvals select" -f -a "rebase" -d 'Rebase onto target'
complete -c wt -n "__fish_wt_using_subcommand beta; and not __fish_seen_subcommand_from run-hook commit squash push rebase ask-approvals clear-approvals select" -f -a "ask-approvals" -d 'Store approvals in config'
complete -c wt -n "__fish_wt_using_subcommand beta; and not __fish_seen_subcommand_from run-hook commit squash push rebase ask-approvals clear-approvals select" -f -a "clear-approvals" -d 'Clear approved commands from config'
@@ -276,12 +276,12 @@ complete -c wt -n "__fish_wt_using_subcommand beta; and __fish_seen_subcommand_f
complete -c wt -n "__fish_wt_using_subcommand beta; and __fish_seen_subcommand_from select" -s C -d 'Change working directory' -r -F
complete -c wt -n "__fish_wt_using_subcommand beta; and __fish_seen_subcommand_from select" -s v -l verbose -d 'Show commands and debug info'
complete -c wt -n "__fish_wt_using_subcommand beta; and __fish_seen_subcommand_from select" -s h -l help -d 'Print help (see more with \'--help\')'
-complete -c wt -n "__fish_wt_using_subcommand list" -l format -d 'Output format' -r -f -a "table\t'Human-readable table format'
+complete -c wt -n "__fish_wt_using_subcommand list" -l format -d 'Output format (table, json)' -r -f -a "table\t'Human-readable table format'
json\t'JSON output'"
complete -c wt -n "__fish_wt_using_subcommand list" -s C -d 'Change working directory' -r -F
complete -c wt -n "__fish_wt_using_subcommand list" -l branches -d 'Include branches without worktrees'
complete -c wt -n "__fish_wt_using_subcommand list" -l full -d 'Show CI, conflicts, diffs'
-complete -c wt -n "__fish_wt_using_subcommand list" -l progressive -d 'Progressive rendering'
+complete -c wt -n "__fish_wt_using_subcommand list" -l progressive -d 'Force progressive (or --no-progressive)'
complete -c wt -n "__fish_wt_using_subcommand list" -l no-progressive -d 'Force buffered rendering'
complete -c wt -n "__fish_wt_using_subcommand list" -s v -l verbose -d 'Show commands and debug info'
complete -c wt -n "__fish_wt_using_subcommand list" -s h -l help -d 'Print help (see more with \'--help\')'
diff --git a/tests/snapshots/integration__integration_tests__init__init_zsh.snap b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
index 7e2d323bb..8ffe0b792 100644
--- a/tests/snapshots/integration__integration_tests__init__init_zsh.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
@@ -19,7 +19,7 @@ info:
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpcO3S47/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmptZYPNz/test-config.toml
---
success: true
exit_code: 0
@@ -427,12 +427,12 @@ esac
;;
(list)
_arguments "${_arguments_options[@]}" : \
-'--format=[Output format]:FORMAT:((table\:"Human-readable table format"
+'--format=[Output format (table, json)]:FORMAT:((table\:"Human-readable table format"
json\:"JSON output"))' \
'-C+[Change working directory]:path:_files' \
'--branches[Include branches without worktrees]' \
'--full[Show CI, conflicts, diffs]' \
-'--progressive[Progressive rendering]' \
+'--progressive[Force progressive (or --no-progressive)]' \
'--no-progressive[Force buffered rendering]' \
'-v[Show commands and debug info]' \
'--verbose[Show commands and debug info]' \
@@ -514,7 +514,7 @@ _wt__beta_commands() {
'run-hook:Run project hook' \
'commit:Commit changes with LLM-generated message' \
'squash:Squash commits with LLM-generated message' \
-'push:Push changes to target branch' \
+'push:Push changes to local target branch' \
'rebase:Rebase onto target' \
'ask-approvals:Store approvals in config' \
'clear-approvals:Clear approved commands from config' \
diff --git a/tests/snapshots/integration__integration_tests__list__json_with_display_fields.snap b/tests/snapshots/integration__integration_tests__list__json_with_display_fields.snap
index cee8350a1..faa6e1270 100644
--- a/tests/snapshots/integration__integration_tests__list__json_with_display_fields.snap
+++ b/tests/snapshots/integration__integration_tests__list__json_with_display_fields.snap
@@ -41,25 +41,25 @@ exit_code: 0
"upstream_behind": 0,
"pr_status": null,
"status": {
- "branch_state": "",
- "git_operation": "",
- "main_divergence": "",
- "upstream_divergence": "",
"working_tree": {
"untracked": false,
"modified": false,
"staged": false,
"renamed": false,
"deleted": false
- }
+ },
+ "branch_state": "",
+ "git_operation": "",
+ "main_divergence": "",
+ "upstream_divergence": ""
},
"status_symbols": {
+ "working_tree": "",
"branch_state": "",
"git_operation": "",
- "worktree_attrs": "",
"main_divergence": "",
"upstream_divergence": "",
- "working_tree": ""
+ "worktree_attrs": ""
},
"type": "worktree",
"path": "[REPO]",
@@ -92,25 +92,25 @@ exit_code: 0
"upstream_behind": 0,
"pr_status": null,
"status": {
- "branch_state": "",
- "git_operation": "",
- "main_divergence": "Diverged",
- "upstream_divergence": "",
"working_tree": {
"untracked": true,
"modified": true,
"staged": false,
"renamed": false,
"deleted": false
- }
+ },
+ "branch_state": "",
+ "git_operation": "",
+ "main_divergence": "Diverged",
+ "upstream_divergence": ""
},
"status_symbols": {
+ "working_tree": "?!",
"branch_state": "",
"git_operation": "",
- "worktree_attrs": "",
"main_divergence": "↕",
"upstream_divergence": "",
- "working_tree": "?!"
+ "worktree_attrs": ""
},
"commits_display": "/u001b[32m↑2/u001b[0m /u001b[2m/u001b[31m↓2/u001b[0m",
"branch_diff_display": "/u001b[32m+1/u001b[0m",
@@ -143,25 +143,25 @@ exit_code: 0
"upstream_behind": 0,
"pr_status": null,
"status": {
- "branch_state": "NoCommits",
- "git_operation": "",
- "main_divergence": "Behind",
- "upstream_divergence": "",
"working_tree": {
"untracked": false,
"modified": false,
"staged": false,
"renamed": false,
"deleted": false
- }
+ },
+ "branch_state": "NoCommits",
+ "git_operation": "",
+ "main_divergence": "Behind",
+ "upstream_divergence": ""
},
"status_symbols": {
+ "working_tree": "",
"branch_state": "∅",
"git_operation": "",
- "worktree_attrs": "",
"main_divergence": "↓",
"upstream_divergence": "",
- "working_tree": ""
+ "worktree_attrs": ""
},
"commits_display": "/u001b[2m/u001b[31m↓2/u001b[0m",
"type": "worktree",
diff --git a/tests/snapshots/integration__integration_tests__list__json_with_metadata.snap b/tests/snapshots/integration__integration_tests__list__json_with_metadata.snap
index b7ff961de..b023be851 100644
--- a/tests/snapshots/integration__integration_tests__list__json_with_metadata.snap
+++ b/tests/snapshots/integration__integration_tests__list__json_with_metadata.snap
@@ -41,25 +41,25 @@ exit_code: 0
"upstream_behind": 0,
"pr_status": null,
"status": {
- "branch_state": "",
- "git_operation": "",
- "main_divergence": "",
- "upstream_divergence": "",
"working_tree": {
"untracked": false,
"modified": false,
"staged": false,
"renamed": false,
"deleted": false
- }
+ },
+ "branch_state": "",
+ "git_operation": "",
+ "main_divergence": "",
+ "upstream_divergence": ""
},
"status_symbols": {
+ "working_tree": "",
"branch_state": "",
"git_operation": "",
- "worktree_attrs": "",
"main_divergence": "",
"upstream_divergence": "",
- "working_tree": ""
+ "worktree_attrs": ""
},
"type": "worktree",
"path": "[REPO]",
@@ -92,25 +92,25 @@ exit_code: 0
"upstream_behind": 0,
"pr_status": null,
"status": {
- "branch_state": "MatchesMain",
- "git_operation": "",
- "main_divergence": "",
- "upstream_divergence": "",
"working_tree": {
"untracked": false,
"modified": false,
"staged": false,
"renamed": false,
"deleted": false
- }
+ },
+ "branch_state": "MatchesMain",
+ "git_operation": "",
+ "main_divergence": "",
+ "upstream_divergence": ""
},
"status_symbols": {
+ "working_tree": "",
"branch_state": "≡",
"git_operation": "",
- "worktree_attrs": "",
"main_divergence": "",
"upstream_divergence": "",
- "working_tree": ""
+ "worktree_attrs": ""
},
"type": "worktree",
"path": "[WORKTREE_FEATURE_DETACHED]",
@@ -143,25 +143,25 @@ exit_code: 0
"upstream_behind": 0,
"pr_status": null,
"status": {
- "branch_state": "MatchesMain",
- "git_operation": "",
- "main_divergence": "",
- "upstream_divergence": "",
"working_tree": {
"untracked": false,
"modified": false,
"staged": false,
"renamed": false,
"deleted": false
- }
+ },
+ "branch_state": "MatchesMain",
+ "git_operation": "",
+ "main_divergence": "",
+ "upstream_divergence": ""
},
"status_symbols": {
+ "working_tree": "",
"branch_state": "≡",
"git_operation": "",
- "worktree_attrs": "⊠",
"main_divergence": "",
"upstream_divergence": "",
- "working_tree": ""
+ "worktree_attrs": "⊠"
},
"type": "worktree",
"path": "[WORKTREE_LOCKED_FEATURE]",
diff --git a/tests/snapshots/integration__integration_tests__list__json_with_user_status.snap b/tests/snapshots/integration__integration_tests__list__json_with_user_status.snap
index 78d7f05cb..6c5b291fd 100644
--- a/tests/snapshots/integration__integration_tests__list__json_with_user_status.snap
+++ b/tests/snapshots/integration__integration_tests__list__json_with_user_status.snap
@@ -41,25 +41,25 @@ exit_code: 0
"upstream_behind": 0,
"pr_status": null,
"status": {
- "branch_state": "",
- "git_operation": "",
- "main_divergence": "",
- "upstream_divergence": "",
"working_tree": {
"untracked": false,
"modified": false,
"staged": false,
"renamed": false,
"deleted": false
- }
+ },
+ "branch_state": "",
+ "git_operation": "",
+ "main_divergence": "",
+ "upstream_divergence": ""
},
"status_symbols": {
+ "working_tree": "",
"branch_state": "",
"git_operation": "",
- "worktree_attrs": "",
"main_divergence": "",
"upstream_divergence": "",
- "working_tree": ""
+ "worktree_attrs": ""
},
"type": "worktree",
"path": "[REPO]",
@@ -92,10 +92,6 @@ exit_code: 0
"upstream_behind": 0,
"pr_status": null,
"status": {
- "branch_state": "MatchesMain",
- "git_operation": "",
- "main_divergence": "",
- "upstream_divergence": "",
"working_tree": {
"untracked": false,
"modified": false,
@@ -103,15 +99,19 @@ exit_code: 0
"renamed": false,
"deleted": false
},
+ "branch_state": "MatchesMain",
+ "git_operation": "",
+ "main_divergence": "",
+ "upstream_divergence": "",
"user_status": "🔧"
},
"status_symbols": {
+ "working_tree": "",
"branch_state": "≡",
"git_operation": "",
- "worktree_attrs": "",
"main_divergence": "",
"upstream_divergence": "",
- "working_tree": "",
+ "worktree_attrs": "",
"user_status": "🔧"
},
"type": "worktree",
@@ -145,25 +145,25 @@ exit_code: 0
"upstream_behind": 0,
"pr_status": null,
"status": {
- "branch_state": "MatchesMain",
- "git_operation": "",
- "main_divergence": "",
- "upstream_divergence": "",
"working_tree": {
"untracked": false,
"modified": false,
"staged": false,
"renamed": false,
"deleted": false
- }
+ },
+ "branch_state": "MatchesMain",
+ "git_operation": "",
+ "main_divergence": "",
+ "upstream_divergence": ""
},
"status_symbols": {
+ "working_tree": "",
"branch_state": "≡",
"git_operation": "",
- "worktree_attrs": "",
"main_divergence": "",
"upstream_divergence": "",
- "working_tree": ""
+ "worktree_attrs": ""
},
"type": "worktree",
"path": "[WORKTREE_WITHOUT_STATUS]",