Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Refactor: Update README for clarity and new features
Maximilian Roos6f64452a6351
diff --git a/README.md b/README.mdindex d2d32a9c7..a2adf908e 100644--- a/README.md+++ b/README.md@@ -1,42 +1,63 @@-# Worktrunk: Git Worktree Management+# Worktrunk-A Rust-based CLI tool for managing git worktrees with seamless shell integration.+Git worktrees solve a real problem: working on multiple branches without stashing or switching contexts. But the vanilla `git worktree` command is cumbersome. Worktrunk makes worktrees fast and seamless.-## Features+## What It Does-- **Shell Integration**: Automatically `cd` to worktrees when switching-- **Multiple Shells**: Supports Bash, Fish, Zsh, Nushell, PowerShell, Elvish, Xonsh, and Oil Shell-- **Customizable**: Configure command prefix-- **Fast**: Built in Rust for performance-- **Clean Design**: Uses the proven "eval init" pattern from tools like zoxide and starship+Worktrunk wraps git worktrees with shell integration that makes them feel native. Switching to a worktree automatically changes the shell directory. The `wt remove` command returns to the original location.++```bash+# Create and switch to a new worktree in one command+$ wt switch --create fix-auth-bug+✅ Created fix-auth-bug+ Path: /Users/you/projects/myapp.fix-auth-bug++# Your shell is already in the new worktree+$ pwd+/Users/you/projects/myapp.fix-auth-bug++# When done, remove the worktree and return to primary+$ wt remove+✅ Removed worktree: fix-auth-bug+ Returned to: /Users/you/projects/myapp+```++## Why Worktrees Matter++Traditional git workflows present painful tradeoffs:+- Stash work and switch branches (lose environment state)+- Make hasty commits just to check something else+- Clone the repo multiple times (waste disk space, create sync issues)++Worktrees enable multiple branches checked out simultaneously. Each worktree is an independent working directory sharing the same git history. Git's native interface for managing them is verbose and requires manual directory navigation.++Worktrunk provides shell integration that makes `wt switch` actually change directories. No manual `cd` commands or path tracking required.## Installation```bashcargo build --release-# Copy target/release/wt to a directory in your PATH+# Copy target/release/wt to somewhere in your PATH```-## Setup--One-command setup that includes shell integration and completions:+Shell integration requires adding one line to your shell config:-**Bash** - Add to `~/.bashrc`:+**Bash** (`~/.bashrc`):```basheval "$(wt init bash)"```-**Fish** - Add to `~/.config/fish/config.fish`:+**Fish** (`~/.config/fish/config.fish`):```fishwt init fish | source```-**Zsh** - Add to `~/.zshrc`:+**Zsh** (`~/.zshrc`):```basheval "$(wt init zsh)"```-**Nushell** - Add to `~/.config/nushell/env.nu`:+**Nushell** (`~/.config/nushell/env.nu`):```nuwt init nushell | save -f ~/.cache/wt-init.nu```@@ -46,164 +67,188 @@ Then add to `~/.config/nushell/config.nu`:source ~/.cache/wt-init.nu```-**PowerShell** - Add to your PowerShell profile:+**PowerShell** (profile):```powershellwt init powershell | Out-String | Invoke-Expression```-**Elvish** - Add to `~/.config/elvish/rc.elv`:+**Elvish** (`~/.config/elvish/rc.elv`):```elvisheval (wt init elvish | slurp)```-**Xonsh** - Add to `~/.xonshrc`:+**Xonsh** (`~/.xonshrc`):```pythonexecx($(wt init xonsh))```-**Oil Shell** - Add to `~/.config/oil/oshrc`:+**Oil Shell** (`~/.config/oil/oshrc`):```basheval "$(wt init oil)"```-This single command provides:-- Shell integration for automatic `cd` on `wt switch` and `wt remove`-- TAB completion for commands, flags, and branch names (Bash, Fish, Zsh, Oil only)+## LLM-Powered Commit Messages-### What Gets Completed+Worktrunk can generate commit messages using an LLM during merge operations. The LLM analyzes the staged diff and recent commit history to write messages matching the project's style.-- **Subcommands**: `wt <TAB>` → shows `list`, `switch`, `remove`, `push`, `merge`-- **Flags**: `wt switch --<TAB>` → shows `--create`, `--base`, `--internal`-- **Branch names**: `wt switch <TAB>` → shows branches without worktrees-- **Target branches**: `wt push <TAB>` → shows all branches+```bash+# Merge with LLM-generated commit message+$ wt merge main --squash++# Provide custom guidance+$ wt merge main --squash -m "Focus on the authentication changes"+```-**Notes:**-- Completion is currently supported for Bash, Fish, Zsh, and Oil Shell only. Other shells (Nushell, PowerShell, Elvish, Xonsh) have shell integration but not yet completion.-- Zsh currently uses Bash-compatible completion syntax. Dynamic branch completion may require `bashcompinit`. For best results, use Fish or Bash.-- After updating `wt`, restart your shell or re-run the init command to get new completions-- Debug completion: Set `WT_DEBUG_COMPLETION=1` to see errors-- Performance: Run `cargo bench` to measure completion performance on your system+Configure the LLM command in `~/.config/worktrunk/config.toml`:-## Usage+```toml+[llm]+command = "llm" # or "claude", "gpt", etc.+args = ["-m", "claude-3-7-sonnet-20250219"]+```-### Basic Commands+The LLM receives the staged diff and recent commit messages, then generates a message following project conventions. If the LLM is unavailable or fails, worktrunk falls back to a deterministic message.-```bash-# List all worktrees-wt list+## Project Automation-# Switch to a worktree-wt switch feature-branch+Projects can define commands that run automatically when creating or switching to worktrees. Create `.config/wt.toml` in the repository root:-# Finish current worktree, returning to primary if current-wt remove+```toml+# Run sequentially after worktree creation (blocking)+[post-create-command]+"npm install" = "npm install --frozen-lockfile"+"build" = "npm run build"-# Push changes between worktrees-wt push target-worktree+# Run in parallel after switching (non-blocking)+[post-start-command]+"dev server" = "npm run dev"+"type check" = "npm run type-check -- --watch"-# Merge worktree into target branch-wt merge main+# Validation before merging (blocking, fail-fast)+[pre-merge-check]+"tests" = "npm test"+"lint" = "npm run lint"```-### Customization+Template variables expand at runtime:+- `{repo}` - Repository name+- `{branch}` - Current branch+- `{worktree}` - Absolute path to worktree+- `{repo_root}` - Absolute path to repository root+- `{target}` - Target branch (pre-merge-check only)-**Custom command prefix:**-```bash-# Use a custom prefix instead of 'wt'-eval "$(wt init bash --cmd myprefix)"+## Customization-# Now use: myprefix switch, myprefix remove, etc.-```+### Worktree Paths-## How It Works+By default, worktrees live as siblings to the main repo:-Worktrunk uses a **directive protocol** to communicate with shell wrappers:+```+myapp/ # primary worktree+myapp.feature-x/ # secondary worktree+myapp.bugfix-y/ # secondary worktree+```-1. Shell wrapper calls `wt switch --internal my-branch`-2. Worktrunk outputs special directives mixed with regular output:- ```- __WORKTRUNK_CD__/path/to/worktree- Switched to worktree: my-branch- ```-3. Shell wrapper parses output, executes `cd` for directives, displays other lines+Customize the pattern in `~/.config/worktrunk/config.toml`:-This separation keeps the Rust binary focused on git logic while letting the shell handle directory changes.+```toml+# Inside the repo (keeps everything contained)+worktree-path = ".worktrees/{branch}"-## Development & Testing+# Shared directory with multiple repos+worktree-path = "../worktrees/{main-worktree}/{branch}"+```-### Running Tests+### Fast Branch Switching-By default, tests only run for **Tier 1 shells** (bash, fish, zsh) which are easily available:+Push changes from the current worktree directly to another branch without committing or merging. Useful for moving work-in-progress code.```bash-cargo test+# Push current changes to another branch+$ wt push feature-experiment```-To run tests for **all shells** including Tier 2 shells (nushell, powershell, elvish, xonsh, oil):+Worktrunk stages the changes, creates a commit, and pushes it to the target branch's worktree if it exists.-```bash-cargo test --features tier-2-integration-tests-```+## How Shell Integration Works-**Important**: When the `tier-2-integration-tests` feature is enabled, **all tier-2 shells must be installed** or tests will fail. Tests will fail naturally when attempting to execute a missing shell.+Worktrunk uses a directive protocol. Running `wt switch --internal my-branch` outputs:-**Tier 2 shells** require additional installation:-- **nushell**: Install via [official instructions](https://www.nushell.sh/book/installation.html)-- **powershell**: `apt install powershell` (requires Microsoft repo on Linux)-- **elvish**: `apt install elvish` (Ubuntu 20.04+)-- **xonsh**: `apt install xonsh`-- **oil**: Must be compiled from source (see [Oil Shell docs](https://www.oilshell.org/release/0.24.0/doc/INSTALL.html))+```+__WORKTRUNK_CD__/path/to/worktree+Switched to worktree: my-branch+```-### CI/CD+The shell wrapper parses this output. Lines starting with `__WORKTRUNK_CD__` trigger directory changes. Other lines print normally. This separation keeps the Rust binary focused on git logic while the shell handles environment changes.-Two GitHub Actions workflows are provided:+This pattern is proven by tools like zoxide, starship, and direnv. The `--internal` flag is hidden from help output—end users never interact with it directly.-- **`ci.yml`**: Fast feedback with Tier 1 shells only (bash, fish, zsh)-- **`tier-2-integration-tests.yml`**: Comprehensive testing with all shells installed+## Commands-## Development Status+**List worktrees:**+```bash+wt list+wt list --branches # also show branches without worktrees+```-Current implementation:+**Switch or create:**+```bash+wt switch feature-branch+wt switch --create new-feature+wt switch --create new-feature --base develop+```-- ✅ Shell integration infrastructure (eval init pattern)-- ✅ Template-based shell code generation (Askama)-- ✅ Directive protocol (__WORKTRUNK_CD__)-- ✅ Basic CLI structure-- ⏳ Git primitives (coming next)-- ⏳ Worktree operations (coming next)-- ⏳ Advanced features (push, merge, etc.)+**Run command after switching:**+```bash+wt switch feature-x --execute "npm test" --force+```-## Architecture+**Remove current worktree:**+```bash+wt remove+```+**Push changes between worktrees:**+```bash+wt push target-branch+```++**Merge into another branch:**+```bash+wt merge main # merge commits as-is+wt merge main --squash # squash all commits+wt merge main --keep # keep worktree after merging+wt merge main -m "Custom message instruction"```-wt (Rust binary)-├── Core commands (work standalone)-│ ├── wt list-│ ├── wt push-│ └── wt merge-├── Internal commands (for shell wrapper)-│ ├── wt switch --internal → outputs __WORKTRUNK_CD__ directives-│ └── wt remove --internal → outputs __WORKTRUNK_CD__ directives-└── Shell integration- └── wt init <shell> → outputs shell wrapper function++## Configuration++Global config at `~/.config/worktrunk/config.toml`:++```toml+worktree-path = "../{main-worktree}.{branch}"++[llm]+command = "llm"+args = ["-m", "claude-3-7-sonnet-20250219"]```+Project config at `.config/wt.toml` in the repository root (see Project Automation above).+## Design Principles-- **Progressive Enhancement**: Works without shell integration, better with it-- **One Canonical Path**: No options, no configuration unless explicitly needed-- **Fast**: Keep shell integration code minimal (<500ms execution time)-- **Stateless**: Binary doesn't maintain state, shell handles environment+**Progressive Enhancement**: Works without shell integration. Better with it.-## Inspiration+**One Canonical Path**: No configuration flags for behavior that should just work. When there's a better way to do something, worktrunk does it that way by default.-Worktrunk's shell integration pattern is inspired by successful tools:+**Fast**: Shell integration overhead is minimal. The binary shells out to git but adds negligible latency.++**Stateless**: The binary maintains no state between invocations. Shell and git are the source of truth.++## Development Status-- **zoxide**: Smarter cd with frequency tracking-- **starship**: Cross-shell prompt customization-- **direnv**: Per-directory environment variables-- **pyenv**: Python version management with shims+This project is pre-release. Breaking changes are expected and acceptable. The best technical solution wins over backward compatibility.## License-MIT (or your preferred license)+MIT