Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: Refine README for clarity and consistency
Maximilian Roosf00a9f55915e
diff --git a/README.md b/README.mdindex 01565e9da..d511dea2f 100644--- a/README.md+++ b/README.md@@ -10,13 +10,13 @@<!-- [](https://crates.io/crates/worktrunk) --><!-- [](https://github.com/max-sixty/worktrunk/stargazers) -->-Worktrunk is a CLI tool which makes working with git worktrees much much easier.+Worktrunk is a CLI tool which makes working with git worktrees much more fluid.It's designed for those running many concurrent AI coding agents.For context, git worktrees let multiple agents work on a single repo withoutcolliding; each agent gets a separate directory with a version of the code. But-creating worktrees, tracking paths & statuses, cleaning up, etc is manual.-Worktrunk offers transparency and automation for this lifecycle.+creating worktrees, tracking paths & statuses, cleaning up, etc, is manual.+Worktrunk offers control, transparency & automation for this workflow.## Quick Start@@ -29,7 +29,7 @@ $ wt switch --create fix-auth✅ Created new worktree for fix-auth from main at ../repo.fix-auth/```-**Work, make changes, then merge back:**+**After making changes, merge it back:**<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_simple.snap -->@@ -43,7 +43,6 @@ $ wt merge✅ Merged to main (1 commit, 1 file, +13)🔄 Removing worktree & branch...✅ Removed worktree & branch for fix-auth, changed directory to ../repo/-# Shell back in main```See [`wt merge`](#wt-merge-target) for all options.@@ -77,9 +76,9 @@ See [Shell Integration](#shell-integration) for details.Worktrunk is opinionated! It's not designed to be all things to all people. The choices optimize for agent workflows:-- Lots of short-lived worktrees- Trunk-based development-- CLI-based agents+- Lots of short-lived worktrees+- Terminal-based coding agents- Inner dev loops are local- Shell navigation- Commits are squashed into linear histories@@ -301,32 +300,36 @@ Options:**BEHAVIOR:**Switching to Existing Worktree:- - If worktree exists for branch, changes directory via shell integration- - No hooks run- - No branch creation++- If worktree exists for branch, changes directory via shell integration+- No hooks run+- No branch creationCreating 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++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++- Run after worktree creation, before success message+- Typically: npm install, cargo build, setup tasks+- Failures block the operation+- Skip with --no-verifypost-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++- 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:**@@ -353,6 +356,7 @@ wt switch --create temp --no-verify**SHORTCUTS:**Use '@' for current HEAD, '-' for previous, '^' for main:+```bashwt switch @ # Switch to current branch's worktreewt switch - # Switch to previous worktree@@ -461,34 +465,38 @@ Options:**BEHAVIOR:**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++- 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 nothingRemove 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++- 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 commandRemove Multiple Worktrees:- - When removing multiple, current worktree is removed last- - Prevents deleting directory you're currently in- - Each worktree must have clean working tree++- When removing multiple, current worktree is removed last+- Prevents deleting directory you're currently in+- Each worktree must have clean working tree**CLEANUP:**When removing a worktree (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)++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:**@@ -671,6 +679,7 @@ Enable AI-generated commit messages2. Configure a modelFor Claude:+```bashllm install llm-anthropicllm keys set anthropic@@ -679,6 +688,7 @@ Enable AI-generated commit messages```For OpenAI:+```bashllm keys set openai# Paste your API key from: https://platform.openai.com/api-keys