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.rsindex 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 = "## OPERATIONDisplays 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`++## EXAMPLESSwitch 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)++## EXAMPLESRemove 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 multiplecommits 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 (ensureslinear history). Temporarily stashes non-conflicting local edits in the targetworktree 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+## EXAMPLESBasic 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())]