Skip to content

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.md
index d67b7ed32..b2be85b69 100644
--- a/docs/content/claude-code.md
+++ b/docs/content/claude-code.md
@@ -6,7 +6,7 @@ weight = 23
group = "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 tracking
diff --git a/docs/content/config.md b/docs/content/config.md
index 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 behavi
Project-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 messages
Worktrunk can generate commit messages using an LLM. Enable in user config:
diff --git a/docs/content/configuration.md b/docs/content/configuration.md
index 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 config
The 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 config
The 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 variables
All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.
diff --git a/docs/content/faq.md b/docs/content/faq.md
index 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 individual
Git 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 errors
Errors 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-tests
diff --git a/docs/content/select.md b/docs/content/select.md
index fe4b5edfe..c632e930c 100644
--- a/docs/content/select.md
+++ b/docs/content/select.md
@@ -24,9 +24,9 @@ wt select
Toggle between views with number keys:
-1. **HEAD±** — Uncommitted changes
+1. **HEAD±** — Diff of uncommitted changes
2. **history** — Recent commits on the branch
-3. **main…±** — Changes relative to main branch
+3. **main…±** — Diff of all changes vs main branch
## Keybindings
diff --git a/docs/content/step.md b/docs/content/step.md
index 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 cleanup
diff --git a/docs/content/switch.md b/docs/content/switch.md
index 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 -`) |
```bash
wt switch - # Back to previous
@@ -55,18 +55,6 @@ wt switch ^ # Main worktree
wt 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 selection
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 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.md
index 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 reading
diff --git a/src/cli.rs b/src/cli.rs
index 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 behavi
Project-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 messages
Worktrunk 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 select
Toggle between views with number keys:
-1. **HEAD±** — Uncommitted changes
+1. **HEAD±** — Diff of uncommitted changes
2. **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 -`) |
```console
wt switch - # Back to previous
@@ -1037,18 +1048,6 @@ wt switch ^ # Main worktree
wt 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 selection
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 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 behavi
Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See Hooks for details.
+Command approvals
+
+Project hooks require approval on first run. Manage saved approvals with:
+
+ wt config approvals list # Show all approved commands
+ wt config approvals clear <repo> # Remove approvals for a repository
+
+See Hooks for how approvals work.
+
LLM commit messages
Worktrunk 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.snap
index 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:
Hooks — run project commands defined in `.config/wt.toml`:
-- 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
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index 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 --create, worktrunk:
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 -) |
wt switch - # Back to previous
wt switch ^ # Main worktree
wt 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 — Interactive worktree selection