Skip to content

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

Refactor command docs for clarity and consistency

Maximilian Roos039616938e3a
diff --git a/README.md b/README.md
index 51d7c43f9..16ec17e2c 100644
--- a/README.md
+++ b/README.md
@@ -503,91 +503,73 @@ Global Options:
-v, --verbose
Show commands and debug info
-Navigate between worktrees or create new ones. Switching to an existing worktree is just a directory change. With `--create`, a new branch and worktree are created, and hooks run.
+Two distinct operations:
-```
-
-### Examples
+- **Switch to existing worktree** — Changes directory, nothing else
+- **Create new worktree** (`--create`) — Creates branch and worktree, runs [hooks](/hooks/)
-Switch to an existing worktree:
-
-```bash
-wt switch feature-auth
-```
-
-Create a new worktree for a fresh branch:
-
-```bash
-wt switch --create new-feature
```
-Create from a specific base branch:
+### Examples
```bash
+wt switch feature-auth # Switch to existing worktree
+wt switch - # Previous worktree (like cd -)
+wt switch --create new-feature # Create branch and worktree
wt switch --create hotfix --base production
```
-Switch to the previous worktree (like `cd -`):
-
-```bash
-wt switch -
-```
-
-### Creating Worktrees
-
-The `--create` flag (or `-c`) creates a new branch from the default branch (or `--base`), sets up a worktree at `../{repo}.{branch}`, runs [post-create hooks](/hooks/#post-create) synchronously, then spawns [post-start hooks](/hooks/#post-start) in the background before switching to the new directory.
-
-```bash
-# Create from main (default)
-wt switch --create api-refactor
-
-# Create from a specific branch
-wt switch --create emergency-fix --base release-2.0
-
-# Create and open in editor
-wt switch --create docs --execute "code ."
-
-# Skip all hooks
-wt switch --create temp --no-verify
-```
+For interactive selection, use [`wt select`](/select/).
### Shortcuts
-Special symbols for common targets:
-
-| Shortcut | Meaning |
-|----------|---------|
-| `-` | Previous worktree (like `cd -`) |
+| Symbol | Meaning |
+|--------|---------|
+| `-` | Previous worktree |
| `@` | Current branch's worktree |
-| `^` | Default branch (main/master) |
+| `^` | Default branch worktree |
```bash
-wt switch - # Go back to previous worktree
-wt switch ^ # Switch to main worktree
-wt switch --create bugfix --base=@ # Branch from current HEAD
+wt switch - # Back to previous
+wt switch ^ # Main worktree
+wt switch --create fix --base=@ # Branch from current HEAD
```
-### Hooks
+### Path-First Lookup
-When creating a worktree (`--create`), hooks run in this order:
+Arguments resolve by checking the filesystem before git branches:
-1. **post-create** — Blocking, sequential. Typically: `npm install`, `cargo build`
-2. **post-start** — Background, parallel. Typically: dev servers, file watchers
+1. Compute expected path from argument (using configured path template)
+2. If worktree exists at that path, switch to it
+3. Otherwise, treat argument as branch name
-See [Hooks](/hooks/) for configuration details.
+**Edge case**: If `repo.foo/` exists but tracks branch `bar`:
+- `wt switch foo` → switches to `repo.foo/` (the `bar` worktree)
+- `wt switch bar` → also works (branch lookup finds same worktree)
+
+### Creating Worktrees
-### How Arguments Are Resolved
+With `--create`, worktrunk:
-Arguments resolve using **path-first lookup**:
+1. Creates branch from `--base` (defaults to default branch)
+2. Creates worktree at configured path
+3. Runs [post-create hooks](/hooks/#post-create) (blocking)
+4. Switches to new directory
+5. Spawns [post-start hooks](/hooks/#post-start) (background)
-1. Compute the expected path for the argument (using the configured path template)
-2. If a worktree exists at that path, switch to it (regardless of what branch it's on)
-3. Otherwise, treat the argument as a branch name
+```bash
+wt switch --create api-refactor
+wt switch --create fix --base release-2.0
+wt switch --create docs --execute "code ."
+wt switch --create temp --no-verify # Skip hooks
+```
-**Example**: If `repo.foo/` exists but is on branch `bar`:
+### See Also
-- `wt switch foo` switches to `repo.foo/` (the `bar` branch worktree)
-- `wt switch bar` also works (falls back to branch lookup)
+- [wt select](/select/) — Interactive worktree selection
+- [wt list](/list/) — View all worktrees
+- [wt remove](/remove/) — Delete worktrees when done
+- [wt merge](/merge/) — Integrate changes back to main
<!-- END AUTO-GENERATED -->
@@ -645,13 +627,15 @@ Global Options:
-v, --verbose
Show commands and debug info
-Integrates the current branch into the target branch (default: main) and removes the worktree. All steps — commit, squash, rebase, push, cleanup — run automatically.
+Merge the current branch into the target branch and clean up. Handles the full workflow: commit uncommitted changes, squash commits, rebase, run hooks, push to target, and remove the worktree.
+
+When already on the target branch or in the main worktree, the worktree is preserved automatically.
```
### Examples
-Merge current worktree into main:
+Basic merge to main:
```bash
wt merge
@@ -669,38 +653,37 @@ Preserve commit history (no squash):
wt merge --no-squash
```
-Skip hooks and approval prompts:
+Skip git operations, only run hooks and push:
```bash
-wt merge --no-verify --force
+wt merge --no-commit
```
-### The Pipeline
-
-`wt merge` runs these steps in order:
+### Pipeline
-1. **Commit** — Stages and commits uncommitted changes with an LLM-generated message. The `--stage` flag controls what gets staged: `all` (default), `tracked`, or `none`.
+`wt merge` runs these steps:
-2. **Squash** — Combines multiple commits into one (like GitHub's "Squash and merge") with an LLM-generated message. The `--no-squash` flag preserves individual commits. A backup ref is saved to `refs/wt-backup/<branch>`.
+1. **Commit** — Stages and commits uncommitted changes. Commit messages are LLM-generated. Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`.
-3. **Rebase** — Rebases onto the target branch. Conflicts abort the merge immediately.
+2. **Squash** — Combines all commits into one (like GitHub's "Squash and merge"). Skip with `--no-squash` to preserve individual commits. A backup ref is saved to `refs/wt-backup/<branch>`.
-4. **Pre-merge hooks** — Project-defined commands run after rebase. Failures abort the merge.
+3. **Rebase** — Rebases onto the target branch. Conflicts abort immediately.
-5. **Push** — Fast-forward push to the local target branch. Non-fast-forward pushes are rejected.
+4. **Pre-merge hooks** — Project commands run after rebase, before push. Failures abort. See [Hooks](/hooks/).
-6. **Cleanup** — Removes the worktree and branch. The `--no-remove` flag keeps the worktree.
+5. **Push** — Fast-forward push to the target branch. Non-fast-forward pushes are rejected.
-7. **Post-merge hooks** — Project-defined commands run after cleanup. Failures are logged but don't abort.
+6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree.
-### Hooks
+7. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
-When merging, hooks run in this order:
+Use `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clean working tree and `--no-remove`.
-1. **pre-merge** — After rebase, before push. Failures abort the merge.
-2. **post-merge** — After cleanup. Failures are logged but don't abort.
+### See Also
-The `--no-verify` flag skips all hooks. See [Hooks](/hooks/) for configuration details.
+- [wt step](/step/) — Run individual merge steps (commit, squash, rebase, push)
+- [wt remove](/remove/) — Remove worktrees without merging
+- [wt switch](/switch/) — Navigate to other worktrees
<!-- END AUTO-GENERATED -->
@@ -742,68 +725,63 @@ Global Options:
-v, --verbose
Show commands and debug info
-Cleans up finished work by removing worktrees and their branches. Without arguments, removes the current worktree and returns to the main worktree.
+Removes worktrees and their branches. Without arguments, removes the current worktree and returns to the main worktree.
```
### Examples
-Remove current worktree and branch:
+Remove current worktree:
```bash
wt remove
```
-Remove a specific worktree:
+Remove specific worktrees:
```bash
wt remove feature-branch
+wt remove old-feature another-branch
```
-Keep the branch after removing the worktree:
+Keep the branch:
```bash
wt remove --no-delete-branch feature-branch
```
-Remove multiple worktrees:
-
-```bash
-wt remove old-feature another-branch
-```
-
Force-delete an unmerged branch:
```bash
wt remove -D experimental
```
-### Branch Deletion
+### When Branches Are Deleted
-By default, branches are deleted only when their content is already integrated into the target branch (typically main). This works correctly with squash-merge and rebase workflows where commit ancestry isn't preserved but the file changes are.
+Branches delete automatically when their content is already in the target branch (typically main). This works with squash-merge and rebase workflows where commit history differs but file changes match.
-The `-D` flag overrides this safety check and force-deletes unmerged branches. The `--no-delete-branch` flag prevents branch deletion entirely.
+Use `-D` to force-delete unmerged branches. Use `--no-delete-branch` to keep the branch.
### Background Removal
-Removal runs in the background by default — the command returns immediately so work can continue. Logs are written to `.git/wt-logs/{branch}-remove.log`.
+Removal runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--no-background` to run in the foreground.
-The `--no-background` flag runs removal in the foreground (blocking).
+### Path-First Lookup
-### How Arguments Are Resolved
+Arguments resolve by checking the expected path first, then falling back to branch name:
-Arguments resolve using **path-first lookup**:
+1. Compute expected path from argument (using configured path template)
+2. If a worktree exists there, remove it (regardless of branch name)
+3. Otherwise, treat argument as a branch name
-1. Compute the expected path for the argument (using the configured path template)
-2. If a worktree exists at that path, use it (regardless of what branch it's on)
-3. Otherwise, treat the argument as a branch name
+If `repo.foo/` exists on branch `bar`, both `wt remove foo` and `wt remove bar` remove the same worktree.
-**Example**: If `repo.foo/` exists but is on branch `bar`:
+**Shortcuts**: `@` (current), `-` (previous), `^` (main worktree)
-- `wt remove foo` removes `repo.foo/` and the `bar` branch
-- `wt remove bar` also works (falls back to branch lookup)
+### See Also
-**Shortcuts**: `@` (current worktree), `-` (previous worktree), `^` (main worktree)
+- [wt merge](/merge/) — Remove worktree after merging
+- [wt list](/list/) — View all worktrees
<!-- END AUTO-GENERATED -->
@@ -855,7 +833,7 @@ Global Options:
-v, --verbose
Show commands and debug info
-Show all worktrees with their status at a glance. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
+Show all worktrees with their status. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
```
@@ -887,51 +865,55 @@ wt list --format=json
### Status Symbols
-The Status column shows a compact summary. Symbols appear in this order:
+Symbols appear in the Status column in this order:
-| Symbol | Meaning |
-|--------|---------|
-| `+` | Staged files (ready to commit) |
-| `!` | Modified files (unstaged changes) |
-| `?` | Untracked files |
-| `✖` | Merge conflicts (fix before continuing) |
-| `⊘` | Would conflict if merged to main |
-| `≡` | Matches main (identical contents) |
-| `_` | No commits (empty branch) |
-| `↻` | Rebase in progress |
-| `⋈` | Merge in progress |
-| `↑` | Ahead of main |
-| `↓` | Behind main |
-| `↕` | Diverged from main |
-| `⇡` | Ahead of remote |
-| `⇣` | Behind remote |
-| `⇅` | Diverged from remote |
-| `⎇` | Branch without worktree |
-| `⌫` | Prunable (directory missing) |
-| `⊠` | Locked worktree |
-
-Rows are dimmed when there's no marginal contribution (`≡` matches main or `_` no commits).
+**Working tree state:**
+- `+` — Staged files
+- `!` — Modified files (unstaged)
+- `?` — Untracked files
+- `✖` — Merge conflicts
+- `↻` — Rebase in progress
+- `⋈` — Merge in progress
-### Columns
+**Branch state:**
+- `⊘` — Would conflict if merged to main (`--full` only)
+- `≡` — Matches main (identical contents)
+- `_` — No commits (empty branch)
+
+**Divergence from main:**
+- `↑` — Ahead of main
+- `↓` — Behind main
+- `↕` — Diverged from main
+
+**Remote tracking:**
+- `⇡` — Ahead of remote
+- `⇣` — Behind remote
+- `⇅` — Diverged from remote
-| Column | Description |
-|--------|-------------|
-| **Branch** | Branch name |
-| **Status** | Compact symbols (see above) |
-| **HEAD±** | Uncommitted changes: `+added` `-deleted` lines |
-| **main↕** | Commits ahead↑/behind↓ relative to main |
-| **main…±** | Line diffs in commits ahead of main (`--full` only) |
-| **Path** | Worktree directory |
-| **Remote⇅** | Commits ahead⇡/behind⇣ vs tracking branch |
-| **CI** | Pipeline status (`--full` only) |
-| **Commit** | Short hash (8 chars) |
-| **Age** | Time since last commit |
-| **Message** | Last commit message (truncated) |
+**Other:**
+- `⎇` — Branch without worktree
+- `⌫` — Prunable (directory missing)
+- `⊠` — Locked worktree
-#### CI Status
+Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).
-The CI column (`--full`) shows pipeline status from GitHub/GitLab:
+### Columns
+| Column | Shows |
+|--------|-------|
+| Branch | Branch name |
+| Status | Compact symbols (see above) |
+| HEAD± | Uncommitted changes: +added -deleted lines |
+| main↕ | Commits ahead/behind main |
+| main…± | Line diffs in commits ahead of main (`--full`) |
+| Path | Worktree directory |
+| Remote⇅ | Commits ahead/behind tracking branch |
+| CI | Pipeline status (`--full`) |
+| Commit | Short hash (8 chars) |
+| Age | Time since last commit |
+| Message | Last commit message (truncated) |
+
+The CI column shows GitHub/GitLab pipeline status:
- `●` green — All checks passed
- `●` blue — Checks running
- `●` red — Checks failed
@@ -942,35 +924,37 @@ The CI column (`--full`) shows pipeline status from GitHub/GitLab:
### JSON Output
-The `--format=json` flag outputs structured data for scripting:
+Query structured data with `--format=json`:
```bash
-# Find worktrees with conflicts
+# Worktrees with conflicts
wt list --format=json | jq '.[] | select(.status.branch_state == "Conflicts")'
-# Find worktrees with uncommitted changes
+# Uncommitted changes
wt list --format=json | jq '.[] | select(.status.working_tree.modified)'
-# Get current worktree
+# Current worktree
wt list --format=json | jq '.[] | select(.is_current == true)'
-# Find branches ahead of main
+# Branches ahead of main
wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
```
**Status fields:**
-
-- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans
+- `working_tree`: `{untracked, modified, staged, renamed, deleted}`
- `branch_state`: `""` | `"Conflicts"` | `"MergeTreeConflicts"` | `"MatchesMain"` | `"NoCommits"`
- `git_operation`: `""` | `"Rebase"` | `"Merge"`
- `main_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
- `upstream_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
**Position fields:**
+- `is_main` — Main worktree
+- `is_current` — Current directory
+- `is_previous` — Previous worktree from [wt switch](/switch/)
-- `is_main`: boolean — is the main worktree
-- `is_current`: boolean — is the current directory
-- `is_previous`: boolean — is the previous worktree from `wt switch`
+### See Also
+
+- [wt select](/select/) — Interactive worktree picker with live preview
<!-- END AUTO-GENERATED -->
@@ -1079,7 +1063,7 @@ See [LLM Commits](/llm-commits/) for installation, provider setup, and customiza
<!-- ⚠️ AUTO-GENERATED from `wt step --help-md` — edit source to update -->
```
-wt step — Workflow building blocks
+wt step — Run individual workflow operations
Usage: wt step [OPTIONS] <COMMAND>
Commands:
@@ -1107,68 +1091,54 @@ Global Options:
-v, --verbose
Show commands and debug info
-Individual workflow steps for scripting and automation. Each subcommand performs one step of the `wt merge` pipeline — commit, squash, rebase, push, or run hooks — allowing custom workflows or manual intervention between steps.
+Run individual workflow operations: commits, squashes, rebases, pushes, and [hooks](/hooks/).
```
### Examples
-Commit with an LLM-generated message:
+Commit with LLM-generated message:
```bash
wt step commit
```
-Squash all branch commits into one:
+Run pre-merge hooks in CI:
```bash
-wt step squash
+wt step pre-merge --force
```
-Run pre-merge hooks (tests, lints):
-
-```bash
-wt step pre-merge
-```
-
-Rebase onto main:
-
-```bash
-wt step rebase
-```
-
-### Use Cases
-
-**Custom merge workflow** — Run steps individually when `wt merge` doesn't fit, such as adding manual review between squash and rebase:
+Manual merge workflow with review between steps:
```bash
wt step commit
wt step squash
-# manual review here
+# Review the squashed commit
wt step rebase
-wt step pre-merge
wt step push
```
-**CI integration** — Run hooks explicitly in CI environments:
+### Operations
-```bash
-wt step pre-merge --force # skip approval prompts
-```
+**Git operations:**
+
+- `commit` — Stage and commit with [LLM-generated message](/llm-commits/)
+- `squash` — Squash all branch commits into one with [LLM-generated message](/llm-commits/)
+- `rebase` — Rebase onto target branch
+- `push` — Push to target branch (default: main)
+
+**Hooks** — run project commands defined in [`.config/wt.toml`](/hooks/):
+
+- `post-create` — After worktree creation
+- `post-start` — After switching to a worktree
+- `pre-commit` — Before committing
+- `pre-merge` — Before pushing to target
+- `post-merge` — After merge cleanup
+
+### See Also
-### Subcommands
-
-| Command | Description |
-|---------|-------------|
-| `commit` | Commits uncommitted changes with an [LLM-generated message](/llm-commits/) |
-| `squash` | Squashes all branch commits into one with an [LLM-generated message](/llm-commits/) |
-| `rebase` | Rebases the branch onto the target (default: main) |
-| `push` | Pushes changes to the local target branch |
-| `post-create` | Runs post-create hooks |
-| `post-start` | Runs post-start hooks |
-| `pre-commit` | Runs pre-commit hooks |
-| `pre-merge` | Runs pre-merge hooks |
-| `post-merge` | Runs post-merge hooks |
+- [wt merge](/merge/) — Runs commit → squash → rebase → hooks → push → cleanup automatically
<!-- END AUTO-GENERATED -->
diff --git a/docs/content/list.md b/docs/content/list.md
index 7a974c8af..5a9598e1f 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -6,7 +6,7 @@ weight = 11
group = "Commands"
+++
-Show all worktrees with their status at a glance. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
+Show all worktrees with their status. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
## Examples
@@ -36,51 +36,55 @@ wt list --format=json
## Status Symbols
-The Status column shows a compact summary. Symbols appear in this order:
-
-| Symbol | Meaning |
-|--------|---------|
-| `+` | Staged files (ready to commit) |
-| `!` | Modified files (unstaged changes) |
-| `?` | Untracked files |
-| `✖` | Merge conflicts (fix before continuing) |
-| `⊘` | Would conflict if merged to main |
-| `≡` | Matches main (identical contents) |
-| `_` | No commits (empty branch) |
-| `↻` | Rebase in progress |
-| `⋈` | Merge in progress |
-| `↑` | Ahead of main |
-| `↓` | Behind main |
-| `↕` | Diverged from main |
-| `⇡` | Ahead of remote |
-| `⇣` | Behind remote |
-| `⇅` | Diverged from remote |
-| `⎇` | Branch without worktree |
-| `⌫` | Prunable (directory missing) |
-| `⊠` | Locked worktree |
-
-Rows are dimmed when there's no marginal contribution (`≡` matches main or `_` no commits).
+Symbols appear in the Status column in this order:
-## Columns
+**Working tree state:**
+- `+` — Staged files
+- `!` — Modified files (unstaged)
+- `?` — Untracked files
+- `✖` — Merge conflicts
+- `↻` — Rebase in progress
+- `⋈` — Merge in progress
+
+**Branch state:**
+- `⊘` — Would conflict if merged to main (`--full` only)
+- `≡` — Matches main (identical contents)
+- `_` — No commits (empty branch)
-| Column | Description |
-|--------|-------------|
-| **Branch** | Branch name |
-| **Status** | Compact symbols (see above) |
-| **HEAD±** | Uncommitted changes: `+added` `-deleted` lines |
-| **main↕** | Commits ahead↑/behind↓ relative to main |
-| **main…±** | Line diffs in commits ahead of main (`--full` only) |
-| **Path** | Worktree directory |
-| **Remote⇅** | Commits ahead⇡/behind⇣ vs tracking branch |
-| **CI** | Pipeline status (`--full` only) |
-| **Commit** | Short hash (8 chars) |
-| **Age** | Time since last commit |
-| **Message** | Last commit message (truncated) |
+**Divergence from main:**
+- `↑` — Ahead of main
+- `↓` — Behind main
+- `↕` — Diverged from main
-### CI Status
+**Remote tracking:**
+- `⇡` — Ahead of remote
+- `⇣` — Behind remote
+- `⇅` — Diverged from remote
-The CI column (`--full`) shows pipeline status from GitHub/GitLab:
+**Other:**
+- `⎇` — Branch without worktree
+- `⌫` — Prunable (directory missing)
+- `⊠` — Locked worktree
+Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).
+
+## Columns
+
+| Column | Shows |
+|--------|-------|
+| Branch | Branch name |
+| Status | Compact symbols (see above) |
+| HEAD± | Uncommitted changes: +added -deleted lines |
+| main↕ | Commits ahead/behind main |
+| main…± | Line diffs in commits ahead of main (`--full`) |
+| Path | Worktree directory |
+| Remote⇅ | Commits ahead/behind tracking branch |
+| CI | Pipeline status (`--full`) |
+| Commit | Short hash (8 chars) |
+| Age | Time since last commit |
+| Message | Last commit message (truncated) |
+
+The CI column shows GitHub/GitLab pipeline status:
- `●` green — All checks passed
- `●` blue — Checks running
- `●` red — Checks failed
@@ -91,35 +95,37 @@ The CI column (`--full`) shows pipeline status from GitHub/GitLab:
## JSON Output
-The `--format=json` flag outputs structured data for scripting:
+Query structured data with `--format=json`:
```bash
-# Find worktrees with conflicts
+# Worktrees with conflicts
wt list --format=json | jq '.[] | select(.status.branch_state == "Conflicts")'
-# Find worktrees with uncommitted changes
+# Uncommitted changes
wt list --format=json | jq '.[] | select(.status.working_tree.modified)'
-# Get current worktree
+# Current worktree
wt list --format=json | jq '.[] | select(.is_current == true)'
-# Find branches ahead of main
+# Branches ahead of main
wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
```
**Status fields:**
-
-- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans
+- `working_tree`: `{untracked, modified, staged, renamed, deleted}`
- `branch_state`: `""` | `"Conflicts"` | `"MergeTreeConflicts"` | `"MatchesMain"` | `"NoCommits"`
- `git_operation`: `""` | `"Rebase"` | `"Merge"`
- `main_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
- `upstream_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
**Position fields:**
+- `is_main` — Main worktree
+- `is_current` — Current directory
+- `is_previous` — Previous worktree from [wt switch](/switch/)
+
+## See Also
-- `is_main`: boolean — is the main worktree
-- `is_current`: boolean — is the current directory
-- `is_previous`: boolean — is the previous worktree from `wt switch`
+- [wt select](/select/) — Interactive worktree picker with live preview
---
diff --git a/docs/content/merge.md b/docs/content/merge.md
index 684f3861c..f7dfcb2d4 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -6,11 +6,13 @@ weight = 12
group = "Commands"
+++
-Integrates the current branch into the target branch (default: main) and removes the worktree. All steps — commit, squash, rebase, push, cleanup — run automatically.
+Merge the current branch into the target branch and clean up. Handles the full workflow: commit uncommitted changes, squash commits, rebase, run hooks, push to target, and remove the worktree.
+
+When already on the target branch or in the main worktree, the worktree is preserved automatically.
## Examples
-Merge current worktree into main:
+Basic merge to main:
```bash
wt merge
@@ -28,38 +30,37 @@ Preserve commit history (no squash):
wt merge --no-squash
```
-Skip hooks and approval prompts:
+Skip git operations, only run hooks and push:
```bash
-wt merge --no-verify --force
+wt merge --no-commit
```
-## The Pipeline
-
-`wt merge` runs these steps in order:
+## Pipeline
-1. **Commit** — Stages and commits uncommitted changes with an LLM-generated message. The `--stage` flag controls what gets staged: `all` (default), `tracked`, or `none`.
+`wt merge` runs these steps:
-2. **Squash** — Combines multiple commits into one (like GitHub's "Squash and merge") with an LLM-generated message. The `--no-squash` flag preserves individual commits. A backup ref is saved to `refs/wt-backup/<branch>`.
+1. **Commit** — Stages and commits uncommitted changes. Commit messages are LLM-generated. Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`.
-3. **Rebase** — Rebases onto the target branch. Conflicts abort the merge immediately.
+2. **Squash** — Combines all commits into one (like GitHub's "Squash and merge"). Skip with `--no-squash` to preserve individual commits. A backup ref is saved to `refs/wt-backup/<branch>`.
-4. **Pre-merge hooks** — Project-defined commands run after rebase. Failures abort the merge.
+3. **Rebase** — Rebases onto the target branch. Conflicts abort immediately.
-5. **Push** — Fast-forward push to the local target branch. Non-fast-forward pushes are rejected.
+4. **Pre-merge hooks** — Project commands run after rebase, before push. Failures abort. See [Hooks](/hooks/).
-6. **Cleanup** — Removes the worktree and branch. The `--no-remove` flag keeps the worktree.
+5. **Push** — Fast-forward push to the target branch. Non-fast-forward pushes are rejected.
-7. **Post-merge hooks** — Project-defined commands run after cleanup. Failures are logged but don't abort.
+6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree.
-## Hooks
+7. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
-When merging, hooks run in this order:
+Use `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clean working tree and `--no-remove`.
-1. **pre-merge** — After rebase, before push. Failures abort the merge.
-2. **post-merge** — After cleanup. Failures are logged but don't abort.
+## See Also
-The `--no-verify` flag skips all hooks. See [Hooks](/hooks/) for configuration details.
+- [wt step](/step/) — Run individual merge steps (commit, squash, rebase, push)
+- [wt remove](/remove/) — Remove worktrees without merging
+- [wt switch](/switch/) — Navigate to other worktrees
---
diff --git a/docs/content/remove.md b/docs/content/remove.md
index e5c84529b..a02ed064c 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -6,66 +6,61 @@ weight = 13
group = "Commands"
+++
-Cleans up finished work by removing worktrees and their branches. Without arguments, removes the current worktree and returns to the main worktree.
+Removes worktrees and their branches. Without arguments, removes the current worktree and returns to the main worktree.
## Examples
-Remove current worktree and branch:
+Remove current worktree:
```bash
wt remove
```
-Remove a specific worktree:
+Remove specific worktrees:
```bash
wt remove feature-branch
+wt remove old-feature another-branch
```
-Keep the branch after removing the worktree:
+Keep the branch:
```bash
wt remove --no-delete-branch feature-branch
```
-Remove multiple worktrees:
-
-```bash
-wt remove old-feature another-branch
-```
-
Force-delete an unmerged branch:
```bash
wt remove -D experimental
```
-## Branch Deletion
+## When Branches Are Deleted
-By default, branches are deleted only when their content is already integrated into the target branch (typically main). This works correctly with squash-merge and rebase workflows where commit ancestry isn't preserved but the file changes are.
+Branches delete automatically when their content is already in the target branch (typically main). This works with squash-merge and rebase workflows where commit history differs but file changes match.
-The `-D` flag overrides this safety check and force-deletes unmerged branches. The `--no-delete-branch` flag prevents branch deletion entirely.
+Use `-D` to force-delete unmerged branches. Use `--no-delete-branch` to keep the branch.
## Background Removal
-Removal runs in the background by default — the command returns immediately so work can continue. Logs are written to `.git/wt-logs/{branch}-remove.log`.
+Removal runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--no-background` to run in the foreground.
-The `--no-background` flag runs removal in the foreground (blocking).
+## Path-First Lookup
-## How Arguments Are Resolved
+Arguments resolve by checking the expected path first, then falling back to branch name:
-Arguments resolve using **path-first lookup**:
+1. Compute expected path from argument (using configured path template)
+2. If a worktree exists there, remove it (regardless of branch name)
+3. Otherwise, treat argument as a branch name
-1. Compute the expected path for the argument (using the configured path template)
-2. If a worktree exists at that path, use it (regardless of what branch it's on)
-3. Otherwise, treat the argument as a branch name
+If `repo.foo/` exists on branch `bar`, both `wt remove foo` and `wt remove bar` remove the same worktree.
-**Example**: If `repo.foo/` exists but is on branch `bar`:
+**Shortcuts**: `@` (current), `-` (previous), `^` (main worktree)
-- `wt remove foo` removes `repo.foo/` and the `bar` branch
-- `wt remove bar` also works (falls back to branch lookup)
+## See Also
-**Shortcuts**: `@` (current worktree), `-` (previous worktree), `^` (main worktree)
+- [wt merge](/merge/) — Remove worktree after merging
+- [wt list](/list/) — View all worktrees
---
diff --git a/docs/content/select.md b/docs/content/select.md
index dd62c9b5e..64309cab3 100644
--- a/docs/content/select.md
+++ b/docs/content/select.md
@@ -6,25 +6,23 @@ weight = 14
group = "Commands"
+++
-Interactive worktree picker with live preview. The selector shows worktree state at a glance — diff stats, commit history, and working tree status — without switching directories first.
+Interactive worktree picker with live preview. Navigate worktrees with keyboard shortcuts and press Enter to switch.
## Examples
-Open the interactive selector:
+Open the selector:
```bash
wt select
```
-## The Interface
+## Preview Tabs
-The selector displays a two-panel layout: a worktree list on the left and a preview panel on the right. The preview updates automatically when navigating between worktrees.
+Toggle between views with number keys:
-**Preview tabs** — toggled with number keys:
-
-1. **Diff** — Changes relative to main branch
-2. **Log** — Recent commits on the branch
-3. **Status** — Working tree status (staged, modified, untracked)
+1. **HEAD±** — Uncommitted changes
+2. **history** — Recent commits on the branch
+3. **main…±** — Changes relative to main branch
## Keybindings
@@ -36,6 +34,12 @@ The selector displays a two-panel layout: a worktree list on the left and a prev
| `/` | Filter worktrees |
| `1`/`2`/`3` | Switch preview tab |
| `Alt+p` | Toggle preview panel |
+| `Ctrl-u`/`Ctrl-d` | Scroll preview up/down |
+
+## See Also
+
+- [wt list](/list/) — Static table view with all worktree metadata
+- [wt switch](/switch/) — Direct switching when you know the target branch
---
diff --git a/docs/content/step.md b/docs/content/step.md
index e525e86ed..87b04e66f 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -6,66 +6,52 @@ weight = 16
group = "Commands"
+++
-Individual workflow steps for scripting and automation. Each subcommand performs one step of the `wt merge` pipeline — commit, squash, rebase, push, or run hooks — allowing custom workflows or manual intervention between steps.
+Run individual workflow operations: commits, squashes, rebases, pushes, and [hooks](/hooks/).
## Examples
-Commit with an LLM-generated message:
+Commit with LLM-generated message:
```bash
wt step commit
```
-Squash all branch commits into one:
+Run pre-merge hooks in CI:
```bash
-wt step squash
-```
-
-Run pre-merge hooks (tests, lints):
-
-```bash
-wt step pre-merge
-```
-
-Rebase onto main:
-
-```bash
-wt step rebase
+wt step pre-merge --force
```
-## Use Cases
-
-**Custom merge workflow** — Run steps individually when `wt merge` doesn't fit, such as adding manual review between squash and rebase:
+Manual merge workflow with review between steps:
```bash
wt step commit
wt step squash
-# manual review here
+# Review the squashed commit
wt step rebase
-wt step pre-merge
wt step push
```
-**CI integration** — Run hooks explicitly in CI environments:
+## Operations
-```bash
-wt step pre-merge --force # skip approval prompts
-```
+**Git operations:**
+
+- `commit` — Stage and commit with [LLM-generated message](/llm-commits/)
+- `squash` — Squash all branch commits into one with [LLM-generated message](/llm-commits/)
+- `rebase` — Rebase onto target branch
+- `push` — Push to target branch (default: main)
+
+**Hooks** — run project commands defined in [`.config/wt.toml`](/hooks/):
+
+- `post-create` — After worktree creation
+- `post-start` — After switching to a worktree
+- `pre-commit` — Before committing
+- `pre-merge` — Before pushing to target
+- `post-merge` — After merge cleanup
-## Subcommands
+## See Also
-| Command | Description |
-|---------|-------------|
-| `commit` | Commits uncommitted changes with an [LLM-generated message](/llm-commits/) |
-| `squash` | Squashes all branch commits into one with an [LLM-generated message](/llm-commits/) |
-| `rebase` | Rebases the branch onto the target (default: main) |
-| `push` | Pushes changes to the local target branch |
-| `post-create` | Runs post-create hooks |
-| `post-start` | Runs post-start hooks |
-| `pre-commit` | Runs pre-commit hooks |
-| `pre-merge` | Runs pre-merge hooks |
-| `post-merge` | Runs post-merge hooks |
+- [wt merge](/merge/) — Runs commit → squash → rebase → hooks → push → cleanup automatically
---
@@ -74,7 +60,7 @@ wt step pre-merge --force # skip approval prompts
<!-- ⚠️ AUTO-GENERATED from `wt step --help-page` — edit cli.rs to update -->
```bash
-wt step - Workflow building blocks
+wt step - Run individual workflow operations
Usage: wt step [OPTIONS] <COMMAND>
Commands:
diff --git a/docs/content/switch.md b/docs/content/switch.md
index 74060ee41..5b28f42c4 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -6,89 +6,71 @@ weight = 10
group = "Commands"
+++
-Navigate between worktrees or create new ones. Switching to an existing worktree is just a directory change. With `--create`, a new branch and worktree are created, and hooks run.
+Two distinct operations:
-## Examples
-
-Switch to an existing worktree:
-
-```bash
-wt switch feature-auth
-```
-
-Create a new worktree for a fresh branch:
-
-```bash
-wt switch --create new-feature
-```
+- **Switch to existing worktree** — Changes directory, nothing else
+- **Create new worktree** (`--create`) — Creates branch and worktree, runs [hooks](/hooks/)
-Create from a specific base branch:
+## Examples
```bash
+wt switch feature-auth # Switch to existing worktree
+wt switch - # Previous worktree (like cd -)
+wt switch --create new-feature # Create branch and worktree
wt switch --create hotfix --base production
```
-Switch to the previous worktree (like `cd -`):
-
-```bash
-wt switch -
-```
-
-## Creating Worktrees
-
-The `--create` flag (or `-c`) creates a new branch from the default branch (or `--base`), sets up a worktree at `../{repo}.{branch}`, runs [post-create hooks](/hooks/#post-create) synchronously, then spawns [post-start hooks](/hooks/#post-start) in the background before switching to the new directory.
-
-```bash
-# Create from main (default)
-wt switch --create api-refactor
-
-# Create from a specific branch
-wt switch --create emergency-fix --base release-2.0
-
-# Create and open in editor
-wt switch --create docs --execute "code ."
-
-# Skip all hooks
-wt switch --create temp --no-verify
-```
+For interactive selection, use [`wt select`](/select/).
## Shortcuts
-Special symbols for common targets:
-
-| Shortcut | Meaning |
-|----------|---------|
-| `-` | Previous worktree (like `cd -`) |
+| Symbol | Meaning |
+|--------|---------|
+| `-` | Previous worktree |
| `@` | Current branch's worktree |
-| `^` | Default branch (main/master) |
+| `^` | Default branch worktree |
```bash
-wt switch - # Go back to previous worktree
-wt switch ^ # Switch to main worktree
-wt switch --create bugfix --base=@ # Branch from current HEAD
+wt switch - # Back to previous
+wt switch ^ # Main worktree
+wt switch --create fix --base=@ # Branch from current HEAD
```
-## Hooks
+## Path-First Lookup
+
+Arguments resolve by checking the filesystem before git branches:
-When creating a worktree (`--create`), hooks run in this order:
+1. Compute expected path from argument (using configured path template)
+2. If worktree exists at that path, switch to it
+3. Otherwise, treat argument as branch name
-1. **post-create** — Blocking, sequential. Typically: `npm install`, `cargo build`
-2. **post-start** — Background, parallel. Typically: dev servers, file watchers
+**Edge case**: If `repo.foo/` exists but tracks branch `bar`:
+- `wt switch foo` → switches to `repo.foo/` (the `bar` worktree)
+- `wt switch bar` → also works (branch lookup finds same worktree)
-See [Hooks](/hooks/) for configuration details.
+## Creating Worktrees
-## How Arguments Are Resolved
+With `--create`, worktrunk:
-Arguments resolve using **path-first lookup**:
+1. Creates branch from `--base` (defaults to default branch)
+2. Creates worktree at configured path
+3. Runs [post-create hooks](/hooks/#post-create) (blocking)
+4. Switches to new directory
+5. Spawns [post-start hooks](/hooks/#post-start) (background)
-1. Compute the expected path for the argument (using the configured path template)
-2. If a worktree exists at that path, switch to it (regardless of what branch it's on)
-3. Otherwise, treat the argument as a branch name
+```bash
+wt switch --create api-refactor
+wt switch --create fix --base release-2.0
+wt switch --create docs --execute "code ."
+wt switch --create temp --no-verify # Skip hooks
+```
-**Example**: If `repo.foo/` exists but is on branch `bar`:
+## See Also
-- `wt switch foo` switches to `repo.foo/` (the `bar` branch worktree)
-- `wt switch bar` also works (falls back to branch lookup)
+- [wt select](/select/) — Interactive worktree selection
+- [wt list](/list/) — View all worktrees
+- [wt remove](/remove/) — Delete worktrees when done
+- [wt merge](/merge/) — Integrate changes back to main
---
diff --git a/src/cli.rs b/src/cli.rs
index da2e7520b..6da463bd8 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -530,7 +530,7 @@ wt config var clear marker --all
},
}
-/// Workflow building blocks
+/// Run individual workflow operations
#[derive(Subcommand)]
pub enum StepCommand {
/// Commit changes with LLM commit message
@@ -720,69 +720,55 @@ See [LLM Commits](/llm-commits/) for installation, provider setup, and customiza
action: ConfigCommand,
},
- /// Workflow building blocks
+ /// Run individual workflow operations
#[command(
name = "step",
- after_long_help = r#"Individual workflow steps for scripting and automation. Each subcommand performs one step of the `wt merge` pipeline — commit, squash, rebase, push, or run hooks — allowing custom workflows or manual intervention between steps.
+ after_long_help = r#"Run individual workflow operations: commits, squashes, rebases, pushes, and [hooks](/hooks/).
## Examples
-Commit with an LLM-generated message:
+Commit with LLM-generated message:
```console
wt step commit
```
-Squash all branch commits into one:
+Run pre-merge hooks in CI:
```console
-wt step squash
-```
-
-Run pre-merge hooks (tests, lints):
-
-```console
-wt step pre-merge
-```
-
-Rebase onto main:
-
-```console
-wt step rebase
+wt step pre-merge --force
```
-## Use Cases
-
-**Custom merge workflow** — Run steps individually when `wt merge` doesn't fit, such as adding manual review between squash and rebase:
+Manual merge workflow with review between steps:
```console
wt step commit
wt step squash
-# manual review here
+# Review the squashed commit
wt step rebase
-wt step pre-merge
wt step push
```
-**CI integration** — Run hooks explicitly in CI environments:
+## Operations
-```console
-wt step pre-merge --force # skip approval prompts
-```
+**Git operations:**
+
+- `commit` — Stage and commit with [LLM-generated message](/llm-commits/)
+- `squash` — Squash all branch commits into one with [LLM-generated message](/llm-commits/)
+- `rebase` — Rebase onto target branch
+- `push` — Push to target branch (default: main)
-## Subcommands
-
-| Command | Description |
-|---------|-------------|
-| `commit` | Commits uncommitted changes with an [LLM-generated message](/llm-commits/) |
-| `squash` | Squashes all branch commits into one with an [LLM-generated message](/llm-commits/) |
-| `rebase` | Rebases the branch onto the target (default: main) |
-| `push` | Pushes changes to the local target branch |
-| `post-create` | Runs post-create hooks |
-| `post-start` | Runs post-start hooks |
-| `pre-commit` | Runs pre-commit hooks |
-| `pre-merge` | Runs pre-merge hooks |
-| `post-merge` | Runs post-merge hooks |
+**Hooks** — run project commands defined in [`.config/wt.toml`](/hooks/):
+
+- `post-create` — After worktree creation
+- `post-start` — After switching to a worktree
+- `pre-commit` — Before committing
+- `pre-merge` — Before pushing to target
+- `post-merge` — After merge cleanup
+
+## See Also
+
+- [wt merge](/merge/) — Runs commit → squash → rebase → hooks → push → cleanup automatically
"#
)]
Step {
@@ -795,25 +781,23 @@ wt step pre-merge --force # skip approval prompts
/// Toggle preview tabs with 1/2/3 keys. Toggle preview visibility with alt-p.
#[cfg(unix)]
#[command(
- after_long_help = r#"Interactive worktree picker with live preview. The selector shows worktree state at a glance — diff stats, commit history, and working tree status — without switching directories first.
+ after_long_help = r#"Interactive worktree picker with live preview. Navigate worktrees with keyboard shortcuts and press Enter to switch.
## Examples
-Open the interactive selector:
+Open the selector:
```console
wt select
```
-## The Interface
-
-The selector displays a two-panel layout: a worktree list on the left and a preview panel on the right. The preview updates automatically when navigating between worktrees.
+## Preview Tabs
-**Preview tabs** — toggled with number keys:
+Toggle between views with number keys:
-1. **Diff** — Changes relative to main branch
-2. **Log** — Recent commits on the branch
-3. **Status** — Working tree status (staged, modified, untracked)
+1. **HEAD±** — Uncommitted changes
+2. **history** — Recent commits on the branch
+3. **main…±** — Changes relative to main branch
## Keybindings
@@ -825,13 +809,19 @@ The selector displays a two-panel layout: a worktree list on the left and a prev
| `/` | Filter worktrees |
| `1`/`2`/`3` | Switch preview tab |
| `Alt+p` | Toggle preview panel |
+| `Ctrl-u`/`Ctrl-d` | Scroll preview up/down |
+
+## See Also
+
+- [wt list](/list/) — Static table view with all worktree metadata
+- [wt switch](/switch/) — Direct switching when you know the target branch
"#
)]
Select,
/// List worktrees and optionally branches
#[command(
- after_long_help = r#"Show all worktrees with their status at a glance. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
+ after_long_help = r#"Show all worktrees with their status. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
## Examples
@@ -861,51 +851,55 @@ wt list --format=json
## Status Symbols
-The Status column shows a compact summary. Symbols appear in this order:
+Symbols appear in the Status column in this order:
-| Symbol | Meaning |
-|--------|---------|
-| `+` | Staged files (ready to commit) |
-| `!` | Modified files (unstaged changes) |
-| `?` | Untracked files |
-| `✖` | Merge conflicts (fix before continuing) |
-| `⊘` | Would conflict if merged to main |
-| `≡` | Matches main (identical contents) |
-| `_` | No commits (empty branch) |
-| `↻` | Rebase in progress |
-| `⋈` | Merge in progress |
-| `↑` | Ahead of main |
-| `↓` | Behind main |
-| `↕` | Diverged from main |
-| `⇡` | Ahead of remote |
-| `⇣` | Behind remote |
-| `⇅` | Diverged from remote |
-| `⎇` | Branch without worktree |
-| `⌫` | Prunable (directory missing) |
-| `⊠` | Locked worktree |
-
-Rows are dimmed when there's no marginal contribution (`≡` matches main or `_` no commits).
+**Working tree state:**
+- `+` — Staged files
+- `!` — Modified files (unstaged)
+- `?` — Untracked files
+- `✖` — Merge conflicts
+- `↻` — Rebase in progress
+- `⋈` — Merge in progress
-## Columns
+**Branch state:**
+- `⊘` — Would conflict if merged to main (`--full` only)
+- `≡` — Matches main (identical contents)
+- `_` — No commits (empty branch)
-| Column | Description |
-|--------|-------------|
-| **Branch** | Branch name |
-| **Status** | Compact symbols (see above) |
-| **HEAD±** | Uncommitted changes: `+added` `-deleted` lines |
-| **main↕** | Commits ahead↑/behind↓ relative to main |
-| **main…±** | Line diffs in commits ahead of main (`--full` only) |
-| **Path** | Worktree directory |
-| **Remote⇅** | Commits ahead⇡/behind⇣ vs tracking branch |
-| **CI** | Pipeline status (`--full` only) |
-| **Commit** | Short hash (8 chars) |
-| **Age** | Time since last commit |
-| **Message** | Last commit message (truncated) |
+**Divergence from main:**
+- `↑` — Ahead of main
+- `↓` — Behind main
+- `↕` — Diverged from main
-### CI Status
+**Remote tracking:**
+- `⇡` — Ahead of remote
+- `⇣` — Behind remote
+- `⇅` — Diverged from remote
-The CI column (`--full`) shows pipeline status from GitHub/GitLab:
+**Other:**
+- `⎇` — Branch without worktree
+- `⌫` — Prunable (directory missing)
+- `⊠` — Locked worktree
+Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).
+
+## Columns
+
+| Column | Shows |
+|--------|-------|
+| Branch | Branch name |
+| Status | Compact symbols (see above) |
+| HEAD± | Uncommitted changes: +added -deleted lines |
+| main↕ | Commits ahead/behind main |
+| main…± | Line diffs in commits ahead of main (`--full`) |
+| Path | Worktree directory |
+| Remote⇅ | Commits ahead/behind tracking branch |
+| CI | Pipeline status (`--full`) |
+| Commit | Short hash (8 chars) |
+| Age | Time since last commit |
+| Message | Last commit message (truncated) |
+
+The CI column shows GitHub/GitLab pipeline status:
- `●` green — All checks passed
- `●` blue — Checks running
- `●` red — Checks failed
@@ -916,35 +910,37 @@ The CI column (`--full`) shows pipeline status from GitHub/GitLab:
## JSON Output
-The `--format=json` flag outputs structured data for scripting:
+Query structured data with `--format=json`:
```console
-# Find worktrees with conflicts
+# Worktrees with conflicts
wt list --format=json | jq '.[] | select(.status.branch_state == "Conflicts")'
-# Find worktrees with uncommitted changes
+# Uncommitted changes
wt list --format=json | jq '.[] | select(.status.working_tree.modified)'
-# Get current worktree
+# Current worktree
wt list --format=json | jq '.[] | select(.is_current == true)'
-# Find branches ahead of main
+# Branches ahead of main
wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
```
**Status fields:**
-
-- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans
+- `working_tree`: `{untracked, modified, staged, renamed, deleted}`
- `branch_state`: `""` | `"Conflicts"` | `"MergeTreeConflicts"` | `"MatchesMain"` | `"NoCommits"`
- `git_operation`: `""` | `"Rebase"` | `"Merge"`
- `main_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
- `upstream_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
**Position fields:**
+- `is_main` — Main worktree
+- `is_current` — Current directory
+- `is_previous` — Previous worktree from [wt switch](/switch/)
-- `is_main`: boolean — is the main worktree
-- `is_current`: boolean — is the current directory
-- `is_previous`: boolean — is the previous worktree from `wt switch`
+## See Also
+
+- [wt select](/select/) — Interactive worktree picker with live preview
"#
)]
#[command(args_conflicts_with_subcommands = true)]
@@ -981,92 +977,72 @@ wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
},
/// Switch to a worktree
- #[command(
- after_long_help = r#"Navigate between worktrees or create new ones. Switching to an existing worktree is just a directory change. With `--create`, a new branch and worktree are created, and hooks run.
-
-## Examples
-
-Switch to an existing worktree:
-
-```console
-wt switch feature-auth
-```
-
-Create a new worktree for a fresh branch:
+ #[command(after_long_help = r#"Two distinct operations:
-```console
-wt switch --create new-feature
-```
+- **Switch to existing worktree** — Changes directory, nothing else
+- **Create new worktree** (`--create`) — Creates branch and worktree, runs [hooks](/hooks/)
-Create from a specific base branch:
+## Examples
```console
+wt switch feature-auth # Switch to existing worktree
+wt switch - # Previous worktree (like cd -)
+wt switch --create new-feature # Create branch and worktree
wt switch --create hotfix --base production
```
-Switch to the previous worktree (like `cd -`):
-
-```console
-wt switch -
-```
-
-## Creating Worktrees
-
-The `--create` flag (or `-c`) creates a new branch from the default branch (or `--base`), sets up a worktree at `../{repo}.{branch}`, runs [post-create hooks](/hooks/#post-create) synchronously, then spawns [post-start hooks](/hooks/#post-start) in the background before switching to the new directory.
-
-```console
-# Create from main (default)
-wt switch --create api-refactor
-
-# Create from a specific branch
-wt switch --create emergency-fix --base release-2.0
-
-# Create and open in editor
-wt switch --create docs --execute "code ."
-
-# Skip all hooks
-wt switch --create temp --no-verify
-```
+For interactive selection, use [`wt select`](/select/).
## Shortcuts
-Special symbols for common targets:
-
-| Shortcut | Meaning |
-|----------|---------|
-| `-` | Previous worktree (like `cd -`) |
+| Symbol | Meaning |
+|--------|---------|
+| `-` | Previous worktree |
| `@` | Current branch's worktree |
-| `^` | Default branch (main/master) |
+| `^` | Default branch worktree |
```console
-wt switch - # Go back to previous worktree
-wt switch ^ # Switch to main worktree
-wt switch --create bugfix --base=@ # Branch from current HEAD
+wt switch - # Back to previous
+wt switch ^ # Main worktree
+wt switch --create fix --base=@ # Branch from current HEAD
```
-## Hooks
+## Path-First Lookup
-When creating a worktree (`--create`), hooks run in this order:
+Arguments resolve by checking the filesystem before git branches:
-1. **post-create** — Blocking, sequential. Typically: `npm install`, `cargo build`
-2. **post-start** — Background, parallel. Typically: dev servers, file watchers
+1. Compute expected path from argument (using configured path template)
+2. If worktree exists at that path, switch to it
+3. Otherwise, treat argument as branch name
-See [Hooks](/hooks/) for configuration details.
+**Edge case**: If `repo.foo/` exists but tracks branch `bar`:
+- `wt switch foo` → switches to `repo.foo/` (the `bar` worktree)
+- `wt switch bar` → also works (branch lookup finds same worktree)
-## How Arguments Are Resolved
+## Creating Worktrees
-Arguments resolve using **path-first lookup**:
+With `--create`, worktrunk:
-1. Compute the expected path for the argument (using the configured path template)
-2. If a worktree exists at that path, switch to it (regardless of what branch it's on)
-3. Otherwise, treat the argument as a branch name
+1. Creates branch from `--base` (defaults to default branch)
+2. Creates worktree at configured path
+3. Runs [post-create hooks](/hooks/#post-create) (blocking)
+4. Switches to new directory
+5. Spawns [post-start hooks](/hooks/#post-start) (background)
-**Example**: If `repo.foo/` exists but is on branch `bar`:
+```console
+wt switch --create api-refactor
+wt switch --create fix --base release-2.0
+wt switch --create docs --execute "code ."
+wt switch --create temp --no-verify # Skip hooks
+```
-- `wt switch foo` switches to `repo.foo/` (the `bar` branch worktree)
-- `wt switch bar` also works (falls back to branch lookup)
-"#
- )]
+## See Also
+
+- [wt select](/select/) — Interactive worktree selection
+- [wt list](/list/) — View all worktrees
+- [wt remove](/remove/) — Delete worktrees when done
+- [wt merge](/merge/) — Integrate changes back to main
+"#)]
Switch {
/// Branch or worktree name
///
@@ -1099,66 +1075,61 @@ Arguments resolve using **path-first lookup**:
/// Remove worktree and branch
#[command(
- after_long_help = r#"Cleans up finished work by removing worktrees and their branches. Without arguments, removes the current worktree and returns to the main worktree.
+ after_long_help = r#"Removes worktrees and their branches. Without arguments, removes the current worktree and returns to the main worktree.
## Examples
-Remove current worktree and branch:
+Remove current worktree:
```console
wt remove
```
-Remove a specific worktree:
+Remove specific worktrees:
```console
wt remove feature-branch
+wt remove old-feature another-branch
```
-Keep the branch after removing the worktree:
+Keep the branch:
```console
wt remove --no-delete-branch feature-branch
```
-Remove multiple worktrees:
-
-```console
-wt remove old-feature another-branch
-```
-
Force-delete an unmerged branch:
```console
wt remove -D experimental
```
-## Branch Deletion
+## When Branches Are Deleted
-By default, branches are deleted only when their content is already integrated into the target branch (typically main). This works correctly with squash-merge and rebase workflows where commit ancestry isn't preserved but the file changes are.
+Branches delete automatically when their content is already in the target branch (typically main). This works with squash-merge and rebase workflows where commit history differs but file changes match.
-The `-D` flag overrides this safety check and force-deletes unmerged branches. The `--no-delete-branch` flag prevents branch deletion entirely.
+Use `-D` to force-delete unmerged branches. Use `--no-delete-branch` to keep the branch.
## Background Removal
-Removal runs in the background by default — the command returns immediately so work can continue. Logs are written to `.git/wt-logs/{branch}-remove.log`.
+Removal runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--no-background` to run in the foreground.
-The `--no-background` flag runs removal in the foreground (blocking).
+## Path-First Lookup
-## How Arguments Are Resolved
+Arguments resolve by checking the expected path first, then falling back to branch name:
-Arguments resolve using **path-first lookup**:
+1. Compute expected path from argument (using configured path template)
+2. If a worktree exists there, remove it (regardless of branch name)
+3. Otherwise, treat argument as a branch name
-1. Compute the expected path for the argument (using the configured path template)
-2. If a worktree exists at that path, use it (regardless of what branch it's on)
-3. Otherwise, treat the argument as a branch name
+If `repo.foo/` exists on branch `bar`, both `wt remove foo` and `wt remove bar` remove the same worktree.
-**Example**: If `repo.foo/` exists but is on branch `bar`:
+**Shortcuts**: `@` (current), `-` (previous), `^` (main worktree)
-- `wt remove foo` removes `repo.foo/` and the `bar` branch
-- `wt remove bar` also works (falls back to branch lookup)
+## See Also
-**Shortcuts**: `@` (current worktree), `-` (previous worktree), `^` (main worktree)
+- [wt merge](/merge/) — Remove worktree after merging
+- [wt list](/list/) — View all worktrees
"#
)]
Remove {
@@ -1181,11 +1152,13 @@ Arguments resolve using **path-first lookup**:
/// Merge worktree into target branch
#[command(
- after_long_help = r#"Integrates the current branch into the target branch (default: main) and removes the worktree. All steps — commit, squash, rebase, push, cleanup — run automatically.
+ after_long_help = r#"Merge the current branch into the target branch and clean up. Handles the full workflow: commit uncommitted changes, squash commits, rebase, run hooks, push to target, and remove the worktree.
+
+When already on the target branch or in the main worktree, the worktree is preserved automatically.
## Examples
-Merge current worktree into main:
+Basic merge to main:
```console
wt merge
@@ -1203,38 +1176,37 @@ Preserve commit history (no squash):
wt merge --no-squash
```
-Skip hooks and approval prompts:
+Skip git operations, only run hooks and push:
```console
-wt merge --no-verify --force
+wt merge --no-commit
```
-## The Pipeline
-
-`wt merge` runs these steps in order:
+## Pipeline
-1. **Commit** — Stages and commits uncommitted changes with an LLM-generated message. The `--stage` flag controls what gets staged: `all` (default), `tracked`, or `none`.
+`wt merge` runs these steps:
-2. **Squash** — Combines multiple commits into one (like GitHub's "Squash and merge") with an LLM-generated message. The `--no-squash` flag preserves individual commits. A backup ref is saved to `refs/wt-backup/<branch>`.
+1. **Commit** — Stages and commits uncommitted changes. Commit messages are LLM-generated. Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`.
-3. **Rebase** — Rebases onto the target branch. Conflicts abort the merge immediately.
+2. **Squash** — Combines all commits into one (like GitHub's "Squash and merge"). Skip with `--no-squash` to preserve individual commits. A backup ref is saved to `refs/wt-backup/<branch>`.
-4. **Pre-merge hooks** — Project-defined commands run after rebase. Failures abort the merge.
+3. **Rebase** — Rebases onto the target branch. Conflicts abort immediately.
-5. **Push** — Fast-forward push to the local target branch. Non-fast-forward pushes are rejected.
+4. **Pre-merge hooks** — Project commands run after rebase, before push. Failures abort. See [Hooks](/hooks/).
-6. **Cleanup** — Removes the worktree and branch. The `--no-remove` flag keeps the worktree.
+5. **Push** — Fast-forward push to the target branch. Non-fast-forward pushes are rejected.
-7. **Post-merge hooks** — Project-defined commands run after cleanup. Failures are logged but don't abort.
+6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree.
-## Hooks
+7. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
-When merging, hooks run in this order:
+Use `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clean working tree and `--no-remove`.
-1. **pre-merge** — After rebase, before push. Failures abort the merge.
-2. **post-merge** — After cleanup. Failures are logged but don't abort.
+## See Also
-The `--no-verify` flag skips all hooks. See [Hooks](/hooks/) for configuration details.
+- [wt step](/step/) — Run individual merge steps (commit, squash, rebase, push)
+- [wt remove](/remove/) — Remove worktrees without merging
+- [wt switch](/switch/) — Navigate to other worktrees
"#
)]
Merge {
diff --git a/src/commands/CLAUDE.md b/src/commands/CLAUDE.md
index 98ebc415e..3a9051bc3 100644
--- a/src/commands/CLAUDE.md
+++ b/src/commands/CLAUDE.md
@@ -122,6 +122,19 @@ Each command page should follow this order:
- Redundant content that duplicates other pages
- Technical details at the top (push Operation/Resolution sections down)
- Wrapper sections that just contain one subsection (remove "Operation" if it only contains "How Arguments Are Resolved")
+- Presuming user intent — describe what the command does, not why users run it
+
+### Example: Don't Presume Intent
+
+```markdown
+# Bad — presumes why users run the command
+See which worktrees need attention.
+
+# Good — describes what it does
+Show all worktrees with their status.
+```
+
+Users run `wt list` for many reasons: checking status, finding a branch, remembering what they were working on, scripting. The intro should describe the command's behavior, not assume the user's goal.
### Example: Good Intro
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 2b1fb731a..d21a1ef09 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -57,7 +57,7 @@ Usage: wt list [OPTIONS]
-v, --verbose
Show commands and debug info
-Show all worktrees with their status at a glance. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
+Show all worktrees with their status. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
Examples
@@ -79,51 +79,55 @@ Output as JSON for scripting:
Status Symbols
-The Status column shows a compact summary. Symbols appear in this order:
-
-| Symbol | Meaning |
-|--------|---------|
-| + | Staged files (ready to commit) |
-| ! | Modified files (unstaged changes) |
-| ? | Untracked files |
-| ✖ | Merge conflicts (fix before continuing) |
-| ⊘ | Would conflict if merged to main |
-| ≡ | Matches main (identical contents) |
-| _ | No commits (empty branch) |
-| ↻ | Rebase in progress |
-| ⋈ | Merge in progress |
-| ↑ | Ahead of main |
-| ↓ | Behind main |
-| ↕ | Diverged from main |
-| ⇡ | Ahead of remote |
-| ⇣ | Behind remote |
-| ⇅ | Diverged from remote |
-| ⎇ | Branch without worktree |
-| ⌫ | Prunable (directory missing) |
-| ⊠ | Locked worktree |
-
-Rows are dimmed when there's no marginal contribution (≡ matches main or _ no commits).
+Symbols appear in the Status column in this order:
-Columns
+Working tree state:
+- + — Staged files
+- ! — Modified files (unstaged)
+- ? — Untracked files
+- ✖ — Merge conflicts
+- ↻ — Rebase in progress
+- ⋈ — Merge in progress
+
+Branch state:
+- ⊘ — Would conflict if merged to main (--full only)
+- ≡ — Matches main (identical contents)
+- _ — No commits (empty branch)
-| Column | Description |
-|--------|-------------|
-| Branch | Branch name |
-| Status | Compact symbols (see above) |
-| HEAD± | Uncommitted changes: +added -deleted lines |
-| main↕ | Commits ahead↑/behind↓ relative to main |
-| main…± | Line diffs in commits ahead of main (--full only) |
-| Path | Worktree directory |
-| Remote⇅ | Commits ahead⇡/behind⇣ vs tracking branch |
-| CI | Pipeline status (--full only) |
-| Commit | Short hash (8 chars) |
-| Age | Time since last commit |
-| Message | Last commit message (truncated) |
+Divergence from main:
+- ↑ — Ahead of main
+- ↓ — Behind main
+- ↕ — Diverged from main
-CI Status
+Remote tracking:
+- ⇡ — Ahead of remote
+- ⇣ — Behind remote
+- ⇅ — Diverged from remote
-The CI column (--full) shows pipeline status from GitHub/GitLab:
+Other:
+- ⎇ — Branch without worktree
+- ⌫ — Prunable (directory missing)
+- ⊠ — Locked worktree
+Rows are dimmed when the branch has no marginal contribution (≡ matches main or _ no commits).
+
+Columns
+
+| Column | Shows |
+|--------|-------|
+| Branch | Branch name |
+| Status | Compact symbols (see above) |
+| HEAD± | Uncommitted changes: +added -deleted lines |
+| main↕ | Commits ahead/behind main |
+| main…± | Line diffs in commits ahead of main (--full) |
+| Path | Worktree directory |
+| Remote⇅ | Commits ahead/behind tracking branch |
+| CI | Pipeline status (--full) |
+| Commit | Short hash (8 chars) |
+| Age | Time since last commit |
+| Message | Last commit message (truncated) |
+
+The CI column shows GitHub/GitLab pipeline status:
- ● green — All checks passed
- ● blue — Checks running
- ● red — Checks failed
@@ -134,30 +138,32 @@ The CI column (--full) shows pipeline status from GitHub/GitLab:
JSON Output
-The --format=json flag outputs structured data for scripting:
+Query structured data with --format=json:
- # Find worktrees with conflicts
+ # Worktrees with conflicts
wt list --format=json | jq '.[] | select(.status.branch_state == "Conflicts")'

- # Find worktrees with uncommitted changes
+ # Uncommitted changes
wt list --format=json | jq '.[] | select(.status.working_tree.modified)'

- # Get current worktree
+ # Current worktree
wt list --format=json | jq '.[] | select(.is_current == true)'

- # Find branches ahead of main
+ # Branches ahead of main
wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
Status fields:
-
-- working_tree: {untracked, modified, staged, renamed, deleted} booleans
+- working_tree: {untracked, modified, staged, renamed, deleted}
- branch_state: "" | "Conflicts" | "MergeTreeConflicts" | "MatchesMain" | "NoCommits"
- git_operation: "" | "Rebase" | "Merge"
- main_divergence: "" | "Ahead" | "Behind" | "Diverged"
- upstream_divergence: "" | "Ahead" | "Behind" | "Diverged"
Position fields:
+- is_main — Main worktree
+- is_current — Current directory
+- is_previous — Previous worktree from [wt switch](/switch/)
+
+See Also
-- is_main: boolean — is the main worktree
-- is_current: boolean — is the current directory
-- is_previous: boolean — is the previous worktree from wt switch
+- [wt select](/select/) — Interactive worktree picker with live preview
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
index 722fb48d4..f829c661a 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -63,11 +63,13 @@ Usage: wt merge [OPTIONS] [TARGET]
-v, --verbose
Show commands and debug info
-Integrates the current branch into the target branch (default: main) and removes the worktree. All steps — commit, squash, rebase, push, cleanup — run automatically.
+Merge the current branch into the target branch and clean up. Handles the full workflow: commit uncommitted changes, squash commits, rebase, run hooks, push to target, and remove the worktree.
+
+When already on the target branch or in the main worktree, the worktree is preserved automatically.
Examples
-Merge current worktree into main:
+Basic merge to main:
wt merge
@@ -79,33 +81,32 @@ Preserve commit history (no squash):
wt merge --no-squash
-Skip hooks and approval prompts:
-
- wt merge --no-verify --force
+Skip git operations, only run hooks and push:
-The Pipeline
+ wt merge --no-commit
-wt merge runs these steps in order:
+Pipeline
-1. Commit — Stages and commits uncommitted changes with an LLM-generated message. The --stage flag controls what gets staged: all (default), tracked, or none.
+wt merge runs these steps:
-2. Squash — Combines multiple commits into one (like GitHub's "Squash and merge") with an LLM-generated message. The --no-squash flag preserves individual commits. A backup ref is saved to refs/wt-backup/<branch>.
+1. Commit — Stages and commits uncommitted changes. Commit messages are LLM-generated. Use --stage to control what gets staged: all (default), tracked, or none.
-3. Rebase — Rebases onto the target branch. Conflicts abort the merge immediately.
+2. Squash — Combines all commits into one (like GitHub's "Squash and merge"). Skip with --no-squash to preserve individual commits. A backup ref is saved to refs/wt-backup/<branch>.
-4. Pre-merge hooks — Project-defined commands run after rebase. Failures abort the merge.
+3. Rebase — Rebases onto the target branch. Conflicts abort immediately.
-5. Push — Fast-forward push to the local target branch. Non-fast-forward pushes are rejected.
+4. Pre-merge hooks — Project commands run after rebase, before push. Failures abort. See [Hooks](/hooks/).
-6. Cleanup — Removes the worktree and branch. The --no-remove flag keeps the worktree.
+5. Push — Fast-forward push to the target branch. Non-fast-forward pushes are rejected.
-7. Post-merge hooks — Project-defined commands run after cleanup. Failures are logged but don't abort.
+6. Cleanup — Removes the worktree and branch. Use --no-remove to keep the worktree.
-Hooks
+7. Post-merge hooks — Project commands run after cleanup. Failures are logged but don't abort.
-When merging, hooks run in this order:
+Use --no-commit to skip steps 1-3 and only run hooks and push. Requires a clean working tree and --no-remove.
-1. pre-merge — After rebase, before push. Failures abort the merge.
-2. post-merge — After cleanup. Failures are logged but don't abort.
+See Also
-The --no-verify flag skips all hooks. See [Hooks](/hooks/) for configuration details.
+- [wt step](/step/) — Run individual merge steps (commit, squash, rebase, push)
+- [wt remove](/remove/) — Remove worktrees without merging
+- [wt switch](/switch/) — Navigate to other worktrees
diff --git a/tests/snapshots/integration__integration_tests__help__help_no_args.snap b/tests/snapshots/integration__integration_tests__help__help_no_args.snap
index d288e5202..78c69abff 100644
--- a/tests/snapshots/integration__integration_tests__help__help_no_args.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_no_args.snap
@@ -20,7 +20,7 @@ Usage: wt [OPTIONS] [COMMAND]
Commands:
config Manage configuration and shell integration
- step Workflow building blocks
+ step Run individual workflow operations
select Interactive worktree selector
list List worktrees and optionally branches
switch Switch to a worktree
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
index 49bfe4c29..dcad0b8a9 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -47,53 +47,50 @@ Usage: wt remove [OPTIONS] [WORKTREES]...
-v, --verbose
Show commands and debug info
-Cleans up finished work by removing worktrees and their branches. Without arguments, removes the current worktree and returns to the main worktree.
+Removes worktrees and their branches. Without arguments, removes the current worktree and returns to the main worktree.
Examples
-Remove current worktree and branch:
+Remove current worktree:
wt remove
-Remove a specific worktree:
+Remove specific worktrees:
wt remove feature-branch
+ wt remove old-feature another-branch
-Keep the branch after removing the worktree:
+Keep the branch:
wt remove --no-delete-branch feature-branch
-Remove multiple worktrees:
-
- wt remove old-feature another-branch
-
Force-delete an unmerged branch:
wt remove -D experimental
-Branch Deletion
+When Branches Are Deleted
-By default, branches are deleted only when their content is already integrated into the target branch (typically main). This works correctly with squash-merge and rebase workflows where commit ancestry isn't preserved but the file changes are.
+Branches delete automatically when their content is already in the target branch (typically main). This works with squash-merge and rebase workflows where commit history differs but file changes match.
-The -D flag overrides this safety check and force-deletes unmerged branches. The --no-delete-branch flag prevents branch deletion entirely.
+Use -D to force-delete unmerged branches. Use --no-delete-branch to keep the branch.
Background Removal
-Removal runs in the background by default — the command returns immediately so work can continue. Logs are written to .git/wt-logs/{branch}-remove.log.
+Removal runs in the background by default (returns immediately). Logs are written to .git/wt-logs/{branch}-remove.log. Use --no-background to run in the foreground.
-The --no-background flag runs removal in the foreground (blocking).
+Path-First Lookup
-How Arguments Are Resolved
+Arguments resolve by checking the expected path first, then falling back to branch name:
-Arguments resolve using path-first lookup:
+1. Compute expected path from argument (using configured path template)
+2. If a worktree exists there, remove it (regardless of branch name)
+3. Otherwise, treat argument as a branch name
-1. Compute the expected path for the argument (using the configured path template)
-2. If a worktree exists at that path, use it (regardless of what branch it's on)
-3. Otherwise, treat the argument as a branch name
+If repo.foo/ exists on branch bar, both wt remove foo and wt remove bar remove the same worktree.
-Example: If repo.foo/ exists but is on branch bar:
+Shortcuts: @ (current), - (previous), ^ (main worktree)
-- wt remove foo removes repo.foo/ and the bar branch
-- wt remove bar also works (falls back to branch lookup)
+See Also
-Shortcuts: @ (current worktree), - (previous worktree), ^ (main worktree)
+- [wt merge](/merge/) — Remove worktree after merging
+- [wt list](/list/) — View all worktrees
diff --git a/tests/snapshots/integration__integration_tests__help__help_root_long.snap b/tests/snapshots/integration__integration_tests__help__help_root_long.snap
index 2f47413fa..63a54e71e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_root_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_root_long.snap
@@ -21,7 +21,7 @@ Usage: wt [OPTIONS] [COMMAND]
Commands:
config Manage configuration and shell integration
- step Workflow building blocks
+ step Run individual workflow operations
select Interactive worktree selector
list List worktrees and optionally branches
switch Switch to a worktree
diff --git a/tests/snapshots/integration__integration_tests__help__help_root_short.snap b/tests/snapshots/integration__integration_tests__help__help_root_short.snap
index a76d43eab..6ccd3d7d1 100644
--- a/tests/snapshots/integration__integration_tests__help__help_root_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_root_short.snap
@@ -21,7 +21,7 @@ Usage: wt [OPTIONS] [COMMAND]
Commands:
config Manage configuration and shell integration
- step Workflow building blocks
+ step Run individual workflow operations
select Interactive worktree selector
list List worktrees and optionally branches
switch Switch to a worktree
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
index 03266b8d9..e55525fdd 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -17,7 +17,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt step - Workflow building blocks
+wt step - Run individual workflow operations
Usage: wt step [OPTIONS] <COMMAND>
Commands:
@@ -45,51 +45,43 @@ Usage: wt step [OPTIONS] <COMMAND>
-v, --verbose
Show commands and debug info
-Individual workflow steps for scripting and automation. Each subcommand performs one step of the wt merge pipeline — commit, squash, rebase, push, or run hooks — allowing custom workflows or manual intervention between steps.
+Run individual workflow operations: commits, squashes, rebases, pushes, and [hooks](/hooks/).
Examples
-Commit with an LLM-generated message:
+Commit with LLM-generated message:
wt step commit
-Squash all branch commits into one:
+Run pre-merge hooks in CI:
- wt step squash
-
-Run pre-merge hooks (tests, lints):
-
- wt step pre-merge
-
-Rebase onto main:
-
- wt step rebase
-
-Use Cases
+ wt step pre-merge --force
-Custom merge workflow — Run steps individually when wt merge doesn't fit, such as adding manual review between squash and rebase:
+Manual merge workflow with review between steps:
wt step commit
wt step squash
- # manual review here
+ # Review the squashed commit
wt step rebase
- wt step pre-merge
wt step push
-CI integration — Run hooks explicitly in CI environments:
+Operations
+
+Git operations:
+
+- commit — Stage and commit with [LLM-generated message](/llm-commits/)
+- squash — Squash all branch commits into one with [LLM-generated message](/llm-commits/)
+- rebase — Rebase onto target branch
+- push — Push to target branch (default: main)
+
+Hooks — run project commands defined in [.config/wt.toml](/hooks/):
- wt step pre-merge --force # skip approval prompts
+- post-create — After worktree creation
+- post-start — After switching to a worktree
+- pre-commit — Before committing
+- pre-merge — Before pushing to target
+- post-merge — After merge cleanup
-Subcommands
+See Also
-| Command | Description |
-|---------|-------------|
-| commit | Commits uncommitted changes with an [LLM-generated message](/llm-commits/) |
-| squash | Squashes all branch commits into one with an [LLM-generated message](/llm-commits/) |
-| rebase | Rebases the branch onto the target (default: main) |
-| push | Pushes changes to the local target branch |
-| post-create | Runs post-create hooks |
-| post-start | Runs post-start hooks |
-| pre-commit | Runs pre-commit hooks |
-| pre-merge | Runs pre-merge hooks |
-| post-merge | Runs post-merge hooks |
+- [wt merge](/merge/) — Runs commit → squash → rebase → hooks → push → cleanup automatically
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_short.snap b/tests/snapshots/integration__integration_tests__help__help_step_short.snap
index f93399a0d..4ea6acf37 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_short.snap
@@ -17,7 +17,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt step - Workflow building blocks
+wt step - Run individual workflow operations
Usage: wt step [OPTIONS] <COMMAND>
Commands:
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index e9cc5d02e..b2bdb692e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -57,74 +57,62 @@ Usage: wt switch [OPTIONS] <BRANCH>
-v, --verbose
Show commands and debug info
-Navigate between worktrees or create new ones. Switching to an existing worktree is just a directory change. With --create, a new branch and worktree are created, and hooks run.
+Two distinct operations:
-Examples
-
-Switch to an existing worktree:
-
- wt switch feature-auth
-
-Create a new worktree for a fresh branch:
-
- wt switch --create new-feature
+- Switch to existing worktree — Changes directory, nothing else
+- Create new worktree (--create) — Creates branch and worktree, runs [hooks](/hooks/)
-Create from a specific base branch:
+Examples
+ wt switch feature-auth # Switch to existing worktree
+ wt switch - # Previous worktree (like cd -)
+ wt switch --create new-feature # Create branch and worktree
wt switch --create hotfix --base production
-Switch to the previous worktree (like cd -):
-
- wt switch -
-
-Creating Worktrees
-
-The --create flag (or -c) creates a new branch from the default branch (or --base), sets up a worktree at ../{repo}.{branch}, runs [post-create hooks](/hooks/#post-create) synchronously, then spawns [post-start hooks](/hooks/#post-start) in the background before switching to the new directory.
-
- # Create from main (default)
- wt switch --create api-refactor
- 
- # Create from a specific branch
- wt switch --create emergency-fix --base release-2.0
- 
- # Create and open in editor
- wt switch --create docs --execute "code ."
- 
- # Skip all hooks
- wt switch --create temp --no-verify
+For interactive selection, use [wt select](/select/).
Shortcuts
-Special symbols for common targets:
-
-| Shortcut | Meaning |
-|----------|---------|
-| - | Previous worktree (like cd -) |
+| Symbol | Meaning |
+|--------|---------|
+| - | Previous worktree |
| @ | Current branch's worktree |
-| ^ | Default branch (main/master) |
+| ^ | Default branch worktree |
- wt switch - # Go back to previous worktree
- wt switch ^ # Switch to main worktree
- wt switch --create bugfix --base=@ # Branch from current HEAD
+ wt switch - # Back to previous
+ wt switch ^ # Main worktree
+ wt switch --create fix --base=@ # Branch from current HEAD
-Hooks
+Path-First Lookup
-When creating a worktree (--create), hooks run in this order:
+Arguments resolve by checking the filesystem before git branches:
-1. post-create — Blocking, sequential. Typically: npm install, cargo build
-2. post-start — Background, parallel. Typically: dev servers, file watchers
+1. Compute expected path from argument (using configured path template)
+2. If worktree exists at that path, switch to it
+3. Otherwise, treat argument as branch name
-See [Hooks](/hooks/) for configuration details.
+Edge case: If repo.foo/ exists but tracks branch bar:
+- wt switch foo → switches to repo.foo/ (the bar worktree)
+- wt switch bar → also works (branch lookup finds same worktree)
-How Arguments Are Resolved
+Creating Worktrees
+
+With --create, worktrunk:
-Arguments resolve using path-first lookup:
+1. Creates branch from --base (defaults to default branch)
+2. Creates worktree at configured path
+3. Runs [post-create hooks](/hooks/#post-create) (blocking)
+4. Switches to new directory
+5. Spawns [post-start hooks](/hooks/#post-start) (background)
-1. Compute the expected path for the argument (using the configured path template)
-2. If a worktree exists at that path, switch to it (regardless of what branch it's on)
-3. Otherwise, treat the argument as a branch name
+ wt switch --create api-refactor
+ wt switch --create fix --base release-2.0
+ wt switch --create docs --execute "code ."
+ wt switch --create temp --no-verify # Skip hooks
-Example: If repo.foo/ exists but is on branch bar:
+See Also
-- wt switch foo switches to repo.foo/ (the bar branch worktree)
-- wt switch bar also works (falls back to branch lookup)
+- [wt select](/select/) — Interactive worktree selection
+- [wt list](/list/) — View all worktrees
+- [wt remove](/remove/) — Delete worktrees when done
+- [wt merge](/merge/) — Integrate changes back to main