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.mdindex 51d7c43f9..16ec17e2c 100644--- a/README.md+++ b/README.md@@ -503,91 +503,73 @@ Global Options:-v, --verboseShow 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 worktreewt 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, --verboseShow 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:```bashwt 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, --verboseShow 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:```bashwt remove```-Remove a specific worktree:+Remove specific worktrees:```bashwt remove feature-branch+wt remove old-feature another-branch```-Keep the branch after removing the worktree:+Keep the branch:```bashwt remove --no-delete-branch feature-branch```-Remove multiple worktrees:--```bash-wt remove old-feature another-branch-```-Force-delete an unmerged branch:```bashwt 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, --verboseShow 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 conflictswt list --format=json | jq '.[] | select(.status.branch_state == "Conflicts")'-# Find worktrees with uncommitted changes+# Uncommitted changeswt list --format=json | jq '.[] | select(.status.working_tree.modified)'-# Get current worktree+# Current worktreewt list --format=json | jq '.[] | select(.is_current == true)'-# Find branches ahead of main+# Branches ahead of mainwt 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 operationsUsage: wt step [OPTIONS] <COMMAND>Commands:@@ -1107,68 +1091,54 @@ Global Options:-v, --verboseShow 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:```bashwt 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:```bashwt step commitwt step squash-# manual review here+# Review the squashed commitwt step rebase-wt step pre-mergewt 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.mdindex 7a974c8af..5a9598e1f 100644--- a/docs/content/list.md+++ b/docs/content/list.md@@ -6,7 +6,7 @@ weight = 11group = "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 conflictswt list --format=json | jq '.[] | select(.status.branch_state == "Conflicts")'-# Find worktrees with uncommitted changes+# Uncommitted changeswt list --format=json | jq '.[] | select(.status.working_tree.modified)'-# Get current worktree+# Current worktreewt list --format=json | jq '.[] | select(.is_current == true)'-# Find branches ahead of main+# Branches ahead of mainwt 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.mdindex 684f3861c..f7dfcb2d4 100644--- a/docs/content/merge.md+++ b/docs/content/merge.md@@ -6,11 +6,13 @@ weight = 12group = "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:```bashwt 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.mdindex e5c84529b..a02ed064c 100644--- a/docs/content/remove.md+++ b/docs/content/remove.md@@ -6,66 +6,61 @@ weight = 13group = "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:```bashwt remove```-Remove a specific worktree:+Remove specific worktrees:```bashwt remove feature-branch+wt remove old-feature another-branch```-Keep the branch after removing the worktree:+Keep the branch:```bashwt remove --no-delete-branch feature-branch```-Remove multiple worktrees:--```bash-wt remove old-feature another-branch-```-Force-delete an unmerged branch:```bashwt 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.mdindex dd62c9b5e..64309cab3 100644--- a/docs/content/select.md+++ b/docs/content/select.md@@ -6,25 +6,23 @@ weight = 14group = "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:```bashwt 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.mdindex e525e86ed..87b04e66f 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -6,66 +6,52 @@ weight = 16group = "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:```bashwt 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:```bashwt step commitwt step squash-# manual review here+# Review the squashed commitwt step rebase-wt step pre-mergewt 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 operationsUsage: wt step [OPTIONS] <COMMAND>Commands:diff --git a/docs/content/switch.md b/docs/content/switch.mdindex 74060ee41..5b28f42c4 100644--- a/docs/content/switch.md+++ b/docs/content/switch.md@@ -6,89 +6,71 @@ weight = 10group = "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 worktreewt 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.rsindex 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 customizaaction: 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:```consolewt 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:```consolewt step commitwt step squash-# manual review here+# Review the squashed commitwt step rebase-wt step pre-mergewt 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:```consolewt 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 conflictswt list --format=json | jq '.[] | select(.status.branch_state == "Conflicts")'-# Find worktrees with uncommitted changes+# Uncommitted changeswt list --format=json | jq '.[] | select(.status.working_tree.modified)'-# Get current worktree+# Current worktreewt list --format=json | jq '.[] | select(.is_current == true)'-# Find branches ahead of main+# Branches ahead of mainwt 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 worktreewt 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:```consolewt remove```-Remove a specific worktree:+Remove specific worktrees:```consolewt remove feature-branch+wt remove old-feature another-branch```-Keep the branch after removing the worktree:+Keep the branch:```consolewt remove --no-delete-branch feature-branch```-Remove multiple worktrees:--```console-wt remove old-feature another-branch-```-Force-delete an unmerged branch:```consolewt 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:```consolewt 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.mdindex 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 Introdiff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snapindex 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: [1m[36mwt list[0m [36m[OPTIONS][0m[1m[36m-v[0m, [1m[36m--verbose[0mShow 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.[32mExamples[0m@@ -79,51 +79,55 @@ Output as JSON for scripting:[32mStatus Symbols[0m-The Status column shows a compact summary. Symbols appear in this order:--| Symbol | Meaning |-|--------|---------|-| [2m+[0m | Staged files (ready to commit) |-| [2m![0m | Modified files (unstaged changes) |-| [2m?[0m | Untracked files |-| [2m✖[0m | Merge conflicts (fix before continuing) |-| [2m⊘[0m | Would conflict if merged to main |-| [2m≡[0m | Matches main (identical contents) |-| [2m_[0m | No commits (empty branch) |-| [2m↻[0m | Rebase in progress |-| [2m⋈[0m | Merge in progress |-| [2m↑[0m | Ahead of main |-| [2m↓[0m | Behind main |-| [2m↕[0m | Diverged from main |-| [2m⇡[0m | Ahead of remote |-| [2m⇣[0m | Behind remote |-| [2m⇅[0m | Diverged from remote |-| [2m⎇[0m | Branch without worktree |-| [2m⌫[0m | Prunable (directory missing) |-| [2m⊠[0m | Locked worktree |--Rows are dimmed when there's no marginal contribution ([2m≡[0m matches main or [2m_[0m no commits).+Symbols appear in the Status column in this order:-[32mColumns[0m+[1mWorking tree state:[0m+- [2m+[0m — Staged files+- [2m![0m — Modified files (unstaged)+- [2m?[0m — Untracked files+- [2m✖[0m — Merge conflicts+- [2m↻[0m — Rebase in progress+- [2m⋈[0m — Merge in progress++[1mBranch state:[0m+- [2m⊘[0m — Would conflict if merged to main ([2m--full[0m only)+- [2m≡[0m — Matches main (identical contents)+- [2m_[0m — No commits (empty branch)-| Column | Description |-|--------|-------------|-| [1mBranch[0m | Branch name |-| [1mStatus[0m | Compact symbols (see above) |-| [1mHEAD±[0m | Uncommitted changes: [2m+added[0m [2m-deleted[0m lines |-| [1mmain↕[0m | Commits ahead↑/behind↓ relative to main |-| [1mmain…±[0m | Line diffs in commits ahead of main ([2m--full[0m only) |-| [1mPath[0m | Worktree directory |-| [1mRemote⇅[0m | Commits ahead⇡/behind⇣ vs tracking branch |-| [1mCI[0m | Pipeline status ([2m--full[0m only) |-| [1mCommit[0m | Short hash (8 chars) |-| [1mAge[0m | Time since last commit |-| [1mMessage[0m | Last commit message (truncated) |+[1mDivergence from main:[0m+- [2m↑[0m — Ahead of main+- [2m↓[0m — Behind main+- [2m↕[0m — Diverged from main-[1mCI Status[0m+[1mRemote tracking:[0m+- [2m⇡[0m — Ahead of remote+- [2m⇣[0m — Behind remote+- [2m⇅[0m — Diverged from remote-The CI column ([2m--full[0m) shows pipeline status from GitHub/GitLab:+[1mOther:[0m+- [2m⎇[0m — Branch without worktree+- [2m⌫[0m — Prunable (directory missing)+- [2m⊠[0m — Locked worktree+Rows are dimmed when the branch has no marginal contribution ([2m≡[0m matches main or [2m_[0m no commits).++[32mColumns[0m++| Column | Shows |+|--------|-------|+| Branch | Branch name |+| Status | Compact symbols (see above) |+| HEAD± | Uncommitted changes: +added -deleted lines |+| main↕ | Commits ahead/behind main |+| main…± | Line diffs in commits ahead of main ([2m--full[0m) |+| Path | Worktree directory |+| Remote⇅ | Commits ahead/behind tracking branch |+| CI | Pipeline status ([2m--full[0m) |+| Commit | Short hash (8 chars) |+| Age | Time since last commit |+| Message | Last commit message (truncated) |++The CI column shows GitHub/GitLab pipeline status:- [2m●[0m green — All checks passed- [2m●[0m blue — Checks running- [2m●[0m red — Checks failed@@ -134,30 +138,32 @@ The CI column ([2m--full[0m) shows pipeline status from GitHub/GitLab:[32mJSON Output[0m-The [2m--format=json[0m flag outputs structured data for scripting:+Query structured data with [2m--format=json[0m:- [2m# Find worktrees with conflicts[0m+ [2m# Worktrees with conflicts[0m[2mwt list --format=json | jq '.[] | select(.status.branch_state == "Conflicts")'[0m[2m[0m- [2m# Find worktrees with uncommitted changes[0m+ [2m# Uncommitted changes[0m[2mwt list --format=json | jq '.[] | select(.status.working_tree.modified)'[0m[2m[0m- [2m# Get current worktree[0m+ [2m# Current worktree[0m[2mwt list --format=json | jq '.[] | select(.is_current == true)'[0m[2m[0m- [2m# Find branches ahead of main[0m+ [2m# Branches ahead of main[0m[2mwt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'[0m[1mStatus fields:[0m--- [2mworking_tree[0m: [2m{untracked, modified, staged, renamed, deleted}[0m booleans+- [2mworking_tree[0m: [2m{untracked, modified, staged, renamed, deleted}[0m- [2mbranch_state[0m: [2m""[0m | [2m"Conflicts"[0m | [2m"MergeTreeConflicts"[0m | [2m"MatchesMain"[0m | [2m"NoCommits"[0m- [2mgit_operation[0m: [2m""[0m | [2m"Rebase"[0m | [2m"Merge"[0m- [2mmain_divergence[0m: [2m""[0m | [2m"Ahead"[0m | [2m"Behind"[0m | [2m"Diverged"[0m- [2mupstream_divergence[0m: [2m""[0m | [2m"Ahead"[0m | [2m"Behind"[0m | [2m"Diverged"[0m[1mPosition fields:[0m+- [2mis_main[0m — Main worktree+- [2mis_current[0m — Current directory+- [2mis_previous[0m — Previous worktree from [wt switch](/switch/)++[32mSee Also[0m-- [2mis_main[0m: boolean — is the main worktree-- [2mis_current[0m: boolean — is the current directory-- [2mis_previous[0m: boolean — is the previous worktree from [2mwt switch[0m+- [wt select](/select/) — Interactive worktree picker with live previewdiff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snapindex 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: [1m[36mwt merge[0m [36m[OPTIONS][0m [36m[TARGET][0m[1m[36m-v[0m, [1m[36m--verbose[0mShow 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.[32mExamples[0m-Merge current worktree into main:+Basic merge to main:[2mwt merge[0m@@ -79,33 +81,32 @@ Preserve commit history (no squash):[2mwt merge --no-squash[0m-Skip hooks and approval prompts:-- [2mwt merge --no-verify --force[0m+Skip git operations, only run hooks and push:-[32mThe Pipeline[0m+ [2mwt merge --no-commit[0m-[2mwt merge[0m runs these steps in order:+[32mPipeline[0m-1. [1mCommit[0m — Stages and commits uncommitted changes with an LLM-generated message. The [2m--stage[0m flag controls what gets staged: [2mall[0m (default), [2mtracked[0m, or [2mnone[0m.+[2mwt merge[0m runs these steps:-2. [1mSquash[0m — Combines multiple commits into one (like GitHub's "Squash and merge") with an LLM-generated message. The [2m--no-squash[0m flag preserves individual commits. A backup ref is saved to [2mrefs/wt-backup/<branch>[0m.+1. [1mCommit[0m — Stages and commits uncommitted changes. Commit messages are LLM-generated. Use [2m--stage[0m to control what gets staged: [2mall[0m (default), [2mtracked[0m, or [2mnone[0m.-3. [1mRebase[0m — Rebases onto the target branch. Conflicts abort the merge immediately.+2. [1mSquash[0m — Combines all commits into one (like GitHub's "Squash and merge"). Skip with [2m--no-squash[0m to preserve individual commits. A backup ref is saved to [2mrefs/wt-backup/<branch>[0m.-4. [1mPre-merge hooks[0m — Project-defined commands run after rebase. Failures abort the merge.+3. [1mRebase[0m — Rebases onto the target branch. Conflicts abort immediately.-5. [1mPush[0m — Fast-forward push to the local target branch. Non-fast-forward pushes are rejected.+4. [1mPre-merge hooks[0m — Project commands run after rebase, before push. Failures abort. See [Hooks](/hooks/).-6. [1mCleanup[0m — Removes the worktree and branch. The [2m--no-remove[0m flag keeps the worktree.+5. [1mPush[0m — Fast-forward push to the target branch. Non-fast-forward pushes are rejected.-7. [1mPost-merge hooks[0m — Project-defined commands run after cleanup. Failures are logged but don't abort.+6. [1mCleanup[0m — Removes the worktree and branch. Use [2m--no-remove[0m to keep the worktree.-[32mHooks[0m+7. [1mPost-merge hooks[0m — Project commands run after cleanup. Failures are logged but don't abort.-When merging, hooks run in this order:+Use [2m--no-commit[0m to skip steps 1-3 and only run hooks and push. Requires a clean working tree and [2m--no-remove[0m.-1. [1mpre-merge[0m — After rebase, before push. Failures abort the merge.-2. [1mpost-merge[0m — After cleanup. Failures are logged but don't abort.+[32mSee Also[0m-The [2m--no-verify[0m 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 worktreesdiff --git a/tests/snapshots/integration__integration_tests__help__help_no_args.snap b/tests/snapshots/integration__integration_tests__help__help_no_args.snapindex 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: [1m[36mwt[0m [36m[OPTIONS][0m [36m[COMMAND][0m[1m[32mCommands:[0m[1m[36mconfig[0m Manage configuration and shell integration- [1m[36mstep[0m Workflow building blocks+ [1m[36mstep[0m Run individual workflow operations[1m[36mselect[0m Interactive worktree selector[1m[36mlist[0m List worktrees and optionally branches[1m[36mswitch[0m Switch to a worktreediff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snapindex 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: [1m[36mwt remove[0m [36m[OPTIONS][0m [36m[WORKTREES]...[0m[1m[36m-v[0m, [1m[36m--verbose[0mShow 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.[32mExamples[0m-Remove current worktree and branch:+Remove current worktree:[2mwt remove[0m-Remove a specific worktree:+Remove specific worktrees:[2mwt remove feature-branch[0m+ [2mwt remove old-feature another-branch[0m-Keep the branch after removing the worktree:+Keep the branch:[2mwt remove --no-delete-branch feature-branch[0m-Remove multiple worktrees:-- [2mwt remove old-feature another-branch[0m-Force-delete an unmerged branch:[2mwt remove -D experimental[0m-[32mBranch Deletion[0m+[32mWhen Branches Are Deleted[0m-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 [2m-D[0m flag overrides this safety check and force-deletes unmerged branches. The [2m--no-delete-branch[0m flag prevents branch deletion entirely.+Use [2m-D[0m to force-delete unmerged branches. Use [2m--no-delete-branch[0m to keep the branch.[32mBackground Removal[0m-Removal runs in the background by default — the command returns immediately so work can continue. Logs are written to [2m.git/wt-logs/{branch}-remove.log[0m.+Removal runs in the background by default (returns immediately). Logs are written to [2m.git/wt-logs/{branch}-remove.log[0m. Use [2m--no-background[0m to run in the foreground.-The [2m--no-background[0m flag runs removal in the foreground (blocking).+[32mPath-First Lookup[0m-[32mHow Arguments Are Resolved[0m+Arguments resolve by checking the expected path first, then falling back to branch name:-Arguments resolve using [1mpath-first lookup[0m:+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 [2mrepo.foo/[0m exists on branch [2mbar[0m, both [2mwt remove foo[0m and [2mwt remove bar[0m remove the same worktree.-[1mExample[0m: If [2mrepo.foo/[0m exists but is on branch [2mbar[0m:+[1mShortcuts[0m: [2m@[0m (current), [2m-[0m (previous), [2m^[0m (main worktree)-- [2mwt remove foo[0m removes [2mrepo.foo/[0m and the [2mbar[0m branch-- [2mwt remove bar[0m also works (falls back to branch lookup)+[32mSee Also[0m-[1mShortcuts[0m: [2m@[0m (current worktree), [2m-[0m (previous worktree), [2m^[0m (main worktree)+- [wt merge](/merge/) — Remove worktree after merging+- [wt list](/list/) — View all worktreesdiff --git a/tests/snapshots/integration__integration_tests__help__help_root_long.snap b/tests/snapshots/integration__integration_tests__help__help_root_long.snapindex 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: [1m[36mwt[0m [36m[OPTIONS][0m [36m[COMMAND][0m[1m[32mCommands:[0m[1m[36mconfig[0m Manage configuration and shell integration- [1m[36mstep[0m Workflow building blocks+ [1m[36mstep[0m Run individual workflow operations[1m[36mselect[0m Interactive worktree selector[1m[36mlist[0m List worktrees and optionally branches[1m[36mswitch[0m Switch to a worktreediff --git a/tests/snapshots/integration__integration_tests__help__help_root_short.snap b/tests/snapshots/integration__integration_tests__help__help_root_short.snapindex 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: [1m[36mwt[0m [36m[OPTIONS][0m [36m[COMMAND][0m[1m[32mCommands:[0m[1m[36mconfig[0m Manage configuration and shell integration- [1m[36mstep[0m Workflow building blocks+ [1m[36mstep[0m Run individual workflow operations[1m[36mselect[0m Interactive worktree selector[1m[36mlist[0m List worktrees and optionally branches[1m[36mswitch[0m Switch to a worktreediff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snapindex 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 operationsUsage: [1m[36mwt step[0m [36m[OPTIONS][0m [36m<COMMAND>[0m[1m[32mCommands:[0m@@ -45,51 +45,43 @@ Usage: [1m[36mwt step[0m [36m[OPTIONS][0m [36m<COMMAND>[0m[1m[36m-v[0m, [1m[36m--verbose[0mShow commands and debug info-Individual workflow steps for scripting and automation. Each subcommand performs one step of the [2mwt merge[0m 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/).[32mExamples[0m-Commit with an LLM-generated message:+Commit with LLM-generated message:[2mwt step commit[0m-Squash all branch commits into one:+Run pre-merge hooks in CI:- [2mwt step squash[0m--Run pre-merge hooks (tests, lints):-- [2mwt step pre-merge[0m--Rebase onto main:-- [2mwt step rebase[0m--[32mUse Cases[0m+ [2mwt step pre-merge --force[0m-[1mCustom merge workflow[0m — Run steps individually when [2mwt merge[0m doesn't fit, such as adding manual review between squash and rebase:+Manual merge workflow with review between steps:[2mwt step commit[0m[2mwt step squash[0m- [2m# manual review here[0m+ [2m# Review the squashed commit[0m[2mwt step rebase[0m- [2mwt step pre-merge[0m[2mwt step push[0m-[1mCI integration[0m — Run hooks explicitly in CI environments:+[32mOperations[0m++[1mGit operations:[0m++- [2mcommit[0m — Stage and commit with [LLM-generated message](/llm-commits/)+- [2msquash[0m — Squash all branch commits into one with [LLM-generated message](/llm-commits/)+- [2mrebase[0m — Rebase onto target branch+- [2mpush[0m — Push to target branch (default: main)++[1mHooks[0m — run project commands defined in [[2m.config/wt.toml[0m](/hooks/):- [2mwt step pre-merge --force # skip approval prompts[0m+- [2mpost-create[0m — After worktree creation+- [2mpost-start[0m — After switching to a worktree+- [2mpre-commit[0m — Before committing+- [2mpre-merge[0m — Before pushing to target+- [2mpost-merge[0m — After merge cleanup-[32mSubcommands[0m+[32mSee Also[0m-| Command | Description |-|---------|-------------|-| [2mcommit[0m | Commits uncommitted changes with an [LLM-generated message](/llm-commits/) |-| [2msquash[0m | Squashes all branch commits into one with an [LLM-generated message](/llm-commits/) |-| [2mrebase[0m | Rebases the branch onto the target (default: main) |-| [2mpush[0m | Pushes changes to the local target branch |-| [2mpost-create[0m | Runs post-create hooks |-| [2mpost-start[0m | Runs post-start hooks |-| [2mpre-commit[0m | Runs pre-commit hooks |-| [2mpre-merge[0m | Runs pre-merge hooks |-| [2mpost-merge[0m | Runs post-merge hooks |+- [wt merge](/merge/) — Runs commit → squash → rebase → hooks → push → cleanup automaticallydiff --git a/tests/snapshots/integration__integration_tests__help__help_step_short.snap b/tests/snapshots/integration__integration_tests__help__help_step_short.snapindex 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 operationsUsage: [1m[36mwt step[0m [36m[OPTIONS][0m [36m<COMMAND>[0m[1m[32mCommands:[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex 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: [1m[36mwt switch[0m [36m[OPTIONS][0m [36m<BRANCH>[0m[1m[36m-v[0m, [1m[36m--verbose[0mShow commands and debug info-Navigate between worktrees or create new ones. Switching to an existing worktree is just a directory change. With [2m--create[0m, a new branch and worktree are created, and hooks run.+Two distinct operations:-[32mExamples[0m--Switch to an existing worktree:-- [2mwt switch feature-auth[0m--Create a new worktree for a fresh branch:-- [2mwt switch --create new-feature[0m+- [1mSwitch to existing worktree[0m — Changes directory, nothing else+- [1mCreate new worktree[0m ([2m--create[0m) — Creates branch and worktree, runs [hooks](/hooks/)-Create from a specific base branch:+[32mExamples[0m+ [2mwt switch feature-auth # Switch to existing worktree[0m+ [2mwt switch - # Previous worktree (like cd -)[0m+ [2mwt switch --create new-feature # Create branch and worktree[0m[2mwt switch --create hotfix --base production[0m-Switch to the previous worktree (like [2mcd -[0m):-- [2mwt switch -[0m--[32mCreating Worktrees[0m--The [2m--create[0m flag (or [2m-c[0m) creates a new branch from the default branch (or [2m--base[0m), sets up a worktree at [2m../{repo}.{branch}[0m, 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.-- [2m# Create from main (default)[0m- [2mwt switch --create api-refactor[0m- [2m[0m- [2m# Create from a specific branch[0m- [2mwt switch --create emergency-fix --base release-2.0[0m- [2m[0m- [2m# Create and open in editor[0m- [2mwt switch --create docs --execute "code ."[0m- [2m[0m- [2m# Skip all hooks[0m- [2mwt switch --create temp --no-verify[0m+For interactive selection, use [[2mwt select[0m](/select/).[32mShortcuts[0m-Special symbols for common targets:--| Shortcut | Meaning |-|----------|---------|-| [2m-[0m | Previous worktree (like [2mcd -[0m) |+| Symbol | Meaning |+|--------|---------|+| [2m-[0m | Previous worktree || [2m@[0m | Current branch's worktree |-| [2m^[0m | Default branch (main/master) |+| [2m^[0m | Default branch worktree |- [2mwt switch - # Go back to previous worktree[0m- [2mwt switch ^ # Switch to main worktree[0m- [2mwt switch --create bugfix --base=@ # Branch from current HEAD[0m+ [2mwt switch - # Back to previous[0m+ [2mwt switch ^ # Main worktree[0m+ [2mwt switch --create fix --base=@ # Branch from current HEAD[0m-[32mHooks[0m+[32mPath-First Lookup[0m-When creating a worktree ([2m--create[0m), hooks run in this order:+Arguments resolve by checking the filesystem before git branches:-1. [1mpost-create[0m — Blocking, sequential. Typically: [2mnpm install[0m, [2mcargo build[0m-2. [1mpost-start[0m — 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.+[1mEdge case[0m: If [2mrepo.foo/[0m exists but tracks branch [2mbar[0m:+- [2mwt switch foo[0m → switches to [2mrepo.foo/[0m (the [2mbar[0m worktree)+- [2mwt switch bar[0m → also works (branch lookup finds same worktree)-[32mHow Arguments Are Resolved[0m+[32mCreating Worktrees[0m++With [2m--create[0m, worktrunk:-Arguments resolve using [1mpath-first lookup[0m:+1. Creates branch from [2m--base[0m (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+ [2mwt switch --create api-refactor[0m+ [2mwt switch --create fix --base release-2.0[0m+ [2mwt switch --create docs --execute "code ."[0m+ [2mwt switch --create temp --no-verify # Skip hooks[0m-[1mExample[0m: If [2mrepo.foo/[0m exists but is on branch [2mbar[0m:+[32mSee Also[0m-- [2mwt switch foo[0m switches to [2mrepo.foo/[0m (the [2mbar[0m branch worktree)-- [2mwt switch bar[0m 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