Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Refactor README for clarity and conciseness
Maximilian Roos398d507c45c6
diff --git a/README.md b/README.mdindex fadf41817..96700b8fd 100644--- a/README.md+++ b/README.md@@ -1,22 +1,20 @@# Worktrunk[](https://opensource.org/licenses/MIT)--Git worktree lifecycle automation. Built for running multiple AI coding agents without conflicts.--<!-- Add after publishing to crates.io:[](https://crates.io/crates/worktrunk)--->-Git worktrees let multiple agents work on one repo without colliding—each gets a separate directory sharing history. But creating worktrees, tracking paths, and cleaning up afterward is manual. Worktrunk automates the lifecycle: create, switch, clean up—your shell stays put.+Git worktree lifecycle automation, designed around running concurrent AI coding agents.-Running ten agents on different features? `wt switch --create feature-a`, `wt switch --create feature-b`, and they're isolated. Agent finishes? `wt remove feature-a` cleans up automatically. No path juggling, no stale directories.+Git worktrees let multiple agents work on one repo without colliding; each gets+a separate directory. But creating worktrees, tracking paths, and cleaning up+afterward is manual. Worktrunk automates that lifecycle.## What It DoesAutomates the full lifecycle: create worktree, work, merge back, remove worktree.<!-- Output generated from: tests/snapshots/integration__integration_tests__merge__readme_example_simple.snap -->+```bash$ wt switch --create fix-auth# Shell now in ../repo.fix-auth/@@ -36,8 +34,6 @@ $ wt merge# Shell back in main```-Shell integration means directories change automatically. Merge handles staging, committing, merging, pushing, cleanup. One command.-## Installation```bash@@ -48,16 +44,19 @@ wt config shell # Sets up shell integration## Three Commands**Create workspace:**+```bashwt switch --create feature-name```**Finish and merge:**+```bashwt merge```**See active worktrees:**+```bashwt list```@@ -65,12 +64,14 @@ wt list## Automation Features**LLM commits** - AI generates merge commits from diff and history:+```bashwt mergewt config help # Setup guide```**Project hooks** - Auto-run tests, install deps:+```toml# .config/wt.toml[pre-merge-command]@@ -100,6 +101,7 @@ These trade manual control for automation. For fine-grained control, use `git wo- `wt config` - Manage configuration**Shortcut:** Use `@` to refer to your current HEAD (following git's convention):+```bashwt switch @ # Switch to current branch's worktreewt switch --create new-feature --base=@ # Branch from current HEAD@@ -115,26 +117,26 @@ The Status column shows git repository state using compact symbols. Symbol order**Symbol order:** `= ≡∅ ↻⋈ ◇⊠⚠ ↑↓ ⇡⇣ ?!+»✘`-| Symbol | Meaning | Category | Dimmed? |-|--------|---------|----------|---------|-| `·` | Branch without worktree | N/A | No |-| `=` | Conflicts with main | Blocking | No |-| `≡` | Working tree matches main (identical to main branch, regardless of commit history) | Worktree state | Yes |-| `∅` | No commits (no commits ahead AND no uncommitted changes) | Worktree state | Yes |-| `↻` | Rebase in progress | Git operation | No |-| `⋈` | Merge in progress | Git operation | No |-| `◇` | Bare worktree (no working directory) | Worktree attribute | No |-| `⊠` | Locked worktree | Worktree attribute | No |-| `⚠` | Prunable worktree | Worktree attribute | No |-| `↑` | Commits ahead of main | Branch divergence | No |-| `↓` | Commits behind main | Branch divergence | No |-| `⇡` | Commits ahead of remote | Remote divergence | No |-| `⇣` | Commits behind remote | Remote divergence | No |-| `?` | Untracked files | Working tree | No |-| `!` | Modified files (unstaged) | Working tree | No |-| `+` | Staged files | Working tree | No |-| `»` | Renamed files | Working tree | No |-| `✘` | Deleted files | Working tree | No |+| Symbol | Meaning | Category | Dimmed? |+| ------ | ---------------------------------------------------------------------------------- | ------------------ | ------- |+| `·` | Branch without worktree | N/A | No |+| `=` | Conflicts with main | Blocking | No |+| `≡` | Working tree matches main (identical to main branch, regardless of commit history) | Worktree state | Yes |+| `∅` | No commits (no commits ahead AND no uncommitted changes) | Worktree state | Yes |+| `↻` | Rebase in progress | Git operation | No |+| `⋈` | Merge in progress | Git operation | No |+| `◇` | Bare worktree (no working directory) | Worktree attribute | No |+| `⊠` | Locked worktree | Worktree attribute | No |+| `⚠` | Prunable worktree | Worktree attribute | No |+| `↑` | Commits ahead of main | Branch divergence | No |+| `↓` | Commits behind main | Branch divergence | No |+| `⇡` | Commits ahead of remote | Remote divergence | No |+| `⇣` | Commits behind remote | Remote divergence | No |+| `?` | Untracked files | Working tree | No |+| `!` | Modified files (unstaged) | Working tree | No |+| `+` | Staged files | Working tree | No |+| `»` | Renamed files | Working tree | No |+| `✘` | Deleted files | Working tree | No |Symbols combine to show complete state (e.g., `≡↓!` means matches main, behind main, and has unstaged changes).@@ -230,7 +232,9 @@ Recent commit style ({{ recent_commits | length }} commits):Changes to commit:```+{{ git_diff }}+```Requirements:@@ -274,12 +278,14 @@ squash-template-file = "~/.config/worktrunk/squash-template.jinja"**Available template variables:**Normal commits:+- `{{ git_diff }}` - Staged changes- `{{ branch }}` - Current branch name- `{{ recent_commits }}` - Array of recent commit messages (for style matching)- `{{ repo }}` - Repository nameSquash commits:+- `{{ commits }}` - Array of commit messages being squashed- `{{ target_branch }}` - Branch being merged into (e.g., "main")- `{{ branch }}` - Current branch name@@ -311,13 +317,13 @@ Automate common tasks by creating `.config/wt.toml` in your repository root. Run<details><summary>All available hooks</summary>-| Hook | When It Runs | Execution | Failure Behavior |-|------|--------------|-----------|------------------|-| **post-create-command** | After `git worktree add` completes | Sequential, blocking | Logs warning, continues with remaining commands |-| **post-start-command** | After post-create completes | Parallel, non-blocking (background processes) | Logs warning, doesn't affect switch result |-| **pre-commit-command** | Before committing changes during `wt merge` (both squash and no-squash modes) | Sequential, blocking, fail-fast | Terminates merge immediately |-| **pre-merge-command** | After rebase completes during `wt merge` (validates rebased state before push) | Sequential, blocking, fail-fast | Terminates merge immediately |-| **post-merge-command** | After successful merge and push to target branch, before cleanup | Sequential, blocking | Logs warning, continues with remaining commands |+| Hook | When It Runs | Execution | Failure Behavior |+| ----------------------- | ------------------------------------------------------------------------------ | --------------------------------------------- | ----------------------------------------------- |+| **post-create-command** | After `git worktree add` completes | Sequential, blocking | Logs warning, continues with remaining commands |+| **post-start-command** | After post-create completes | Parallel, non-blocking (background processes) | Logs warning, doesn't affect switch result |+| **pre-commit-command** | Before committing changes during `wt merge` (both squash and no-squash modes) | Sequential, blocking, fail-fast | Terminates merge immediately |+| **pre-merge-command** | After rebase completes during `wt merge` (validates rebased state before push) | Sequential, blocking, fail-fast | Terminates merge immediately |+| **post-merge-command** | After successful merge and push to target branch, before cleanup | Sequential, blocking | Logs warning, continues with remaining commands |**Template variables:** `{repo}`, `{branch}`, `{worktree}`, `{repo_root}`, `{target}`@@ -419,6 +425,7 @@ The custom emoji appears directly after the git status symbols.Claude Code can automatically set/clear emoji status when coding sessions start and end. This shows which branches have active AI sessions.**Easy setup:** Install the Worktrunk Claude Code plugin which includes these hooks automatically:+<!-- [Worktrunk Claude Code plugin](https://github.com/max-sixty/worktrunk) -->```bash@@ -468,6 +475,7 @@ git clone https://github.com/max-sixty/worktrunk.git worktrunk-skills```Now when you use Claude:+- Sets status to `🤖` for the current branch when you submit a prompt (working)- Changes to `💬` when Claude returns a response (ready for your input)- Clears the status completely when the session ends@@ -502,11 +510,13 @@ feature-x ↑!💬 +5 -2 ./myapp.feature-x/For true per-worktree isolation (different status for multiple worktrees on the same branch), use worktree-specific config:**One-time setup (enables per-worktree config for the repo):**+```bashgit config extensions.worktreeConfig true```**Set status from within a worktree:**+```bash# From within the worktreegit config --worktree worktrunk.status "🚧"@@ -516,6 +526,7 @@ git config --worktree --unset worktrunk.status```**Claude Code hooks for per-worktree:**+```json{"hooks": {@@ -586,46 +597,55 @@ This adds shell integration to your config files (supports Bash, Zsh, Fish, NushAdd one line to your shell config:**Bash** (`~/.bashrc`):+```basheval "$(wt init bash)"```**Fish** (`~/.config/fish/config.fish`):+```fishwt init fish | source```**Zsh** (`~/.zshrc`):+```basheval "$(wt init zsh)"```**Nushell** (`~/.config/nushell/env.nu`):+```nuwt init nushell | save -f ~/.cache/wt-init.nu```Then add to `~/.config/nushell/config.nu`:+```nusource ~/.cache/wt-init.nu```**PowerShell** (profile):+```powershellwt init powershell | Out-String | Invoke-Expression```**Elvish** (`~/.config/elvish/rc.elv`):+```elvisheval (wt init elvish | slurp)```**Xonsh** (`~/.xonshrc`):+```pythonexecx($(wt init xonsh))```**Oil Shell** (`~/.config/oil/oshrc`):+```basheval "$(wt init oil)"```