Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: release 0.81 documentation review fixes (#4531)
Maximilian Roos13d4d5b4e2f4
diff --git a/docs/public/schema/list-v2.json b/docs/public/schema/list-v2.jsonindex e0eb31444..4a85d4c98 100644--- a/docs/public/schema/list-v2.json+++ b/docs/public/schema/list-v2.json@@ -217,7 +217,7 @@},"integration": {"$ref": "#/$defs/Nullable_JsonIntegration",- "description": "How committed content is integrated; absent when determined\nnot-integrated, null when undetermined (a probe timed out or was\nskipped)."+ "description": "How committed content is integrated; absent when determined\nnot-integrated, null when undetermined (a check timed out or was\nskipped)."},"merge_conflicts": {"description": "A merge into the default branch would conflict based on committed\ncontent and tracked worktree changes (local `merge-tree` simulation);\nnull while unresolved.",diff --git a/docs/src/content/docs/claude-code.md b/docs/src/content/docs/claude-code.mdindex bf37c9713..9f3926aae 100644--- a/docs/src/content/docs/claude-code.md+++ b/docs/src/content/docs/claude-code.md@@ -13,7 +13,7 @@ Worktrunk ships a plugin for each supported agent CLI. What a plugin provides de| Worktree isolation | ✓ | | ✓ | | | || `/wt-switch-create` skill | ✓ | | | | | |-The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks, which only Claude Code and OpenCode 2 expose, so Codex, Pi, oh-my-pi, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex tracks activity through its own `Stop` and `SessionEnd` hooks.+The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks, which only Claude Code and OpenCode 2 expose, so Codex, Pi, oh-my-pi, and Gemini users invoke `wt switch --create` and `wt remove` directly.## Installation@@ -136,9 +136,9 @@ Activity tracking is not plugin-specific. The plugins above only call `wt` on th## Worktree isolation (Claude Code and OpenCode)-Claude Code agents can run in isolated worktrees (`isolation: "worktree"`). By default, Claude Code creates these with `git worktree add`. The plugin's `WorktreeCreate` and `WorktreeRemove` hooks route this through `wt switch --create` and `wt remove` instead, so worktrees created by agents get worktrunk's naming conventions, hooks, and lifecycle management.+Claude Code agents can run in isolated worktrees (`isolation: "worktree"`). By default, Claude Code creates these with `git worktree add`. The plugin's `WorktreeCreate` and `WorktreeRemove` hooks route this through `wt switch --create` and `wt remove` instead, so worktrees created by agents get worktrunk's naming conventions, hooks, and lifecycle management. If the branch already exists, the hook runs `wt switch` without `--create`, which returns the branch's worktree, creating one if it has none.-Under OpenCode 2, the plugin registers a `worktrunk` worktree strategy, so worktrees OpenCode creates and removes go through the same commands. Each gets a branch named after the worktree name OpenCode chooses, at the path from `worktree-path`; OpenCode's `worktree.directory` setting no longer applies. A dirty worktree fails removal with worktrunk's message rather than an offer to force.+Under OpenCode 2, the plugin registers a `worktrunk` worktree strategy, so worktrees OpenCode creates and removes go through the same commands. Each gets a branch named after the worktree name OpenCode chooses, at the path from `worktree-path`; OpenCode's `worktree.directory` setting is ignored. New branches start from the default branch (or the starting ref OpenCode passes), not the current checkout's HEAD. A dirty worktree fails removal with worktrunk's message rather than an offer to force.## `/wt-switch-create` skill (Claude Code only)diff --git a/docs/src/content/docs/extending.md b/docs/src/content/docs/extending.mdindex 6b72bcc27..96d94749d 100644--- a/docs/src/content/docs/extending.md+++ b/docs/src/content/docs/extending.md@@ -232,7 +232,7 @@ Aside from the differences below, hooks and aliases behave the same.| Source discrimination | `user:` / `project:` / `user:name` / `project:name` filter syntax | Run user first, then project; no filter syntax || `--help` | `wt hook --help` lists hook types; `wt hook <type> --help` shows flags and arguments for that type | The template body is the documentation: `wt <alias> --help` redirects to `wt config alias show` / `dry-run`. `wt --help` and `wt step --help` list configured aliases alongside built-in commands || Inspection | `wt hook show [type] [--expanded]` | `wt config alias show <name>` / `wt config alias dry-run <name>` |-| Stdin | See [Interactive hooks](/hook/#interactive-hooks) | Serial steps inherit parent stdin |+| Stdin | A command running alone in the foreground inherits wt's stdin; concurrent and background commands get empty stdin ([Interactive hooks](/hook/#interactive-hooks)) | A command running alone inherits wt's stdin; concurrent commands get empty stdin || Template-context extras | `hook_type`, `hook_name`, per-type operation vars (`base`, `target`, `pr_number`, …) | `args` on top of the shared base variables |</details>diff --git a/docs/src/content/docs/hook.md b/docs/src/content/docs/hook.mdindex e73907239..f7fba6a97 100644--- a/docs/src/content/docs/hook.md+++ b/docs/src/content/docs/hook.md@@ -199,6 +199,22 @@ The `tojson` filter renders a whole object or array as JSON, for commands that tseed = "curl -X POST localhost:3000/seed -d {{ vars.config | tojson }}"```+Logic that templates can't express belongs in a script, with the values it needs passed as arguments:++```toml+# .config/wt.toml+[post-start]+setup = "python3 scripts/post-start-setup.py {{ branch }} {{ repo }}"+```++```python+# scripts/post-start-setup.py+import subprocess, sys+branch, repo = sys.argv[1], sys.argv[2]+if branch.startswith('feature/') and 'backend' in repo:+ subprocess.run(['make', 'seed-db'])+```+## Worktrunk filtersTemplates support Jinja2 filters for transforming values:@@ -277,7 +293,7 @@ wt switch "$(wt step eval "{{ expected_worktree_path_of_branch('feature') }}")"## Interactive hooks-Hooks can prompt when run serially in the foreground, as in this `pre-start` hook:+A hook command inherits wt's stdin, so it can prompt, when it runs in the foreground with no other command alongside it. Commands that run concurrently, such as the keys of a multi-key table, get empty stdin, as do `post-*` hooks running in the background and the hooks `wt step prune` runs for several worktrees at once. This `pre-start` hook asks before trusting the worktree:```toml# .config/wt.toml@@ -285,22 +301,6 @@ Hooks can prompt when run serially in the foreground, as in this `pre-start` hootrust = "gum confirm 'trust this worktree?' && mise trust"```-Logic that templates can't express belongs in a script, with the values it needs passed as arguments:--```toml-# .config/wt.toml-[post-start]-setup = "python3 scripts/post-start-setup.py {{ branch }} {{ repo }}"-```--```python-# scripts/post-start-setup.py-import subprocess, sys-branch, repo = sys.argv[1], sys.argv[2]-if branch.startswith('feature/') and 'backend' in repo:- subprocess.run(['make', 'seed-db'])-```-## Copying untracked filesGit worktrees share the repository but not untracked files. [`wt step copy-ignored`](/step/#wt-step-copy-ignored) copies gitignored files between worktrees:diff --git a/docs/src/content/docs/merge.md b/docs/src/content/docs/merge.mdindex 72ade3017..cdf05a1b2 100644--- a/docs/src/content/docs/merge.md+++ b/docs/src/content/docs/merge.md@@ -8,7 +8,7 @@ sidebar:Merge a branch into the target branch. Squash & rebase, fast-forward the target branch, remove the worktree.-Unlike `git merge`, this merges the source branch into the target branch — not the target into current. Similar to clicking "Merge pull request" on GitHub, but locally. The source defaults to the current branch; the target defaults to the default branch.+Unlike `git merge`, this merges a source branch into the target branch, not the target into the current branch. Similar to clicking "Merge pull request" on GitHub, but locally. The source defaults to the current branch (`--branch` names another); the target defaults to the default branch.<figure class="demo"><picture>@@ -137,7 +137,7 @@ Arguments:Options:-b, --branch <BRANCH>- Branch to merge from (defaults to current worktree)+ Branch to merge (defaults to the current branch)--no-squashSkip commit squashingdiff --git a/docs/src/content/docs/remove.md b/docs/src/content/docs/remove.mdindex 6e89c4b86..b7deafcaa 100644--- a/docs/src/content/docs/remove.md+++ b/docs/src/content/docs/remove.md@@ -104,7 +104,7 @@ Unix only; on Windows `--reap` is rejected.## JSON output-`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal. Branch-only results also include `detached_worktree`: the path of a detached worktree left behind, or `null`.+`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal. Branch-only results also include `detached_worktree`: the path of a detached worktree at the branch's expected location, which the removal leaves in place, or `null`.`branch_outcome` names what happened to the branch, so a caller can tell a deletion the removal declined from one it was never asked to make:diff --git a/docs/src/content/docs/shell-integration.md b/docs/src/content/docs/shell-integration.mdindex 4122952cf..3a5d99725 100644--- a/docs/src/content/docs/shell-integration.md+++ b/docs/src/content/docs/shell-integration.md@@ -8,7 +8,7 @@ sidebar:## Why shell integration exists-The [shell integration overview](/config/#wt-config-shell) explains why directory switching needs a shell function. [How the shell wrapper works](#how-the-shell-wrapper-works) describes the directive mechanism.+A subprocess can't change its parent shell's directory, so `wt` installs a shell function that runs the binary and then changes directory when the command asks. [How the shell wrapper works](#how-the-shell-wrapper-works) has the details.## Installation@@ -16,13 +16,13 @@ See [`wt config shell install`](/config/#wt-config-shell-install) for automatic## Files created-[`wt config shell install`](/config/#wt-config-shell-install) uses these locations:+[`wt config shell install`](/config/#wt-config-shell-install) appends a line to the bash, zsh, and PowerShell files, and writes the fish and Nushell files whole:- **Bash**: `~/.bashrc`- **Zsh**: `~/.zshrc` (or `$ZDOTDIR/.zshrc`)- **Fish**: `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish` (under `$XDG_CONFIG_HOME/fish` when that is set)- **Nushell 0.113+** <span class="badge-experimental"></span>: `wt.nu` in Nushell's user vendor-autoload directory — the last entry of `$nu.vendor-autoload-dirs`, under `$nu.data-dir` (typically `~/.local/share/nushell/vendor/autoload` on Linux, `~/Library/Application Support/nushell/vendor/autoload` on macOS)-- **PowerShell** (Windows): both profile files:+- **PowerShell** (Windows): both profile files, created if they don't exist:- `Documents/PowerShell/Microsoft.PowerShell_profile.ps1` (PowerShell 7+)- `Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1` (Windows PowerShell 5.1)@@ -32,7 +32,7 @@ See [`wt config shell uninstall`](/config/#wt-config-shell-uninstall) for remova## Checking status-The [current-shell checks](/config/#wt-config-shell) explain how to inspect installation and activation with `wt config show` and the shell's command lookup.+Run `wt config show`. Its SHELL INTEGRATION section reports whether the wrapper is active in the current shell.## Warning messagesdiff --git a/docs/src/content/docs/step.md b/docs/src/content/docs/step.mdindex f3ddac75a..25517e089 100644--- a/docs/src/content/docs/step.md+++ b/docs/src/content/docs/step.md@@ -205,7 +205,7 @@ The squash commit is made on a detached HEAD, as `git rebase` does, so git's own### Recovering staged changes-Before squashing staged changes, Worktrunk saves them to `refs/wt-backup/<branch>`. Changes left unstaged are not included in the backup.+Before squashing, Worktrunk saves the uncommitted changes the squash includes (everything staged, by hand or by `--stage`) to `refs/wt-backup/<branch>`. Changes left out of the squash stay in the working tree and aren't backed up.The output prints a command to recover the saved changes in a new worktree, including after `wt merge` removes the original.@@ -829,7 +829,7 @@ Prune removes worktrees concurrently, so hooks that write shared resources must### Min-age guard-Candidates younger than `--min-age` (default: 1 day) are skipped. A worktree's age comes from its creation time. For branches without a reflog, Git maintenance or branch deletion can restart the age guard, even on older branches. This prevents removing a worktree just created from the default branch: it looks "merged" because its branch points at the same commit.+Candidates younger than `--min-age` (default: 1 day) are skipped, so a worktree just created from the default branch isn't removed for looking "merged" (its branch points at the same commit). A worktree's age is its creation time; a branch with no worktree takes its age from its reflog. A branch with no reflog, which is common in bare repositories, can look new again after Git maintenance or a branch deletion, and is then skipped until `--min-age` passes.```console$ wt step prune --min-age=0s # no age guarddiff --git a/docs/src/content/docs/switch.md b/docs/src/content/docs/switch.mdindex 1f7bcb181..a492b34a2 100644--- a/docs/src/content/docs/switch.md+++ b/docs/src/content/docs/switch.md@@ -64,7 +64,7 @@ $ wt switch ../dark-mode # Switch by path...$ wt switch feature/JIRA-1234 # ...or by branch```-Worktrunk finds the worktree from git's own records, so commands reach it by branch or path as usual. [`wt list`](/list/#worktree) marks it `⚐`, since it isn't at the path its branch implies, and [`wt step relocate`](/step/#wt-step-relocate) offers to move it back to the template path.+Other commands reach it by branch or path as usual. [`wt list`](/list/#worktree) marks it `⚐`, since it isn't at the path its branch implies, and [`wt step relocate`](/step/#wt-step-relocate) offers to move it back to the template path.## Naming a worktree@@ -148,7 +148,7 @@ The comparison base is the merge-base with the default branch, or with its upstrpager = "delta --paging=never --width=$COLUMNS"```-**Starting list-only:** Set `preview = false` under `[switch.picker]` to open the picker with the preview hidden; `Alt-p` still shows it.+**Hiding the preview:** Set `preview = false` under `[switch.picker]` to open the picker with the preview hidden; `Alt-p` still shows it.## Pull requests and merge requestsdiff --git a/plugins/worktrunk/README.md b/plugins/worktrunk/README.mdindex 1d996282b..0c7e6a76d 100644--- a/plugins/worktrunk/README.md+++ b/plugins/worktrunk/README.md@@ -16,16 +16,14 @@ by the worktree-lifecycle hooks).Every hook calls `wt` through `hooks/wt.sh`:- **Activity markers**: `UserPromptSubmit`, `Notification`, `Stop`, and `PreToolUse` on `AskUserQuestion` set the branch's marker with `wt config state marker set`; `SessionEnd` clears it.-- **Worktree creation and removal**: when Claude Code creates or removes a worktree, the `WorktreeCreate` and `WorktreeRemove` hooks run `wt switch --create` and `wt remove` in place of Claude Code's own `git worktree` commands, so the worktree follows worktrunk's path layout and runs the project's approved worktrunk hooks.+- **Worktree creation and removal**: when Claude Code creates or removes a worktree, the `WorktreeCreate` and `WorktreeRemove` hooks run `wt switch --create` (plain `wt switch` when the branch already exists, which returns its worktree) and `wt remove` in place of Claude Code's own `git worktree` commands, so the worktree follows worktrunk's path layout and runs the project's approved worktrunk hooks.- **`EnterWorktree` approval**: the `PermissionRequest` hook allows an `EnterWorktree` call without a dialog when its path is a worktree of the current repository at the location worktrunk's `worktree-path` template gives its branch. Every other request shows Claude Code's usual dialog and sets the branch's marker to 💬 while it waits.## Examples**Activity tracking across worktrees**-The plugin installs Claude Code hooks that track session activity per branch. When a prompt is submitted, the hook sets 🤖 on that branch. When Claude finishes and waits for input, it switches to 💬. When the session ends, the marker clears.--These markers appear in `wt list` output, making it easy to see which worktrees have active Claude sessions — useful when running multiple instances in parallel.+The 🤖 and 💬 markers appear in `wt list` output, making it easy to see which worktrees have active Claude sessions — useful when running multiple instances in parallel.**Set up LLM commit message generation**diff --git a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md b/plugins/worktrunk/skills/worktrunk/reference/claude-code.mdindex d06429e3f..452b81dec 100644--- a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md+++ b/plugins/worktrunk/skills/worktrunk/reference/claude-code.md@@ -9,7 +9,7 @@ Worktrunk ships a plugin for each supported agent CLI. What a plugin provides de| Worktree isolation | ✓ | | ✓ | | | || `/wt-switch-create` skill | ✓ | | | | | |-The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks, which only Claude Code and OpenCode 2 expose, so Codex, Pi, oh-my-pi, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex tracks activity through its own `Stop` and `SessionEnd` hooks.+The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks, which only Claude Code and OpenCode 2 expose, so Codex, Pi, oh-my-pi, and Gemini users invoke `wt switch --create` and `wt remove` directly.## Installation@@ -128,9 +128,9 @@ Activity tracking is not plugin-specific. The plugins above only call `wt` on th## Worktree isolation (Claude Code and OpenCode)-Claude Code agents can run in isolated worktrees (`isolation: "worktree"`). By default, Claude Code creates these with `git worktree add`. The plugin's `WorktreeCreate` and `WorktreeRemove` hooks route this through `wt switch --create` and `wt remove` instead, so worktrees created by agents get worktrunk's naming conventions, hooks, and lifecycle management.+Claude Code agents can run in isolated worktrees (`isolation: "worktree"`). By default, Claude Code creates these with `git worktree add`. The plugin's `WorktreeCreate` and `WorktreeRemove` hooks route this through `wt switch --create` and `wt remove` instead, so worktrees created by agents get worktrunk's naming conventions, hooks, and lifecycle management. If the branch already exists, the hook runs `wt switch` without `--create`, which returns the branch's worktree, creating one if it has none.-Under OpenCode 2, the plugin registers a `worktrunk` worktree strategy, so worktrees OpenCode creates and removes go through the same commands. Each gets a branch named after the worktree name OpenCode chooses, at the path from `worktree-path`; OpenCode's `worktree.directory` setting no longer applies. A dirty worktree fails removal with worktrunk's message rather than an offer to force.+Under OpenCode 2, the plugin registers a `worktrunk` worktree strategy, so worktrees OpenCode creates and removes go through the same commands. Each gets a branch named after the worktree name OpenCode chooses, at the path from `worktree-path`; OpenCode's `worktree.directory` setting is ignored. New branches start from the default branch (or the starting ref OpenCode passes), not the current checkout's HEAD. A dirty worktree fails removal with worktrunk's message rather than an offer to force.## `/wt-switch-create` skill (Claude Code only)diff --git a/plugins/worktrunk/skills/worktrunk/reference/extending.md b/plugins/worktrunk/skills/worktrunk/reference/extending.mdindex 6584af4b4..5df28997f 100644--- a/plugins/worktrunk/skills/worktrunk/reference/extending.md+++ b/plugins/worktrunk/skills/worktrunk/reference/extending.md@@ -228,7 +228,7 @@ Aside from the differences below, hooks and aliases behave the same.| Source discrimination | `user:` / `project:` / `user:name` / `project:name` filter syntax | Run user first, then project; no filter syntax || `--help` | `wt hook --help` lists hook types; `wt hook <type> --help` shows flags and arguments for that type | The template body is the documentation: `wt <alias> --help` redirects to `wt config alias show` / `dry-run`. `wt --help` and `wt step --help` list configured aliases alongside built-in commands || Inspection | `wt hook show [type] [--expanded]` | `wt config alias show <name>` / `wt config alias dry-run <name>` |-| Stdin | See [Interactive hooks](https://worktrunk.dev/hook/#interactive-hooks) | Serial steps inherit parent stdin |+| Stdin | A command running alone in the foreground inherits wt's stdin; concurrent and background commands get empty stdin ([Interactive hooks](https://worktrunk.dev/hook/#interactive-hooks)) | A command running alone inherits wt's stdin; concurrent commands get empty stdin || Template-context extras | `hook_type`, `hook_name`, per-type operation vars (`base`, `target`, `pr_number`, …) | `args` on top of the shared base variables |</details>diff --git a/plugins/worktrunk/skills/worktrunk/reference/hook.md b/plugins/worktrunk/skills/worktrunk/reference/hook.mdindex 7352a9ed4..ce360f86f 100644--- a/plugins/worktrunk/skills/worktrunk/reference/hook.md+++ b/plugins/worktrunk/skills/worktrunk/reference/hook.md@@ -193,6 +193,22 @@ The `tojson` filter renders a whole object or array as JSON, for commands that tseed = "curl -X POST localhost:3000/seed -d {{ vars.config | tojson }}"```+Logic that templates can't express belongs in a script, with the values it needs passed as arguments:++```toml+# .config/wt.toml+[post-start]+setup = "python3 scripts/post-start-setup.py {{ branch }} {{ repo }}"+```++```python+# scripts/post-start-setup.py+import subprocess, sys+branch, repo = sys.argv[1], sys.argv[2]+if branch.startswith('feature/') and 'backend' in repo:+ subprocess.run(['make', 'seed-db'])+```+## Worktrunk filtersTemplates support Jinja2 filters for transforming values:@@ -271,7 +287,7 @@ wt switch "$(wt step eval "{{ expected_worktree_path_of_branch('feature') }}")"## Interactive hooks-Hooks can prompt when run serially in the foreground, as in this `pre-start` hook:+A hook command inherits wt's stdin, so it can prompt, when it runs in the foreground with no other command alongside it. Commands that run concurrently, such as the keys of a multi-key table, get empty stdin, as do `post-*` hooks running in the background and the hooks `wt step prune` runs for several worktrees at once. This `pre-start` hook asks before trusting the worktree:```toml# .config/wt.toml@@ -279,22 +295,6 @@ Hooks can prompt when run serially in the foreground, as in this `pre-start` hootrust = "gum confirm 'trust this worktree?' && mise trust"```-Logic that templates can't express belongs in a script, with the values it needs passed as arguments:--```toml-# .config/wt.toml-[post-start]-setup = "python3 scripts/post-start-setup.py {{ branch }} {{ repo }}"-```--```python-# scripts/post-start-setup.py-import subprocess, sys-branch, repo = sys.argv[1], sys.argv[2]-if branch.startswith('feature/') and 'backend' in repo:- subprocess.run(['make', 'seed-db'])-```-## Copying untracked filesGit worktrees share the repository but not untracked files. [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) copies gitignored files between worktrees:diff --git a/plugins/worktrunk/skills/worktrunk/reference/merge.md b/plugins/worktrunk/skills/worktrunk/reference/merge.mdindex 4efc4fe9e..a6f2f6e88 100644--- a/plugins/worktrunk/skills/worktrunk/reference/merge.md+++ b/plugins/worktrunk/skills/worktrunk/reference/merge.md@@ -2,7 +2,7 @@Merge a branch into the target branch. Squash & rebase, fast-forward the target branch, remove the worktree.-Unlike `git merge`, this merges the source branch into the target branch — not the target into current. Similar to clicking "Merge pull request" on GitHub, but locally. The source defaults to the current branch; the target defaults to the default branch.+Unlike `git merge`, this merges a source branch into the target branch, not the target into the current branch. Similar to clicking "Merge pull request" on GitHub, but locally. The source defaults to the current branch (`--branch` names another); the target defaults to the default branch.## Examples@@ -117,7 +117,7 @@ Arguments:Options:-b, --branch <BRANCH>- Branch to merge from (defaults to current worktree)+ Branch to merge (defaults to the current branch)--no-squashSkip commit squashingdiff --git a/plugins/worktrunk/skills/worktrunk/reference/remove.md b/plugins/worktrunk/skills/worktrunk/reference/remove.mdindex c0ca3d985..062a1a51f 100644--- a/plugins/worktrunk/skills/worktrunk/reference/remove.md+++ b/plugins/worktrunk/skills/worktrunk/reference/remove.md@@ -96,7 +96,7 @@ Unix only; on Windows `--reap` is rejected.## JSON output-`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal. Branch-only results also include `detached_worktree`: the path of a detached worktree left behind, or `null`.+`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal. Branch-only results also include `detached_worktree`: the path of a detached worktree at the branch's expected location, which the removal leaves in place, or `null`.`branch_outcome` names what happened to the branch, so a caller can tell a deletion the removal declined from one it was never asked to make:diff --git a/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md b/plugins/worktrunk/skills/worktrunk/reference/shell-integration.mdindex 5b0d33b33..296bec5d5 100644--- a/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md+++ b/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md@@ -4,7 +4,7 @@## Why shell integration exists-The [shell integration overview](https://worktrunk.dev/config/#wt-config-shell) explains why directory switching needs a shell function. [How the shell wrapper works](#how-the-shell-wrapper-works) describes the directive mechanism.+A subprocess can't change its parent shell's directory, so `wt` installs a shell function that runs the binary and then changes directory when the command asks. [How the shell wrapper works](#how-the-shell-wrapper-works) has the details.## Installation@@ -12,13 +12,13 @@ See [`wt config shell install`](https://worktrunk.dev/config/#wt-config-shell-in## Files created-[`wt config shell install`](https://worktrunk.dev/config/#wt-config-shell-install) uses these locations:+[`wt config shell install`](https://worktrunk.dev/config/#wt-config-shell-install) appends a line to the bash, zsh, and PowerShell files, and writes the fish and Nushell files whole:- **Bash**: `~/.bashrc`- **Zsh**: `~/.zshrc` (or `$ZDOTDIR/.zshrc`)- **Fish**: `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish` (under `$XDG_CONFIG_HOME/fish` when that is set)- **Nushell 0.113+** [experimental]: `wt.nu` in Nushell's user vendor-autoload directory — the last entry of `$nu.vendor-autoload-dirs`, under `$nu.data-dir` (typically `~/.local/share/nushell/vendor/autoload` on Linux, `~/Library/Application Support/nushell/vendor/autoload` on macOS)-- **PowerShell** (Windows): both profile files:+- **PowerShell** (Windows): both profile files, created if they don't exist:- `Documents/PowerShell/Microsoft.PowerShell_profile.ps1` (PowerShell 7+)- `Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1` (Windows PowerShell 5.1)@@ -28,7 +28,7 @@ See [`wt config shell uninstall`](https://worktrunk.dev/config/#wt-config-shell-## Checking status-The [current-shell checks](https://worktrunk.dev/config/#wt-config-shell) explain how to inspect installation and activation with `wt config show` and the shell's command lookup.+Run `wt config show`. Its SHELL INTEGRATION section reports whether the wrapper is active in the current shell.## Warning messagesdiff --git a/plugins/worktrunk/skills/worktrunk/reference/step.md b/plugins/worktrunk/skills/worktrunk/reference/step.mdindex 06c31b296..684cf228c 100644--- a/plugins/worktrunk/skills/worktrunk/reference/step.md+++ b/plugins/worktrunk/skills/worktrunk/reference/step.md@@ -193,7 +193,7 @@ The squash commit is made on a detached HEAD, as `git rebase` does, so git's own### Recovering staged changes-Before squashing staged changes, Worktrunk saves them to `refs/wt-backup/<branch>`. Changes left unstaged are not included in the backup.+Before squashing, Worktrunk saves the uncommitted changes the squash includes (everything staged, by hand or by `--stage`) to `refs/wt-backup/<branch>`. Changes left out of the squash stay in the working tree and aren't backed up.The output prints a command to recover the saved changes in a new worktree, including after `wt merge` removes the original.@@ -817,7 +817,7 @@ Prune removes worktrees concurrently, so hooks that write shared resources must### Min-age guard-Candidates younger than `--min-age` (default: 1 day) are skipped. A worktree's age comes from its creation time. For branches without a reflog, Git maintenance or branch deletion can restart the age guard, even on older branches. This prevents removing a worktree just created from the default branch: it looks "merged" because its branch points at the same commit.+Candidates younger than `--min-age` (default: 1 day) are skipped, so a worktree just created from the default branch isn't removed for looking "merged" (its branch points at the same commit). A worktree's age is its creation time; a branch with no worktree takes its age from its reflog. A branch with no reflog, which is common in bare repositories, can look new again after Git maintenance or a branch deletion, and is then skipped until `--min-age` passes.```console$ wt step prune --min-age=0s # no age guarddiff --git a/plugins/worktrunk/skills/worktrunk/reference/switch.md b/plugins/worktrunk/skills/worktrunk/reference/switch.mdindex 3f6909774..fe2a4519f 100644--- a/plugins/worktrunk/skills/worktrunk/reference/switch.md+++ b/plugins/worktrunk/skills/worktrunk/reference/switch.md@@ -48,7 +48,7 @@ $ wt switch ../dark-mode # Switch by path...$ wt switch feature/JIRA-1234 # ...or by branch```-Worktrunk finds the worktree from git's own records, so commands reach it by branch or path as usual. [`wt list`](https://worktrunk.dev/list/#worktree) marks it `⚐`, since it isn't at the path its branch implies, and [`wt step relocate`](https://worktrunk.dev/step/#wt-step-relocate) offers to move it back to the template path.+Other commands reach it by branch or path as usual. [`wt list`](https://worktrunk.dev/list/#worktree) marks it `⚐`, since it isn't at the path its branch implies, and [`wt step relocate`](https://worktrunk.dev/step/#wt-step-relocate) offers to move it back to the template path.## Naming a worktree@@ -124,7 +124,7 @@ The comparison base is the merge-base with the default branch, or with its upstrpager = "delta --paging=never --width=$COLUMNS"```-**Starting list-only:** Set `preview = false` under `[switch.picker]` to open the picker with the preview hidden; `Alt-p` still shows it.+**Hiding the preview:** Set `preview = false` under `[switch.picker]` to open the picker with the preview hidden; `Alt-p` still shows it.## Pull requests and merge requestsdiff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.mdindex d06429e3f..452b81dec 100644--- a/skills/worktrunk/reference/claude-code.md+++ b/skills/worktrunk/reference/claude-code.md@@ -9,7 +9,7 @@ Worktrunk ships a plugin for each supported agent CLI. What a plugin provides de| Worktree isolation | ✓ | | ✓ | | | || `/wt-switch-create` skill | ✓ | | | | | |-The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks, which only Claude Code and OpenCode 2 expose, so Codex, Pi, oh-my-pi, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex tracks activity through its own `Stop` and `SessionEnd` hooks.+The configuration skill is documentation the agent reads to help set up LLM commits, hooks, and troubleshooting. Activity tracking shows which worktrees have running sessions. Worktree isolation needs worktree-lifecycle hooks, which only Claude Code and OpenCode 2 expose, so Codex, Pi, oh-my-pi, and Gemini users invoke `wt switch --create` and `wt remove` directly.## Installation@@ -128,9 +128,9 @@ Activity tracking is not plugin-specific. The plugins above only call `wt` on th## Worktree isolation (Claude Code and OpenCode)-Claude Code agents can run in isolated worktrees (`isolation: "worktree"`). By default, Claude Code creates these with `git worktree add`. The plugin's `WorktreeCreate` and `WorktreeRemove` hooks route this through `wt switch --create` and `wt remove` instead, so worktrees created by agents get worktrunk's naming conventions, hooks, and lifecycle management.+Claude Code agents can run in isolated worktrees (`isolation: "worktree"`). By default, Claude Code creates these with `git worktree add`. The plugin's `WorktreeCreate` and `WorktreeRemove` hooks route this through `wt switch --create` and `wt remove` instead, so worktrees created by agents get worktrunk's naming conventions, hooks, and lifecycle management. If the branch already exists, the hook runs `wt switch` without `--create`, which returns the branch's worktree, creating one if it has none.-Under OpenCode 2, the plugin registers a `worktrunk` worktree strategy, so worktrees OpenCode creates and removes go through the same commands. Each gets a branch named after the worktree name OpenCode chooses, at the path from `worktree-path`; OpenCode's `worktree.directory` setting no longer applies. A dirty worktree fails removal with worktrunk's message rather than an offer to force.+Under OpenCode 2, the plugin registers a `worktrunk` worktree strategy, so worktrees OpenCode creates and removes go through the same commands. Each gets a branch named after the worktree name OpenCode chooses, at the path from `worktree-path`; OpenCode's `worktree.directory` setting is ignored. New branches start from the default branch (or the starting ref OpenCode passes), not the current checkout's HEAD. A dirty worktree fails removal with worktrunk's message rather than an offer to force.## `/wt-switch-create` skill (Claude Code only)diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.mdindex 6584af4b4..5df28997f 100644--- a/skills/worktrunk/reference/extending.md+++ b/skills/worktrunk/reference/extending.md@@ -228,7 +228,7 @@ Aside from the differences below, hooks and aliases behave the same.| Source discrimination | `user:` / `project:` / `user:name` / `project:name` filter syntax | Run user first, then project; no filter syntax || `--help` | `wt hook --help` lists hook types; `wt hook <type> --help` shows flags and arguments for that type | The template body is the documentation: `wt <alias> --help` redirects to `wt config alias show` / `dry-run`. `wt --help` and `wt step --help` list configured aliases alongside built-in commands || Inspection | `wt hook show [type] [--expanded]` | `wt config alias show <name>` / `wt config alias dry-run <name>` |-| Stdin | See [Interactive hooks](https://worktrunk.dev/hook/#interactive-hooks) | Serial steps inherit parent stdin |+| Stdin | A command running alone in the foreground inherits wt's stdin; concurrent and background commands get empty stdin ([Interactive hooks](https://worktrunk.dev/hook/#interactive-hooks)) | A command running alone inherits wt's stdin; concurrent commands get empty stdin || Template-context extras | `hook_type`, `hook_name`, per-type operation vars (`base`, `target`, `pr_number`, …) | `args` on top of the shared base variables |</details>diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex 7352a9ed4..ce360f86f 100644--- a/skills/worktrunk/reference/hook.md+++ b/skills/worktrunk/reference/hook.md@@ -193,6 +193,22 @@ The `tojson` filter renders a whole object or array as JSON, for commands that tseed = "curl -X POST localhost:3000/seed -d {{ vars.config | tojson }}"```+Logic that templates can't express belongs in a script, with the values it needs passed as arguments:++```toml+# .config/wt.toml+[post-start]+setup = "python3 scripts/post-start-setup.py {{ branch }} {{ repo }}"+```++```python+# scripts/post-start-setup.py+import subprocess, sys+branch, repo = sys.argv[1], sys.argv[2]+if branch.startswith('feature/') and 'backend' in repo:+ subprocess.run(['make', 'seed-db'])+```+## Worktrunk filtersTemplates support Jinja2 filters for transforming values:@@ -271,7 +287,7 @@ wt switch "$(wt step eval "{{ expected_worktree_path_of_branch('feature') }}")"## Interactive hooks-Hooks can prompt when run serially in the foreground, as in this `pre-start` hook:+A hook command inherits wt's stdin, so it can prompt, when it runs in the foreground with no other command alongside it. Commands that run concurrently, such as the keys of a multi-key table, get empty stdin, as do `post-*` hooks running in the background and the hooks `wt step prune` runs for several worktrees at once. This `pre-start` hook asks before trusting the worktree:```toml# .config/wt.toml@@ -279,22 +295,6 @@ Hooks can prompt when run serially in the foreground, as in this `pre-start` hootrust = "gum confirm 'trust this worktree?' && mise trust"```-Logic that templates can't express belongs in a script, with the values it needs passed as arguments:--```toml-# .config/wt.toml-[post-start]-setup = "python3 scripts/post-start-setup.py {{ branch }} {{ repo }}"-```--```python-# scripts/post-start-setup.py-import subprocess, sys-branch, repo = sys.argv[1], sys.argv[2]-if branch.startswith('feature/') and 'backend' in repo:- subprocess.run(['make', 'seed-db'])-```-## Copying untracked filesGit worktrees share the repository but not untracked files. [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) copies gitignored files between worktrees:diff --git a/skills/worktrunk/reference/merge.md b/skills/worktrunk/reference/merge.mdindex 4efc4fe9e..a6f2f6e88 100644--- a/skills/worktrunk/reference/merge.md+++ b/skills/worktrunk/reference/merge.md@@ -2,7 +2,7 @@Merge a branch into the target branch. Squash & rebase, fast-forward the target branch, remove the worktree.-Unlike `git merge`, this merges the source branch into the target branch — not the target into current. Similar to clicking "Merge pull request" on GitHub, but locally. The source defaults to the current branch; the target defaults to the default branch.+Unlike `git merge`, this merges a source branch into the target branch, not the target into the current branch. Similar to clicking "Merge pull request" on GitHub, but locally. The source defaults to the current branch (`--branch` names another); the target defaults to the default branch.## Examples@@ -117,7 +117,7 @@ Arguments:Options:-b, --branch <BRANCH>- Branch to merge from (defaults to current worktree)+ Branch to merge (defaults to the current branch)--no-squashSkip commit squashingdiff --git a/skills/worktrunk/reference/remove.md b/skills/worktrunk/reference/remove.mdindex c0ca3d985..062a1a51f 100644--- a/skills/worktrunk/reference/remove.md+++ b/skills/worktrunk/reference/remove.md@@ -96,7 +96,7 @@ Unix only; on Windows `--reap` is rejected.## JSON output-`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal. Branch-only results also include `detached_worktree`: the path of a detached worktree left behind, or `null`.+`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal. Branch-only results also include `detached_worktree`: the path of a detached worktree at the branch's expected location, which the removal leaves in place, or `null`.`branch_outcome` names what happened to the branch, so a caller can tell a deletion the removal declined from one it was never asked to make:diff --git a/skills/worktrunk/reference/shell-integration.md b/skills/worktrunk/reference/shell-integration.mdindex 5b0d33b33..296bec5d5 100644--- a/skills/worktrunk/reference/shell-integration.md+++ b/skills/worktrunk/reference/shell-integration.md@@ -4,7 +4,7 @@## Why shell integration exists-The [shell integration overview](https://worktrunk.dev/config/#wt-config-shell) explains why directory switching needs a shell function. [How the shell wrapper works](#how-the-shell-wrapper-works) describes the directive mechanism.+A subprocess can't change its parent shell's directory, so `wt` installs a shell function that runs the binary and then changes directory when the command asks. [How the shell wrapper works](#how-the-shell-wrapper-works) has the details.## Installation@@ -12,13 +12,13 @@ See [`wt config shell install`](https://worktrunk.dev/config/#wt-config-shell-in## Files created-[`wt config shell install`](https://worktrunk.dev/config/#wt-config-shell-install) uses these locations:+[`wt config shell install`](https://worktrunk.dev/config/#wt-config-shell-install) appends a line to the bash, zsh, and PowerShell files, and writes the fish and Nushell files whole:- **Bash**: `~/.bashrc`- **Zsh**: `~/.zshrc` (or `$ZDOTDIR/.zshrc`)- **Fish**: `~/.config/fish/functions/wt.fish` and `~/.config/fish/completions/wt.fish` (under `$XDG_CONFIG_HOME/fish` when that is set)- **Nushell 0.113+** [experimental]: `wt.nu` in Nushell's user vendor-autoload directory — the last entry of `$nu.vendor-autoload-dirs`, under `$nu.data-dir` (typically `~/.local/share/nushell/vendor/autoload` on Linux, `~/Library/Application Support/nushell/vendor/autoload` on macOS)-- **PowerShell** (Windows): both profile files:+- **PowerShell** (Windows): both profile files, created if they don't exist:- `Documents/PowerShell/Microsoft.PowerShell_profile.ps1` (PowerShell 7+)- `Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1` (Windows PowerShell 5.1)@@ -28,7 +28,7 @@ See [`wt config shell uninstall`](https://worktrunk.dev/config/#wt-config-shell-## Checking status-The [current-shell checks](https://worktrunk.dev/config/#wt-config-shell) explain how to inspect installation and activation with `wt config show` and the shell's command lookup.+Run `wt config show`. Its SHELL INTEGRATION section reports whether the wrapper is active in the current shell.## Warning messagesdiff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.mdindex 06c31b296..684cf228c 100644--- a/skills/worktrunk/reference/step.md+++ b/skills/worktrunk/reference/step.md@@ -193,7 +193,7 @@ The squash commit is made on a detached HEAD, as `git rebase` does, so git's own### Recovering staged changes-Before squashing staged changes, Worktrunk saves them to `refs/wt-backup/<branch>`. Changes left unstaged are not included in the backup.+Before squashing, Worktrunk saves the uncommitted changes the squash includes (everything staged, by hand or by `--stage`) to `refs/wt-backup/<branch>`. Changes left out of the squash stay in the working tree and aren't backed up.The output prints a command to recover the saved changes in a new worktree, including after `wt merge` removes the original.@@ -817,7 +817,7 @@ Prune removes worktrees concurrently, so hooks that write shared resources must### Min-age guard-Candidates younger than `--min-age` (default: 1 day) are skipped. A worktree's age comes from its creation time. For branches without a reflog, Git maintenance or branch deletion can restart the age guard, even on older branches. This prevents removing a worktree just created from the default branch: it looks "merged" because its branch points at the same commit.+Candidates younger than `--min-age` (default: 1 day) are skipped, so a worktree just created from the default branch isn't removed for looking "merged" (its branch points at the same commit). A worktree's age is its creation time; a branch with no worktree takes its age from its reflog. A branch with no reflog, which is common in bare repositories, can look new again after Git maintenance or a branch deletion, and is then skipped until `--min-age` passes.```console$ wt step prune --min-age=0s # no age guarddiff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.mdindex 3f6909774..fe2a4519f 100644--- a/skills/worktrunk/reference/switch.md+++ b/skills/worktrunk/reference/switch.md@@ -48,7 +48,7 @@ $ wt switch ../dark-mode # Switch by path...$ wt switch feature/JIRA-1234 # ...or by branch```-Worktrunk finds the worktree from git's own records, so commands reach it by branch or path as usual. [`wt list`](https://worktrunk.dev/list/#worktree) marks it `⚐`, since it isn't at the path its branch implies, and [`wt step relocate`](https://worktrunk.dev/step/#wt-step-relocate) offers to move it back to the template path.+Other commands reach it by branch or path as usual. [`wt list`](https://worktrunk.dev/list/#worktree) marks it `⚐`, since it isn't at the path its branch implies, and [`wt step relocate`](https://worktrunk.dev/step/#wt-step-relocate) offers to move it back to the template path.## Naming a worktree@@ -124,7 +124,7 @@ The comparison base is the merge-base with the default branch, or with its upstrpager = "delta --paging=never --width=$COLUMNS"```-**Starting list-only:** Set `preview = false` under `[switch.picker]` to open the picker with the preview hidden; `Alt-p` still shows it.+**Hiding the preview:** Set `preview = false` under `[switch.picker]` to open the picker with the preview hidden; `Alt-p` still shows it.## Pull requests and merge requestsdiff --git a/src/cli/mod.rs b/src/cli/mod.rsindex f544976c7..38104cfe9 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -556,7 +556,7 @@ pub(crate) struct RemoveArgs {#[derive(Args)]pub(crate) struct MergeArgs {- /// Branch to merge from (defaults to current worktree)+ /// Branch to merge (defaults to the current branch)#[arg(short, long, add = crate::completion::worktree_only_completer(), value_parser = crate::cli::non_empty_branch)]pub(crate) branch: Option<String>,@@ -688,7 +688,7 @@ $ wt switch ../dark-mode # Switch by path...$ wt switch feature/JIRA-1234 # ...or by branch```-Worktrunk finds the worktree from git's own records, so commands reach it by branch or path as usual. [`wt list`](/list/#worktree) marks it `⚐`, since it isn't at the path its branch implies, and [`wt step relocate`](/step/#wt-step-relocate) offers to move it back to the template path.+Other commands reach it by branch or path as usual. [`wt list`](/list/#worktree) marks it `⚐`, since it isn't at the path its branch implies, and [`wt step relocate`](/step/#wt-step-relocate) offers to move it back to the template path.## Naming a worktree@@ -765,7 +765,7 @@ The comparison base is the merge-base with the default branch, or with its upstrpager = "delta --paging=never --width=$COLUMNS"```-**Starting list-only:** Set `preview = false` under `[switch.picker]` to open the picker with the preview hidden; `Alt-p` still shows it.+**Hiding the preview:** Set `preview = false` under `[switch.picker]` to open the picker with the preview hidden; `Alt-p` still shows it.## Pull requests and merge requests@@ -1408,7 +1408,7 @@ Unix only; on Windows `--reap` is rejected.## JSON output-`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal. Branch-only results also include `detached_worktree`: the path of a detached worktree left behind, or `null`.+`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal. Branch-only results also include `detached_worktree`: the path of a detached worktree at the branch's expected location, which the removal leaves in place, or `null`.`branch_outcome` names what happened to the branch, so a caller can tell a deletion the removal declined from one it was never asked to make:@@ -1441,7 +1441,7 @@ Detached worktrees have no branch name. Pass the worktree path instead: `wt remo////// Squash & rebase, fast-forward the target branch, remove the worktree.#[command(- after_long_help = r#"Unlike `git merge`, this merges the source branch into the target branch — not the target into current. Similar to clicking "Merge pull request" on GitHub, but locally. The source defaults to the current branch; the target defaults to the default branch.+ after_long_help = r#"Unlike `git merge`, this merges a source branch into the target branch, not the target into the current branch. Similar to clicking "Merge pull request" on GitHub, but locally. The source defaults to the current branch (`--branch` names another); the target defaults to the default branch.<!-- demo: wt-merge.gif 1600x900 | Creating a worktree, committing in it, and merging it away -->## Examples@@ -1823,6 +1823,22 @@ The `tojson` filter renders a whole object or array as JSON, for commands that tseed = "curl -X POST localhost:3000/seed -d {{ vars.config | tojson }}"```+Logic that templates can't express belongs in a script, with the values it needs passed as arguments:++```toml+# .config/wt.toml+[post-start]+setup = "python3 scripts/post-start-setup.py {{ branch }} {{ repo }}"+```++```python+# scripts/post-start-setup.py+import subprocess, sys+branch, repo = sys.argv[1], sys.argv[2]+if branch.startswith('feature/') and 'backend' in repo:+ subprocess.run(['make', 'seed-db'])+```+## Worktrunk filtersTemplates support Jinja2 filters for transforming values:@@ -1901,7 +1917,7 @@ wt switch "$(wt step eval "{{ expected_worktree_path_of_branch('feature') }}")"## Interactive hooks-Hooks can prompt when run serially in the foreground, as in this `pre-start` hook:+A hook command inherits wt's stdin, so it can prompt, when it runs in the foreground with no other command alongside it. Commands that run concurrently, such as the keys of a multi-key table, get empty stdin, as do `post-*` hooks running in the background and the hooks `wt step prune` runs for several worktrees at once. This `pre-start` hook asks before trusting the worktree:```toml# .config/wt.toml@@ -1909,22 +1925,6 @@ Hooks can prompt when run serially in the foreground, as in this `pre-start` hootrust = "gum confirm 'trust this worktree?' && mise trust"```-Logic that templates can't express belongs in a script, with the values it needs passed as arguments:--```toml-# .config/wt.toml-[post-start]-setup = "python3 scripts/post-start-setup.py {{ branch }} {{ repo }}"-```--```python-# scripts/post-start-setup.py-import subprocess, sys-branch, repo = sys.argv[1], sys.argv[2]-if branch.startswith('feature/') and 'backend' in repo:- subprocess.run(['make', 'seed-db'])-```-## Copying untracked filesGit worktrees share the repository but not untracked files. [`wt step copy-ignored`](/step/#wt-step-copy-ignored) copies gitignored files between worktrees:diff --git a/src/cli/step.rs b/src/cli/step.rsindex ecf82ee9a..2622a7757 100644--- a/src/cli/step.rs+++ b/src/cli/step.rs@@ -136,7 +136,7 @@ The squash commit is made on a detached HEAD, as `git rebase` does, so git's own## Recovering staged changes-Before squashing staged changes, Worktrunk saves them to `refs/wt-backup/<branch>`. Changes left unstaged are not included in the backup.+Before squashing, Worktrunk saves the uncommitted changes the squash includes (everything staged, by hand or by `--stage`) to `refs/wt-backup/<branch>`. Changes left out of the squash stay in the working tree and aren't backed up.The output prints a command to recover the saved changes in a new worktree, including after `wt merge` removes the original.@@ -631,7 +631,7 @@ Prune removes worktrees concurrently, so hooks that write shared resources must## Min-age guard-Candidates younger than `--min-age` (default: 1 day) are skipped. A worktree's age comes from its creation time. For branches without a reflog, Git maintenance or branch deletion can restart the age guard, even on older branches. This prevents removing a worktree just created from the default branch: it looks "merged" because its branch points at the same commit.+Candidates younger than `--min-age` (default: 1 day) are skipped, so a worktree just created from the default branch isn't removed for looking "merged" (its branch points at the same commit). A worktree's age is its creation time; a branch with no worktree takes its age from its reflog. A branch with no reflog, which is common in bare repositories, can look new again after Git maintenance or a branch deletion, and is then skipped until `--min-age` passes.```console$ wt step prune --min-age=0s # no age guarddiff --git a/src/commands/list/json_v2.rs b/src/commands/list/json_v2.rsindex 2150a0006..bd1f2165e 100644--- a/src/commands/list/json_v2.rs+++ b/src/commands/list/json_v2.rs@@ -335,7 +335,7 @@ pub struct JsonDefaultBranch {pub orphan: Option<bool>,/// How committed content is integrated; absent when determined- /// not-integrated, null when undetermined (a probe timed out or was+ /// not-integrated, null when undetermined (a check timed out or was/// skipped).#[serde(skip_serializing_if = "Tri::is_absent")]pub integration: Tri<JsonIntegration>,diff --git a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap b/tests/snapshots/integration__integration_tests__help__help_md_merge.snapindex ef2f07971..2f37c9808 100644--- a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap@@ -56,7 +56,7 @@ Arguments:Options:-b, --branch <BRANCH>- Branch to merge from (defaults to current worktree)+ Branch to merge (defaults to the current branch)--no-squashSkip commit squashing@@ -112,7 +112,7 @@ Global Options:-y, --yesSkip approval prompts-Unlike `git merge`, this merges the source branch into the target branch — not the target into current. Similar to clicking "Merge pull request" on GitHub, but locally. The source defaults to the current branch; the target defaults to the default branch.+Unlike `git merge`, this merges a source branch into the target branch, not the target into the current branch. Similar to clicking "Merge pull request" on GitHub, but locally. The source defaults to the current branch (`--branch` names another); the target defaults to the default branch.<!-- demo: wt-merge.gif 1600x900 | Creating a worktree, committing in it, and merging it away -->## Examplesdiff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snapindex 2c78a5a70..175ef531e 100644--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap@@ -56,7 +56,7 @@ Usage: [1m[36mwt merge[0m [36m[OPTIONS][0m [36m[TARGET][0m[1m[32mOptions:[0m[1m[36m-b[0m, [1m[36m--branch[0m[36m [0m[36m<BRANCH>[0m- Branch to merge from (defaults to current worktree)+ Branch to merge (defaults to the current branch)[1m[36m--no-squash[0mSkip commit squashing@@ -112,7 +112,7 @@ Usage: [1m[36mwt merge[0m [36m[OPTIONS][0m [36m[TARGET][0m[1m[36m-y[0m, [1m[36m--yes[0mSkip approval prompts-Unlike [2mgit merge[0m, this merges the source branch into the target branch — not the target into current. Similar to clicking "Merge pull request" on GitHub, but locally. The source defaults to the current branch; the target defaults to the default branch.+Unlike [2mgit merge[0m, this merges a source branch into the target branch, not the target into the current branch. Similar to clicking "Merge pull request" on GitHub, but locally. The source defaults to the current branch ([2m--branch[0m names another); the target defaults to the default branch.[1m[32mExamples[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_merge_short.snap b/tests/snapshots/integration__integration_tests__help__help_merge_short.snapindex 44913da42..f98b2de18 100644--- a/tests/snapshots/integration__integration_tests__help__help_merge_short.snap+++ b/tests/snapshots/integration__integration_tests__help__help_merge_short.snap@@ -50,7 +50,7 @@ Usage: [1m[36mwt merge[0m [36m[OPTIONS][0m [36m[TARGET][0m[36m[TARGET][0m Target branch[1m[32mOptions:[0m- [1m[36m-b[0m, [1m[36m--branch[0m[36m [0m[36m<BRANCH>[0m Branch to merge from (defaults to current worktree)+ [1m[36m-b[0m, [1m[36m--branch[0m[36m [0m[36m<BRANCH>[0m Branch to merge (defaults to the current branch)[1m[36m--no-squash[0m Skip commit squashing[1m[36m--no-commit[0m Skip commit and squash[1m[36m--no-rebase[0m Skip rebase; require the target to fast-forward to the resulting tipdiff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snapindex e87df4618..ef598d639 100644--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap@@ -185,7 +185,7 @@ Unix only; on Windows [2m--reap[0m is rejected.[1m[32mJSON output[0m-[2m--format=json[0m prints one object per removal to stdout: [2m{kind, branch, path, branch_outcome, branch_checked_out_at}[0m for a worktree, with [2mpruned[0m in place of [2mpath[0m for a branch-only removal. Branch-only results also include [2mdetached_worktree[0m: the path of a detached worktree left behind, or [2mnull[0m.+[2m--format=json[0m prints one object per removal to stdout: [2m{kind, branch, path, branch_outcome, branch_checked_out_at}[0m for a worktree, with [2mpruned[0m in place of [2mpath[0m for a branch-only removal. Branch-only results also include [2mdetached_worktree[0m: the path of a detached worktree at the branch's expected location, which the removal leaves in place, or [2mnull[0m.[2mbranch_outcome[0m names what happened to the branch, so a caller can tell a deletion the removal declined from one it was never asked to make:diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex b4dad3430..e820627f8 100644--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap@@ -184,7 +184,7 @@ If the branch already has a worktree, [2mwt switch[0m changes directories to i[107m [0m [2m[0m[2m[34mwt[0m[2m switch ../dark-mode # Switch by path...[0m[107m [0m [2m[0m[2m[34mwt[0m[2m switch feature/JIRA-1234 # ...or by branch[0m-Worktrunk finds the worktree from git's own records, so commands reach it by branch or path as usual. [2mwt list[0m marks it [2m⚐[0m, since it isn't at the path its branch implies, and [2mwt step relocate[0m offers to move it back to the template path.+Other commands reach it by branch or path as usual. [2mwt list[0m marks it [2m⚐[0m, since it isn't at the path its branch implies, and [2mwt step relocate[0m offers to move it back to the template path.[1m[32mNaming a worktree[0m@@ -256,7 +256,7 @@ The comparison base is the merge-base with the default branch, or with its upstr[107m [0m [2m[36m[switch.picker][0m[107m [0m [2mpager = [0m[2m[32m"delta --paging=never --width=$COLUMNS"[0m-[1mStarting list-only:[0m Set [2mpreview = false[0m under [2m[switch.picker][0m to open the picker with the preview hidden; [2mAlt-p[0m still shows it.+[1mHiding the preview:[0m Set [2mpreview = false[0m under [2m[switch.picker][0m to open the picker with the preview hidden; [2mAlt-p[0m still shows it.[1m[32mPull requests and merge requests[0m