Skip to content

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

docs: Improve help message formatting and readability

Maximilian Roos4829c3584723
diff --git a/.claude-plugin/skills/worktrunk/reference/README.md b/.claude-plugin/skills/worktrunk/reference/README.md
index e52d73b93..07d745acf 100644
--- a/.claude-plugin/skills/worktrunk/reference/README.md
+++ b/.claude-plugin/skills/worktrunk/reference/README.md
@@ -328,15 +328,15 @@ Global Options:
-v, --verbose Show commands and debug info
```
-**BEHAVIOR:**
+## Operation
-Switching to Existing Worktree:
+### Switching to Existing Worktree
- If worktree exists for branch, changes directory via shell integration
- No hooks run
- No branch creation
-Creating New Worktree (--create):
+### Creating New Worktree (`--create`)
1. Creates new branch (defaults to current default branch as base)
2. Creates worktree in configured location (default: `../{{ main_worktree }}.{{ branch }}`)
@@ -345,50 +345,59 @@ Creating New Worktree (--create):
5. Spawns post-start hooks in background (non-blocking)
6. Changes directory to new worktree via shell integration
-**HOOKS:**
+## Hooks
-post-create (sequential, blocking):
+### post-create (sequential, blocking)
- Run after worktree creation, before success message
-- Typically: npm install, cargo build, setup tasks
+- Typically: `npm install`, `cargo build`, setup tasks
- Failures block the operation
-- Skip with --no-verify
+- Skip with `--no-verify`
-post-start (parallel, background):
+### post-start (parallel, background)
- Spawned after success message shown
- Typically: dev servers, file watchers, editors
- Run in background, failures logged but don't block
- Logs: `.git/wt-logs/{branch}-post-start-{name}.log`
-- Skip with --no-verify
+- Skip with `--no-verify`
-**EXAMPLES:**
+## Examples
-```bash
-# Switch to existing worktree
+Switch to existing worktree:
+```
wt switch feature-branch
+```
-# Create new worktree from main
+Create new worktree from main:
+```
wt switch --create new-feature
+```
-# Switch to previous worktree
+Switch to previous worktree:
+```
wt switch -
+```
-# Create from specific base
+Create from specific base:
+```
wt switch --create hotfix --base production
+```
-# Create and run command
+Create and run command:
+```
wt switch --create docs --execute "code ."
+```
-# Skip hooks during creation
+Skip hooks during creation:
+```
wt switch --create temp --no-verify
```
-**SHORTCUTS:**
-
-Use '@' for current HEAD, '-' for previous, '^' for main:
+## Shortcuts
-```bash
+Use `@` for current HEAD, `-` for previous, `^` for main:
+```
wt switch @ # Switch to current branch's worktree
wt switch - # Switch to previous worktree
wt switch --create new-feature --base=^ # Branch from main (default)
@@ -424,57 +433,56 @@ Global Options:
-v, --verbose Show commands and debug info
```
-**LIFECYCLE:**
+## Operation
-The merge operation follows a strict order designed for fail-fast execution:
+Commit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks
-1. **Validate branches**
- Verifies current branch exists (not detached HEAD) and determines target branch
- (defaults to repository's default branch).
+### Commit
-2. **Auto-commit uncommitted changes**
- If working tree has uncommitted changes, stages all changes (git add -A) and commits
- with LLM message.
+Uncommitted changes are staged and committed with LLM message.
+Use `--stage=tracked` to stage only tracked files, or `--stage=none` to commit only what's already staged.
-3. **Squash commits (default)**
- By default, counts commits since merge base with target branch. When multiple
- commits exist, squashes them into one with LLM message. Skip squashing
- with --no-squash.
+### Squash
- A safety backup is created before squashing if there are working tree changes.
- Recover with: `git reflog show refs/wt-backup/<branch>`
+Multiple commits are squashed into one with LLM message.
+Skip with `--no-squash`. Safety backup: `git reflog show refs/wt-backup/<branch>`
-4. **Rebase onto target**
- Rebases current branch onto target branch. Detects conflicts and aborts if found.
- This fails fast before running expensive checks.
+### Rebase
-5. **Run pre-merge commands**
- Runs commands from project config's `[pre-merge-command]` after rebase completes.
- These receive `{{ target }}` placeholder for the target branch. Commands run sequentially
- and any failure aborts the merge immediately. Skip with --no-verify.
+Branch is rebased onto target. Conflicts abort the merge immediately.
-6. **Push to target**
- Fast-forward pushes to target branch. Rejects non-fast-forward pushes (ensures
- linear history). Temporarily stashes non-conflicting local edits in the target
- worktree so they don't block the push, then restores them after success.
+### Hooks
-7. **Clean up worktree and branch**
- Removes current worktree, deletes the branch, and switches to the main worktree or target
- branch if needed. Skip removal with --no-remove.
+Pre-merge commands run after rebase (failures abort). Post-merge commands
+run after cleanup (failures logged). Skip all with `--no-verify`.
-**EXAMPLES:**
+### Push
-```bash
-# Basic merge to main
+Fast-forward push to local target branch. Non-fast-forward pushes are rejected.
+
+### Cleanup
+
+Worktree and branch are removed. Skip with `--no-remove`.
+
+## Examples
+
+Basic merge to main:
+```
wt merge
+```
-# Merge without squashing
+Merge without squashing:
+```
wt merge --no-squash
+```
-# Keep worktree after merging
+Keep worktree after merging:
+```
wt merge --no-remove
+```
-# Skip pre-merge commands
+Skip all hooks:
+```
wt merge --no-verify
```
@@ -501,61 +509,59 @@ Global Options:
-v, --verbose Show commands and debug info
```
-**BEHAVIOR:**
+## Operation
-Remove Current Worktree (no arguments):
+Removes worktree directory, git metadata, and branch. Requires clean working tree.
-- Requires clean working tree (no uncommitted changes)
-- If in worktree: removes it and switches to main worktree
-- If in main worktree: switches to default branch (e.g., main)
-- If already on default branch in main: does nothing
+### No arguments (remove current)
-Remove Specific Worktree (by name):
+- Removes current worktree and switches to main worktree
+- In main worktree: switches to default branch
-- Requires target worktree has clean working tree
-- Removes specified worktree(s) and associated branches
-- If removing current worktree, switches to main first
-- Can remove multiple worktrees in one command
+### By name (remove specific)
-Remove Multiple Worktrees:
+- Removes specified worktree(s) and branches
+- Current worktree removed last (switches to main first)
-- When removing multiple, current worktree is removed last
-- Prevents deleting directory you're currently in
-- Each worktree must have clean working tree
+### Background removal (default)
-**CLEANUP:**
+- Returns immediately so you can continue working
+- Logs: `.git/wt-logs/{branch}-remove.log`
+- Use `--no-background` for foreground (blocking)
-When removing a worktree (by default):
+### Cleanup
-1. Validates worktree has no uncommitted changes
-2. Changes directory (if removing current worktree)
-3. Spawns background removal process (non-blocking)
- - Directory deletion happens in background
- - Git worktree metadata removed in background
- - Branch deletion in background (uses git branch -d, safe delete)
- - Logs: `.git/wt-logs/{branch}-remove.log`
-4. Returns immediately so you can continue working
- - Use --no-background for foreground removal (blocking)
+Stops any git fsmonitor daemon for the worktree before removal. This prevents orphaned processes when using builtin fsmonitor (`core.fsmonitor=true`). No effect on Watchman users.
-**EXAMPLES:**
+## Examples
-```bash
-# Remove current worktree and branch
+Remove current worktree and branch:
+```
wt remove
+```
-# Remove specific worktree and branch
+Remove specific worktree and branch:
+```
wt remove feature-branch
+```
-# Remove worktree but keep branch
+Remove worktree but keep branch:
+```
wt remove --no-delete-branch feature-branch
+```
-# Remove multiple worktrees
+Remove multiple worktrees:
+```
wt remove old-feature another-branch
+```
-# Remove in foreground (blocking)
+Remove in foreground (blocking):
+```
wt remove --no-background feature-branch
+```
-# Switch to default in main
+Switch to default in main:
+```
wt remove # (when already in main worktree)
```
@@ -583,7 +589,7 @@ Global Options:
-v, --verbose Show commands and debug info
```
-**COLUMNS:**
+## Columns
- **Branch:** Branch name
- **Status:** Quick status symbols (see STATUS SYMBOLS below)
diff --git a/README.md b/README.md
index e52d73b93..07d745acf 100644
--- a/README.md
+++ b/README.md
@@ -328,15 +328,15 @@ Global Options:
-v, --verbose Show commands and debug info
```
-**BEHAVIOR:**
+## Operation
-Switching to Existing Worktree:
+### Switching to Existing Worktree
- If worktree exists for branch, changes directory via shell integration
- No hooks run
- No branch creation
-Creating New Worktree (--create):
+### Creating New Worktree (`--create`)
1. Creates new branch (defaults to current default branch as base)
2. Creates worktree in configured location (default: `../{{ main_worktree }}.{{ branch }}`)
@@ -345,50 +345,59 @@ Creating New Worktree (--create):
5. Spawns post-start hooks in background (non-blocking)
6. Changes directory to new worktree via shell integration
-**HOOKS:**
+## Hooks
-post-create (sequential, blocking):
+### post-create (sequential, blocking)
- Run after worktree creation, before success message
-- Typically: npm install, cargo build, setup tasks
+- Typically: `npm install`, `cargo build`, setup tasks
- Failures block the operation
-- Skip with --no-verify
+- Skip with `--no-verify`
-post-start (parallel, background):
+### post-start (parallel, background)
- Spawned after success message shown
- Typically: dev servers, file watchers, editors
- Run in background, failures logged but don't block
- Logs: `.git/wt-logs/{branch}-post-start-{name}.log`
-- Skip with --no-verify
+- Skip with `--no-verify`
-**EXAMPLES:**
+## Examples
-```bash
-# Switch to existing worktree
+Switch to existing worktree:
+```
wt switch feature-branch
+```
-# Create new worktree from main
+Create new worktree from main:
+```
wt switch --create new-feature
+```
-# Switch to previous worktree
+Switch to previous worktree:
+```
wt switch -
+```
-# Create from specific base
+Create from specific base:
+```
wt switch --create hotfix --base production
+```
-# Create and run command
+Create and run command:
+```
wt switch --create docs --execute "code ."
+```
-# Skip hooks during creation
+Skip hooks during creation:
+```
wt switch --create temp --no-verify
```
-**SHORTCUTS:**
-
-Use '@' for current HEAD, '-' for previous, '^' for main:
+## Shortcuts
-```bash
+Use `@` for current HEAD, `-` for previous, `^` for main:
+```
wt switch @ # Switch to current branch's worktree
wt switch - # Switch to previous worktree
wt switch --create new-feature --base=^ # Branch from main (default)
@@ -424,57 +433,56 @@ Global Options:
-v, --verbose Show commands and debug info
```
-**LIFECYCLE:**
+## Operation
-The merge operation follows a strict order designed for fail-fast execution:
+Commit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks
-1. **Validate branches**
- Verifies current branch exists (not detached HEAD) and determines target branch
- (defaults to repository's default branch).
+### Commit
-2. **Auto-commit uncommitted changes**
- If working tree has uncommitted changes, stages all changes (git add -A) and commits
- with LLM message.
+Uncommitted changes are staged and committed with LLM message.
+Use `--stage=tracked` to stage only tracked files, or `--stage=none` to commit only what's already staged.
-3. **Squash commits (default)**
- By default, counts commits since merge base with target branch. When multiple
- commits exist, squashes them into one with LLM message. Skip squashing
- with --no-squash.
+### Squash
- A safety backup is created before squashing if there are working tree changes.
- Recover with: `git reflog show refs/wt-backup/<branch>`
+Multiple commits are squashed into one with LLM message.
+Skip with `--no-squash`. Safety backup: `git reflog show refs/wt-backup/<branch>`
-4. **Rebase onto target**
- Rebases current branch onto target branch. Detects conflicts and aborts if found.
- This fails fast before running expensive checks.
+### Rebase
-5. **Run pre-merge commands**
- Runs commands from project config's `[pre-merge-command]` after rebase completes.
- These receive `{{ target }}` placeholder for the target branch. Commands run sequentially
- and any failure aborts the merge immediately. Skip with --no-verify.
+Branch is rebased onto target. Conflicts abort the merge immediately.
-6. **Push to target**
- Fast-forward pushes to target branch. Rejects non-fast-forward pushes (ensures
- linear history). Temporarily stashes non-conflicting local edits in the target
- worktree so they don't block the push, then restores them after success.
+### Hooks
-7. **Clean up worktree and branch**
- Removes current worktree, deletes the branch, and switches to the main worktree or target
- branch if needed. Skip removal with --no-remove.
+Pre-merge commands run after rebase (failures abort). Post-merge commands
+run after cleanup (failures logged). Skip all with `--no-verify`.
-**EXAMPLES:**
+### Push
-```bash
-# Basic merge to main
+Fast-forward push to local target branch. Non-fast-forward pushes are rejected.
+
+### Cleanup
+
+Worktree and branch are removed. Skip with `--no-remove`.
+
+## Examples
+
+Basic merge to main:
+```
wt merge
+```
-# Merge without squashing
+Merge without squashing:
+```
wt merge --no-squash
+```
-# Keep worktree after merging
+Keep worktree after merging:
+```
wt merge --no-remove
+```
-# Skip pre-merge commands
+Skip all hooks:
+```
wt merge --no-verify
```
@@ -501,61 +509,59 @@ Global Options:
-v, --verbose Show commands and debug info
```
-**BEHAVIOR:**
+## Operation
-Remove Current Worktree (no arguments):
+Removes worktree directory, git metadata, and branch. Requires clean working tree.
-- Requires clean working tree (no uncommitted changes)
-- If in worktree: removes it and switches to main worktree
-- If in main worktree: switches to default branch (e.g., main)
-- If already on default branch in main: does nothing
+### No arguments (remove current)
-Remove Specific Worktree (by name):
+- Removes current worktree and switches to main worktree
+- In main worktree: switches to default branch
-- Requires target worktree has clean working tree
-- Removes specified worktree(s) and associated branches
-- If removing current worktree, switches to main first
-- Can remove multiple worktrees in one command
+### By name (remove specific)
-Remove Multiple Worktrees:
+- Removes specified worktree(s) and branches
+- Current worktree removed last (switches to main first)
-- When removing multiple, current worktree is removed last
-- Prevents deleting directory you're currently in
-- Each worktree must have clean working tree
+### Background removal (default)
-**CLEANUP:**
+- Returns immediately so you can continue working
+- Logs: `.git/wt-logs/{branch}-remove.log`
+- Use `--no-background` for foreground (blocking)
-When removing a worktree (by default):
+### Cleanup
-1. Validates worktree has no uncommitted changes
-2. Changes directory (if removing current worktree)
-3. Spawns background removal process (non-blocking)
- - Directory deletion happens in background
- - Git worktree metadata removed in background
- - Branch deletion in background (uses git branch -d, safe delete)
- - Logs: `.git/wt-logs/{branch}-remove.log`
-4. Returns immediately so you can continue working
- - Use --no-background for foreground removal (blocking)
+Stops any git fsmonitor daemon for the worktree before removal. This prevents orphaned processes when using builtin fsmonitor (`core.fsmonitor=true`). No effect on Watchman users.
-**EXAMPLES:**
+## Examples
-```bash
-# Remove current worktree and branch
+Remove current worktree and branch:
+```
wt remove
+```
-# Remove specific worktree and branch
+Remove specific worktree and branch:
+```
wt remove feature-branch
+```
-# Remove worktree but keep branch
+Remove worktree but keep branch:
+```
wt remove --no-delete-branch feature-branch
+```
-# Remove multiple worktrees
+Remove multiple worktrees:
+```
wt remove old-feature another-branch
+```
-# Remove in foreground (blocking)
+Remove in foreground (blocking):
+```
wt remove --no-background feature-branch
+```
-# Switch to default in main
+Switch to default in main:
+```
wt remove # (when already in main worktree)
```
@@ -583,7 +589,7 @@ Global Options:
-v, --verbose Show commands and debug info
```
-**COLUMNS:**
+## Columns
- **Branch:** Branch name
- **Status:** Quick status symbols (see STATUS SYMBOLS below)
diff --git a/src/cli.rs b/src/cli.rs
index 536e956cd..a5bbcc8f7 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -458,7 +458,7 @@ Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat
},
/// List worktrees and optionally branches
- #[command(after_long_help = "## COLUMNS
+ #[command(after_long_help = "## Columns
- **Branch:** Branch name
- **Status:** Quick status symbols (see STATUS SYMBOLS below)
@@ -479,7 +479,7 @@ Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat
- **Age:** Time since last commit (relative)
- **Message:** Last commit message (truncated)
-## STATUS SYMBOLS
+## Status Symbols
Order: `?!+»✘ ✖⚠≡∅ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠`
@@ -506,7 +506,7 @@ Order: `?!+»✘ ✖⚠≡∅ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠`
*Rows are dimmed when no unique work (≡ matches main OR ∅ no commits).*
-## JSON OUTPUT
+## JSON Output
Use `--format=json` for structured data. Each object contains two status maps
with the same fields in the same order as STATUS SYMBOLS above:
@@ -569,14 +569,15 @@ Note: `locked` and `prunable` are top-level fields on worktree objects, not in s
},
/// Switch to a worktree
- #[command(after_long_help = r#"## OPERATION
+ #[command(after_long_help = r#"## Operation
+
+### Switching to Existing Worktree
-**Switching to Existing Worktree:**
- If worktree exists for branch, changes directory via shell integration
- No hooks run
- No branch creation
-**Creating New Worktree** (`--create`):
+### Creating New Worktree (`--create`)
1. Creates new branch (defaults to current default branch as base)
2. Creates worktree in configured location (default: `../{{ main_worktree }}.{{ branch }}`)
3. Runs post-create hooks sequentially (blocking)
@@ -584,22 +585,23 @@ Note: `locked` and `prunable` are top-level fields on worktree objects, not in s
5. Spawns post-start hooks in background (non-blocking)
6. Changes directory to new worktree via shell integration
-## HOOKS
+## Hooks
+
+### post-create (sequential, blocking)
-**post-create** (sequential, blocking):
- Run after worktree creation, before success message
- Typically: `npm install`, `cargo build`, setup tasks
- Failures block the operation
- Skip with `--no-verify`
-**post-start** (parallel, background):
+### post-start (parallel, background)
- Spawned after success message shown
- Typically: dev servers, file watchers, editors
- Run in background, failures logged but don't block
- Logs: `.git/wt-logs/{branch}-post-start-{name}.log`
- Skip with `--no-verify`
-## EXAMPLES
+## Examples
Switch to existing worktree:
```
@@ -631,7 +633,7 @@ Skip hooks during creation:
wt switch --create temp --no-verify
```
-## SHORTCUTS
+## Shortcuts
Use `@` for current HEAD, `-` for previous, `^` for main:
```
@@ -670,26 +672,31 @@ wt remove @ # Remove current worktree
},
/// Remove worktree and branch
- #[command(after_long_help = r#"## OPERATION
+ #[command(after_long_help = r#"## Operation
Removes worktree directory, git metadata, and branch. Requires clean working tree.
-**No arguments** (remove current):
+### No arguments (remove current)
+
- Removes current worktree and switches to main worktree
- In main worktree: switches to default branch
-**By name** (remove specific):
+### By name (remove specific)
+
- Removes specified worktree(s) and branches
- Current worktree removed last (switches to main first)
-**Background removal** (default):
+### Background removal (default)
+
- Returns immediately so you can continue working
- Logs: `.git/wt-logs/{branch}-remove.log`
- Use `--no-background` for foreground (blocking)
-**Cleanup**: Stops any git fsmonitor daemon for the worktree before removal. This prevents orphaned processes when using builtin fsmonitor (`core.fsmonitor=true`). No effect on Watchman users.
+### Cleanup
+
+Stops any git fsmonitor daemon for the worktree before removal. This prevents orphaned processes when using builtin fsmonitor (`core.fsmonitor=true`). No effect on Watchman users.
-## EXAMPLES
+## Examples
Remove current worktree and branch:
```
@@ -739,26 +746,38 @@ wt remove # (when already in main worktree)
},
/// Merge worktree into target branch
- #[command(after_long_help = r#"## OPERATION
+ #[command(after_long_help = r#"## Operation
Commit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks
-**Commit**: Uncommitted changes are staged and committed with LLM message.
+### Commit
+
+Uncommitted changes are staged and committed with LLM message.
Use `--stage=tracked` to stage only tracked files, or `--stage=none` to commit only what's already staged.
-**Squash**: Multiple commits are squashed into one with LLM message.
+### Squash
+
+Multiple commits are squashed into one with LLM message.
Skip with `--no-squash`. Safety backup: `git reflog show refs/wt-backup/<branch>`
-**Rebase**: Branch is rebased onto target. Conflicts abort the merge immediately.
+### Rebase
+
+Branch is rebased onto target. Conflicts abort the merge immediately.
-**Hooks**: Pre-merge commands run after rebase (failures abort). Post-merge commands
+### Hooks
+
+Pre-merge commands run after rebase (failures abort). Post-merge commands
run after cleanup (failures logged). Skip all with `--no-verify`.
-**Push**: Fast-forward push to local target branch. Non-fast-forward pushes are rejected.
+### Push
+
+Fast-forward push to local target branch. Non-fast-forward pushes are rejected.
+
+### Cleanup
-**Cleanup**: Worktree and branch are removed. Skip with `--no-remove`.
+Worktree and branch are removed. Skip with `--no-remove`.
-## EXAMPLES
+## Examples
Basic merge to main:
```
diff --git a/tests/snapshots/integration__integration_tests__help__help_list.snap b/tests/snapshots/integration__integration_tests__help__help_list.snap
index 5d3d8cc68..dfbba024d 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list.snap
@@ -9,6 +9,7 @@ info:
CLICOLOR_FORCE: "1"
COLUMNS: "150"
GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
---
success: true
exit_code: 0
@@ -50,7 +51,7 @@ Global Options:
-v, --verbose
Show commands and debug info
-COLUMNS
+Columns
- Branch: Branch name
- Status: Quick status symbols (see STATUS SYMBOLS below)
@@ -73,7 +74,7 @@ branch workflows)
- Age: Time since last commit (relative)
- Message: Last commit message (truncated)
-STATUS SYMBOLS
+Status Symbols
Order: ?!+»✘ ✖⚠≡∅ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠
@@ -101,7 +102,7 @@ continuing)
Rows are dimmed when no unique work (≡ matches main OR ∅ no commits).
-JSON OUTPUT
+JSON Output
Use --format=json for structured data. Each object contains two status maps
with the same fields in the same order as STATUS SYMBOLS above:
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge.snap b/tests/snapshots/integration__integration_tests__help__help_merge.snap
index ae6e28790..a4e6423b3 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge.snap
@@ -9,6 +9,7 @@ info:
CLICOLOR_FORCE: "1"
COLUMNS: "150"
GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
---
success: true
exit_code: 0
@@ -59,28 +60,39 @@ Global Options:
-v, --verbose
Show commands and debug info
-OPERATION
+Operation
Commit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks
-Commit: Uncommitted changes are staged and committed with LLM message.
+Commit
+
+Uncommitted changes are staged and committed with LLM message.
Use --stage=tracked to stage only tracked files, or --stage=none to commit only
what's already staged.
-Squash: Multiple commits are squashed into one with LLM message.
+Squash
+
+Multiple commits are squashed into one with LLM message.
Skip with --no-squash. Safety backup: git reflog show refs/wt-backup/<branch>
-Rebase: Branch is rebased onto target. Conflicts abort the merge immediately.
+Rebase
+
+Branch is rebased onto target. Conflicts abort the merge immediately.
-Hooks: Pre-merge commands run after rebase (failures abort). Post-merge commands
+Hooks
+
+Pre-merge commands run after rebase (failures abort). Post-merge commands
run after cleanup (failures logged). Skip all with --no-verify.
-Push: Fast-forward push to local target branch. Non-fast-forward pushes are
-rejected.
+Push
+
+Fast-forward push to local target branch. Non-fast-forward pushes are rejected.
+
+Cleanup
-Cleanup: Worktree and branch are removed. Skip with --no-remove.
+Worktree and branch are removed. Skip with --no-remove.
-EXAMPLES
+Examples
Basic merge to main:
wt merge
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove.snap b/tests/snapshots/integration__integration_tests__help__help_remove.snap
index 6314d4c39..b18f04bc2 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove.snap
@@ -9,6 +9,7 @@ info:
CLICOLOR_FORCE: "1"
COLUMNS: "150"
GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
---
success: true
exit_code: 0
@@ -43,29 +44,34 @@ Global Options:
-v, --verbose
Show commands and debug info
-OPERATION
+Operation
Removes worktree directory, git metadata, and branch. Requires clean working
tree.
-No arguments (remove current):
+No arguments (remove current)
+
- Removes current worktree and switches to main worktree
- In main worktree: switches to default branch
-By name (remove specific):
+By name (remove specific)
+
- Removes specified worktree(s) and branches
- Current worktree removed last (switches to main first)
-Background removal (default):
+Background removal (default)
+
- Returns immediately so you can continue working
- Logs: .git/wt-logs/{branch}-remove.log
- Use --no-background for foreground (blocking)
-Cleanup: Stops any git fsmonitor daemon for the worktree before removal. This
-prevents orphaned processes when using builtin fsmonitor (core.fsmonitor=true).
-No effect on Watchman users.
+Cleanup
+
+Stops any git fsmonitor daemon for the worktree before removal. This prevents
+orphaned processes when using builtin fsmonitor (core.fsmonitor=true). No effect
+on Watchman users.
-EXAMPLES
+Examples
Remove current worktree and branch:
wt remove
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch.snap b/tests/snapshots/integration__integration_tests__help__help_switch.snap
index bf53f4083..0cc1f196e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch.snap
@@ -9,6 +9,7 @@ info:
CLICOLOR_FORCE: "1"
COLUMNS: "150"
GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
---
success: true
exit_code: 0
@@ -51,14 +52,15 @@ Global Options:
-v, --verbose
Show commands and debug info
-OPERATION
+Operation
+
+Switching to Existing Worktree
-Switching to Existing Worktree:
- If worktree exists for branch, changes directory via shell integration
- No hooks run
- No branch creation
-Creating New Worktree (--create):
+Creating New Worktree (--create)
1. Creates new branch (defaults to current default branch as base)
2. Creates worktree in configured location (default:
../{{ main_worktree }}.{{ branch }})
@@ -67,22 +69,23 @@ Creating New Worktree (--create):
5. Spawns post-start hooks in background (non-blocking)
6. Changes directory to new worktree via shell integration
-HOOKS
+Hooks
+
+post-create (sequential, blocking)
-post-create (sequential, blocking):
- Run after worktree creation, before success message
- Typically: npm install, cargo build, setup tasks
- Failures block the operation
- Skip with --no-verify
-post-start (parallel, background):
+post-start (parallel, background)
- Spawned after success message shown
- Typically: dev servers, file watchers, editors
- Run in background, failures logged but don't block
- Logs: .git/wt-logs/{branch}-post-start-{name}.log
- Skip with --no-verify
-EXAMPLES
+Examples
Switch to existing worktree:
wt switch feature-branch
@@ -102,7 +105,7 @@ wt switch --create docs --execute "code ."
Skip hooks during creation:
wt switch --create temp --no-verify
-SHORTCUTS
+Shortcuts
Use @ for current HEAD, - for previous, ^ for main:
wt switch @ # Switch to current branch's worktree