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.mdindex 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.mdindex 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.mdindex 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 outputdiff --git a/docs/content/llm-commits.md b/docs/content/llm-commits.mdindex 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 mergediff --git a/docs/content/remove.md b/docs/content/remove.mdindex 62cf10432..29810ee03 100644--- a/docs/content/remove.md+++ b/docs/content/remove.md@@ -41,7 +41,15 @@ wt remove -D experimentalBranches 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 removaldiff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex 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.```bashwt switch --create hotfix --base=@ # Branch from current HEAD-wt switch --create feature --base=^ # Branch from main (default)wt switch - # Switch to previous worktreewt remove @ # Remove current worktree```diff --git a/docs/content/why-worktrunk.md b/docs/content/why-worktrunk.mdindex 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 readingdiff --git a/src/cli.rs b/src/cli.rsindex 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 experimentalBranches 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 removaldiff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snapindex 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:| | [2m⋈[0m | Merge in progress || Branch state | [2m⊘[0m | Would conflict if merged to main ([2m--full[0m only) || | [2m≡[0m | Matches main (identical contents) |-| | [2m_[0m | No commits (empty branch) |+| | [2m_[0m | No commits ahead, clean working tree || Divergence | [2m↑[0m | Ahead of main || | [2m↓[0m | Behind main || | [2m↕[0m | Diverged from main |@@ -133,7 +133,7 @@ Symbols appear in the Status column in this order:| | [2m⌫[0m | Prunable (directory missing) || | [2m⊠[0m | Locked worktree |-Rows are dimmed when the branch has no marginal contribution ([2m≡[0m matches main or [2m_[0m no commits).+Rows are dimmed when the branch content is already in main ([2m≡[0m matches main or [2m_[0m no commits ahead).[32mJSON output[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snapindex 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 [2m-D[0m to force-delete unmerged branches. Use [2m--no-delete-branch[0m to keep the branch.+A branch is safe to delete when its content is already reflected in the target. Worktrunk checks three conditions:++1. [1mBranch is ancestor[0m — Three-dot diff ([2mmain...branch[0m) shows no files. All commits on branch are reachable from main.+2. [1mTree contents match[0m — 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. [1mMerge adds nothing[0m — Simulated merge ([2mgit merge-tree[0m) produces the same tree as main. Handles squash-merged branches where main has since advanced.++In [2mwt list[0m, [2m_[0m indicates condition 1 (no commits ahead) and [2m≡[0m indicates condition 2 (contents match). Rows with either are dimmed.++Use [2m-D[0m to force-delete branches with unmerged changes. Use [2m--no-delete-branch[0m to keep the branch regardless of status.[32mBackground removal[0m