Skip to content

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

docs: clarify configuration, hooks, branch cleanup, and LLM usage

Maximilian Roosb203be8de1c9
diff --git a/docs/content/claude-code.md b/docs/content/claude-code.md
index b2be85b69..76c4a37c6 100644
--- a/docs/content/claude-code.md
+++ b/docs/content/claude-code.md
@@ -49,7 +49,7 @@ $ git config worktrunk.marker.feature "💬" # Direct git config
## Statusline
-`wt list statusline --claude-code` outputs a single-line status for the Claude Code statusline (currently this grabs CI status, so is too slow to use in synchronous contexts—if a faster version would be helpful, please [open an issue](https://github.com/max-sixty/worktrunk/issues)):
+`wt list statusline --claude-code` outputs a single-line status for the Claude Code statusline. This fetches CI status from the network (1-2 seconds), making it suitable for async statuslines but too slow for synchronous shell prompts. If a faster version would be helpful, please [open an issue](https://github.com/max-sixty/worktrunk/issues).
<code>~/w/myproject.feature-auth !🤖 @<span style='color:#0a0'>+42</span> <span style='color:#a00'>-8</span> <span style='color:#0a0'>↑3</span> <span style='color:#0a0'>⇡1</span> <span style='color:#0a0'>●</span> | Opus</code>
diff --git a/docs/content/hooks.md b/docs/content/hooks.md
index f21740832..fdf0d7de9 100644
--- a/docs/content/hooks.md
+++ b/docs/content/hooks.md
@@ -23,7 +23,7 @@ Hooks automate setup and validation at worktree lifecycle events. They're define
## Configuration formats
-All hooks support two formats in `.config/wt.toml`:
+Hooks can be a single command or multiple named commands. All hooks support both formats in `.config/wt.toml`:
### Single command (string)
@@ -162,7 +162,7 @@ build = "cargo build --release"
### post-merge
-Runs after successful merge, **best-effort**. The merge has already completed, so failures are logged but don't abort.
+Runs after successful merge and cleanup, **best-effort**. The merge has already completed and the feature worktree has been removed, so failures are logged but don't abort.
**Use cases**: Deployment, notifications, installing updated binaries — post-merge automation.
@@ -171,9 +171,9 @@ post-merge = "cargo install --path ."
```
**Behavior**:
-- Commands run sequentially in the **main worktree** (not feature branch)
-- Runs after push succeeds, before cleanup
-- Failures show errors but cleanup proceeds
+- Commands run sequentially in the **main worktree**
+- Runs after cleanup completes
+- Failures show errors but don't affect the completed merge
## When hooks run during merge
@@ -371,10 +371,10 @@ fi
### Symlinks and caches
-Set up shared resources that shouldn't be duplicated:
+Set up shared resources that shouldn't be duplicated. The `{{ repo_root }}` variable points to the main worktree:
```toml
[post-create]
-cache = "ln -sf ../main-worktree/node_modules node_modules"
-env = "cp ../.env.local .env"
+cache = "ln -sf {{ repo_root }}/node_modules node_modules"
+env = "cp {{ repo_root }}/.env.local .env"
```
diff --git a/docs/content/list.md b/docs/content/list.md
index c0be7a896..f76638e00 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -113,7 +113,7 @@ Symbols appear in the Status column in this order:
| | `⋈` | Merge in progress |
| Branch state | `⊘` | Would conflict if merged to main (`--full` only) |
| | `≡` | Matches main (identical contents) |
-| | `_` | No commits (empty branch) |
+| | `_` | No commits ahead, clean working tree |
| Divergence | `↑` | Ahead of main |
| | `↓` | Behind main |
| | `↕` | Diverged from main |
@@ -124,7 +124,7 @@ Symbols appear in the Status column in this order:
| | `⌫` | Prunable (directory missing) |
| | `⊠` | Locked worktree |
-Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).
+Rows are dimmed when the branch [content is already in main](@/remove.md#branch-cleanup) (`≡` matches main or `_` no commits ahead).
## JSON output
diff --git a/docs/content/llm-commits.md b/docs/content/llm-commits.md
index 3e66e2c19..bbc86b359 100644
--- a/docs/content/llm-commits.md
+++ b/docs/content/llm-commits.md
@@ -63,9 +63,11 @@ When worktrunk needs a commit message, it builds a prompt from a template and pi
## Usage
+These examples assume a feature worktree with changes to commit.
+
### wt merge
-Merges branch into target with LLM-generated commit message. Generates a commit message if there are uncommitted changes, and a squash message for the branch commits.
+Squashes all changes (uncommitted + existing commits) into one commit with an LLM-generated message, then merges to main:
```bash
$ wt merge
diff --git a/docs/content/remove.md b/docs/content/remove.md
index 62cf10432..29810ee03 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -41,7 +41,15 @@ wt remove -D experimental
Branches delete automatically when their content is already in the target branch (typically main). This works with squash-merge and rebase workflows where commit history differs but file changes match.
-Use `-D` to force-delete unmerged branches. Use `--no-delete-branch` to keep the branch.
+A branch is safe to delete when its content is already reflected in the target. Worktrunk checks three conditions:
+
+1. **Branch is ancestor** — Three-dot diff (`main...branch`) shows no files. All commits on branch are reachable from main.
+2. **Tree contents match** — Branch tree SHA equals main tree SHA. Commit history differs but file contents are identical (e.g., after a revert or merge commit pulling in main).
+3. **Merge adds nothing** — Simulated merge (`git merge-tree`) produces the same tree as main. Handles squash-merged branches where main has since advanced.
+
+In `wt list`, `_` indicates condition 1 (no commits ahead) and `≡` indicates condition 2 (contents match). Rows with either are dimmed.
+
+Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch` to keep the branch regardless of status.
## Background removal
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 2c7c6fe67..074636e81 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -93,19 +93,10 @@ Reference Taskfile/Justfile/Makefile in hooks:
## Shortcuts
-Special arguments work across all commands:
-
-| Shortcut | Meaning |
-|----------|---------|
-| `^` | Default branch (main/master) |
-| `@` | Current branch/worktree |
-| `-` | Previous worktree (like `cd -`) |
-
-Examples:
+Special arguments work across all commands—see [wt switch](@/switch.md#shortcuts) for the full list.
```bash
wt switch --create hotfix --base=@ # Branch from current HEAD
-wt switch --create feature --base=^ # Branch from main (default)
wt switch - # Switch to previous worktree
wt remove @ # Remove current worktree
```
diff --git a/docs/content/why-worktrunk.md b/docs/content/why-worktrunk.md
index 6a4f35730..44e2450a6 100644
--- a/docs/content/why-worktrunk.md
+++ b/docs/content/why-worktrunk.md
@@ -108,6 +108,7 @@ $ wt config shell install
- 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), [fzf-like picker](@/select.md), [Claude Code integration](@/claude-code.md)
+- Run `wt --help` or `wt <command> --help` for quick CLI reference
## Further reading
diff --git a/src/cli.rs b/src/cli.rs
index a68fd9c01..802c5bbdf 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1046,7 +1046,7 @@ Symbols appear in the Status column in this order:
| | `⋈` | Merge in progress |
| Branch state | `⊘` | Would conflict if merged to main (`--full` only) |
| | `≡` | Matches main (identical contents) |
-| | `_` | No commits (empty branch) |
+| | `_` | No commits ahead, clean working tree |
| Divergence | `↑` | Ahead of main |
| | `↓` | Behind main |
| | `↕` | Diverged from main |
@@ -1057,7 +1057,7 @@ Symbols appear in the Status column in this order:
| | `⌫` | Prunable (directory missing) |
| | `⊠` | Locked worktree |
-Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).
+Rows are dimmed when the branch [content is already in main](@/remove.md#branch-cleanup) (`≡` matches main or `_` no commits ahead).
## JSON output
@@ -1260,7 +1260,15 @@ wt remove -D experimental
Branches delete automatically when their content is already in the target branch (typically main). This works with squash-merge and rebase workflows where commit history differs but file changes match.
-Use `-D` to force-delete unmerged branches. Use `--no-delete-branch` to keep the branch.
+A branch is safe to delete when its content is already reflected in the target. Worktrunk checks three conditions:
+
+1. **Branch is ancestor** — Three-dot diff (`main...branch`) shows no files. All commits on branch are reachable from main.
+2. **Tree contents match** — Branch tree SHA equals main tree SHA. Commit history differs but file contents are identical (e.g., after a revert or merge commit pulling in main).
+3. **Merge adds nothing** — Simulated merge (`git merge-tree`) produces the same tree as main. Handles squash-merged branches where main has since advanced.
+
+In `wt list`, `_` indicates condition 1 (no commits ahead) and `≡` indicates condition 2 (contents match). Rows with either are dimmed.
+
+Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch` to keep the branch regardless of status.
## Background removal
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index 2c27f0f23..21e1d5f1a 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -122,7 +122,7 @@ Symbols appear in the Status column in this order:
| | ⋈ | Merge in progress |
| Branch state | ⊘ | Would conflict if merged to main (--full only) |
| | ≡ | Matches main (identical contents) |
-| | _ | No commits (empty branch) |
+| | _ | No commits ahead, clean working tree |
| Divergence | ↑ | Ahead of main |
| | ↓ | Behind main |
| | ↕ | Diverged from main |
@@ -133,7 +133,7 @@ Symbols appear in the Status column in this order:
| | ⌫ | Prunable (directory missing) |
| | ⊠ | Locked worktree |
-Rows are dimmed when the branch has no marginal contribution (≡ matches main or _ no commits).
+Rows are dimmed when the branch content is already in main (≡ matches main or _ no commits ahead).
JSON output
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
index 2030efec4..cff68cdf1 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -72,7 +72,15 @@ Force-delete an unmerged branch:
Branches delete automatically when their content is already in the target branch (typically main). This works with squash-merge and rebase workflows where commit history differs but file changes match.
-Use -D to force-delete unmerged branches. Use --no-delete-branch to keep the branch.
+A branch is safe to delete when its content is already reflected in the target. Worktrunk checks three conditions:
+
+1. Branch is ancestor — Three-dot diff (main...branch) shows no files. All commits on branch are reachable from main.
+2. Tree contents match — Branch tree SHA equals main tree SHA. Commit history differs but file contents are identical (e.g., after a revert or merge commit pulling in main).
+3. Merge adds nothing — Simulated merge (git merge-tree) produces the same tree as main. Handles squash-merged branches where main has since advanced.
+
+In wt list, _ indicates condition 1 (no commits ahead) and ≡ indicates condition 2 (contents match). Rows with either are dimmed.
+
+Use -D to force-delete branches with unmerged changes. Use --no-delete-branch to keep the branch regardless of status.
Background removal