Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: clarify hooks, Claude Code, configuration, and merge operations
Maximilian Roosc7856ee38bf7
diff --git a/docs/content/claude-code.md b/docs/content/claude-code.mdindex d67b7ed32..b2be85b69 100644--- a/docs/content/claude-code.md+++ b/docs/content/claude-code.md@@ -6,7 +6,7 @@ weight = 23group = "Reference"+++-Worktrunk includes a Claude Code plugin for tracking agent status across worktrees.+Worktrunk includes a Claude Code plugin that automatically tracks which worktrees have active Claude sessions. When Claude starts working in a worktree, the plugin sets a status marker; when Claude waits for input, the marker updates. This makes it easy to monitor multiple parallel agents from `wt list`.## Status trackingdiff --git a/docs/content/config.md b/docs/content/config.mdindex 217a4f6f8..85a179907 100644--- a/docs/content/config.md+++ b/docs/content/config.md@@ -57,6 +57,17 @@ Personal settings like LLM commit generation, path templates, and default behaviProject-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](@/hooks.md) for details.+## Command approvals++Project hooks require approval on first run. Manage saved approvals with:++```bash+wt config approvals list # Show all approved commands+wt config approvals clear <repo> # Remove approvals for a repository+```++See [Hooks](@/hooks.md#security--approval) for how approvals work.+## LLM commit messagesWorktrunk can generate commit messages using an LLM. Enable in user config:diff --git a/docs/content/configuration.md b/docs/content/configuration.mdindex 0c5cc3339..58921e99a 100644--- a/docs/content/configuration.md+++ b/docs/content/configuration.md@@ -13,6 +13,10 @@ Worktrunk uses two configuration files:| **User config** | `~/.config/worktrunk/config.toml` | Personal settings, command defaults, approved project commands || **Project config** | `.config/wt.toml` | Lifecycle hooks, checked into version control |+## Shell integration++Worktrunk needs shell integration to change directories when switching worktrees. Install with `wt config shell install`. See [wt config](@/config.md#shell-integration) for manual installation options.+## User configThe user config stores personal preferences that apply across all repositories. Create it with:@@ -81,9 +85,15 @@ Configure automatic commit message generation. Requires an external tool like [l[commit-generation]command = "llm"args = ["-m", "claude-haiku-4.5"]++# Optional: custom prompt templates (inline or from files)+template = "Write a commit message for: {{ git_diff }}"+squash-template = "Summarize these commits: {{ commits }}"+template-file = "~/.config/worktrunk/commit.txt"+squash-template-file = "~/.config/worktrunk/squash.txt"```-See [LLM Commit Messages](@/llm-commits.md) for setup details and template customization.+See [LLM Commit Messages](@/llm-commits.md) for setup details and template variables.### Approved commands@@ -99,6 +109,10 @@ approved-commands = [Manage approvals with `wt config approvals list` and `wt config approvals clear <repo>`.+### Statusline++`wt list statusline` outputs a compact single-line status for shell prompts or editor statuslines. See [Claude Code Integration](@/claude-code.md#statusline) for Claude Code configuration.+## Project configThe project config defines lifecycle hooks — commands that run at specific points during worktree operations. This file is checked into version control and shared across the team.@@ -116,26 +130,6 @@ lint = "npm run lint"See [Hooks](@/hooks.md) for complete documentation on hook types, execution order, and template variables.-## Shell integration--Worktrunk needs shell integration to change directories when switching worktrees. Install with:--```bash-wt config shell install-```--Or manually add to the shell config:--```bash-# bash/zsh-eval "$(wt config shell init bash)"--# fish-wt config shell init fish | source-```--Without shell integration, `wt switch` prints the target directory but cannot `cd` into it.-## Environment variablesAll user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.diff --git a/docs/content/faq.md b/docs/content/faq.mdindex 3be2fd952..9728376c5 100644--- a/docs/content/faq.md+++ b/docs/content/faq.md@@ -43,7 +43,7 @@ Use `--force` to bypass prompts (useful for CI/automation).### vs. branch switching-Branch switching uses one directory, so only one agent can work at a time. Worktrees give each agent its own directory.+Branch switching uses one directory: uncommitted changes from one agent get mixed with the next agent's work, or block switching entirely. Worktrees give each agent its own directory with independent files and index.### vs. Plain `git worktree`@@ -88,6 +88,15 @@ These tools can be used together—run git-machete or git-town inside individualGit TUIs operate on a single repository. Worktrunk manages multiple worktrees, runs automation hooks, and aggregates status across branches. TUIs work inside each worktree directory.+## How does wt switch resolve branch names?++Arguments resolve by checking the filesystem before git branches:++1. Compute expected path from argument (using configured path template)+2. If worktree exists at that path, switch to it+3. Otherwise, look up as branch name+4. If the path and branch resolve to different worktrees (e.g., `repo.foo/` tracks branch `bar`), the path takes precedence+## Installation fails with C compilation errorsErrors related to tree-sitter or C compilation (C99 mode, `le16toh` undefined) can be avoided by installing without syntax highlighting:@@ -110,13 +119,12 @@ This disables bash syntax highlighting in command output but keeps all core func### Quick tests```bash-$ cargo test --lib --bins # Unit tests (~200 tests)-$ cargo test --test integration # Integration tests (~300 tests)+$ cargo test```### Full integration tests-Requires bash, zsh, and fish:+Shell integration tests require bash, zsh, and fish:```bash$ cargo test --test integration --features shell-integration-testsdiff --git a/docs/content/select.md b/docs/content/select.mdindex fe4b5edfe..c632e930c 100644--- a/docs/content/select.md+++ b/docs/content/select.md@@ -24,9 +24,9 @@ wt selectToggle between views with number keys:-1. **HEAD±** — Uncommitted changes+1. **HEAD±** — Diff of uncommitted changes2. **history** — Recent commits on the branch-3. **main…±** — Changes relative to main branch+3. **main…±** — Diff of all changes vs main branch## Keybindingsdiff --git a/docs/content/step.md b/docs/content/step.mdindex 7e1b611f5..2978f7ea8 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -45,8 +45,8 @@ wt step push**Hooks** — run project commands defined in [`.config/wt.toml`](@/hooks.md):-- `post-create` — After worktree creation-- `post-start` — After switching to a worktree+- `post-create` — After worktree creation (blocking)+- `post-start` — After worktree creation (background)- `pre-commit` — Before committing- `pre-merge` — Before pushing to target- `post-merge` — After merge cleanupdiff --git a/docs/content/switch.md b/docs/content/switch.mdindex 2fe50e6c9..8e368eb62 100644--- a/docs/content/switch.md+++ b/docs/content/switch.md@@ -43,11 +43,11 @@ wt switch --create temp --no-verify # Skip hooks## Shortcuts-| Symbol | Meaning |-|--------|---------|-| `-` | Previous worktree |-| `@` | Current branch's worktree |-| `^` | Default branch worktree |+| Shortcut | Meaning |+|----------|---------|+| `^` | Default branch (main/master) |+| `@` | Current branch/worktree |+| `-` | Previous worktree (like `cd -`) |```bashwt switch - # Back to previous@@ -55,18 +55,6 @@ wt switch ^ # Main worktreewt switch --create fix --base=@ # Branch from current HEAD```-## Path-first lookup--Arguments resolve by checking the filesystem before git branches:--1. Compute expected path from argument (using configured path template)-2. If worktree exists at that path, switch to it-3. Otherwise, treat argument as branch name--**Edge case**: If `repo.foo/` exists but tracks branch `bar`:-- `wt switch foo` → switches to `repo.foo/` (the `bar` worktree)-- `wt switch bar` → also works (branch lookup finds same worktree)-## See also- [wt select](@/select.md) — Interactive worktree selectiondiff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex 0c790b5c1..2c7c6fe67 100644--- a/docs/content/tips-patterns.md+++ b/docs/content/tips-patterns.md@@ -97,9 +97,9 @@ Special arguments work across all commands:| Shortcut | Meaning ||----------|---------|-| `^` | default branch (main/master) |-| `@` | current branch/worktree |-| `-` | previous worktree (like `cd -`) |+| `^` | Default branch (main/master) |+| `@` | Current branch/worktree |+| `-` | Previous worktree (like `cd -`) |Examples:diff --git a/docs/content/why-worktrunk.md b/docs/content/why-worktrunk.mdindex 9f1a5560f..6a4f35730 100644--- a/docs/content/why-worktrunk.md+++ b/docs/content/why-worktrunk.md@@ -105,9 +105,9 @@ $ wt config shell install## Next steps-- Learn the core commands: [wt switch](@/switch.md), [wt list](@/list.md), [wt remove](@/remove.md)+- Learn the core commands: [wt switch](@/switch.md), [wt list](@/list.md), [wt merge](@/merge.md), [wt remove](@/remove.md)- Set up [project hooks](@/hooks.md) for automated setup-- Explore [LLM commit messages](@/llm-commits.md), [local merging](@/merge.md), [fzf-like picker](@/select.md), [Claude Code integration](@/claude-code.md)+- Explore [LLM commit messages](@/llm-commits.md), [fzf-like picker](@/select.md), [Claude Code integration](@/claude-code.md)## Further readingdiff --git a/src/cli.rs b/src/cli.rsindex bf22b879f..9c3572ce5 100644--- a/src/cli.rs+++ b/src/cli.rs@@ -712,6 +712,17 @@ Personal settings like LLM commit generation, path templates, and default behaviProject-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](@/hooks.md) for details.+## Command approvals++Project hooks require approval on first run. Manage saved approvals with:++```console+wt config approvals list # Show all approved commands+wt config approvals clear <repo> # Remove approvals for a repository+```++See [Hooks](@/hooks.md#security--approval) for how approvals work.+## LLM commit messagesWorktrunk can generate commit messages using an LLM. Enable in user config:@@ -769,8 +780,8 @@ wt step push**Hooks** — run project commands defined in [`.config/wt.toml`](@/hooks.md):-- `post-create` — After worktree creation-- `post-start` — After switching to a worktree+- `post-create` — After worktree creation (blocking)+- `post-start` — After worktree creation (background)- `pre-commit` — Before committing- `pre-merge` — Before pushing to target- `post-merge` — After merge cleanup@@ -806,9 +817,9 @@ wt selectToggle between views with number keys:-1. **HEAD±** — Uncommitted changes+1. **HEAD±** — Diff of uncommitted changes2. **history** — Recent commits on the branch-3. **main…±** — Changes relative to main branch+3. **main…±** — Diff of all changes vs main branch## Keybindings@@ -1025,11 +1036,11 @@ wt switch --create temp --no-verify # Skip hooks## Shortcuts-| Symbol | Meaning |-|--------|---------|-| `-` | Previous worktree |-| `@` | Current branch's worktree |-| `^` | Default branch worktree |+| Shortcut | Meaning |+|----------|---------|+| `^` | Default branch (main/master) |+| `@` | Current branch/worktree |+| `-` | Previous worktree (like `cd -`) |```consolewt switch - # Back to previous@@ -1037,18 +1048,6 @@ wt switch ^ # Main worktreewt switch --create fix --base=@ # Branch from current HEAD```-## Path-first lookup--Arguments resolve by checking the filesystem before git branches:--1. Compute expected path from argument (using configured path template)-2. If worktree exists at that path, switch to it-3. Otherwise, treat argument as branch name--**Edge case**: If `repo.foo/` exists but tracks branch `bar`:-- `wt switch foo` → switches to `repo.foo/` (the `bar` worktree)-- `wt switch bar` → also works (branch lookup finds same worktree)-## See also- [wt select](@/select.md) — Interactive worktree selectiondiff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snapindex 2800d846f..a043e22af 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap@@ -83,6 +83,15 @@ Personal settings like LLM commit generation, path templates, and default behaviProject-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See Hooks for details.+[32mCommand approvals[0m++Project hooks require approval on first run. Manage saved approvals with:++ [2mwt config approvals list # Show all approved commands[0m+ [2mwt config approvals clear <repo> # Remove approvals for a repository[0m++See Hooks for how approvals work.+[32mLLM commit messages[0mWorktrunk can generate commit messages using an LLM. Enable in user config:diff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snapindex ec0a1dde1..03dd97663 100644--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap@@ -76,8 +76,8 @@ Manual merge workflow with review between steps:[1mHooks[0m — run project commands defined in `.config/wt.toml`:-- [2mpost-create[0m — After worktree creation-- [2mpost-start[0m — After switching to a worktree+- [2mpost-create[0m — After worktree creation (blocking)+- [2mpost-start[0m — After worktree creation (background)- [2mpre-commit[0m — Before committing- [2mpre-merge[0m — Before pushing to target- [2mpost-merge[0m — After merge cleanupdiff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex 54047cf4c..0bbd2521f 100644--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap@@ -96,28 +96,16 @@ With [2m--create[0m, worktrunk:[32mShortcuts[0m-| Symbol | Meaning |-|--------|---------|-| [2m-[0m | Previous worktree |-| [2m@[0m | Current branch's worktree |-| [2m^[0m | Default branch worktree |+| Shortcut | Meaning |+|----------|---------|+| [2m^[0m | Default branch (main/master) |+| [2m@[0m | Current branch/worktree |+| [2m-[0m | Previous worktree (like [2mcd -[0m) |[2mwt switch - # Back to previous[0m[2mwt switch ^ # Main worktree[0m[2mwt switch --create fix --base=@ # Branch from current HEAD[0m-[32mPath-first lookup[0m--Arguments resolve by checking the filesystem before git branches:--1. Compute expected path from argument (using configured path template)-2. If worktree exists at that path, switch to it-3. Otherwise, treat argument as branch name--[1mEdge case[0m: If [2mrepo.foo/[0m exists but tracks branch [2mbar[0m:-- [2mwt switch foo[0m → switches to [2mrepo.foo/[0m (the [2mbar[0m worktree)-- [2mwt switch bar[0m → also works (branch lookup finds same worktree)-[32mSee also[0m- wt select — Interactive worktree selection