Skip to content

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

feat: Improve README content and structure

Maximilian Roosdb20e700743c
diff --git a/.claude-plugin/hooks/hooks.worktree.json b/.claude-plugin/hooks/hooks.worktree.json
new file mode 100644
index 000000000..efbe9437a
--- /dev/null
+++ b/.claude-plugin/hooks/hooks.worktree.json
@@ -0,0 +1,25 @@
+{
+ "hooks": {
+ "UserPromptSubmit": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "git rev-parse --is-inside-work-tree >/dev/null 2>&1 && git config extensions.worktreeConfig true 2>/dev/null; git config --worktree worktrunk.status πŸ€– 2>/dev/null || true"
+ }
+ ]
+ }
+ ],
+ "Stop": [
+ {
+ "matcher": "",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "git config --worktree --unset worktrunk.status 2>/dev/null || true"
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/README.md b/README.md
index e0c3c4543..f5c7c78d8 100644
--- a/README.md
+++ b/README.md
@@ -3,22 +3,32 @@
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Crates.io](https://img.shields.io/crates/v/worktrunk.svg)](https://crates.io/crates/worktrunk)
-Git worktree lifecycle automation, designed around running concurrent AI coding agents.
+Worktrunk is a CLI tool to make working with git worktrees much much easier.
+It's designed for those running concurrent AI coding agents.
-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.
+Git worktrees let multiple agents work on one repo without colliding; each agent
+gets a separate directory. But creating worktrees, tracking paths, and cleaning
+up afterward is manual. Worktrunk automates that lifecycle.
-## What It Does
+## Quick Start
-Automates the full lifecycle: create worktree, work, merge back, remove worktree.
+Worktrunk automates the full worktree lifecycle: create worktree, work, merge back, remove worktree.
+
+<!-- Output generated from:
+ Switch: tests/snapshots/integration__integration_tests__merge__readme_example_simple_switch.snap
+ Merge: tests/snapshots/integration__integration_tests__merge__readme_example_simple.snap
+ (snapshot output includes [SHA]/[REPO]; replace with representative values when copying into README) -->
+
+**Create a worktree:**
-<!-- Output generated from: tests/snapshots/integration__integration_tests__merge__readme_example_simple.snap (snapshot output includes [SHA]/[REPO]; replace with representative values when copying into README) -->
```bash
$ wt switch --create fix-auth
-# Shell now in ../repo.fix-auth/
+βœ… Created new worktree for fix-auth from main at ../repo.fix-auth/
+```
-# Agent works, makes changes, then:
+**Work on your changes, then merge back:**
+
+```bash
$ wt merge
πŸ”„ Merging 1 commit to main @ a1b2c3d (no commit/squash/rebase needed)
@@ -31,179 +41,58 @@ $ wt merge
# Shell back in main
```
-## Installation
+**See all active worktrees:**
```bash
-cargo install worktrunk
-wt config shell # Sets up shell integration
-```
-
-## Three Commands
-
-**Create workspace:**
-
-```bash
-wt switch --create feature-name
-```
-
-**Finish and merge:**
-
-```bash
-wt merge
+$ wt list
+Branch Status HEADΒ± main↕ Path
+main ./myapp/
+feature-x ↑! +5 -2 ↑3 ./myapp.feature-x/
+bugfix-y ↑ +0 -0 ↑1 ./myapp.bugfix-y/
```
-**See active worktrees:**
+## Installation
```bash
-wt list
+cargo install worktrunk
+wt config shell # Sets up shell integration
```
## Automation Features
-**LLM commits** - AI generates merge commits from diff and history:
-
-```bash
-wt merge
-wt config help # Setup guide
-```
-
-**Project hooks** - Auto-run tests, install deps:
-
-```toml
-# .config/wt.toml
-[pre-merge-command]
-"test" = "npm test"
-```
-
-**Shell integration** - Bash, Zsh, Fish, Nushell, PowerShell, Elvish, Xonsh, Oil.
-
-## Design Philosophy
-
-Worktrunk is opinionated. The choices optimize for AI agent workflows:
-
-1. **Merge does everything** - Staging, committing all changes, merging, pushing, cleanup in one command
-2. **Squash by default** - Linear history, configurable
-3. **Automatic shell navigation** - No manual `cd` commands
-4. **Fail-fast hooks** - Tests block bad merges
-
-These trade manual control for automation. For fine-grained control, use `git worktree` directly.
-
-## All Commands
-
-- `wt switch [branch]` - Switch to existing worktree
-- `wt switch --create [branch]` - Create and switch (supports `--base=@` to branch from current HEAD)
-- `wt remove [branch]` - Remove worktree (use `@` for current)
-- `wt merge [target]` - Merge, push, cleanup
-- `wt list` - Show all worktrees
-- `wt config` - Manage configuration
-
-**Shortcut:** Use `@` to refer to your current HEAD (following git's convention):
-
-```bash
-wt switch @ # Switch to current branch's worktree
-wt switch --create new-feature --base=@ # Branch from current HEAD
-wt remove @ # Remove current worktree
-```
-
-See `wt --help` for details.
-
-<details>
-<summary>Status column symbols in <code>wt list</code></summary>
-
-The Status column shows git repository state using compact symbols. Symbol order indicates priority: conflicts (blocking) β†’ worktree state β†’ git operations β†’ branch divergence β†’ working tree changes.
-
-**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 |
-
-Symbols combine to show complete state (e.g., `≑↓!` means matches main, behind main, and has unstaged changes).
-
-**Dimming logic:** **Dimmed rows** indicate worktrees with no marginal information beyond main (no unique work). Lines dim when they have either `≑` (matches main) OR `βˆ…` (no commits). Both conditions use OR logic: either is sufficient to dim. This focuses attention on worktrees containing work.
-
-**Branch-only entries:** Branches without worktrees show `Β·` in the Status column, indicating git status is not applicable (no working directory to check).
-
-</details>
-
-## Configuration
+### LLM-Powered Commit Messages
-```bash
-wt config list # Show all config files and locations
-wt config init # Create global config with examples
-wt config help # Show LLM setup guide
-```
+During merge operations, worktrunk can generate commit messages using an LLM. The LLM analyzes the staged diff and recent commit history to write messages matching the project's style.
-<details>
-<summary>Configuration details</summary>
+<!-- Config and output from: tests/snapshots/integration__integration_tests__merge__readme_example_complex.snap (uses mock llm) -->
-Global config at `~/.config/worktrunk/config.toml`:
+Add to `~/.config/worktrunk/config.toml`:
```toml
-worktree-path = "../{main-worktree}.{branch}"
-
[commit-generation]
command = "llm"
args = ["-m", "claude-haiku-4-5-20251001"]
```
-Project config at `.config/wt.toml` in the repository root (see Project Automation above).
-
-Worktree path defaults: `../repo.branch/` (siblings to main repo). Variables: `{main-worktree}`, `{branch}`, `{repo}`.
-
-</details>
-
-## Advanced Features
-
-### LLM-Powered Commit Messages
-
-During merge operations, worktrunk can generate commit messages using an LLM. The LLM analyzes the staged diff and recent commit history to write messages matching the project's style.
+Then `wt merge` will generate commit messages automatically:
```bash
-# Merge with LLM-generated commit message (squashes by default)
$ wt merge
+πŸ”„ Generating squash commit message...
+ feat(auth): Implement JWT authentication system
-# Merge without squashing commits
-$ wt merge --no-squash
+ Add comprehensive JWT token handling including validation, refresh logic,
+ and authentication tests. This establishes the foundation for secure
+ API authentication.
-# Merge to a specific target branch
-$ wt merge staging
+ - Implement token refresh mechanism with expiry handling
+ - Add JWT encoding/decoding with signature verification
+ - Create test suite covering all authentication flows
+βœ… Squashed @ a1b2c3d
```
Set up LLM integration: `wt config help` shows the setup guide, `wt config init` creates example config.
-<details>
-<summary>Manual configuration</summary>
-
-Edit `~/.config/worktrunk/config.toml`:
-
-```toml
-[commit-generation]
-command = "llm" # or "claude", "gpt", etc.
-args = ["-m", "claude-haiku-4-5-20251001"]
-```
-
-If the LLM is unavailable or fails, worktrunk falls back to a deterministic message.
-
-</details>
-
<details>
<summary><b>Advanced: Custom Prompt Templates</b></summary>
@@ -292,23 +181,83 @@ See the [minijinja template documentation](https://docs.rs/minijinja/latest/mini
</details>
-### Project Automation
+### Project Hooks
Automate common tasks by creating `.config/wt.toml` in your repository root. Run tests before merging, install dependencies when creating worktrees, start dev servers automatically.
```toml
# Install deps when creating a worktree
[post-create-command]
-"install" = "npm install --frozen-lockfile"
+"install" = "uv sync"
# Start dev server automatically
[post-start-command]
-"dev" = "npm run dev"
+"dev" = "uv run dev"
# Run tests before merging
[pre-merge-command]
-"test" = "npm test"
-"lint" = "npm run lint"
+"test" = "uv run pytest"
+"lint" = "uv run ruff check"
+```
+
+**Example: Creating a worktree with hooks:**
+
+```bash
+$ wt switch --create feature-x
+πŸ”„ Creating worktree for feature-x...
+βœ… Created worktree, changed directory to ../repo.feature-x/
+πŸ”„ Running post-create install:
+ uv sync
+
+ Resolved 24 packages in 145ms
+ Installed 24 packages in 1.2s
+
+πŸ”„ Running post-start dev (background):
+ uv run dev
+
+ Starting dev server on http://localhost:3000...
+```
+
+**Example: Merging with pre-merge hooks:**
+
+```bash
+$ wt merge
+πŸ”„ Squashing 3 commits into 1 (2 files, +45)...
+πŸ”„ Generating squash commit message...
+ feat(api): Add user authentication endpoints
+
+ Implement login and token refresh endpoints with JWT validation.
+ Includes comprehensive test coverage and input validation.
+βœ… Squashed @ a1b2c3d
+πŸ”„ Running pre-merge test:
+ uv run pytest
+
+ ============================= test session starts ==============================
+ collected 18 items
+
+ tests/test_auth.py::test_login_success PASSED [ 11%]
+ tests/test_auth.py::test_login_invalid_password PASSED [ 22%]
+ tests/test_auth.py::test_token_refresh PASSED [ 33%]
+ tests/test_auth.py::test_token_validation PASSED [ 44%]
+
+ ============================== 18 passed in 0.8s ===============================
+
+πŸ”„ Running pre-merge lint:
+ uv run ruff check
+
+ All checks passed!
+
+πŸ”„ Merging 1 commit to main @ a1b2c3d (no rebase needed)
+
+ * a1b2c3d (HEAD -> feature-auth) feat(api): Add user authentication endpoints
+
+ api/auth.py | 32 ++++++++++++++++++++++++++++++++
+ tests/test_auth.py | 13 +++++++++++++
+ 2 files changed, 45 insertions(+)
+
+βœ… Merged to main (1 commit, 2 files, +45)
+πŸ”„ Removing worktree & branch...
+βœ… Removed worktree & branch for feature-auth, returned to primary at ../repo/
```
<details>
@@ -328,68 +277,115 @@ Automate common tasks by creating `.config/wt.toml` in your repository root. Run
**Security:** Commands require approval on first run. Use `--force` to bypass.
-**Example output with hooks:**
+</details>
-<!-- Output generated from: tests/snapshots/integration__integration_tests__merge__readme_example_complex.snap (snapshot output includes [SHA]/[REPO]; replace with representative values when copying into README) -->
+## Design Philosophy
-```bash
-$ wt merge
-πŸ”„ Squashing 3 commits into 1 (3 files, +33)...
-πŸ”„ Generating squash commit message...
- feat(auth): Implement JWT authentication system
+Worktrunk is opinionated! It's not designed to be all things to all people. The choices optimize for agent workflows:
- Add comprehensive JWT token handling including validation, refresh logic,
- and authentication tests. This establishes the foundation for secure
- API authentication.
+- Lots of short-lived worktrees
+- CLI-based Agents
+- Local inner dev loops
+- Navigated using the shell
+- Commits are squashed, linear histories
+- Maximum automation
- - Implement token refresh mechanism with expiry handling
- - Add JWT encoding/decoding with signature verification
- - Create test suite covering all authentication flows
-βœ… Squashed @ a1b2c3d
-πŸ”„ Running pre-merge test:
- cargo test
+Standard `git worktree` commands continue working fine β€”Β adopting Worktrunk for a portion of a workflow doesn't require adopting it for everything.
- Finished test [unoptimized + debuginfo] target(s) in 0.12s
- Running unittests src/lib.rs (target/debug/deps/worktrunk-abc123)
+## All Commands
-running 18 tests
-test auth::tests::test_jwt_decode ... ok
-test auth::tests::test_jwt_encode ... ok
-test auth::tests::test_token_refresh ... ok
-test auth::tests::test_token_validation ... ok
+- `wt switch [branch]` - Switch to existing worktree
+- `wt switch --create [branch]` - Create and switch (supports `--base=@` to branch from current HEAD)
+- `wt remove [branch]` - Remove worktree (use `@` for current)
+- `wt merge [target]` - Merge, push, cleanup
+- `wt list` - Show all worktrees
+- `wt config` - Manage configuration
+- `wt beta` - Development and testing utilities (see below)
-test result: ok. 18 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.08s
+See `wt --help` for details.
-πŸ”„ Running pre-merge lint:
- cargo clippy
+<details>
+<summary>Beta commands (<code>wt beta</code>)</summary>
- Checking worktrunk v0.1.0
- Finished dev [unoptimized + debuginfo] target(s) in 1.23s
+Experimental commands for advanced workflows. These are subject to change.
-πŸ”„ Merging 1 commit to main @ a1b2c3d (no rebase needed)
+- `wt beta commit` - Commit changes with LLM-generated message
+- `wt beta squash [target]` - Squash commits with LLM-generated message
+- `wt beta push [target]` - Push changes to target branch (auto-stashes non-conflicting edits)
+- `wt beta rebase [target]` - Rebase current branch onto target
+- `wt beta ask-approvals` - Approve commands in project config
+- `wt beta run-hook <hook-type>` - Run a project hook for testing
+- `wt beta select` - Interactive worktree selector (Unix only)
- * a1b2c3d (HEAD -> feature-auth) feat(auth): Implement JWT authentication system
+**Note:** Beta commands may have breaking changes between releases.
- auth.rs | 8 ++++++++
- auth_test.rs | 17 +++++++++++++++++
- jwt.rs | 8 ++++++++
- 3 files changed, 33 insertions(+)
+</details>
-βœ… Merged to main (1 commit, 3 files, +33)
-πŸ”„ Removing worktree & branch...
-βœ… Removed worktree & branch for feature-auth, returned to primary at ../repo/
-πŸ”„ Running post-merge install:
- cargo install --path .
-
- Installing worktrunk v0.1.0
- Compiling worktrunk v0.1.0
- Finished release [optimized] target(s) in 2.34s
- Installing ~/.cargo/bin/wt
- Installed package `worktrunk v0.1.0` (executable `wt`)
+<details>
+<summary>Status column symbols in <code>wt list</code></summary>
+
+The Status column shows git repository state using compact symbols. Symbol order indicates priority: conflicts (blocking) β†’ worktree state β†’ git operations β†’ branch divergence β†’ working tree changes.
+
+**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 |
+
+Symbols combine to show complete state (e.g., `≑↓!` means matches main, behind main, and has unstaged changes).
+
+**Dimming logic:** **Dimmed rows** indicate worktrees with no marginal information beyond main (no unique work). Lines dim when they have either `≑` (matches main) OR `βˆ…` (no commits). Both conditions use OR logic: either is sufficient to dim. This focuses attention on worktrees containing work.
+
+**Branch-only entries:** Branches without worktrees show `Β·` in the Status column, indicating git status is not applicable (no working directory to check).
+
+</details>
+
+## Configuration
+
+```bash
+wt config list # Show all config files and locations
+wt config init # Create global config with examples
+wt config help # Show LLM setup guide
+```
+
+<details>
+<summary>Configuration details</summary>
+
+Global config at `~/.config/worktrunk/config.toml`:
+
+```toml
+worktree-path = "../{main-worktree}.{branch}"
+
+[commit-generation]
+command = "llm"
+args = ["-m", "claude-haiku-4-5-20251001"]
```
+Project config at `.config/wt.toml` in the repository root (see Project Hooks above).
+
+Worktree path defaults: `../repo.branch/` (siblings to main repo). Variables: `{main-worktree}`, `{branch}`, `{repo}`.
+
</details>
+## Advanced Features
+
### Custom Worktree Status
Add emoji status markers to worktrees that appear in `wt list`. Perfect for tracking work-in-progress states, CI status, or team coordination.
@@ -406,11 +402,15 @@ git config --unset worktrunk.status.feature-x
**Status appears in the Status column:**
+<!-- Output from: tests/snapshots/integration__integration_tests__list__with_user_status.snap -->
+
```
-Branch Status Working Β± Main ↕ Path
-feature-a ≑↓!🚧 ↓2 ./feature-a/
-feature-b ↑!βœ… +2 -1 ↑1 ./feature-b/
-feature-c πŸ€– ./feature-c/
+Branch Status HEADΒ± main↕ Path Remoteβ‡… Commit Age Message
+main ./test-repo b834638e 10 months ago Initial commit
+clean-no-status ≑ ./clean-no-status b834638e 10 months ago Initial commit
+clean-with-status ≑ πŸ’¬ ./clean-with-status b834638e 10 months ago Initial commit
+dirty-no-status ! +1 -1 ./dirty-no-status b834638e 10 months ago Initial commit
+dirty-with-status ≑?πŸ€– ./dirty-with-status b834638e 10 months ago Initial commit
```
The custom emoji appears directly after the git status symbols.
@@ -420,55 +420,9 @@ 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) -->
+**Easy setup:** The Worktrunk repository includes a `.claude-plugin` directory with pre-configured hooks. If you're working in this repository, the hooks are automatically available.
-```bash
-cd ~/.claude/plugins/marketplaces
-git clone https://github.com/max-sixty/worktrunk.git worktrunk-skills
-```
-
-**Manual setup:** Alternatively, add to `~/.claude/settings.json`:
-
-```json
-{
- "hooks": {
- "UserPromptSubmit": [
- {
- "hooks": [
- {
- "type": "command",
- "command": "git branch --show-current 2>/dev/null | xargs -I {} git config worktrunk.status.{} πŸ€–"
- }
- ]
- }
- ],
- "Notification": [
- {
- "matcher": "",
- "hooks": [
- {
- "type": "command",
- "command": "git branch --show-current 2>/dev/null | xargs -I {} git config worktrunk.status.{} πŸ’¬"
- }
- ]
- }
- ],
- "SessionEnd": [
- {
- "matcher": "",
- "hooks": [
- {
- "type": "command",
- "command": "git branch --show-current 2>/dev/null | xargs -I {} git config --unset worktrunk.status.{} 2>/dev/null || true"
- }
- ]
- }
- ]
- }
-}
-```
+**Manual setup for other repositories:** Copy the hooks from [`.claude-plugin/hooks/hooks.json`](.claude-plugin/hooks/hooks.json) to your `~/.claude/settings.json`.
Now when you use Claude:
@@ -478,18 +432,13 @@ Now when you use Claude:
**Status from other terminal:**
-```bash
-# While Claude is working
-$ wt list
-Branch Status Working Β± Path
-main ./myapp/
-feature-x ↑!πŸ€– +5 -2 ./myapp.feature-x/
+<!-- from tests/snapshots/integration__integration_tests__list__with_user_status.snap -->
-# When Claude needs your input (permission or idle)
+```bash
$ wt list
-Branch Status Working Β± Path
-main ./myapp/
-feature-x ↑!πŸ’¬ +5 -2 ./myapp.feature-x/
+Branch Status HEADΒ± main↕ Path
+main ./myapp/
+dirty-with-status ≑?πŸ€– ./myapp.dirty-with-status/
```
**How it works:**
@@ -523,33 +472,7 @@ git config --worktree --unset worktrunk.status
**Claude Code hooks for per-worktree:**
-```json
-{
- "hooks": {
- "UserPromptSubmit": [
- {
- "hooks": [
- {
- "type": "command",
- "command": "git rev-parse --is-inside-work-tree >/dev/null 2>&1 && git config extensions.worktreeConfig true 2>/dev/null; git config --worktree worktrunk.status πŸ€– 2>/dev/null || true"
- }
- ]
- }
- ],
- "Stop": [
- {
- "matcher": "",
- "hooks": [
- {
- "type": "command",
- "command": "git config --worktree --unset worktrunk.status 2>/dev/null || true"
- }
- ]
- }
- ]
- }
-}
-```
+Copy the hooks from [`.claude-plugin/hooks/hooks.worktree.json`](.claude-plugin/hooks/hooks.worktree.json) to your `~/.claude/settings.json`.
**Priority:** Worktree-specific config takes precedence over branch-keyed config when both exist.
@@ -577,9 +500,9 @@ worktree-path = ".worktrees/{branch}"
worktree-path = "../worktrees/{main-worktree}/{branch}"
```
-### Shell Integration Details
+### Shell Integration
-Worktrunk automatically configures your shell:
+Worktrunk can automatically configure your shell:
```bash
wt config shell
@@ -587,66 +510,7 @@ wt config shell
This adds shell integration to your config files (supports Bash, Zsh, Fish, Nushell, PowerShell, Elvish, Xonsh, Oil). The integration enables `wt switch` to change directories and `wt remove` to return to the previous location.
-<details>
-<summary>Manual setup (if you prefer)</summary>
-
-Add one line to your shell config:
-
-**Bash** (`~/.bashrc`):
-
-```bash
-eval "$(wt init bash)"
-```
-
-**Fish** (`~/.config/fish/config.fish`):
-
-```fish
-wt init fish | source
-```
-
-**Zsh** (`~/.zshrc`):
-
-```bash
-eval "$(wt init zsh)"
-```
-
-**Nushell** (`~/.config/nushell/env.nu`):
-
-```nu
-wt init nushell | save -f ~/.cache/wt-init.nu
-```
-
-Then add to `~/.config/nushell/config.nu`:
-
-```nu
-source ~/.cache/wt-init.nu
-```
-
-**PowerShell** (profile):
-
-```powershell
-wt init powershell | Out-String | Invoke-Expression
-```
-
-**Elvish** (`~/.config/elvish/rc.elv`):
-
-```elvish
-eval (wt init elvish | slurp)
-```
-
-**Xonsh** (`~/.xonshrc`):
-
-```python
-execx($(wt init xonsh))
-```
-
-**Oil Shell** (`~/.config/oil/oshrc`):
-
-```bash
-eval "$(wt init oil)"
-```
-
-</details>
+For manual setup instructions, see `wt config shell --help`.
## Status
diff --git a/src/cli.rs b/src/cli.rs
index 74e2854f1..b00497a86 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -55,6 +55,44 @@ pub enum ConfigCommand {
/// Refresh the cached default branch by querying the remote
RefreshCache,
/// Configure shell by writing to config files
+ #[command(long_about = r#"Configure shell by writing to config files
+
+This command automatically adds the appropriate integration line to your shell's config file.
+It supports Bash, Zsh, Fish, Nushell, PowerShell, Elvish, Xonsh, and Oil.
+
+The integration enables 'wt switch' to change directories and 'wt remove' to return to the
+previous location.
+
+MANUAL SETUP (if you prefer):
+
+Add one line to your shell config:
+
+Bash (~/.bashrc):
+ eval "$(wt init bash)"
+
+Fish (~/.config/fish/config.fish):
+ wt init fish | source
+
+Zsh (~/.zshrc):
+ eval "$(wt init zsh)"
+
+Nushell (~/.config/nushell/env.nu):
+ wt init nushell | save -f ~/.cache/wt-init.nu
+
+Then add to ~/.config/nushell/config.nu:
+ source ~/.cache/wt-init.nu
+
+PowerShell (profile):
+ wt init powershell | Out-String | Invoke-Expression
+
+Elvish (~/.config/elvish/rc.elv):
+ eval (wt init elvish | slurp)
+
+Xonsh (~/.xonshrc):
+ execx($(wt init xonsh))
+
+Oil Shell (~/.config/oil/oshrc):
+ eval "$(wt init oil)""#)]
Shell {
/// Specific shell to configure (default: all shells with existing config files)
#[arg(long, value_enum)]
@@ -274,7 +312,14 @@ Create and run command:
wt switch --create docs --execute "code ."
Skip hooks during creation:
- wt switch --create temp --no-verify"#)]
+ wt switch --create temp --no-verify
+
+SHORTCUTS:
+
+Use '@' to refer to your current HEAD (following git's convention):
+ wt switch @ # Switch to current branch's worktree
+ wt switch --create new-feature --base=@ # Branch from current HEAD
+ wt remove @ # Remove current worktree"#)]
Switch {
/// Branch name, worktree path, '@' for current HEAD, or '-' for previous branch
branch: String,
diff --git a/tests/integration_tests/list.rs b/tests/integration_tests/list.rs
index 50a7c3c56..a2a43d606 100644
--- a/tests/integration_tests/list.rs
+++ b/tests/integration_tests/list.rs
@@ -555,7 +555,7 @@ fn test_list_with_user_status() {
// Set user status (emoji only, branch-keyed)
let mut cmd = Command::new("git");
repo.configure_git_cmd(&mut cmd);
- cmd.args(["config", "worktrunk.status.clean-with-status", "⏸️"])
+ cmd.args(["config", "worktrunk.status.clean-with-status", "πŸ’¬"])
.current_dir(repo.root_path())
.output()
.expect("Failed to set user status");
diff --git a/tests/integration_tests/merge.rs b/tests/integration_tests/merge.rs
index b02eacb48..9c47ac55b 100644
--- a/tests/integration_tests/merge.rs
+++ b/tests/integration_tests/merge.rs
@@ -1,10 +1,11 @@
use crate::common::{TestRepo, make_snapshot_cmd, setup_snapshot_settings};
use insta_cmd::assert_cmd_snapshot;
use std::fs;
+use std::path::Path;
use std::process::Command;
/// Helper to create snapshot with normalized paths
-fn snapshot_merge(test_name: &str, repo: &TestRepo, args: &[&str], cwd: Option<&std::path::Path>) {
+fn snapshot_merge(test_name: &str, repo: &TestRepo, args: &[&str], cwd: Option<&Path>) {
let settings = setup_snapshot_settings(repo);
settings.bind(|| {
let mut cmd = make_snapshot_cmd(repo, "merge", args, cwd);
@@ -12,6 +13,15 @@ fn snapshot_merge(test_name: &str, repo: &TestRepo, args: &[&str], cwd: Option<&
});
}
+/// Helper to snapshot switch command
+fn snapshot_switch(test_name: &str, repo: &TestRepo, args: &[&str], cwd: Option<&Path>) {
+ let settings = setup_snapshot_settings(repo);
+ settings.bind(|| {
+ let mut cmd = make_snapshot_cmd(repo, "switch", args, cwd);
+ assert_cmd_snapshot!(test_name, cmd);
+ });
+}
+
/// Helper to create snapshot with custom environment (for LLM testing)
fn snapshot_merge_with_env(
test_name: &str,
@@ -1615,24 +1625,28 @@ fn test_merge_no_remote() {
/// This demonstrates the basic "What It Does" flow - create worktree, make changes, merge back.
///
/// Output is used in README.md "What It Does" section.
-/// Source: tests/snapshots/integration__integration_tests__merge__readme_example_simple.snap
+/// Merge output: tests/snapshots/integration__integration_tests__merge__readme_example_simple.snap
+/// Switch output: tests/snapshots/integration__integration_tests__merge__readme_example_simple_switch.snap
#[test]
fn test_readme_example_simple() {
let mut repo = TestRepo::new();
repo.commit("Initial commit");
repo.setup_remote("main");
- // Create a worktree for main
- let main_wt = repo.root_path().parent().unwrap().join("test-repo.main-wt");
- let mut cmd = Command::new("git");
- repo.configure_git_cmd(&mut cmd);
- cmd.args(["worktree", "add", main_wt.to_str().unwrap(), "main"])
- .current_dir(repo.root_path())
- .output()
- .expect("Failed to add worktree");
+ // Snapshot the switch --create command (runs from bare repo)
+ snapshot_switch(
+ "readme_example_simple_switch",
+ &repo,
+ &["--create", "fix-auth"],
+ None,
+ );
- // Create a fix-auth worktree and make a commit
- let feature_wt = repo.add_worktree("fix-auth", "fix-auth");
+ // Get the created worktree path and make a commit
+ let feature_wt = repo
+ .root_path()
+ .parent()
+ .unwrap()
+ .join("test-repo.fix-auth");
let auth_rs = r#"// JWT validation utilities
pub struct JwtClaims {
pub sub: String,
@@ -1663,7 +1677,7 @@ pub fn refresh(refresh_token: &str) -> String {
.output()
.expect("Failed to commit");
- // Merge fix-auth into main
+ // Snapshot the merge command
snapshot_merge("readme_example_simple", &repo, &["main"], Some(&feature_wt));
}
diff --git a/tests/snapshots/integration__integration_tests__init__init_fish.snap b/tests/snapshots/integration__integration_tests__init__init_fish.snap
index ea9ecd71a..4cffebc00 100644
--- a/tests/snapshots/integration__integration_tests__init__init_fish.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_fish.snap
@@ -12,11 +12,10 @@ info:
GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
GIT_CONFIG_GLOBAL: /dev/null
GIT_CONFIG_SYSTEM: /dev/null
- GIT_EDITOR: ""
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpQUjOPT/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpmJ34gU/test-config.toml
---
success: true
exit_code: 0
@@ -232,7 +231,7 @@ xonsh\t''
zsh\t''"
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from shell" -s f -l force -d 'Skip confirmation prompt'
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from shell" -s v -l verbose -d 'Enable verbose output (show git commands and debug info)'
-complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from shell" -s h -l help -d 'Print help'
+complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from shell" -s h -l help -d 'Print help (see more with \'--help\')'
complete -c wt -n "__fish_wt_using_subcommand beta; and not __fish_seen_subcommand_from run-hook commit squash push rebase ask-approvals select" -s v -l verbose -d 'Enable verbose output (show git commands and debug info)'
complete -c wt -n "__fish_wt_using_subcommand beta; and not __fish_seen_subcommand_from run-hook commit squash push rebase ask-approvals select" -s h -l help -d 'Print help'
complete -c wt -n "__fish_wt_using_subcommand beta; and not __fish_seen_subcommand_from run-hook commit squash push rebase ask-approvals select" -f -a "run-hook" -d 'Run a project hook for testing'
diff --git a/tests/snapshots/integration__integration_tests__init__init_zsh.snap b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
index ee114d442..a4de7fd06 100644
--- a/tests/snapshots/integration__integration_tests__init__init_zsh.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
@@ -12,11 +12,10 @@ info:
GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
GIT_CONFIG_GLOBAL: /dev/null
GIT_CONFIG_SYSTEM: /dev/null
- GIT_EDITOR: ""
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpfdRKfo/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmp58Uw1Q/test-config.toml
---
success: true
exit_code: 0
@@ -235,8 +234,8 @@ _arguments "${_arguments_options[@]}" : \
'--force[Skip confirmation prompt]' \
'-v[Enable verbose output (show git commands and debug info)]' \
'--verbose[Enable verbose output (show git commands and debug info)]' \
-'-h[Print help]' \
-'--help[Print help]' \
+'-h[Print help (see more with '\''--help'\'')]' \
+'--help[Print help (see more with '\''--help'\'')]' \
&& ret=0
;;
esac
diff --git a/tests/snapshots/integration__integration_tests__list__with_user_status.snap b/tests/snapshots/integration__integration_tests__list__with_user_status.snap
index 5e25b6234..edde92069 100644
--- a/tests/snapshots/integration__integration_tests__list__with_user_status.snap
+++ b/tests/snapshots/integration__integration_tests__list__with_user_status.snap
@@ -15,7 +15,7 @@ info:
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpzOVEyI/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmptopHjL/test-config.toml
---
success: true
exit_code: 0
@@ -23,7 +23,7 @@ exit_code: 0
Branch Status HEADΒ± main↕ Path Remoteβ‡… Commit Age Message
main ./test-repo b834638e 10 months ago Initial commit
clean-no-status ≑ ./clean-no-status b834638e 10 months ago Initial commit
-clean-with-status ≑ ⏸️ ./clean-with-status b834638e 10 months ago Initial commit
+clean-with-status ≑ πŸ’¬ ./clean-with-status b834638e 10 months ago Initial commit
dirty-no-status ! +1 -1 ./dirty-no-status b834638e 10 months ago Initial commit
dirty-with-status ≑?πŸ€– ./dirty-with-status b834638e 10 months ago Initial commit
diff --git a/tests/snapshots/integration__integration_tests__merge__readme_example_simple_switch.snap b/tests/snapshots/integration__integration_tests__merge__readme_example_simple_switch.snap
new file mode 100644
index 000000000..68d2fe9a1
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__merge__readme_example_simple_switch.snap
@@ -0,0 +1,29 @@
+---
+source: tests/integration_tests/merge.rs
+info:
+ program: wt
+ args:
+ - switch
+ - "--create"
+ - fix-auth
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_ASKPASS: ""
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: /dev/null
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ LANG: C
+ LC_ALL: C
+ SOURCE_DATE_EPOCH: "1761609600"
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpltdI8S/test-config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+βœ… Created new worktree for fix-auth from main at [REPO].fix-auth
+πŸ’‘ To enable automatic cd, run: wt config shell
+
+----- stderr -----