Skip to content

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

feat: Improve CLI help output and readability

Maximilian Roosee87e196f296
diff --git a/src/cli.rs b/src/cli.rs
index ab7ddb6f9..55eb82a00 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -329,57 +329,60 @@ Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat
},
/// List worktrees and optionally branches
- #[command(after_help = "OPERATION
+ #[command(after_help = "## OPERATION
Displays worktrees in a table format with status information, commit details, and optional branch listings.
-- By default: Shows only worktrees
-- With --branches: Includes branches without worktrees
-- With --full: Adds CI status, conflict detection, and detailed diffs
-- With --format=json: Outputs structured JSON for scripting
-
-COLUMNS
-
- Branch: Branch name
- Status: Quick status symbols (see STATUS SYMBOLS below)
- HEAD±: Uncommitted changes vs HEAD (+added -deleted lines, staged + unstaged)
- main↕: Commit count ahead↑/behind↓ relative to main (commits in HEAD vs main)
- main…± (--full): Line diffs in commits ahead of main (+added -deleted)
- Path: Worktree directory location
- Remote⇅: Commits ahead↑/behind↓ relative to tracking branch (e.g. origin/branch)
- CI (--full): CI pipeline status (tries PR/MR checks first, falls back to branch workflows)
- \x1b[32m●\x1b[0m passed (green) - All checks passed
- \x1b[34m●\x1b[0m running (blue) - Checks in progress
- \x1b[31m●\x1b[0m failed (red) - Checks failed
- \x1b[33m●\x1b[0m conflicts (yellow) - Merge conflicts with base
- \x1b[90m●\x1b[0m no-ci (gray) - PR/MR or workflow found but no checks configured
- (blank) - No PR/MR or workflow found, or gh/glab CLI unavailable
- (dimmed) - Stale: unpushed local changes differ from PR/MR head
- Commit: Short commit hash (8 chars)
- Age: Time since last commit (relative)
- Message: Last commit message (truncated)
-
-STATUS SYMBOLS (order: =≠ ≡∅ ↻⋈ ⊠⚠ ↑↓ ⇡⇣ ?!+»✘):
- · Branch without worktree (no working directory to check)
- \x1b[31m=\x1b[0m Merge conflicts (unmerged paths in working tree)
- \x1b[33m≠\x1b[0m Potential conflicts with main (--full only, detected via git merge-tree)
- ≡ Working tree matches main (identical contents, regardless of commit history)
- ∅ No commits (no commits ahead AND no uncommitted changes)
- ↻ Rebase in progress
- ⋈ Merge in progress
- ⊠ Locked worktree
- ⚠ Prunable worktree
- ↑ Ahead of main branch
- ↓ Behind main branch
- ⇡ Ahead of remote tracking branch
- ⇣ Behind remote tracking branch
- ? Untracked files present
- ! Modified files (unstaged changes)
- + Staged files (ready to commit)
- » Renamed files
- ✘ Deleted files
-
-Rows are dimmed when no unique work (≡ matches main OR ∅ no commits).")]
+- **By default:** Shows only worktrees
+- **With `--branches`:** Includes branches without worktrees
+- **With `--full`:** Adds CI status, conflict detection, and detailed diffs
+- **With `--format=json`:** Outputs structured JSON for scripting
+
+## COLUMNS
+
+- **Branch:** Branch name
+- **Status:** Quick status symbols (see STATUS SYMBOLS below)
+- **HEAD±:** Uncommitted changes vs HEAD (+added -deleted lines, staged + unstaged)
+- **main↕:** Commit count ahead↑/behind↓ relative to main (commits in HEAD vs main)
+- **main…±** (`--full`): Line diffs in commits ahead of main (+added -deleted)
+- **Path:** Worktree directory location
+- **Remote⇅:** Commits ahead↑/behind↓ relative to tracking branch (e.g. `origin/branch`)
+- **CI** (`--full`): CI pipeline status (tries PR/MR checks first, falls back to branch workflows)
+ - `●` **passed** (green) - All checks passed
+ - `●` **running** (blue) - Checks in progress
+ - `●` **failed** (red) - Checks failed
+ - `●` **conflicts** (yellow) - Merge conflicts with base
+ - `●` **no-ci** (gray) - PR/MR or workflow found but no checks configured
+ - (blank) - No PR/MR or workflow found, or `gh`/`glab` CLI unavailable
+ - (dimmed) - Stale: unpushed local changes differ from PR/MR head
+- **Commit:** Short commit hash (8 chars)
+- **Age:** Time since last commit (relative)
+- **Message:** Last commit message (truncated)
+
+## STATUS SYMBOLS
+
+Order: `=≠ ≡∅ ↻⋈ ⊠⚠ ↑↓ ⇡⇣ ?!+»✘`
+
+- `·` Branch without worktree (no working directory to check)
+- `=` **Merge conflicts** (unmerged paths in working tree)
+- `≠` **Potential conflicts** with main (`--full` only, detected via `git merge-tree`)
+- `≡` Working tree matches main (identical contents, regardless of commit history)
+- `∅` No commits (no commits ahead AND no uncommitted changes)
+- `↻` Rebase in progress
+- `⋈` Merge in progress
+- `⊠` Locked worktree
+- `⚠` Prunable worktree
+- `↑` Ahead of main branch
+- `↓` Behind main branch
+- `⇡` Ahead of remote tracking branch
+- `⇣` Behind remote tracking branch
+- `?` Untracked files present
+- `!` Modified files (unstaged changes)
+- `+` Staged files (ready to commit)
+- `»` Renamed files
+- `✘` Deleted files
+
+*Rows are dimmed when no unique work (≡ matches main OR ∅ no commits).*")]
List {
/// Output format
#[arg(long, value_enum, default_value = "table")]
@@ -410,64 +413,78 @@ Rows are dimmed when no unique work (≡ matches main OR ∅ no commits).")]
},
/// Switch to a worktree
- #[command(after_help = r#"OPERATION
-
-Switching to Existing Worktree:
- - If worktree exists for branch, changes directory via shell integration
- - No hooks run
- - No branch creation
-
-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)
- 4. Shows success message
- 5. Spawns post-start hooks in background (non-blocking)
- 6. Changes directory to new worktree via shell integration
-
-HOOKS
-
-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):
- - 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
+ #[command(after_help = r#"## OPERATION
+
+**Switching to Existing Worktree:**
+- If worktree exists for branch, changes directory via shell integration
+- No hooks run
+- No branch creation
+
+**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)
+4. Shows success message
+5. Spawns post-start hooks in background (non-blocking)
+6. Changes directory to new worktree via shell integration
+
+## HOOKS
+
+**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):
+- 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
Switch to existing worktree:
- wt switch feature-branch
+```
+wt switch feature-branch
+```
Create new worktree from main:
- wt switch --create new-feature
+```
+wt switch --create new-feature
+```
Switch to previous worktree:
- wt switch -
+```
+wt switch -
+```
Create from specific base:
- wt switch --create hotfix --base production
+```
+wt switch --create hotfix --base production
+```
Create and run command:
- wt switch --create docs --execute "code ."
+```
+wt switch --create docs --execute "code ."
+```
Skip hooks during creation:
- wt switch --create temp --no-verify
-
-SHORTCUTS
-
-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)
- wt switch --create bugfix --base=@ # Branch from current HEAD
- wt remove @ # Remove current worktree"#)]
+```
+wt switch --create temp --no-verify
+```
+
+## SHORTCUTS
+
+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)
+wt switch --create bugfix --base=@ # Branch from current HEAD
+wt remove @ # Remove current worktree
+```"#)]
Switch {
/// Branch, path, '@' (HEAD), '-' (previous), or '^' (main)
#[arg(add = crate::completion::worktree_branch_completer())]
@@ -495,55 +512,67 @@ Use '@' for current HEAD, '-' for previous, '^' for main:
},
/// Remove worktree and branch
- #[command(after_help = r#"OPERATION
-
-Remove Current Worktree (no arguments):
- - Requires clean working tree (no uncommitted changes)
- - If in worktree: removes it and switches to main worktree
- - If in main worktree: switches to default branch (e.g., main)
- - If already on default branch in main: does nothing
-
-Remove Specific Worktree (by name):
- - Requires target worktree has clean working tree
- - Removes specified worktree(s) and associated branches
- - If removing current worktree, switches to main first
- - Can remove multiple worktrees in one command
-
-Remove Multiple Worktrees:
- - When removing multiple, current worktree is removed last
- - Prevents deleting directory you're currently in
- - Each worktree must have clean working tree
-
-Removal Process (by default):
- 1. Validates worktree has no uncommitted changes
- 2. Changes directory (if removing current worktree)
- 3. Spawns background removal process (non-blocking)
- - Directory deletion happens in background
- - Git worktree metadata removed in background
- - Branch deletion in background (uses git branch -d, safe delete)
- - Logs: .git/wt-logs/{branch}-remove.log
- 4. Returns immediately so you can continue working
- - Use --no-background for foreground removal (blocking)
-
-EXAMPLES
+ #[command(after_help = r#"## OPERATION
+
+**Remove Current Worktree** (no arguments):
+- Requires clean working tree (no uncommitted changes)
+- If in worktree: removes it and switches to main worktree
+- If in main worktree: switches to default branch (e.g., `main`)
+- If already on default branch in main: does nothing
+
+**Remove Specific Worktree** (by name):
+- Requires target worktree has clean working tree
+- Removes specified worktree(s) and associated branches
+- If removing current worktree, switches to main first
+- Can remove multiple worktrees in one command
+
+**Remove Multiple Worktrees:**
+- When removing multiple, current worktree is removed last
+- Prevents deleting directory you're currently in
+- Each worktree must have clean working tree
+
+**Removal Process** (by default):
+1. **Validates** worktree has no uncommitted changes
+2. **Changes directory** (if removing current worktree)
+3. **Spawns background removal process** (non-blocking)
+ - Directory deletion happens in background
+ - Git worktree metadata removed in background
+ - Branch deletion in background (uses `git branch -d`, safe delete)
+ - Logs: `.git/wt-logs/{branch}-remove.log`
+4. **Returns immediately** so you can continue working
+ - Use `--no-background` for foreground removal (blocking)
+
+## EXAMPLES
Remove current worktree and branch:
- wt remove
+```
+wt remove
+```
Remove specific worktree and branch:
- wt remove feature-branch
+```
+wt remove feature-branch
+```
Remove worktree but keep branch:
- wt remove --no-delete-branch feature-branch
+```
+wt remove --no-delete-branch feature-branch
+```
Remove multiple worktrees:
- wt remove old-feature another-branch
+```
+wt remove old-feature another-branch
+```
Remove in foreground (blocking):
- wt remove --no-background feature-branch
+```
+wt remove --no-background feature-branch
+```
Switch to default in main:
- wt remove # (when already in main worktree)"#)]
+```
+wt remove # (when already in main worktree)
+```"#)]
Remove {
/// Worktree or branch (@ for current)
#[arg(add = crate::completion::worktree_branch_completer())]
@@ -565,70 +594,78 @@ Switch to default in main:
/// Merge worktree into target branch
#[command(long_about = r#"Merge worktree into target branch
-OPERATION
+## OPERATION
-The merge operation follows a strict order designed for fail-fast execution:
+The merge operation follows a strict order designed for **fail-fast execution**:
-1. Validate branches
+1. **Validate branches**
Verifies current branch exists (not detached HEAD) and determines target branch
(defaults to repository's default branch).
-2. Auto-commit uncommitted changes
+2. **Auto-commit uncommitted changes**
If working tree has uncommitted changes, stages changes and commits with LLM-generated
- message. By default stages all changes (git add -A). Use --tracked-only to stage only
- tracked files (git add -u).
+ message. By default stages all changes (`git add -A`). Use `--tracked-only` to stage only
+ tracked files (`git add -u`).
-3. Squash commits (default)
+3. **Squash commits** (default)
By default, counts commits since merge base with target branch. When multiple
commits exist, squashes them into one with LLM-generated message. Skip squashing
- with --no-squash.
+ with `--no-squash`.
A safety backup is created before squashing if there are working tree changes.
- Recover with: git reflog show refs/wt-backup/<branch>
+ Recover with: `git reflog show refs/wt-backup/<branch>`
-4. Rebase onto target
+4. **Rebase onto target**
Rebases current branch onto target branch. Detects conflicts and aborts if found.
This fails fast before running expensive checks.
-5. Run pre-merge commands
- Runs commands from project config's [pre-merge-command] after rebase completes.
- These receive {{ target }} placeholder for the target branch. Commands run sequentially
- and any failure aborts the merge immediately. Skip with --no-verify.
+5. **Run pre-merge commands**
+ Runs commands from project config's `[pre-merge-command]` after rebase completes.
+ These receive `{{ target }}` placeholder for the target branch. Commands run sequentially
+ and any failure aborts the merge immediately. Skip with `--no-verify`.
-6. Push to target
+6. **Push to target**
Fast-forward pushes to target branch. Rejects non-fast-forward pushes (ensures
linear history). Temporarily stashes non-conflicting local edits in the target
worktree so they don't block the push, then restores them after success.
-7. Clean up worktree and branch
+7. **Clean up worktree and branch**
Removes current worktree, deletes the branch, and switches main worktree to target
- branch if needed. Skip removal with --no-remove.
+ branch if needed. Skip removal with `--no-remove`.
-8. Run post-merge commands
- Runs commands from project config's [post-merge-command] in the destination worktree
- after cleanup. These receive {{ target }} placeholder. Commands run sequentially,
- failures are logged but don't abort. Skip with --no-verify.
+8. **Run post-merge commands**
+ Runs commands from project config's `[post-merge-command]` in the destination worktree
+ after cleanup. These receive `{{ target }}` placeholder. Commands run sequentially,
+ failures are logged but don't abort. Skip with `--no-verify`.
-HOOKS
+## HOOKS
-The --no-verify flag skips all project hooks:
+The `--no-verify` flag skips all project hooks:
- Pre-commit hooks (before committing working tree changes)
- Pre-merge hooks (after rebase, before push)
- Post-merge hooks (after cleanup)
-EXAMPLES
+## EXAMPLES
Basic merge to main:
- wt merge
+```
+wt merge
+```
Merge without squashing:
- wt merge --no-squash
+```
+wt merge --no-squash
+```
Keep worktree after merging:
- wt merge --no-remove
+```
+wt merge --no-remove
+```
Skip all hooks:
- wt merge --no-verify"#)]
+```
+wt merge --no-verify
+```"#)]
Merge {
/// Target branch (defaults to default branch)
#[arg(add = crate::completion::branch_value_completer())]