Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: cut internals, edge-case mechanics, and deprecated behavior (#4157)
Maximilian Roos7649c7057e49
diff --git a/dev/config.example.toml b/dev/config.example.tomlindex bb13b969f..8cd3eb504 100644--- a/dev/config.example.toml+++ b/dev/config.example.toml@@ -133,14 +133,11 @@# A selection mixes built-ins with custom columns (#custom-columns), each named# by its `[list.custom-columns]` header (`columns = ["branch", "Ticket", "ci"]`),# and is exhaustive: only the listed columns render. Omit `columns` to keep the-# default set, where custom columns append automatically. A built-in name wins a-# header collision; the gutter type indicator always shows.+# default set, where custom columns append automatically.#-# Listing a column forces it on, space permitting: `ci` shows without `--full`,-# since `--full` only bundles columns into the default table rather than gating a-# named one. A column whose data source is missing still stays hidden — `summary`-# needs an LLM command (`[commit.generation]`), `url` needs a `[list] url`-# template — since listing can't supply the data.+# Listing a column forces it on, space permitting: `ci` shows without `--full`. A+# column whose data source is missing still stays hidden — `summary` needs an LLM+# command (`[commit.generation]`), `url` needs a `[list] url` template.## #### Custom columns [experimental]#@@ -262,7 +259,7 @@## Every matching entry applies, least- to most-specific, following the rule above: a more specific entry — `git.company.example/platform/*` over `git.company.example/*` — wins where both set the same setting, while hooks and aliases from every matching entry all run, least-specific first. A literal key is the most specific of all; specificity is the count of non-`*` characters in the key. End a host-wide key with `/*` — a bare `git.company.example*` also covers hosts whose names merely start with that string.#-# `approved-commands` matches the same way, so a pattern entry approves its commands for every repository it covers. Only a key written by hand is ever a pattern: `wt config approvals add` and the interactive prompt record under the exact identifier, and `wt config approvals clear` removes only that exact entry, leaving a pattern other repositories share intact.+# Entries in `approvals.toml` match the same way, so a hand-written pattern entry approves its commands for every repository it covers.## #### Forge platform and hostname#@@ -272,9 +269,9 @@# forge.platform = "gitlab" # or "github", "gitea" (experimental), "azure-devops" (experimental)# forge.hostname = "api.git.company.example" # API host, when the remote's own host isn't it#-# Both fields describe the host rather than the repository, which is why a pattern keyed to a hostname suits them, and why an SSH alias resolved through `~/.ssh/config` — where the name in the remote URL is local to one machine — belongs here rather than in a repository's committed config. A repository's own `[forge]` block still wins over any entry here, field by field: a repository that sets only `platform` still takes a matching entry's `hostname`.+# A repository's own `[forge]` block still wins over any entry here, field by field.#-# Hooks support all three hook forms (https://worktrunk.dev/hook/#hook-forms). A table runs multiple commands concurrently; an array-of-tables pipeline runs steps in sequence. The dotted-key examples below are equivalent to the table forms — TOML treats `projects."github.com/user/repo".post-start.server = "..."` and a `[projects."github.com/user/repo".post-start]` table the same way:+# Hooks support all three hook forms (https://worktrunk.dev/hook/#hook-forms). A table runs multiple commands concurrently; an array-of-tables pipeline runs steps in sequence:## # Single command# [projects."github.com/user/repo"]@@ -409,7 +406,7 @@# - Explain the rationale in the body, not just the change# """#-# How the fragment renders, and the project-config counterpart: the LLM commits guide (https://worktrunk.dev/llm-commits/#appending-to-the-prompt).+# See the LLM commits guide (https://worktrunk.dev/llm-commits/#appending-to-the-prompt) for how the fragment renders and its project-config counterpart.## ## User hooks#diff --git a/dev/wt.example.toml b/dev/wt.example.tomlindex 744dc3356..cbec4d5f5 100644--- a/dev/wt.example.toml+++ b/dev/wt.example.toml@@ -39,7 +39,7 @@# - Reference the relevant issue ID in the body# """#-# The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in user config (https://worktrunk.dev/config/), since they describe per-developer environment (which CLI is installed, which agent the developer prefers). How the fragment renders: the LLM commits guide (https://worktrunk.dev/llm-commits/#appending-to-the-prompt).+# The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in user config (https://worktrunk.dev/config/). See the LLM commits guide (https://worktrunk.dev/llm-commits/#appending-to-the-prompt) for how the fragment renders.## ## Copy-ignored excludes#diff --git a/docs/src/content/docs/claude-code.md b/docs/src/content/docs/claude-code.mdindex 720f32a61..3e60aa2b3 100644--- a/docs/src/content/docs/claude-code.md+++ b/docs/src/content/docs/claude-code.md@@ -55,7 +55,7 @@ codex plugin add worktrunk@worktrunkwt config plugins opencode install```-This writes the activity-tracking plugin to OpenCode's global plugins directory, `~/.config/opencode/plugins/worktrunk.ts` (honoring `$OPENCODE_CONFIG_DIR` and `$XDG_CONFIG_HOME`). `wt config plugins opencode uninstall` removes it. The one file covers both plugin runtimes — OpenCode 2 loads its `setup` export, OpenCode 1.16 and later its `server` export.+This writes the activity-tracking plugin to OpenCode's global plugins directory, `~/.config/opencode/plugins/worktrunk.ts` (honoring `$OPENCODE_CONFIG_DIR` and `$XDG_CONFIG_HOME`). `wt config plugins opencode uninstall` removes it.### Pi@@ -63,7 +63,7 @@ This writes the activity-tracking plugin to OpenCode's global plugins directory,wt config plugins pi install```-This writes the activity extension to `~/.pi/agent/extensions/worktrunk.ts`, where Pi discovers it on startup; `$PI_CODING_AGENT_DIR` replaces the agent directory. Pi has no profile concept. `wt config plugins pi uninstall` removes the extension.+This writes the activity extension to `~/.pi/agent/extensions/worktrunk.ts`, where Pi discovers it on startup; `$PI_CODING_AGENT_DIR` replaces the agent directory. `wt config plugins pi uninstall` removes the extension.### oh-my-pi@@ -136,12 +136,6 @@ Activity tracking is not plugin-specific. The plugins above only call `wt` on th| Agent finishes a turn and waits for input | `wt config state marker set "💬"` || Session ends | `wt config state marker clear` |-Three things to get right:--- **Run the command inside the worktree.** Each one resolves the branch from its working directory, so a hook that runs elsewhere marks the wrong branch, and one that runs outside a repository silently does nothing. Where the host pins the working directory elsewhere, pass the global `-C <worktree>`, which moves both the repository lookup and the branch resolution. `--branch <branch>` names the branch on its own, but the repository lookup still comes from the working directory — that, not a missing worktree argument, is why a caller pinned outside the repository needs `-C`. Elsewhere, a command that names a branch ([`wt switch`](/switch/), [`wt remove`](/remove/), `wt step diff --branch`) already names the worktree it acts on, and `-C` is for reaching a different repository rather than a different worktree.-- **Don't let a failed marker call fail the session.** Outside a repository both `set` and `clear` do nothing and exit 0, but an invalid `--branch` or a failed git config write still exits non-zero, and hosts differ on what a non-zero hook does. Append `|| true` (or the host's equivalent) to every call unless you want that surfaced.-- **Clear on exit.** A marker set on session start persists until something clears it, so pair every set with a clear on the host's session-end event — and expect the same stale marker as above if the process is killed first.-## Worktree isolation (Claude Code only)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.diff --git a/docs/src/content/docs/config.md b/docs/src/content/docs/config.mdindex 106cbe85d..d40b83e04 100644--- a/docs/src/content/docs/config.md+++ b/docs/src/content/docs/config.md@@ -226,14 +226,11 @@ Valid built-in names:A selection mixes built-ins with [custom columns](#custom-columns), each namedby its `[list.custom-columns]` header (`columns = ["branch", "Ticket", "ci"]`),and is exhaustive: only the listed columns render. Omit `columns` to keep the-default set, where custom columns append automatically. A built-in name wins a-header collision; the gutter type indicator always shows.+default set, where custom columns append automatically.-Listing a column forces it on, space permitting: `ci` shows without `--full`,-since `--full` only bundles columns into the default table rather than gating a-named one. A column whose data source is missing still stays hidden — `summary`-needs an LLM command (`[commit.generation]`), `url` needs a `[list] url`-template — since listing can't supply the data.+Listing a column forces it on, space permitting: `ci` shows without `--full`. A+column whose data source is missing still stays hidden — `summary` needs an LLM+command (`[commit.generation]`), `url` needs a `[list] url` template.#### Custom columns@@ -377,7 +374,7 @@ worktree-path = ".worktrees/{{ branch | sanitize }}"Every matching entry applies, least- to most-specific, following the rule above: a more specific entry — `git.company.example/platform/*` over `git.company.example/*` — wins where both set the same setting, while hooks and aliases from every matching entry all run, least-specific first. A literal key is the most specific of all; specificity is the count of non-`*` characters in the key. End a host-wide key with `/*` — a bare `git.company.example*` also covers hosts whose names merely start with that string.-`approved-commands` matches the same way, so a pattern entry approves its commands for every repository it covers. Only a key written by hand is ever a pattern: `wt config approvals add` and the interactive prompt record under the exact identifier, and `wt config approvals clear` removes only that exact entry, leaving a pattern other repositories share intact.+Entries in `approvals.toml` match the same way, so a hand-written pattern entry approves its commands for every repository it covers.#### Forge platform and hostname@@ -389,9 +386,9 @@ forge.platform = "gitlab" # or "github", "gitea" (experimentaforge.hostname = "api.git.company.example" # API host, when the remote's own host isn't it```-Both fields describe the host rather than the repository, which is why a pattern keyed to a hostname suits them, and why an SSH alias resolved through `~/.ssh/config` — where the name in the remote URL is local to one machine — belongs here rather than in a repository's committed config. A repository's own `[forge]` block still wins over any entry here, field by field: a repository that sets only `platform` still takes a matching entry's `hostname`.+A repository's own `[forge]` block still wins over any entry here, field by field.-Hooks support all three [hook forms](/hook/#hook-forms). A table runs multiple commands concurrently; an array-of-tables pipeline runs steps in sequence. The dotted-key examples below are equivalent to the table forms — TOML treats `projects."github.com/user/repo".post-start.server = "..."` and a `[projects."github.com/user/repo".post-start]` table the same way:+Hooks support all three [hook forms](/hook/#hook-forms). A table runs multiple commands concurrently; an array-of-tables pipeline runs steps in sequence:```toml# Single command@@ -534,7 +531,7 @@ template-append = """"""```-How the fragment renders, and the project-config counterpart: [the LLM commits guide](/llm-commits/#appending-to-the-prompt).+See [the LLM commits guide](/llm-commits/#appending-to-the-prompt) for how the fragment renders and its project-config counterpart.## User hooks@@ -590,7 +587,7 @@ template-append = """"""```-The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in [user config](/config/), since they describe per-developer environment (which CLI is installed, which agent the developer prefers). How the fragment renders: [the LLM commits guide](/llm-commits/#appending-to-the-prompt).+The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in [user config](/config/). See [the LLM commits guide](/llm-commits/#appending-to-the-prompt) for how the fragment renders.## Copy-ignored excludes@@ -667,9 +664,6 @@ $ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge| `WORKTRUNK_SYSTEM_CONFIG_PATH` | Override system config file location || `WORKTRUNK_PROJECT_CONFIG_PATH` | Override project config file location (defaults to `.config/wt.toml`); relative paths resolve from the worktree root || `XDG_CONFIG_DIRS` | Colon-separated system config directories (default: `/etc/xdg`) |-| `WORKTRUNK_DIRECTIVE_CD_FILE` | Internal: set by shell wrappers. wt writes a raw path; the wrapper `cd`s to it |-| `WORKTRUNK_SHELL_CWD` | Internal: set by wt on alias and hook bodies, so a nested `wt` preserves the user's subdirectory |-| `WORKTRUNK_COMPLETE_NAME` | Internal: set by shell wrappers to the command name completions register under (defaults to the binary name) || `WORKTRUNK_MAX_CONCURRENT_COMMANDS` | Max parallel git commands (default: 32). Lower if hitting file descriptor limits. || `WORKTRUNK_VERBOSE` | Verbosity level (`0`/`1`/`2`), like `-v`/`-vv` but applied everywhere — including shell completion, which no flag can reach || `RUST_LOG` | Logging directive (e.g. `worktrunk=debug`); overrides the verbosity baseline for what reaches stderr |@@ -902,7 +896,7 @@ Approved commands are saved to `~/.config/worktrunk/approvals.toml`. Re-approval`state` is `no_commands` (the project declares none), `approval_required` (at least one is unapproved), or `approved`. `name` is absent for an unnamed command and for the commit-template fragment.-`stale` is separate rather than a fourth `state`, because it co-occurs with all three: these are approvals recorded earlier whose command has since been edited or removed from the project config. They are what `--yes` would silently re-approve, so an orchestrator preserving the approval model reads them before choosing that flag.+`stale`, which can accompany any `state`, lists approvals whose command has since been edited or removed from the project config.### Command reference@@ -1041,7 +1035,7 @@ View or drop worktrunk's regenerable caches in one place. Everything here is reb### What's cached-- **CI status** — GitHub/GitLab CI per branch (30–60s TTL), shown in [`wt list`](/list/#ci-status), plus the largest PR/MR number seen (sizes the CI column)+- **CI status** — GitHub/GitLab CI per branch (30–60s TTL), shown in [`wt list`](/list/#ci-status)- **Summaries** — LLM-generated branch summaries (`wt list --full`, `wt switch` preview)- **Git commands** — cached merge-tree, ancestry, diff-stat, and `wt switch` preview results- **Hints** — one-time hints already shown in this repo@@ -1097,20 +1091,16 @@ In a hook or alias template, prefer the `{{ default_branch }}` [template variablWithout a subcommand, runs `get`. `set` stores the override in the repository's local git config. The override adds no project file and applies to every linked worktree in the clone. `clear` then `get` re-detects. The branch must exist locally for `wt list` comparisons.-`default-branch get` resolves the value and caches it on a miss; the aggregate `wt config state get` only reports the cache (read-only), so it can show `(none)` until something populates it.-### DetectionWorktrunk detects the default branch automatically:1. **Worktrunk cache** — Checks `git config worktrunk.default-branch`2. **Git cache** — Detects primary remote and checks its HEAD (e.g., `origin/HEAD`)-3. **Remote query** — If not cached, queries `git ls-remote` — typically 100ms–2s, abandoned after 10s+3. **Remote query** — If not cached, queries `git ls-remote`, giving up after 10s4. **Local inference** — If no remote, or the query was abandoned, infers from local branches-Once detected, the result is cached in `worktrunk.default-branch` for fast access. The cache isn't re-validated on every command, so a later change to `origin/HEAD` — a renamed default branch followed by `git remote set-head origin -a` — isn't picked up automatically. `wt config state` flags the drift when the cached value differs from the remote's local HEAD — expected for a deliberate override; `set` adopts the new branch and `clear` re-detects.--An abandoned remote query is the one case that isn't cached: the branch it inferred locally answers that command, but a value guessed while the remote was unreachable would otherwise become permanent, so the next command queries again.+Once detected, the result is cached in `worktrunk.default-branch` — except a value inferred after the remote query was abandoned, so an outage can't make a guess permanent. A later change to `origin/HEAD` isn't picked up automatically: `wt config state` flags the mismatch, `set` adopts the new branch, and `clear` re-detects.The local inference fallback uses these heuristics in order:- If only one local branch exists, uses it@@ -1171,7 +1161,7 @@ Hook output lives in per-branch subtrees under `.git/wt/logs/{branch}/`:| Background hooks | `{branch}/{source}/{hook-type}/{name}.log` || Background removal | `{branch}/internal/remove.log` |-All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is `user` or `project`. Branch and hook names are sanitized for filesystem safety (invalid characters → `-`; short collision-avoidance hash appended). Same operation on same branch overwrites the previous log. Removing a branch clears its subtree; orphans from deleted branches can be swept with `wt config state logs clear`.+All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is `user` or `project`. Branch and hook names are sanitized for filesystem safety. Same operation on same branch overwrites the previous log. Removing a branch clears its subtree; orphans from deleted branches can be swept with `wt config state logs clear`.#### Diagnostic files@@ -1182,11 +1172,11 @@ All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the| `subprocess.log` | Running with `-vv` || `diagnostic.md` | Running with `-vv` |-`trace.log` is the human-readable trace at `-vv` — each command's start (`$ …`) and completion (`✓`/`✗ … 12.3ms`), in-process spans, milestones, and bounded subprocess previews. `trace.jsonl` is the same event stream as one JSON object per line, for machines (`jq`, chrome://tracing); `wt config state logs profile` reads it to summarize a performance report (where time went, parallelism, redundant commands). `subprocess.log` holds the raw uncapped subprocess stdout/stderr bodies. `diagnostic.md` is a markdown bug-report bundle that leads with that same performance profile and inlines `trace.log`; `wt` prints a `gh gist create` command pointing at it. All four are overwritten on each `-vv` run.+`trace.log` is the human-readable trace of commands and their timings. `trace.jsonl` holds the same events as JSON lines, which `wt config state logs profile` summarizes into a performance report. `subprocess.log` holds full subprocess output. `diagnostic.md` is a bug-report bundle; `wt` prints a `gh gist create` command for it. All four are overwritten on each `-vv` run.### Location-All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory. Top-level files are shared logs (command audit + diagnostics); top-level directories are per-branch log trees.+All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory.### Structured output@@ -1240,36 +1230,6 @@ Output:Output format (text, json) [default: text]```-## wt config state ci-status--CI status cache.--**Deprecated** — the CI status cache is now part of [`wt config state cache`](/config/#wt-config-state-cache). This subcommand still works but prints a deprecation notice.--Status values, display symbols, and fetch behavior: [`wt list` CI status](/list/#ci-status).--Without a subcommand, runs `get` for the current branch. Use `clear` to reset cache for a branch or `clear --all` to reset all.--### Command reference--```text wt-command-reference-wt config state ci-status - CI status cache--Usage: wt config state ci-status [OPTIONS] [COMMAND]--Commands:- get Get CI status for a branch- clear Clear CI status cache--Options:- -h, --help- Print help (see a summary with '-h')--Output:- --format <FORMAT>- Output format (text, json) [default: text]-```-## wt config state markerBranch markers.@@ -1378,7 +1338,7 @@ dev = "npm start -- --port {{ vars.config.port }}"### Storage format-Stored in git config as `worktrunk.state.<branch>.vars.<key>`. Keys must contain only letters, digits and hyphens — dots conflict with git config's section separator, underscores with its variable name format.+Stored in git config as `worktrunk.state.<branch>.vars.<key>`. Keys may contain only letters, digits, and hyphens.### Command referencediff --git a/docs/src/content/docs/extending.md b/docs/src/content/docs/extending.mdindex 0719c53e9..1ab6cc74d 100644--- a/docs/src/content/docs/extending.md+++ b/docs/src/content/docs/extending.md@@ -156,14 +156,12 @@ git fetch --all --prune; wt step for-each -- sh -c '`wt up` fetches every remote, then brings each worktree up to date with its upstream: skip if there is no upstream or a rebase is already in progress, fast-forward if a tracked file is modified or staged, otherwise rebase, aborting on conflict. It rebases onto git-native `@{u}` rather than a `{{ … }}` template, so git resolves each worktree's own upstream and there is nothing to defer.-A sweep finds each worktree in whatever state you left it, so most of the script is guards:+Two details matter when adapting it:-- `git fetch --all` exits non-zero when any single remote fails. With `&&`, one remote with lapsed credentials is enough to skip the whole sweep, so even worktrees whose refs fetched fine go unrebased. With `;` the sweep runs on what did fetch, and the fetch error still prints.-- `git rebase` refuses to run in a worktree with a modified or staged tracked file, whether or not there is anything to rebase — so a worktree you are editing would fail the sweep. `git merge --ff-only` is the piece of the rebase git will still do there: it advances a branch that is simply behind, and otherwise changes nothing — a diverged branch, or an incoming file that collides with your edits, leaves the worktree exactly as it was, with the reason printed. Untracked files trigger neither the refusal nor the `git diff` guard, so a worktree carrying only new files still rebases — unless one of them has the same name as a file the incoming commits add, which git declines to overwrite.-- `rebasing` tells the two ways `git rebase` fails apart. Conflicting partway leaves a rebase in progress, which the abort winds back. Refusing to start — a tracked file modified under you, an untracked file in the way of an incoming one, a `pre-rebase` hook saying no — leaves nothing to abort and nothing to clean up, so the sweep moves on; an unconditional `git rebase --abort` there would answer `fatal: no rebase in progress` and exit 128 in place of git's own message.-- Both arms pass `--no-autostash`, because a global `rebase.autostash` or `merge.autostash` breaks what each arm relies on. An autostash that pops with conflicts leaves the markers in the worktree and still exits 0, so the sweep would report success on a worktree it had just left in conflict — and an autostashed tree is momentarily clean, so a fast-forward that should have refused goes through and the collision lands on the pop instead.+- `;` after the fetch lets the sweep run even when one remote fails to fetch.+- `--no-autostash` overrides a global `rebase.autostash` or `merge.autostash`, whose conflicting pop would leave markers behind and still exit 0.-So the sweep exits non-zero only when it leaves a worktree needing attention — an abort that itself failed. Everything git declines to do, it declines atomically, and the sweep carries on to the next worktree with git's reason in the output. That matters where the alias is a hook step, since a failing step stops the rest of the pipeline.+The sweep exits non-zero only when it leaves a worktree needing attention, which matters when the alias runs as a hook step: a failing step stops the rest of the pipeline.### Recipe: move or copy in-progress changes to a new worktree@@ -237,7 +235,6 @@ Aside from the differences below, hooks and aliases behave the same.| Reach `{{ args }}` from positionals | Must use `--` (`wt hook pre-merge -- extra`) | Any bare positional lands there || Approval skip flag | Post-subcommand `--yes` / `-y` supported (`wt hook pre-merge --yes`) | Only the global form (`wt -y <alias>`); post-alias `--yes` falls through to `{{ args }}` || Source discrimination | `user:` / `project:` / `user:name` / `project:name` filter syntax | Run user first, then project; no filter syntax |-| Force-bind escape | `--var KEY=VALUE` (deprecated in favor of `--KEY=VALUE`, but still force-binds) | None; smart routing is the only path || `--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 | All template variables as JSON (parse with `json.load(sys.stdin)`) | Inherits parent stdin (pipes pass through; interactive TUIs like `wt switch` keep the tty) |diff --git a/docs/src/content/docs/faq.md b/docs/src/content/docs/faq.mdindex e1f1acf90..f33c845bf 100644--- a/docs/src/content/docs/faq.md+++ b/docs/src/content/docs/faq.md@@ -212,10 +212,10 @@ A branch checked out in a second worktree is retained regardless, `-D` included.### Other cleanup- `wt merge` / `wt step push` — the target branch's checked-out worktree is updated to the merged commits, so a file those commits delete disappears from it, and an ignored file at a path they track is overwritten — the same result a `git merge` run in that worktree would produce. Uncommitted changes at paths the merge doesn't touch stay in place, staged or not; one at a path it does touch refuses the merge upfront, naming the file-- `wt remove` — besides the worktree being removed, two cleanup mechanisms run. The removed worktree's own `git fsmonitor--daemon` (git's per-worktree filesystem watcher under `core.fsmonitor=true`, which would leak once its worktree is gone) is sent `git fsmonitor--daemon stop`, then force-terminated (`SIGTERM`, then `SIGKILL`) via the PID resolved from its IPC socket if it didn't exit. A background sweep then deletes `.git/wt/trash/` entries older than 24 hours (directories orphaned when a previous background removal was interrupted) and terminates fsmonitor daemons whose worktree no longer exists (orphans from `git worktree remove`, `rm -rf`, or a crashed `wt`)+- `wt remove` — also stops the removed worktree's `git fsmonitor--daemon` (under `core.fsmonitor=true`), and sweeps `.git/wt/trash/` entries older than 24 hours along with fsmonitor daemons whose worktree no longer exists- `wt config state clear` — removes all worktrunk data from `.git/` (config keys, caches, markers, hints, variables, logs, stale trash)-- `wt config shell install` — when migrating an integration to a new location, removes the file left at the old one: fish `conf.d/wt.fish` (now `functions/wt.fish`) and nushell wrappers stranded under `<config-dir>/vendor/autoload` (now `<data-dir>/vendor/autoload`). The old path is where worktrunk's own wrapper lived and is named after the command being installed, so it's taken back whole without reading it — a `conf.d/wt.fish` left in place would be sourced at startup and shadow the new wrapper anyway. Only that exact filename is touched, and each removal is printed. The same rule covers the path being installed to, so an existing `functions/wt.fish`, `completions/wt.fish`, or `wt.nu` is replaced whole; [Files created](/shell-integration/#files-created) names the file each shell gets-- `wt config shell uninstall` — removes integration lines from bash/zsh/PowerShell rc files, and deletes worktrunk's wrapper and completion files (fish `functions/`, `conf.d/`, and `completions/`; nushell `vendor/autoload`). Uninstall takes no command name, so it lists those directories and recognizes files by worktrunk's own content markers, whatever binary name they were installed under; files without the markers are left alone. An rc file belongs to the user, so a line qualifies only where it runs the init command: one that merely mentions it, inside a comment, an `echo`, or an alias body, stays. Every line uninstall does take is printed, before removal and again after+- `wt config shell install` — replaces an existing fish or Nushell wrapper file whole, and removes one an older version installed at a previous location (fish `conf.d/wt.fish`, Nushell `<config-dir>/vendor/autoload/wt.nu`), printing each removal; [Files created](/shell-integration/#files-created) names the file each shell gets+- `wt config shell uninstall` — removes the lines that run `wt config shell init` from bash/zsh/PowerShell rc files, and deletes wrapper and completion files carrying worktrunk's content markers (fish `functions/`, `conf.d/`, and `completions/`; nushell `vendor/autoload`). Every removed line is printed- `wt config plugins opencode uninstall` / `wt config plugins pi uninstall` / `wt config plugins omp uninstall` — deletes that agent's `worktrunk.ts` plugin file. Only worktrunk's own file is touched; the rest of the agent's plugin directory is left aloneSee [What files does Worktrunk create?](#what-files-does-worktrunk-create) for details.@@ -250,7 +250,7 @@ Use `--yes` to bypass prompts (useful for CI/automation).### Command log-All hook executions and LLM commands are recorded in `.git/wt/logs/commands.jsonl` — one JSON object per line. Fields: `ts` (timestamp), `wt` (the wt command that triggered it), `label` (what ran, e.g., `pre-merge user:lint`), `cmd` (shell command), `exit` (exit code, `null` for background), `dur_ms` (duration, `null` for background). The file rotates to `commands.jsonl.old` at 1MB, bounding storage to ~2MB.+All hook executions and LLM commands are recorded in `.git/wt/logs/commands.jsonl`, one JSON object per line; [`wt config state logs`](/config/#wt-config-state-logs) lists the fields.View the log with `wt config state logs get`, or query directly:@@ -270,7 +270,7 @@ Yes. Core commands, shell integration, and tab completion work in both Git Bash**Git for Windows required** — Hooks use bash syntax and execute via Git Bash, so [Git for Windows](https://gitforwindows.org/) must be installed even when PowerShell is the interactive shell.-The `wt switch` interactive picker runs on Windows too, on [skim](https://github.com/skim-rs/skim)'s crossterm backend.+The `wt switch` interactive picker runs on Windows too.## How does Worktrunk determine the default branch?@@ -294,7 +294,7 @@ Installing with Cargo and the default features also requires a C99 compiler forcargo install worktrunk --no-default-features --features cli```-This disables bash syntax highlighting in command output but keeps all core functionality. The syntax highlighting feature requires C99 compiler support and can fail on older systems or minimal Docker images.+This disables bash syntax highlighting in command output but keeps all core functionality.## How can I contribute?diff --git a/docs/src/content/docs/hook.md b/docs/src/content/docs/hook.mdindex 8d1cadd92..f5611ef74 100644--- a/docs/src/content/docs/hook.md+++ b/docs/src/content/docs/hook.md@@ -37,7 +37,7 @@ The most common creation hook is `post-start` — it runs background tasks (dev| `pre-remove` | Cleanup before worktree deletion: saving test artifacts, backing up state. Runs in the worktree being removed || `post-remove` | Stopping dev servers, removing containers, notifying external systems. Template variables reference the removed worktree |-During `wt merge`, the blocking hooks run in this order: pre-commit → pre-merge → pre-remove. The `post-*` hooks all start together once the merge finishes, each in the worktree it is anchored on — post-merge, post-switch and post-remove in the destination, post-commit in the worktree the commit was made in. A merge that removes that worktree reports `post-commit` as skipped instead of running it — the worktree is gone by the time the hook would start. Use `pre-remove` for work that must finish there, or `--no-remove` to keep the worktree. See [`wt merge`](/merge/#pipeline) for the complete pipeline.+During `wt merge`, the blocking hooks run in this order: pre-commit → pre-merge → pre-remove. The `post-*` hooks start together once the merge finishes. See [`wt merge`](/merge/#pipeline) for the complete pipeline.# Security@@ -99,7 +99,7 @@ server = "npm run dev"Here `install` runs first, then `build` and `server` run together.-Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Because an earlier step can still change those values, a preview stands the reference in for its value instead of resolving it: `wt hook <type> --dry-run` and `wt hook show --expanded` render `{{ vars.thing | default('none') }}` as `{{ vars.thing }}` — the reference is defined, so the `default` never fires — while every other variable expands. A filter that transforms its input still runs, against the placeholder text, and its output is shell-escaped like any other value: `{{ vars.thing | upper }}` previews as `'{{ VARS.THING }}'`.+Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Previews (`wt hook <type> --dry-run`, `wt hook show --expanded`) leave `{{ vars.* }}` references unexpanded for that reason.Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependency chain — typically setup that must complete before later steps, like installing dependencies before running a build and dev server concurrently.@@ -163,9 +163,9 @@ All hooks share the same perspective — `{{ branch | hash_port }}` produces the`cwd` is the worktree root where the hook command runs. It equals `worktree_path` except in three cases:-- `pre-switch`: hook runs in the source worktree; `worktree_path` is the destination when that worktree already exists — a switch that creates one has no destination directory yet, so `worktree_path` stays on the source (use `pre-start` to work in the new worktree)+- `pre-switch`: hook runs in the source worktree; `worktree_path` is the destination, or the source when the switch creates a new worktree (use `pre-start` to work in the new worktree)- `post-remove`: the active worktree is gone, so the hook runs in the primary worktree-- `post-merge`: the hook runs in the target branch's worktree (the primary worktree if the target has none), including under `--no-remove`, where the merged worktree `worktree_path` names is still on disk+- `post-merge`: the hook runs in the target branch's worktree (the primary worktree if the target has none)Undefined variables error — use conditionals or defaults for optional behavior:@@ -175,7 +175,7 @@ Undefined variables error — use conditionals or defaults for optional behaviorsync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"```-A detached worktree is on no branch, so `branch` is undefined there — as are the `base` and `target` names derived from it, whether by a manual `wt hook` or by an operation whose source or destination worktree is detached (`base` in a `pre-switch` fired from one, `target` in a removal that lands in one) — and the same `{% if branch %}` guard applies. This matches `wt list --format=json`, which reports `branch: null` for the same worktree.+A detached worktree has no branch, so `branch` — and a `base` or `target` that names that worktree — is undefined there; guard with `{% if branch %}`.Run any hook-firing command with `-v` to see the resolved variables for the actual invocation — each hook prints a `template variables:` block showing every in-scope variable and its value (`(unset)` for conditional vars that didn't populate, like `target_worktree_path` during `wt switch -`). Aliases do the same under `-v`: `wt -v <alias>` prints the alias's in-scope variables before the pipeline runs.@@ -267,7 +267,7 @@ if ctx.get('branch', '').startswith('feature/') and 'backend' in ctx['repo']:## Copying untracked files-One specific command worth calling out: [`wt step copy-ignored`](/step/#wt-step-copy-ignored). Git worktrees share the repository but not untracked files, and this copies gitignored files between worktrees:+Git worktrees share the repository but not untracked files. [`wt step copy-ignored`](/step/#wt-step-copy-ignored) copies gitignored files between worktrees:```toml[post-start]@@ -323,8 +323,6 @@ $ wt hook post-startAny `--KEY=VALUE` whose key isn't referenced by a hook template forwards into `{{ args }}` as a literal `--KEY=VALUE` token. Tokens after `--` also forward into `{{ args }}` verbatim. `{{ args }}` renders as a space-joined, shell-escaped string; index with `{{ args[0] }}`, loop with `{% for a in args %}…{% endfor %}`, count with `{{ args | length }}`.-The long form `--var KEY=VALUE` is deprecated but still supported. It force-binds regardless of whether any hook template references `KEY` — useful when a template only references the key conditionally (e.g. `{% if override %}…{% endif %}`).-# Recipes- [Eliminate cold starts](/tips-patterns/#eliminate-cold-starts): `wt step copy-ignored` in `post-start` shares build caches and dependencies; use a `[[post-start]]` pipeline when a later hook depends on the copydiff --git a/docs/src/content/docs/list.md b/docs/src/content/docs/list.mdindex 224993677..40bb3f800 100644--- a/docs/src/content/docs/list.md+++ b/docs/src/content/docs/list.md@@ -22,7 +22,7 @@ The table renders progressively: branch names, paths, and commit hashes appear i## Full mode-`--full` adds the two columns that reach off-machine: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail, over the network) and [LLM-generated summaries](#llm-summaries) of each branch's changes. The `main…±` line diffs are local git, so they show by default.+`--full` adds the two columns that reach off-machine: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail, over the network) and [LLM-generated summaries](#llm-summaries) of each branch's changes.## Examples@@ -77,7 +77,7 @@ $ wt list --format=json| Column | Shows ||--------|-------|-| Branch | Branch name, elided with `…` past 32 characters so one long name can't size the column for every row (`--format=json` keeps it whole); a detached worktree has none, so it shows its short hash in dim yellow |+| Branch | Branch name, elided with `…` past 32 characters; a detached worktree shows its short hash || Status | Compact symbols (see below) || HEAD± | Uncommitted changes, including untracked files: +added -deleted lines || main↕ | Commits ahead/behind default branch |@@ -94,9 +94,7 @@ $ wt list --format=jsonThe `main↕` and `main…±` headers keep the familiar `main` label in every repository.-The table sizes itself to the terminal. When the columns don't all fit, the least important go first — roughly right to left, since the order above runs from identity to nice-to-have — and the summary footer names them (`hidden: Commit, Age, Message`). A column with nothing to show on any row — `Remote⇅` in a repo with no remote — ranks below every populated column, so it goes first. A wider terminal brings them back. To pin a set rather than leave it to the width, name the columns in [`[list] columns`](/config/#list); `--format=json` carries every field at any width.--`main↕` and `main…±` measure against the default branch's upstream tip when the local copy lags it — so in a fork whose local `main` trails `origin/main`, a branch reads as ahead of the real mainline, not of a stale local checkout. The `↑`/`↓`/`↕` Status symbols derive from these counts, so they track the upstream tip too.+The table sizes itself to the terminal. When the columns don't all fit, the least important go first — roughly right to left, since the order above runs from identity to nice-to-have — and the summary footer names them (`hidden: Commit, Age, Message`). A wider terminal brings them back. To pin a set rather than leave it to the width, name the columns in [`[list] columns`](/config/#list); `--format=json` carries every field at any width.### Gutter@@ -112,7 +110,7 @@ The leftmost column marks each row by physical presence, from most present to le### CI status-The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and Azure DevOps, `!3035` on GitLab — colored by pipeline status, or a bare `#` when no number is available (e.g. branch workflows without a PR/MR). One color folds two JSON fields: green/blue/red/yellow/gray are the pipeline state, magenta/cyan the review state. The `Value` column names each state; [checks object](#checks-object) and [review states](#review-states) give the JSON spelling — schema 2 reports three of the pipeline values by the shape of `pr` and `checks` rather than as a `checks.status` string:+The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and Azure DevOps, `!3035` on GitLab — colored by pipeline status, or a bare `#` when no number is available (e.g. branch workflows without a PR/MR). Green, blue, red, yellow, and gray show the pipeline state; magenta and cyan show the review state. [checks object](#checks-object) and [review states](#review-states) give the JSON form of each value:| Indicator | Value | Meaning ||-----------|-------|---------|@@ -128,9 +126,9 @@ The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and AzThe two remaining review states have no indicator of their own: `"draft"` only dims the cell and `"approved"` leaves the color unchanged.-Color precedence resolves the fold: changes-requested (magenta) outranks running checks — waiting can't clear it — while an outstanding required review (cyan) only recolors an otherwise green or quiet branch. Cool colors mean waiting, warm colors mean act. An approved PR, or one with no review signal at all (no required reviewers and no reviews), keeps its plain pipeline color — `pr.review` is then `"approved"` or absent, respectively. GitLab MR data carries only `"pending"` and `"draft"` — no approved or changes-requested signal.+Changes requested (magenta) outranks running checks, while a required review (cyan) only recolors an otherwise green or gray branch. GitLab reports only the `"pending"` and `"draft"` review states.-CI cells are clickable links to the PR or pipeline page, and appear dimmed for a draft PR/MR (`"draft"`) or when unpushed local changes make the status stale (`checks.stale`). PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches — visible with `--remotes` — get CI status detection. Results are cached for 30-60 seconds; use `wt config state cache` to view or clear.+CI cells are clickable links to the PR or pipeline page, and appear dimmed for a draft PR/MR (`"draft"`) or when unpushed local changes make the status stale (`checks.stale`). Results are cached for 30-60 seconds; use `wt config state cache` to view or clear.### LLM summaries@@ -147,7 +145,7 @@ Each `[list.custom-columns]` entry in user config adds a column: the key is thetemplate = "{{ vars.ticket }}"```-A custom column that renders empty for every row is dropped from the table outright, rather than merely ranked last as an empty built-in is. Templates, widths, and drop priority: [custom columns config](/config/#custom-columns).+The [custom columns config](/config/#custom-columns) covers templates, widths, and drop priority.## Status symbols@@ -173,10 +171,10 @@ An in-progress git operation, a worktree-location attribute, or a branch with no|--------|------|---------|| `✘` | `worktree.changes.conflicted` | Merge conflicts || `↻` | `worktree.operation` `"rebase"`, `"merge"`, `"cherry_pick"`, `"revert"`, `"bisect"` | A git operation is in progress; `git status` names it |-| `⊟` | `worktree.prunable` | Prunable (worktree directory missing); nothing can be read from a directory that isn't there, so the row's data cells stay blank |+| `⊟` | `worktree.prunable` | Prunable (worktree directory missing) || `⊞` | `worktree.locked` | Locked worktree |-| `⊘` | `worktree.detached` | Detached HEAD — the worktree is on a commit, not a branch, which is why its Branch cell holds a short hash |-| `⚑` | `worktree.duplicate_branch` | Branch checked out in more than one worktree, so `wt` resolves it to whichever git lists first; every worktree on the branch is flagged |+| `⊘` | `worktree.detached` | Detached HEAD |+| `⚑` | `worktree.duplicate_branch` | Branch checked out in more than one worktree || `⚑` | `worktree.branch_mismatch` | Worktree isn't at the path its branch implies || `/` | no `worktree` object | Branch without a worktree |@@ -211,13 +209,10 @@ Relation to the tracking branch, derived from the `upstream.ahead` / `upstream.b### Marker-The last subcolumn carries the branch's own marker — whatever-[`wt config state marker set`](/config/#wt-config-state-marker) stored, usually-an emoji, which is why the subcolumn is two cells wide. Nothing in `wt` writes-it; it is there for agents and scripts to say what a branch is for, and it-reads back as the item's `marker` field. `wt config state marker set 🤖` on a-branch whose default-branch state is `_` renders `_ 🤖` in the column and-`"_🤖"` in `display.symbols`.+The last subcolumn shows the branch's marker, set with+[`wt config state marker set`](/config/#wt-config-state-marker) — usually an+emoji saying what the branch is for. It reads back as the item's `marker`+field.### Placeholder symbols@@ -379,7 +374,7 @@ Independent facts; the table's priority-collapsed symbol is `display.state`.| `number` | integer/null | PR/MR number || `url` | string/null | URL to the PR/MR page || `review` | string | Review state (see [review states](#review-states)); absent when the forge reports no review signal |-| `mergeable` | boolean/null | False when the forge reports conflicts, null otherwise — the fetch records only the conflicted case |+| `mergeable` | boolean/null | False when the forge reports conflicts, null otherwise || `repo` | object | Structured metadata for the repository the PR/MR targets, the upstream for fork PRs (see [repo object](#repo-object)); absent when the URL doesn't parse |### checks object@@ -443,7 +438,7 @@ The single highest-priority state describing the branch's relation to the defaul### review states-`pr.review` is one of `"changes_requested"`, `"pending"`, `"draft"`, `"approved"`, absent when the forge reports no review signal. The [CI status](#ci-status) section is the single source: its table maps the colored values, and the notes below it cover `"draft"` and `"approved"`. The vocabulary matches Claude Code's statusline `pr.review_state` field.+`pr.review` is one of `"changes_requested"`, `"pending"`, `"draft"`, `"approved"`, absent when the forge reports no review signal. [CI status](#ci-status) shows how each renders. The vocabulary matches Claude Code's statusline `pr.review_state` field.```console# Current worktree path (for scripts)@@ -473,8 +468,6 @@ $ wt list --format=json --full | jq '.items[] | select(.checks.stale) | .branch'A JSON Schema for the envelope is published at[worktrunk.dev/schema/list-v2.json](https://worktrunk.dev/schema/list-v2.json).-It describes what `wt` writes, so a field the absence rule can omit is-optional there rather than required-and-null.### Schema 1@@ -586,9 +579,9 @@ The line carries the same cells as the worktree's row in `wt list`. A stale CI s- `json`: the current [`wt list --format=json`](/list/#json-output) schema — a one-item envelope by default, or a one-item array with `[list] json-schema = 1`- `claude-code`: the `table` cells, preceded by `dir` and followed by `model context pace`-A cell with nothing to show is left out rather than blanked, so most lines are shorter than that; `claude-code` also drops `branch` where `dir` already ends in `.<branch>`. A line that still overruns the terminal drops whole cells, least important first, starting with the dev server URL.+A cell with nothing to show is left out, so most lines are shorter than that. A line that overruns the terminal drops whole cells, least important first.-The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both are underlined, which is what marks them as clickable. They are OSC 8 links, and a terminal that doesn't support those discards the escape, leaving the underlined text unclickable.+The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both are underlined terminal links.### Claude Code mode@@ -600,7 +593,7 @@ The CI reference links to its PR/MR, and a dev server URL carrying a port shows- `.rate_limits.{five_hour,seven_day}.used_percentage` — rate-limit window usage (0–100)- `.rate_limits.{five_hour,seven_day}.resets_at` — window reset time (Unix epoch seconds)-The pace segment appears only when usage is likely to hit a rate limit before its window resets, and shows the higher-risk window: `2.9×(Tue–Tue 5pm)` reads as 2.9× the pace that would exactly fill that window. Above 90% used it shows usage instead of pace — `93%(Tue–Tue 5pm)` — near the cap, how much is left matters more than how fast it's going. "Likely" is a Bayesian forecast; early-window bursts don't trigger it. Its colour deepens with severity — dim, then dim-yellow, then yellow — as the forecast lockout (how much of the window would be spent capped) grows, so a fast pace that would only tip over near the reset stays dim rather than alarming. With `-vv`, each window's inputs and projection are logged to `.git/wt/logs/trace.log`.+The pace segment appears only when usage is likely to hit a rate limit before its window resets, and shows the higher-risk window: `2.9×(Tue–Tue 5pm)` reads as 2.9× the pace that would exactly fill that window. Above 90% used it shows usage instead of pace — `93%(Tue–Tue 5pm)`. Its color deepens from dim to yellow as more of the window would be spent capped.[Claude Code statusline setup](/claude-code/#statusline-claude-code-only) has the `~/.claude/settings.json` entry that feeds this mode.diff --git a/docs/src/content/docs/merge.md b/docs/src/content/docs/merge.mdindex 33f1afb96..5949c5018 100644--- a/docs/src/content/docs/merge.md+++ b/docs/src/content/docs/merge.md@@ -77,7 +77,7 @@ $ wt merge --no-commit --no-rebase`wt merge` runs these steps:-1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background; when step 7 removes the worktree they are anchored on, the merge reports them rather than running them. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.+1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.3. **Rebase** — Rebases onto target, skipping when nothing needs replaying ([`wt step rebase`](/step/#wt-step-rebase) gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](/hook/).@@ -88,7 +88,7 @@ $ wt merge --no-commit --no-rebaseUse `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Combining both flags preserves the exact source graph and requires the target to be its ancestor. Useful after preparing commits manually with `wt step commit`. Requires a clean working tree.-`wt merge` targets the *local* default-branch ref and never fetches. When that ref lags its upstream — e.g. a primary checkout's `main` left behind `origin/main` — a branch based on the newer upstream tip is measured, squashed, and rebased against the upstream (so already-upstream commits are never folded into the squash), and the final fast-forward carries the local ref through the already-fetched upstream commits by their real SHAs. `wt step squash` and `wt step rebase` measure the same way. A local target that has *diverged* from its upstream — its own commits and behind — cannot fast-forward, so the merge is refused until the target is reconciled.+`wt merge` merges into the *local* target branch and never fetches.## Local CIdiff --git a/docs/src/content/docs/remove.md b/docs/src/content/docs/remove.mdindex 7b874a033..c99867896 100644--- a/docs/src/content/docs/remove.md+++ b/docs/src/content/docs/remove.md@@ -44,7 +44,7 @@ $ wt remove -D experimentalBy default, branches are deleted when they would add no changes to the default branch if merged. This works with both unchanged git histories, and squash-merge or rebase workflows where commit history differs but file changes match.-Worktrunk checks six conditions (in order of cost):+Worktrunk checks six conditions:1. **Same commit** — Branch HEAD equals the default branch. Shows `_` in `wt list`.2. **Ancestor** — Branch is in target's history (fast-forward or rebase case). Shows `⊂`.@@ -59,8 +59,6 @@ The 'same commit' check uses the local default branch; for other checks, 'targetBranches matching these conditions and with empty working trees are dimmed in `wt list` as safe to delete.-Those six ask whether deleting loses work. A branch checked out in a second worktree (only reachable via `git worktree add --force`) fails a different test: deleting the ref would leave that worktree unable to resolve `HEAD`, which is why `git branch -d` refuses the same delete. Such a branch is retained whatever `-D` asks, and the surviving checkout is named.-## Force flagsWorktrunk has two force flags for different situations:@@ -80,9 +78,7 @@ Use `--no-delete-branch` to keep the branch regardless of merge status.## Background removal-Removal runs in the background by default — the command returns immediately. The worktree is renamed into `.git/wt/trash/` (instant same-filesystem rename), git metadata is pruned, the branch is deleted, and a detached `rm -rf` finishes cleanup. Cross-filesystem worktrees fall back to `git worktree remove`. Logs: `.git/wt/logs/{branch}/internal/remove.log`. Use `--foreground` to run in the foreground.--After each `wt remove`, entries in `.git/wt/trash/` older than 24 hours are swept by a detached `rm -rf` — eventual cleanup for directories orphaned when a previous background removal was interrupted (SIGKILL, reboot, disk full).+Removal runs in the background by default — the command returns immediately, and output goes to `.git/wt/logs/{branch}/internal/remove.log`. Use `--foreground` to wait for it.## Reaping processes@@ -104,7 +100,7 @@ To avoid killing work the user did not mean to kill, two guards keep `--reap` co- **Interactive processes are spared.** A process holding a controlling terminal — an interactive shell, or a terminal editor such as `vim` with unsaved buffers — is never reaped. Only detached processes remain candidates.- **Discovery is by working directory only.** A process that started in the worktree and later changed directory, or a daemon that reparented to `init`, no longer reports a directory under the worktree and is not found. To reliably reap those, launch them with [`wt step tether`](/step/#wt-step-tether), which kills the whole process group when the worktree is removed.-Reaping runs before the worktree directory is touched, so it is independent of foreground/background removal and the `--force` flag. Unix only; on Windows `--reap` is rejected.+Unix only; on Windows `--reap` is rejected.## JSON output@@ -115,11 +111,11 @@ Reaping runs before the worktree directory is touched, so it is independent of f| Value | Meaning ||-------|---------|| `deleted` | The branch is gone |-| `deferred` | Handed to the detached background process, whose result this run never sees. `--foreground` never reports it |+| `deferred` | Left to the background removal, whose result this run doesn't see. `--foreground` never reports it || `not_attempted` | No deletion was tried: a detached worktree, a sibling checkout, or `--no-delete-branch` || `retained_unmerged` | Declined: the branch was not integrated into the target |-| `retained_checked_out` | Declined: the final topology read found a live worktree with it checked out |-| `retained_raced` | Refused by the compare-and-swap — the branch moved between the integration check and the delete. Re-read the ref and retry |+| `retained_checked_out` | Declined: another worktree has the branch checked out |+| `retained_raced` | Declined: the branch moved during the removal. Retry || `retained_failed` | The delete command itself failed |## Hooksdiff --git a/docs/src/content/docs/shell-integration.md b/docs/src/content/docs/shell-integration.mdindex 8cde50101..0f705a53a 100644--- a/docs/src/content/docs/shell-integration.md+++ b/docs/src/content/docs/shell-integration.md@@ -68,7 +68,7 @@ When shell integration isn't working, `wt switch` shows a warning explaining why### "shell wrapper is out of date"-**Meaning**: The active shell still has a retired wrapper loaded. Current versions no longer write to that wrapper's single directive file, so the parent shell cannot follow a directory change.+**Meaning**: The active shell has a wrapper from an older Worktrunk version loaded, which can't follow a directory change.**Fix**: Run `wt config shell install`, then restart the shell (or reload its config) to activate the current wrapper.@@ -243,8 +243,6 @@ eval "$(wt config shell init zsh)"### Windows Git Bash issues-Git Bash uses MSYS2, which automatically converts POSIX paths in environment variables. The directive file path is handled correctly without manual conversion.-If you see path issues, make sure you're on a recent Git for Windows version.## Environment variablesdiff --git a/docs/src/content/docs/step.md b/docs/src/content/docs/step.mdindex b0dd0a992..a0dcc3353 100644--- a/docs/src/content/docs/step.md+++ b/docs/src/content/docs/step.md@@ -113,7 +113,7 @@ See [LLM-generated commit messages](/llm-commits/) for configuration and prompt$ wt step commit --branch feature```-The branch must have a checked-out worktree. `--branch` re-roots the whole command: staging, hooks, and the commit all happen there. It selects the previewed worktree the same way, so `--dry-run` describes the commit the same flags would make.+The branch must have a checked-out worktree; staging, hooks, and the commit all happen there.### Hooks@@ -302,13 +302,9 @@ The first matching row wins:| The branch is an ancestor of the target, so it has no commits of its own | `Fast-forwarded to <target>` || Otherwise | The branch's commits replay onto the target's tip — refused outright if the two share no history |-A branch that merged the target into itself still rebases: the target is its ancestor, but the merge commit in between keeps the first row from applying.--When the target's local ref lags its upstream, the rows are measured against that upstream, which the result then names in place of the argument. [`wt merge`](/merge/) covers why.-### Conflicts-A conflicting commit leaves the rebase open rather than undoing it. The worktree keeps git's conflict markers, and the ways out are `git rebase --continue` once the conflict is resolved, `git rebase --skip`, or `git rebase --abort`. Until the rebase is settled, `wt step rebase`, `wt step squash`, `wt step push`, and `wt merge` refuse to run — as they do while any other git operation is open, a conflicted `git merge` included.+A conflicting commit leaves the rebase open rather than undoing it. The worktree keeps git's conflict markers, and the ways out are `git rebase --continue` once the conflict is resolved, `git rebase --skip`, or `git rebase --abort`. Until the rebase is settled, `wt step rebase`, `wt step squash`, `wt step push`, and `wt merge` refuse to run.### Command reference@@ -355,9 +351,7 @@ $ wt step push --no-ff # Merge commit instead of a fast-forward### Target worktree-When the target branch has a worktree of its own, that worktree's files move to the new commits too. Uncommitted changes there never move: the update carries any file the push doesn't touch — staged or not — exactly where it is, and a change touching a file the push does change is refused upfront, naming the file. If the sync can't be applied for any reason — a conflicting file appearing in the race window after the check, or a busy index — the update is rolled back whole, leaving branch and worktree as they were.--A worktree that is still registered but whose directory is gone is refused as well, since nothing can be synced into it — `git worktree prune` clears the registration.+When the target branch has a worktree of its own, that worktree's files move to the new commits too. Uncommitted changes there never move: the update carries any file the push doesn't touch — staged or not — exactly where it is, and a change touching a file the push does change is refused upfront, naming the file. If the update can't be applied, it is rolled back, leaving branch and worktree as they were.### Command reference@@ -421,18 +415,6 @@ The diff is pipeable to tools like `delta`:$ wt step diff | delta```-### How it works--Equivalent to:--```bash-cp "$(git rev-parse --git-dir)/index" /tmp/idx-GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .-GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))-```--`git diff` ignores untracked files. `git add --intent-to-add .` registers them in the index without staging their content, making them visible to `git diff`. This runs against a copy of the real index so the original is never modified.-### Command reference```text wt-command-reference@@ -530,18 +512,12 @@ Files are reflinked where the filesystem supports it: APFS (macOS), btrfs and XF| `cp -R` (full copy) | 2m | 14GB || `cp -Rc` / `wt step copy-ignored` | 20s | ~0 |-On ext4 and NTFS, which have no reflink, every file is copied in full. The same byte count therefore costs nothing on one filesystem and 14GB on the other, so the summary says which happened: `Copied 4,812 files · 14.0 GB (reflinked, no extra disk)`, against `(full copy)` where those bytes were written out.+On ext4 and NTFS, which have no reflink, every file is copied in full; the summary says `(reflinked, no extra disk)` or `(full copy)`.Reflinks are per file (like `cp -Rc`), so copy time scales with file count.Use the `post-start` hook so the copy runs in the background. Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.-### Background-hook priority (experimental)--When invoked from a background hook pipeline (`post-*` hooks), `wt step copy-ignored` self-lowers its CPU and I/O priority — `taskpolicy -b` on macOS, `nice -n 19` plus `ionice -c 3` on Linux — so it yields to interactive work. Foreground callers (`pre-*` hooks, direct interactive use) run at normal priority so the user isn't waiting on a throttled copy.--wt signals background-hook context by exporting `WORKTRUNK_FOREGROUND=-1` into every detached hook pipeline; `copy-ignored` inspects that variable on entry. The variable name is experimental and may change.-### Language-specific notes#### Rust@@ -693,7 +669,7 @@ Automation:Run command in each worktree. Executes sequentially with real-time output; continues past command failures.-A summary of successes and failures is shown at the end. A template-expansion error (a malformed `{{ … }}` argument) aborts the whole run; only command failures are tolerated and reported. Context JSON — a flat object of every template variable — is piped to stdin for scripts that need structured data.+A summary of successes and failures is shown at the end. Context JSON — a flat object of every template variable — is piped to stdin for scripts that need structured data.### Arguments@@ -797,8 +773,6 @@ Without an argument, promotes the current branch — or restores the default braGitignored files (build artifacts, `node_modules/`, `.env`) are swapped along with the branches so each worktree keeps the artifacts that belong to its branch. Files are discovered using the same mechanism as [`copy-ignored`](#wt-step-copy-ignored) and can be filtered with `.worktreeinclude`.-The swap uses `rename()` for each entry — fast regardless of entry size, since only filesystem metadata changes. If the worktree is on a different filesystem from `.git/`, it falls back to reflink copy.-### Command reference```text wt-command-reference@@ -850,7 +824,7 @@ $ wt step prune --min-age=2d # skip candidates younger than 2 days### JSON output-`--format=json` prints one object per candidate to stdout. The two modes report different things, and name their fields accordingly: a live run reports `branch_outcome`, the executed outcome, using the vocabulary [`wt remove`](/remove/#json-output) documents; `--dry-run` reports `branch_deleted`, its prediction of whether the removal would take the branch, since it runs nothing to have an outcome. A dry run also carries `reason` and `target` (why the candidate qualifies, and what it was measured against).+`--format=json` prints one object per candidate to stdout. A live run reports `branch_outcome`, as [`wt remove`](/remove/#json-output) does. `--dry-run` reports `branch_deleted` (whether the removal would delete the branch), `reason` (why the candidate qualifies), and `target` (what it was measured against).### Examples@@ -936,9 +910,8 @@ this by using a temporary location.### ClobberingWith `--clobber`, non-worktree paths at target locations are moved to-`<path>.bak.<timestamp>` before relocating. If that name is already taken,-the move counts up (`…-2`, `…-3`, …) until it finds a free name, so an-existing backup is never overwritten.+`<path>.bak.<timestamp>` before relocating, never overwriting an existing+backup.### Main worktree behavior@@ -982,8 +955,7 @@ Options:--clobberBackup non-worktree paths at target locations- Moves blocking paths to <path>.bak.<timestamp>. If that name is taken, counts up (…-2, …-3- , …) to a free name.+ Moves blocking paths to <path>.bak.<timestamp>.-h, --helpPrint help (see a summary with '-h')@@ -1029,9 +1001,7 @@ For pipes, redirects, variables, or globs, wrap in `sh -c`:$ wt step tether -- sh -c 'PORT=$P npm run dev | tee dev.log'```-To run the command from a subdirectory, pass the global `-C` flag (teardown-still watches the worktree root, so a server launched with a relative `-C` is-torn down with the worktree):+To run the command from a subdirectory, pass the global `-C` flag:```console$ wt step tether -C frontend -- npm run devdiff --git a/docs/src/content/docs/switch.md b/docs/src/content/docs/switch.mdindex efcb3c6c7..be72f7d1b 100644--- a/docs/src/content/docs/switch.md+++ b/docs/src/content/docs/switch.md@@ -33,7 +33,7 @@ $ wt switch https://github.com/owner/repo/pull/123 # ...or paste the PR's URLThe `--create` flag creates a new branch from `--base` — the default branch unless specified. Without `--create`, the branch must already exist. Switching to a remote branch (e.g., `wt switch feature` when only `origin/feature` exists) creates a local tracking branch.-One rule decides the upstream, whatever `branch.autoSetupMerge` is set to: a new branch tracks the remote branch it starts from only when the two share a name. Switching to `origin/feature` shares it, so that branch tracks. `--create` need not: `--create release --base origin/release` tracks `origin/release`, while `--create feature --base origin/release` — and the bare `--base release` that resolves to it — gets no upstream. Git's default would have `feature` track `origin/release`, so under `push.default = upstream` a bare `git push` would push the new work to `release`. Publishing such a branch takes `git push --set-upstream origin <branch>`, or git's `push.autoSetupRemote = true` set once, after which a bare `git push` from the new worktree publishes it and configures its tracking.+A new branch tracks the remote branch it starts from only when the two share a name: `--create release --base origin/release` tracks `origin/release`, while `--create feature --base origin/release` gets no upstream. Publish such a branch with `git push --set-upstream origin <branch>`, or set git's `push.autoSetupRemote = true` once.## Creating worktrees@@ -75,7 +75,7 @@ $ wt switch pr:123 # PR #123's branch$ wt switch mr:101 # MR !101's branch```-Shortcuts also apply to `--base`. For a fork PR/MR, the head commit is fetched and used as the base SHA without creating a tracking branch.+Shortcuts also apply to `--base`.## Interactive picker@@ -99,7 +99,7 @@ The CI column shows each row's PR/MR CI and review status, the same as [`wt list| (type) | Filter worktrees || `Enter` | Switch to selected worktree || `Alt-c` | Create new worktree named as entered text |-| `Alt-x` | Remove selected worktree/branch (never forces) |+| `Alt-x` | Remove selected worktree/branch (never forces; not the current worktree) || `Alt-y` | Copy selected branch name to the clipboard || `Alt-o` | Open the selected row's PR/MR URL in the browser || `Alt-r` | Refresh the list (pick up worktrees created elsewhere) |@@ -109,13 +109,7 @@ The CI column shows each row's PR/MR CI and review status, the same as [`wt list| `Alt-p` | Toggle preview panel || `Ctrl-u`/`Ctrl-d` | Scroll preview up/down |-`Alt-o` is a no-op on a row with no PR/MR (or whose status hasn't loaded yet).--`Alt-x` is a no-op on the current worktree (the `@` row) — removing the worktree in use would have to switch elsewhere first, so switch away and remove it from there.--Each row filters by its branch, path, and — when it has a PR/MR — the PR/MR's number, title, and author, the same fields whether the PR is checked out (a worktree row) or listed via `--prs`. Plain digits go to the filter, so a number can be typed directly and the preview tabs move to `Alt`.--Typing a gutter sigil filters by row kind: `+` narrows to linked worktrees and `@` to the current worktree. The other sigils don't filter cleanly — `^` and `|` are skim's prefix-anchor and OR query operators (so `^` matches every row and `|` none), and `/` matches most rows because every worktree path contains it.+The filter matches each row's branch, path, and — when it has a PR/MR — the PR/MR's number, title, and author. Typing `+` narrows to linked worktrees, and `@` to the current worktree.**Preview tabs:**@@ -130,8 +124,6 @@ Typing a gutter sigil filters by row kind: `+` narrows to linked worktrees and `The comparison base is the merge-base with the default branch, or with its upstream when the local default branch lags. The picker opens on **diff** for local rows and **pr** for a PR/MR listed by `--prs` but not available locally. `Tab` and `Shift-Tab` skip tabs without content; `Alt-1` through `Alt-8` open any tab directly. After you choose a tab, that choice stays active while you navigate.-On narrow previews the tab bar compacts to digits — only the active tab keeps its label — so every `Alt-N` accelerator stays visible.-**Pager configuration:** The preview panel pipes diff output through git's pager. Override in user config:```toml@@ -155,7 +147,7 @@ Both work anywhere a branch is accepted, including `--base`. The `--create` flagIf the PR or MR is on a fork, the local branch uses its branch name directly, so `git push` works normally. A pre-existing local branch with that name tracking something else requires renaming first.-The `--prs` flag adds the repository's open PRs (GitHub) or MRs (GitLab) to the interactive picker — only the ones not already there: a PR whose branch is already shown (as a worktree, or a local or remote branch) isn't listed twice, so `--prs` only adds the rest and the two pickers differ solely by those extra rows. Each added row resolves to the same `pr:`/`mr:` shortcut, so selecting one fetches the ref and switches to its branch. A `--prs` row has no local worktree, so its `pr` and `comments` preview tabs load the PR/MR's metadata and comments from the forge in the background. The `log` tab uses a local `git log` — graph and merge-base dimming included — whenever the head commit is already in the object store (a same-repo PR off a fetched remote), falling back to a flat forge-fetched commit list otherwise.+The `--prs` flag adds the repository's open PRs (GitHub) or MRs (GitLab) that aren't already in the interactive picker. Selecting one switches to it as `pr:<number>` / `mr:<number>` would.Requires `gh` (GitHub), `glab` (GitLab), or an equivalent CLI installed and authenticated; see [forge platform](/config/#forge-platform) for Gitea, Azure DevOps, and other supported platforms.diff --git a/docs/src/content/docs/tips-patterns.md b/docs/src/content/docs/tips-patterns.mdindex b7f6e7ed3..ff3c0a83a 100644--- a/docs/src/content/docs/tips-patterns.md+++ b/docs/src/content/docs/tips-patterns.md@@ -284,7 +284,7 @@ MY_PACKAGES_PATH = "{{ config_root }}/.packages"`{{ config_root }}` is the project root mise resolves relative paths against ([env directives](https://mise.jdx.dev/environments/)) — the worktree root, not the primary worktree. mise also covers Windows / PowerShell, which direnv doesn't natively.-Both set real environment variables in the shell session, so every child process inherits them — hooks, build tools, subshells — without the `--execute` workaround. Each new worktree is a new path, so it needs its own one-time trust step (`direnv allow` / `mise trust`); worktrunk deliberately doesn't bypass that prompt, the same safety reasoning behind [disabling `--execute` in project alias and hook bodies](https://github.com/max-sixty/worktrunk/issues/2101).+Both set real environment variables in the shell session, so every child process inherits them — hooks, build tools, subshells. Each new worktree is a new path, so it needs its own one-time trust step (`direnv allow` / `mise trust`).### Eliminate cold startsdiff --git a/docs/tests/built-site.test.mjs b/docs/tests/built-site.test.mjsindex ffc6b7c9c..572bbb8af 100644--- a/docs/tests/built-site.test.mjs+++ b/docs/tests/built-site.test.mjs@@ -225,7 +225,7 @@ test('build preserves the public route contract', async () => {assert.ok(configToc, 'config page is missing its desktop table of contents');assert.equal([...configToc.matchAll(/<a href="#[^"]+"/g)].length,- 33,+ 32,'config table of contents should expose overview and structural section headings only',);for (const [id, title] of [diff --git a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md b/plugins/worktrunk/skills/worktrunk/reference/claude-code.mdindex cbb5b1624..d8724c79f 100644--- a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md+++ b/plugins/worktrunk/skills/worktrunk/reference/claude-code.md@@ -51,7 +51,7 @@ codex plugin add worktrunk@worktrunkwt config plugins opencode install```-This writes the activity-tracking plugin to OpenCode's global plugins directory, `~/.config/opencode/plugins/worktrunk.ts` (honoring `$OPENCODE_CONFIG_DIR` and `$XDG_CONFIG_HOME`). `wt config plugins opencode uninstall` removes it. The one file covers both plugin runtimes — OpenCode 2 loads its `setup` export, OpenCode 1.16 and later its `server` export.+This writes the activity-tracking plugin to OpenCode's global plugins directory, `~/.config/opencode/plugins/worktrunk.ts` (honoring `$OPENCODE_CONFIG_DIR` and `$XDG_CONFIG_HOME`). `wt config plugins opencode uninstall` removes it.### Pi@@ -59,7 +59,7 @@ This writes the activity-tracking plugin to OpenCode's global plugins directory,wt config plugins pi install```-This writes the activity extension to `~/.pi/agent/extensions/worktrunk.ts`, where Pi discovers it on startup; `$PI_CODING_AGENT_DIR` replaces the agent directory. Pi has no profile concept. `wt config plugins pi uninstall` removes the extension.+This writes the activity extension to `~/.pi/agent/extensions/worktrunk.ts`, where Pi discovers it on startup; `$PI_CODING_AGENT_DIR` replaces the agent directory. `wt config plugins pi uninstall` removes the extension.### oh-my-pi@@ -128,12 +128,6 @@ Activity tracking is not plugin-specific. The plugins above only call `wt` on th| Agent finishes a turn and waits for input | `wt config state marker set "💬"` || Session ends | `wt config state marker clear` |-Three things to get right:--- **Run the command inside the worktree.** Each one resolves the branch from its working directory, so a hook that runs elsewhere marks the wrong branch, and one that runs outside a repository silently does nothing. Where the host pins the working directory elsewhere, pass the global `-C <worktree>`, which moves both the repository lookup and the branch resolution. `--branch <branch>` names the branch on its own, but the repository lookup still comes from the working directory — that, not a missing worktree argument, is why a caller pinned outside the repository needs `-C`. Elsewhere, a command that names a branch ([`wt switch`](https://worktrunk.dev/switch/), [`wt remove`](https://worktrunk.dev/remove/), `wt step diff --branch`) already names the worktree it acts on, and `-C` is for reaching a different repository rather than a different worktree.-- **Don't let a failed marker call fail the session.** Outside a repository both `set` and `clear` do nothing and exit 0, but an invalid `--branch` or a failed git config write still exits non-zero, and hosts differ on what a non-zero hook does. Append `|| true` (or the host's equivalent) to every call unless you want that surfaced.-- **Clear on exit.** A marker set on session start persists until something clears it, so pair every set with a clear on the host's session-end event — and expect the same stale marker as above if the process is killed first.-## Worktree isolation (Claude Code only)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.diff --git a/plugins/worktrunk/skills/worktrunk/reference/config.md b/plugins/worktrunk/skills/worktrunk/reference/config.mdindex 8f7bf8c64..fae65d742 100644--- a/plugins/worktrunk/skills/worktrunk/reference/config.md+++ b/plugins/worktrunk/skills/worktrunk/reference/config.md@@ -220,14 +220,11 @@ Valid built-in names:A selection mixes built-ins with [custom columns](#custom-columns), each namedby its `[list.custom-columns]` header (`columns = ["branch", "Ticket", "ci"]`),and is exhaustive: only the listed columns render. Omit `columns` to keep the-default set, where custom columns append automatically. A built-in name wins a-header collision; the gutter type indicator always shows.+default set, where custom columns append automatically.-Listing a column forces it on, space permitting: `ci` shows without `--full`,-since `--full` only bundles columns into the default table rather than gating a-named one. A column whose data source is missing still stays hidden — `summary`-needs an LLM command (`[commit.generation]`), `url` needs a `[list] url`-template — since listing can't supply the data.+Listing a column forces it on, space permitting: `ci` shows without `--full`. A+column whose data source is missing still stays hidden — `summary` needs an LLM+command (`[commit.generation]`), `url` needs a `[list] url` template.#### Custom columns [experimental]@@ -369,7 +366,7 @@ worktree-path = ".worktrees/{{ branch | sanitize }}"Every matching entry applies, least- to most-specific, following the rule above: a more specific entry — `git.company.example/platform/*` over `git.company.example/*` — wins where both set the same setting, while hooks and aliases from every matching entry all run, least-specific first. A literal key is the most specific of all; specificity is the count of non-`*` characters in the key. End a host-wide key with `/*` — a bare `git.company.example*` also covers hosts whose names merely start with that string.-`approved-commands` matches the same way, so a pattern entry approves its commands for every repository it covers. Only a key written by hand is ever a pattern: `wt config approvals add` and the interactive prompt record under the exact identifier, and `wt config approvals clear` removes only that exact entry, leaving a pattern other repositories share intact.+Entries in `approvals.toml` match the same way, so a hand-written pattern entry approves its commands for every repository it covers.#### Forge platform and hostname@@ -381,9 +378,9 @@ forge.platform = "gitlab" # or "github", "gitea" (experimentaforge.hostname = "api.git.company.example" # API host, when the remote's own host isn't it```-Both fields describe the host rather than the repository, which is why a pattern keyed to a hostname suits them, and why an SSH alias resolved through `~/.ssh/config` — where the name in the remote URL is local to one machine — belongs here rather than in a repository's committed config. A repository's own `[forge]` block still wins over any entry here, field by field: a repository that sets only `platform` still takes a matching entry's `hostname`.+A repository's own `[forge]` block still wins over any entry here, field by field.-Hooks support all three [hook forms](https://worktrunk.dev/hook/#hook-forms). A table runs multiple commands concurrently; an array-of-tables pipeline runs steps in sequence. The dotted-key examples below are equivalent to the table forms — TOML treats `projects."github.com/user/repo".post-start.server = "..."` and a `[projects."github.com/user/repo".post-start]` table the same way:+Hooks support all three [hook forms](https://worktrunk.dev/hook/#hook-forms). A table runs multiple commands concurrently; an array-of-tables pipeline runs steps in sequence:```toml# Single command@@ -526,7 +523,7 @@ template-append = """"""```-How the fragment renders, and the project-config counterpart: [the LLM commits guide](https://worktrunk.dev/llm-commits/#appending-to-the-prompt).+See [the LLM commits guide](https://worktrunk.dev/llm-commits/#appending-to-the-prompt) for how the fragment renders and its project-config counterpart.## User hooks@@ -582,7 +579,7 @@ template-append = """"""```-The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in [user config](https://worktrunk.dev/config/), since they describe per-developer environment (which CLI is installed, which agent the developer prefers). How the fragment renders: [the LLM commits guide](https://worktrunk.dev/llm-commits/#appending-to-the-prompt).+The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in [user config](https://worktrunk.dev/config/). See [the LLM commits guide](https://worktrunk.dev/llm-commits/#appending-to-the-prompt) for how the fragment renders.## Copy-ignored excludes@@ -659,9 +656,6 @@ $ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge| `WORKTRUNK_SYSTEM_CONFIG_PATH` | Override system config file location || `WORKTRUNK_PROJECT_CONFIG_PATH` | Override project config file location (defaults to `.config/wt.toml`); relative paths resolve from the worktree root || `XDG_CONFIG_DIRS` | Colon-separated system config directories (default: `/etc/xdg`) |-| `WORKTRUNK_DIRECTIVE_CD_FILE` | Internal: set by shell wrappers. wt writes a raw path; the wrapper `cd`s to it |-| `WORKTRUNK_SHELL_CWD` | Internal: set by wt on alias and hook bodies, so a nested `wt` preserves the user's subdirectory |-| `WORKTRUNK_COMPLETE_NAME` | Internal: set by shell wrappers to the command name completions register under (defaults to the binary name) || `WORKTRUNK_MAX_CONCURRENT_COMMANDS` | Max parallel git commands (default: 32). Lower if hitting file descriptor limits. || `WORKTRUNK_VERBOSE` | Verbosity level (`0`/`1`/`2`), like `-v`/`-vv` but applied everywhere — including shell completion, which no flag can reach || `RUST_LOG` | Logging directive (e.g. `worktrunk=debug`); overrides the verbosity baseline for what reaches stderr |@@ -894,7 +888,7 @@ Approved commands are saved to `~/.config/worktrunk/approvals.toml`. Re-approval`state` is `no_commands` (the project declares none), `approval_required` (at least one is unapproved), or `approved`. `name` is absent for an unnamed command and for the commit-template fragment.-`stale` is separate rather than a fourth `state`, because it co-occurs with all three: these are approvals recorded earlier whose command has since been edited or removed from the project config. They are what `--yes` would silently re-approve, so an orchestrator preserving the approval model reads them before choosing that flag.+`stale`, which can accompany any `state`, lists approvals whose command has since been edited or removed from the project config.### Command reference@@ -1033,7 +1027,7 @@ View or drop worktrunk's regenerable caches in one place. Everything here is reb### What's cached-- **CI status** — GitHub/GitLab CI per branch (30–60s TTL), shown in [`wt list`](https://worktrunk.dev/list/#ci-status), plus the largest PR/MR number seen (sizes the CI column)+- **CI status** — GitHub/GitLab CI per branch (30–60s TTL), shown in [`wt list`](https://worktrunk.dev/list/#ci-status)- **Summaries** — LLM-generated branch summaries (`wt list --full`, `wt switch` preview)- **Git commands** — cached merge-tree, ancestry, diff-stat, and `wt switch` preview results- **Hints** — one-time hints already shown in this repo@@ -1089,20 +1083,16 @@ In a hook or alias template, prefer the `{{ default_branch }}` [template variablWithout a subcommand, runs `get`. `set` stores the override in the repository's local git config. The override adds no project file and applies to every linked worktree in the clone. `clear` then `get` re-detects. The branch must exist locally for `wt list` comparisons.-`default-branch get` resolves the value and caches it on a miss; the aggregate `wt config state get` only reports the cache (read-only), so it can show `(none)` until something populates it.-### DetectionWorktrunk detects the default branch automatically:1. **Worktrunk cache** — Checks `git config worktrunk.default-branch`2. **Git cache** — Detects primary remote and checks its HEAD (e.g., `origin/HEAD`)-3. **Remote query** — If not cached, queries `git ls-remote` — typically 100ms–2s, abandoned after 10s+3. **Remote query** — If not cached, queries `git ls-remote`, giving up after 10s4. **Local inference** — If no remote, or the query was abandoned, infers from local branches-Once detected, the result is cached in `worktrunk.default-branch` for fast access. The cache isn't re-validated on every command, so a later change to `origin/HEAD` — a renamed default branch followed by `git remote set-head origin -a` — isn't picked up automatically. `wt config state` flags the drift when the cached value differs from the remote's local HEAD — expected for a deliberate override; `set` adopts the new branch and `clear` re-detects.--An abandoned remote query is the one case that isn't cached: the branch it inferred locally answers that command, but a value guessed while the remote was unreachable would otherwise become permanent, so the next command queries again.+Once detected, the result is cached in `worktrunk.default-branch` — except a value inferred after the remote query was abandoned, so an outage can't make a guess permanent. A later change to `origin/HEAD` isn't picked up automatically: `wt config state` flags the mismatch, `set` adopts the new branch, and `clear` re-detects.The local inference fallback uses these heuristics in order:- If only one local branch exists, uses it@@ -1163,7 +1153,7 @@ Hook output lives in per-branch subtrees under `.git/wt/logs/{branch}/`:| Background hooks | `{branch}/{source}/{hook-type}/{name}.log` || Background removal | `{branch}/internal/remove.log` |-All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is `user` or `project`. Branch and hook names are sanitized for filesystem safety (invalid characters → `-`; short collision-avoidance hash appended). Same operation on same branch overwrites the previous log. Removing a branch clears its subtree; orphans from deleted branches can be swept with `wt config state logs clear`.+All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is `user` or `project`. Branch and hook names are sanitized for filesystem safety. Same operation on same branch overwrites the previous log. Removing a branch clears its subtree; orphans from deleted branches can be swept with `wt config state logs clear`.#### Diagnostic files@@ -1174,11 +1164,11 @@ All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the| `subprocess.log` | Running with `-vv` || `diagnostic.md` | Running with `-vv` |-`trace.log` is the human-readable trace at `-vv` — each command's start (`$ …`) and completion (`✓`/`✗ … 12.3ms`), in-process spans, milestones, and bounded subprocess previews. `trace.jsonl` is the same event stream as one JSON object per line, for machines (`jq`, chrome://tracing); `wt config state logs profile` reads it to summarize a performance report (where time went, parallelism, redundant commands). `subprocess.log` holds the raw uncapped subprocess stdout/stderr bodies. `diagnostic.md` is a markdown bug-report bundle that leads with that same performance profile and inlines `trace.log`; `wt` prints a `gh gist create` command pointing at it. All four are overwritten on each `-vv` run.+`trace.log` is the human-readable trace of commands and their timings. `trace.jsonl` holds the same events as JSON lines, which `wt config state logs profile` summarizes into a performance report. `subprocess.log` holds full subprocess output. `diagnostic.md` is a bug-report bundle; `wt` prints a `gh gist create` command for it. All four are overwritten on each `-vv` run.### Location-All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory. Top-level files are shared logs (command audit + diagnostics); top-level directories are per-branch log trees.+All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory.### Structured output@@ -1232,36 +1222,6 @@ Output:Output format (text, json) [default: text]```-## wt config state ci-status--CI status cache.--**Deprecated** — the CI status cache is now part of [`wt config state cache`](https://worktrunk.dev/config/#wt-config-state-cache). This subcommand still works but prints a deprecation notice.--Status values, display symbols, and fetch behavior: [`wt list` CI status](https://worktrunk.dev/list/#ci-status).--Without a subcommand, runs `get` for the current branch. Use `clear` to reset cache for a branch or `clear --all` to reset all.--### Command reference--```-wt config state ci-status - CI status cache--Usage: wt config state ci-status [OPTIONS] [COMMAND]--Commands:- get Get CI status for a branch- clear Clear CI status cache--Options:- -h, --help- Print help (see a summary with '-h')--Output:- --format <FORMAT>- Output format (text, json) [default: text]-```-## wt config state markerBranch markers.@@ -1370,7 +1330,7 @@ dev = "npm start -- --port {{ vars.config.port }}"### Storage format-Stored in git config as `worktrunk.state.<branch>.vars.<key>`. Keys must contain only letters, digits and hyphens — dots conflict with git config's section separator, underscores with its variable name format.+Stored in git config as `worktrunk.state.<branch>.vars.<key>`. Keys may contain only letters, digits, and hyphens.### Command referencediff --git a/plugins/worktrunk/skills/worktrunk/reference/extending.md b/plugins/worktrunk/skills/worktrunk/reference/extending.mdindex bef10ddf2..c688d4654 100644--- a/plugins/worktrunk/skills/worktrunk/reference/extending.md+++ b/plugins/worktrunk/skills/worktrunk/reference/extending.md@@ -152,14 +152,12 @@ git fetch --all --prune; wt step for-each -- sh -c '`wt up` fetches every remote, then brings each worktree up to date with its upstream: skip if there is no upstream or a rebase is already in progress, fast-forward if a tracked file is modified or staged, otherwise rebase, aborting on conflict. It rebases onto git-native `@{u}` rather than a `{{ … }}` template, so git resolves each worktree's own upstream and there is nothing to defer.-A sweep finds each worktree in whatever state you left it, so most of the script is guards:+Two details matter when adapting it:-- `git fetch --all` exits non-zero when any single remote fails. With `&&`, one remote with lapsed credentials is enough to skip the whole sweep, so even worktrees whose refs fetched fine go unrebased. With `;` the sweep runs on what did fetch, and the fetch error still prints.-- `git rebase` refuses to run in a worktree with a modified or staged tracked file, whether or not there is anything to rebase — so a worktree you are editing would fail the sweep. `git merge --ff-only` is the piece of the rebase git will still do there: it advances a branch that is simply behind, and otherwise changes nothing — a diverged branch, or an incoming file that collides with your edits, leaves the worktree exactly as it was, with the reason printed. Untracked files trigger neither the refusal nor the `git diff` guard, so a worktree carrying only new files still rebases — unless one of them has the same name as a file the incoming commits add, which git declines to overwrite.-- `rebasing` tells the two ways `git rebase` fails apart. Conflicting partway leaves a rebase in progress, which the abort winds back. Refusing to start — a tracked file modified under you, an untracked file in the way of an incoming one, a `pre-rebase` hook saying no — leaves nothing to abort and nothing to clean up, so the sweep moves on; an unconditional `git rebase --abort` there would answer `fatal: no rebase in progress` and exit 128 in place of git's own message.-- Both arms pass `--no-autostash`, because a global `rebase.autostash` or `merge.autostash` breaks what each arm relies on. An autostash that pops with conflicts leaves the markers in the worktree and still exits 0, so the sweep would report success on a worktree it had just left in conflict — and an autostashed tree is momentarily clean, so a fast-forward that should have refused goes through and the collision lands on the pop instead.+- `;` after the fetch lets the sweep run even when one remote fails to fetch.+- `--no-autostash` overrides a global `rebase.autostash` or `merge.autostash`, whose conflicting pop would leave markers behind and still exit 0.-So the sweep exits non-zero only when it leaves a worktree needing attention — an abort that itself failed. Everything git declines to do, it declines atomically, and the sweep carries on to the next worktree with git's reason in the output. That matters where the alias is a hook step, since a failing step stops the rest of the pipeline.+The sweep exits non-zero only when it leaves a worktree needing attention, which matters when the alias runs as a hook step: a failing step stops the rest of the pipeline.### Recipe: move or copy in-progress changes to a new worktree@@ -233,7 +231,6 @@ Aside from the differences below, hooks and aliases behave the same.| Reach `{{ args }}` from positionals | Must use `--` (`wt hook pre-merge -- extra`) | Any bare positional lands there || Approval skip flag | Post-subcommand `--yes` / `-y` supported (`wt hook pre-merge --yes`) | Only the global form (`wt -y <alias>`); post-alias `--yes` falls through to `{{ args }}` || Source discrimination | `user:` / `project:` / `user:name` / `project:name` filter syntax | Run user first, then project; no filter syntax |-| Force-bind escape | `--var KEY=VALUE` (deprecated in favor of `--KEY=VALUE`, but still force-binds) | None; smart routing is the only path || `--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 | All template variables as JSON (parse with `json.load(sys.stdin)`) | Inherits parent stdin (pipes pass through; interactive TUIs like `wt switch` keep the tty) |diff --git a/plugins/worktrunk/skills/worktrunk/reference/faq.md b/plugins/worktrunk/skills/worktrunk/reference/faq.mdindex cf50adfa2..1af900ec4 100644--- a/plugins/worktrunk/skills/worktrunk/reference/faq.md+++ b/plugins/worktrunk/skills/worktrunk/reference/faq.md@@ -208,10 +208,10 @@ A branch checked out in a second worktree is retained regardless, `-D` included.### Other cleanup- `wt merge` / `wt step push` — the target branch's checked-out worktree is updated to the merged commits, so a file those commits delete disappears from it, and an ignored file at a path they track is overwritten — the same result a `git merge` run in that worktree would produce. Uncommitted changes at paths the merge doesn't touch stay in place, staged or not; one at a path it does touch refuses the merge upfront, naming the file-- `wt remove` — besides the worktree being removed, two cleanup mechanisms run. The removed worktree's own `git fsmonitor--daemon` (git's per-worktree filesystem watcher under `core.fsmonitor=true`, which would leak once its worktree is gone) is sent `git fsmonitor--daemon stop`, then force-terminated (`SIGTERM`, then `SIGKILL`) via the PID resolved from its IPC socket if it didn't exit. A background sweep then deletes `.git/wt/trash/` entries older than 24 hours (directories orphaned when a previous background removal was interrupted) and terminates fsmonitor daemons whose worktree no longer exists (orphans from `git worktree remove`, `rm -rf`, or a crashed `wt`)+- `wt remove` — also stops the removed worktree's `git fsmonitor--daemon` (under `core.fsmonitor=true`), and sweeps `.git/wt/trash/` entries older than 24 hours along with fsmonitor daemons whose worktree no longer exists- `wt config state clear` — removes all worktrunk data from `.git/` (config keys, caches, markers, hints, variables, logs, stale trash)-- `wt config shell install` — when migrating an integration to a new location, removes the file left at the old one: fish `conf.d/wt.fish` (now `functions/wt.fish`) and nushell wrappers stranded under `<config-dir>/vendor/autoload` (now `<data-dir>/vendor/autoload`). The old path is where worktrunk's own wrapper lived and is named after the command being installed, so it's taken back whole without reading it — a `conf.d/wt.fish` left in place would be sourced at startup and shadow the new wrapper anyway. Only that exact filename is touched, and each removal is printed. The same rule covers the path being installed to, so an existing `functions/wt.fish`, `completions/wt.fish`, or `wt.nu` is replaced whole; [Files created](https://worktrunk.dev/shell-integration/#files-created) names the file each shell gets-- `wt config shell uninstall` — removes integration lines from bash/zsh/PowerShell rc files, and deletes worktrunk's wrapper and completion files (fish `functions/`, `conf.d/`, and `completions/`; nushell `vendor/autoload`). Uninstall takes no command name, so it lists those directories and recognizes files by worktrunk's own content markers, whatever binary name they were installed under; files without the markers are left alone. An rc file belongs to the user, so a line qualifies only where it runs the init command: one that merely mentions it, inside a comment, an `echo`, or an alias body, stays. Every line uninstall does take is printed, before removal and again after+- `wt config shell install` — replaces an existing fish or Nushell wrapper file whole, and removes one an older version installed at a previous location (fish `conf.d/wt.fish`, Nushell `<config-dir>/vendor/autoload/wt.nu`), printing each removal; [Files created](https://worktrunk.dev/shell-integration/#files-created) names the file each shell gets+- `wt config shell uninstall` — removes the lines that run `wt config shell init` from bash/zsh/PowerShell rc files, and deletes wrapper and completion files carrying worktrunk's content markers (fish `functions/`, `conf.d/`, and `completions/`; nushell `vendor/autoload`). Every removed line is printed- `wt config plugins opencode uninstall` / `wt config plugins pi uninstall` / `wt config plugins omp uninstall` — deletes that agent's `worktrunk.ts` plugin file. Only worktrunk's own file is touched; the rest of the agent's plugin directory is left aloneSee [What files does Worktrunk create?](#what-files-does-worktrunk-create) for details.@@ -246,7 +246,7 @@ Use `--yes` to bypass prompts (useful for CI/automation).### Command log-All hook executions and LLM commands are recorded in `.git/wt/logs/commands.jsonl` — one JSON object per line. Fields: `ts` (timestamp), `wt` (the wt command that triggered it), `label` (what ran, e.g., `pre-merge user:lint`), `cmd` (shell command), `exit` (exit code, `null` for background), `dur_ms` (duration, `null` for background). The file rotates to `commands.jsonl.old` at 1MB, bounding storage to ~2MB.+All hook executions and LLM commands are recorded in `.git/wt/logs/commands.jsonl`, one JSON object per line; [`wt config state logs`](https://worktrunk.dev/config/#wt-config-state-logs) lists the fields.View the log with `wt config state logs get`, or query directly:@@ -266,7 +266,7 @@ Yes. Core commands, shell integration, and tab completion work in both Git Bash**Git for Windows required** — Hooks use bash syntax and execute via Git Bash, so [Git for Windows](https://gitforwindows.org/) must be installed even when PowerShell is the interactive shell.-The `wt switch` interactive picker runs on Windows too, on [skim](https://github.com/skim-rs/skim)'s crossterm backend.+The `wt switch` interactive picker runs on Windows too.## How does Worktrunk determine the default branch?@@ -290,7 +290,7 @@ Installing with Cargo and the default features also requires a C99 compiler forcargo install worktrunk --no-default-features --features cli```-This disables bash syntax highlighting in command output but keeps all core functionality. The syntax highlighting feature requires C99 compiler support and can fail on older systems or minimal Docker images.+This disables bash syntax highlighting in command output but keeps all core functionality.## How can I contribute?diff --git a/plugins/worktrunk/skills/worktrunk/reference/hook.md b/plugins/worktrunk/skills/worktrunk/reference/hook.mdindex 010bc2233..e3e71c131 100644--- a/plugins/worktrunk/skills/worktrunk/reference/hook.md+++ b/plugins/worktrunk/skills/worktrunk/reference/hook.md@@ -31,7 +31,7 @@ The most common creation hook is `post-start` — it runs background tasks (dev| `pre-remove` | Cleanup before worktree deletion: saving test artifacts, backing up state. Runs in the worktree being removed || `post-remove` | Stopping dev servers, removing containers, notifying external systems. Template variables reference the removed worktree |-During `wt merge`, the blocking hooks run in this order: pre-commit → pre-merge → pre-remove. The `post-*` hooks all start together once the merge finishes, each in the worktree it is anchored on — post-merge, post-switch and post-remove in the destination, post-commit in the worktree the commit was made in. A merge that removes that worktree reports `post-commit` as skipped instead of running it — the worktree is gone by the time the hook would start. Use `pre-remove` for work that must finish there, or `--no-remove` to keep the worktree. See [`wt merge`](https://worktrunk.dev/merge/#pipeline) for the complete pipeline.+During `wt merge`, the blocking hooks run in this order: pre-commit → pre-merge → pre-remove. The `post-*` hooks start together once the merge finishes. See [`wt merge`](https://worktrunk.dev/merge/#pipeline) for the complete pipeline.# Security@@ -93,7 +93,7 @@ server = "npm run dev"Here `install` runs first, then `build` and `server` run together.-Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](https://worktrunk.dev/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Because an earlier step can still change those values, a preview stands the reference in for its value instead of resolving it: `wt hook <type> --dry-run` and `wt hook show --expanded` render `{{ vars.thing | default('none') }}` as `{{ vars.thing }}` — the reference is defined, so the `default` never fires — while every other variable expands. A filter that transforms its input still runs, against the placeholder text, and its output is shell-escaped like any other value: `{{ vars.thing | upper }}` previews as `'{{ VARS.THING }}'`.+Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](https://worktrunk.dev/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Previews (`wt hook <type> --dry-run`, `wt hook show --expanded`) leave `{{ vars.* }}` references unexpanded for that reason.Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependency chain — typically setup that must complete before later steps, like installing dependencies before running a build and dev server concurrently.@@ -157,9 +157,9 @@ All hooks share the same perspective — `{{ branch | hash_port }}` produces the`cwd` is the worktree root where the hook command runs. It equals `worktree_path` except in three cases:-- `pre-switch`: hook runs in the source worktree; `worktree_path` is the destination when that worktree already exists — a switch that creates one has no destination directory yet, so `worktree_path` stays on the source (use `pre-start` to work in the new worktree)+- `pre-switch`: hook runs in the source worktree; `worktree_path` is the destination, or the source when the switch creates a new worktree (use `pre-start` to work in the new worktree)- `post-remove`: the active worktree is gone, so the hook runs in the primary worktree-- `post-merge`: the hook runs in the target branch's worktree (the primary worktree if the target has none), including under `--no-remove`, where the merged worktree `worktree_path` names is still on disk+- `post-merge`: the hook runs in the target branch's worktree (the primary worktree if the target has none)Undefined variables error — use conditionals or defaults for optional behavior:@@ -169,7 +169,7 @@ Undefined variables error — use conditionals or defaults for optional behaviorsync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"```-A detached worktree is on no branch, so `branch` is undefined there — as are the `base` and `target` names derived from it, whether by a manual `wt hook` or by an operation whose source or destination worktree is detached (`base` in a `pre-switch` fired from one, `target` in a removal that lands in one) — and the same `{% if branch %}` guard applies. This matches `wt list --format=json`, which reports `branch: null` for the same worktree.+A detached worktree has no branch, so `branch` — and a `base` or `target` that names that worktree — is undefined there; guard with `{% if branch %}`.Run any hook-firing command with `-v` to see the resolved variables for the actual invocation — each hook prints a `template variables:` block showing every in-scope variable and its value (`(unset)` for conditional vars that didn't populate, like `target_worktree_path` during `wt switch -`). Aliases do the same under `-v`: `wt -v <alias>` prints the alias's in-scope variables before the pipeline runs.@@ -261,7 +261,7 @@ if ctx.get('branch', '').startswith('feature/') and 'backend' in ctx['repo']:## Copying untracked files-One specific command worth calling out: [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored). Git worktrees share the repository but not untracked files, and this copies gitignored files between worktrees:+Git 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:```toml[post-start]@@ -317,8 +317,6 @@ $ wt hook post-startAny `--KEY=VALUE` whose key isn't referenced by a hook template forwards into `{{ args }}` as a literal `--KEY=VALUE` token. Tokens after `--` also forward into `{{ args }}` verbatim. `{{ args }}` renders as a space-joined, shell-escaped string; index with `{{ args[0] }}`, loop with `{% for a in args %}…{% endfor %}`, count with `{{ args | length }}`.-The long form `--var KEY=VALUE` is deprecated but still supported. It force-binds regardless of whether any hook template references `KEY` — useful when a template only references the key conditionally (e.g. `{% if override %}…{% endif %}`).-# Recipes- [Eliminate cold starts](https://worktrunk.dev/tips-patterns/#eliminate-cold-starts): `wt step copy-ignored` in `post-start` shares build caches and dependencies; use a `[[post-start]]` pipeline when a later hook depends on the copydiff --git a/plugins/worktrunk/skills/worktrunk/reference/list.md b/plugins/worktrunk/skills/worktrunk/reference/list.mdindex 6e7c8a403..f25a56bcb 100644--- a/plugins/worktrunk/skills/worktrunk/reference/list.md+++ b/plugins/worktrunk/skills/worktrunk/reference/list.md@@ -8,7 +8,7 @@ The table renders progressively: branch names, paths, and commit hashes appear i## Full mode-`--full` adds the two columns that reach off-machine: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail, over the network) and [LLM-generated summaries](#llm-summaries) of each branch's changes. The `main…±` line diffs are local git, so they show by default.+`--full` adds the two columns that reach off-machine: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail, over the network) and [LLM-generated summaries](#llm-summaries) of each branch's changes.## Examples@@ -63,7 +63,7 @@ $ wt list --format=json| Column | Shows ||--------|-------|-| Branch | Branch name, elided with `…` past 32 characters so one long name can't size the column for every row (`--format=json` keeps it whole); a detached worktree has none, so it shows its short hash in dim yellow |+| Branch | Branch name, elided with `…` past 32 characters; a detached worktree shows its short hash || Status | Compact symbols (see below) || HEAD± | Uncommitted changes, including untracked files: +added -deleted lines || main↕ | Commits ahead/behind default branch |@@ -80,9 +80,7 @@ $ wt list --format=jsonThe `main↕` and `main…±` headers keep the familiar `main` label in every repository.-The table sizes itself to the terminal. When the columns don't all fit, the least important go first — roughly right to left, since the order above runs from identity to nice-to-have — and the summary footer names them (`hidden: Commit, Age, Message`). A column with nothing to show on any row — `Remote⇅` in a repo with no remote — ranks below every populated column, so it goes first. A wider terminal brings them back. To pin a set rather than leave it to the width, name the columns in [`[list] columns`](https://worktrunk.dev/config/#list); `--format=json` carries every field at any width.--`main↕` and `main…±` measure against the default branch's upstream tip when the local copy lags it — so in a fork whose local `main` trails `origin/main`, a branch reads as ahead of the real mainline, not of a stale local checkout. The `↑`/`↓`/`↕` Status symbols derive from these counts, so they track the upstream tip too.+The table sizes itself to the terminal. When the columns don't all fit, the least important go first — roughly right to left, since the order above runs from identity to nice-to-have — and the summary footer names them (`hidden: Commit, Age, Message`). A wider terminal brings them back. To pin a set rather than leave it to the width, name the columns in [`[list] columns`](https://worktrunk.dev/config/#list); `--format=json` carries every field at any width.### Gutter@@ -98,7 +96,7 @@ The leftmost column marks each row by physical presence, from most present to le### CI status-The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and Azure DevOps, `!3035` on GitLab — colored by pipeline status, or a bare `#` when no number is available (e.g. branch workflows without a PR/MR). One color folds two JSON fields: green/blue/red/yellow/gray are the pipeline state, magenta/cyan the review state. The `Value` column names each state; [checks object](#checks-object) and [review states](#review-states) give the JSON spelling — schema 2 reports three of the pipeline values by the shape of `pr` and `checks` rather than as a `checks.status` string:+The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and Azure DevOps, `!3035` on GitLab — colored by pipeline status, or a bare `#` when no number is available (e.g. branch workflows without a PR/MR). Green, blue, red, yellow, and gray show the pipeline state; magenta and cyan show the review state. [checks object](#checks-object) and [review states](#review-states) give the JSON form of each value:| Indicator | Value | Meaning ||-----------|-------|---------|@@ -114,9 +112,9 @@ The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and AzThe two remaining review states have no indicator of their own: `"draft"` only dims the cell and `"approved"` leaves the color unchanged.-Color precedence resolves the fold: changes-requested (magenta) outranks running checks — waiting can't clear it — while an outstanding required review (cyan) only recolors an otherwise green or quiet branch. Cool colors mean waiting, warm colors mean act. An approved PR, or one with no review signal at all (no required reviewers and no reviews), keeps its plain pipeline color — `pr.review` is then `"approved"` or absent, respectively. GitLab MR data carries only `"pending"` and `"draft"` — no approved or changes-requested signal.+Changes requested (magenta) outranks running checks, while a required review (cyan) only recolors an otherwise green or gray branch. GitLab reports only the `"pending"` and `"draft"` review states.-CI cells are clickable links to the PR or pipeline page, and appear dimmed for a draft PR/MR (`"draft"`) or when unpushed local changes make the status stale (`checks.stale`). PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches — visible with `--remotes` — get CI status detection. Results are cached for 30-60 seconds; use `wt config state cache` to view or clear.+CI cells are clickable links to the PR or pipeline page, and appear dimmed for a draft PR/MR (`"draft"`) or when unpushed local changes make the status stale (`checks.stale`). Results are cached for 30-60 seconds; use `wt config state cache` to view or clear.### LLM summaries@@ -131,7 +129,7 @@ Each `[list.custom-columns]` entry in user config adds a column: the key is thetemplate = "{{ vars.ticket }}"```-A custom column that renders empty for every row is dropped from the table outright, rather than merely ranked last as an empty built-in is. Templates, widths, and drop priority: [custom columns config](https://worktrunk.dev/config/#custom-columns).+The [custom columns config](https://worktrunk.dev/config/#custom-columns) covers templates, widths, and drop priority.## Status symbols@@ -157,10 +155,10 @@ An in-progress git operation, a worktree-location attribute, or a branch with no|--------|------|---------|| `✘` | `worktree.changes.conflicted` | Merge conflicts || `↻` | `worktree.operation` `"rebase"`, `"merge"`, `"cherry_pick"`, `"revert"`, `"bisect"` | A git operation is in progress; `git status` names it |-| `⊟` | `worktree.prunable` | Prunable (worktree directory missing); nothing can be read from a directory that isn't there, so the row's data cells stay blank |+| `⊟` | `worktree.prunable` | Prunable (worktree directory missing) || `⊞` | `worktree.locked` | Locked worktree |-| `⊘` | `worktree.detached` | Detached HEAD — the worktree is on a commit, not a branch, which is why its Branch cell holds a short hash |-| `⚑` | `worktree.duplicate_branch` | Branch checked out in more than one worktree, so `wt` resolves it to whichever git lists first; every worktree on the branch is flagged |+| `⊘` | `worktree.detached` | Detached HEAD |+| `⚑` | `worktree.duplicate_branch` | Branch checked out in more than one worktree || `⚑` | `worktree.branch_mismatch` | Worktree isn't at the path its branch implies || `/` | no `worktree` object | Branch without a worktree |@@ -195,13 +193,10 @@ Relation to the tracking branch, derived from the `upstream.ahead` / `upstream.b### Marker-The last subcolumn carries the branch's own marker — whatever-[`wt config state marker set`](https://worktrunk.dev/config/#wt-config-state-marker) stored, usually-an emoji, which is why the subcolumn is two cells wide. Nothing in `wt` writes-it; it is there for agents and scripts to say what a branch is for, and it-reads back as the item's `marker` field. `wt config state marker set 🤖` on a-branch whose default-branch state is `_` renders `_ 🤖` in the column and-`"_🤖"` in `display.symbols`.+The last subcolumn shows the branch's marker, set with+[`wt config state marker set`](https://worktrunk.dev/config/#wt-config-state-marker) — usually an+emoji saying what the branch is for. It reads back as the item's `marker`+field.### Placeholder symbols@@ -363,7 +358,7 @@ Independent facts; the table's priority-collapsed symbol is `display.state`.| `number` | integer/null | PR/MR number || `url` | string/null | URL to the PR/MR page || `review` | string | Review state (see [review states](#review-states)); absent when the forge reports no review signal |-| `mergeable` | boolean/null | False when the forge reports conflicts, null otherwise — the fetch records only the conflicted case |+| `mergeable` | boolean/null | False when the forge reports conflicts, null otherwise || `repo` | object | Structured metadata for the repository the PR/MR targets, the upstream for fork PRs (see [repo object](#repo-object)); absent when the URL doesn't parse |### checks object@@ -427,7 +422,7 @@ The single highest-priority state describing the branch's relation to the defaul### review states-`pr.review` is one of `"changes_requested"`, `"pending"`, `"draft"`, `"approved"`, absent when the forge reports no review signal. The [CI status](#ci-status) section is the single source: its table maps the colored values, and the notes below it cover `"draft"` and `"approved"`. The vocabulary matches Claude Code's statusline `pr.review_state` field.+`pr.review` is one of `"changes_requested"`, `"pending"`, `"draft"`, `"approved"`, absent when the forge reports no review signal. [CI status](#ci-status) shows how each renders. The vocabulary matches Claude Code's statusline `pr.review_state` field.```console# Current worktree path (for scripts)@@ -457,8 +452,6 @@ $ wt list --format=json --full | jq '.items[] | select(.checks.stale) | .branch'A JSON Schema for the envelope is published at[worktrunk.dev/schema/list-v2.json](https://worktrunk.dev/schema/list-v2.json).-It describes what `wt` writes, so a field the absence rule can omit is-optional there rather than required-and-null.### Schema 1@@ -566,9 +559,9 @@ The line carries the same cells as the worktree's row in `wt list`. A stale CI s- `json`: the current [`wt list --format=json`](https://worktrunk.dev/list/#json-output) schema — a one-item envelope by default, or a one-item array with `[list] json-schema = 1`- `claude-code`: the `table` cells, preceded by `dir` and followed by `model context pace`-A cell with nothing to show is left out rather than blanked, so most lines are shorter than that; `claude-code` also drops `branch` where `dir` already ends in `.<branch>`. A line that still overruns the terminal drops whole cells, least important first, starting with the dev server URL.+A cell with nothing to show is left out, so most lines are shorter than that. A line that overruns the terminal drops whole cells, least important first.-The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both are underlined, which is what marks them as clickable. They are OSC 8 links, and a terminal that doesn't support those discards the escape, leaving the underlined text unclickable.+The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both are underlined terminal links.### Claude Code mode@@ -580,7 +573,7 @@ The CI reference links to its PR/MR, and a dev server URL carrying a port shows- `.rate_limits.{five_hour,seven_day}.used_percentage` — rate-limit window usage (0–100)- `.rate_limits.{five_hour,seven_day}.resets_at` — window reset time (Unix epoch seconds)-The pace segment appears only when usage is likely to hit a rate limit before its window resets, and shows the higher-risk window: `2.9×(Tue–Tue 5pm)` reads as 2.9× the pace that would exactly fill that window. Above 90% used it shows usage instead of pace — `93%(Tue–Tue 5pm)` — near the cap, how much is left matters more than how fast it's going. "Likely" is a Bayesian forecast; early-window bursts don't trigger it. Its colour deepens with severity — dim, then dim-yellow, then yellow — as the forecast lockout (how much of the window would be spent capped) grows, so a fast pace that would only tip over near the reset stays dim rather than alarming. With `-vv`, each window's inputs and projection are logged to `.git/wt/logs/trace.log`.+The pace segment appears only when usage is likely to hit a rate limit before its window resets, and shows the higher-risk window: `2.9×(Tue–Tue 5pm)` reads as 2.9× the pace that would exactly fill that window. Above 90% used it shows usage instead of pace — `93%(Tue–Tue 5pm)`. Its color deepens from dim to yellow as more of the window would be spent capped.[Claude Code statusline setup](https://worktrunk.dev/claude-code/#statusline-claude-code-only) has the `~/.claude/settings.json` entry that feeds this mode.diff --git a/plugins/worktrunk/skills/worktrunk/reference/merge.md b/plugins/worktrunk/skills/worktrunk/reference/merge.mdindex 37d505f0d..fb456e829 100644--- a/plugins/worktrunk/skills/worktrunk/reference/merge.md+++ b/plugins/worktrunk/skills/worktrunk/reference/merge.md@@ -63,7 +63,7 @@ $ wt merge --no-commit --no-rebase`wt merge` runs these steps:-1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background; when step 7 removes the worktree they are anchored on, the merge reports them rather than running them. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.+1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.3. **Rebase** — Rebases onto target, skipping when nothing needs replaying ([`wt step rebase`](https://worktrunk.dev/step/#wt-step-rebase) gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](https://worktrunk.dev/hook/).@@ -74,7 +74,7 @@ $ wt merge --no-commit --no-rebaseUse `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Combining both flags preserves the exact source graph and requires the target to be its ancestor. Useful after preparing commits manually with `wt step commit`. Requires a clean working tree.-`wt merge` targets the *local* default-branch ref and never fetches. When that ref lags its upstream — e.g. a primary checkout's `main` left behind `origin/main` — a branch based on the newer upstream tip is measured, squashed, and rebased against the upstream (so already-upstream commits are never folded into the squash), and the final fast-forward carries the local ref through the already-fetched upstream commits by their real SHAs. `wt step squash` and `wt step rebase` measure the same way. A local target that has *diverged* from its upstream — its own commits and behind — cannot fast-forward, so the merge is refused until the target is reconciled.+`wt merge` merges into the *local* target branch and never fetches.## Local CIdiff --git a/plugins/worktrunk/skills/worktrunk/reference/remove.md b/plugins/worktrunk/skills/worktrunk/reference/remove.mdindex f7f81360e..4980b21c1 100644--- a/plugins/worktrunk/skills/worktrunk/reference/remove.md+++ b/plugins/worktrunk/skills/worktrunk/reference/remove.md@@ -38,7 +38,7 @@ $ wt remove -D experimentalBy default, branches are deleted when they would add no changes to the default branch if merged. This works with both unchanged git histories, and squash-merge or rebase workflows where commit history differs but file changes match.-Worktrunk checks six conditions (in order of cost):+Worktrunk checks six conditions:1. **Same commit** — Branch HEAD equals the default branch. Shows `_` in `wt list`.2. **Ancestor** — Branch is in target's history (fast-forward or rebase case). Shows `⊂`.@@ -53,8 +53,6 @@ The 'same commit' check uses the local default branch; for other checks, 'targetBranches matching these conditions and with empty working trees are dimmed in `wt list` as safe to delete.-Those six ask whether deleting loses work. A branch checked out in a second worktree (only reachable via `git worktree add --force`) fails a different test: deleting the ref would leave that worktree unable to resolve `HEAD`, which is why `git branch -d` refuses the same delete. Such a branch is retained whatever `-D` asks, and the surviving checkout is named.-## Force flagsWorktrunk has two force flags for different situations:@@ -74,9 +72,7 @@ Use `--no-delete-branch` to keep the branch regardless of merge status.## Background removal-Removal runs in the background by default — the command returns immediately. The worktree is renamed into `.git/wt/trash/` (instant same-filesystem rename), git metadata is pruned, the branch is deleted, and a detached `rm -rf` finishes cleanup. Cross-filesystem worktrees fall back to `git worktree remove`. Logs: `.git/wt/logs/{branch}/internal/remove.log`. Use `--foreground` to run in the foreground.--After each `wt remove`, entries in `.git/wt/trash/` older than 24 hours are swept by a detached `rm -rf` — eventual cleanup for directories orphaned when a previous background removal was interrupted (SIGKILL, reboot, disk full).+Removal runs in the background by default — the command returns immediately, and output goes to `.git/wt/logs/{branch}/internal/remove.log`. Use `--foreground` to wait for it.## Reaping processes [experimental]@@ -96,7 +92,7 @@ To avoid killing work the user did not mean to kill, two guards keep `--reap` co- **Interactive processes are spared.** A process holding a controlling terminal — an interactive shell, or a terminal editor such as `vim` with unsaved buffers — is never reaped. Only detached processes remain candidates.- **Discovery is by working directory only.** A process that started in the worktree and later changed directory, or a daemon that reparented to `init`, no longer reports a directory under the worktree and is not found. To reliably reap those, launch them with [`wt step tether`](https://worktrunk.dev/step/#wt-step-tether), which kills the whole process group when the worktree is removed.-Reaping runs before the worktree directory is touched, so it is independent of foreground/background removal and the `--force` flag. Unix only; on Windows `--reap` is rejected.+Unix only; on Windows `--reap` is rejected.## JSON output@@ -107,11 +103,11 @@ Reaping runs before the worktree directory is touched, so it is independent of f| Value | Meaning ||-------|---------|| `deleted` | The branch is gone |-| `deferred` | Handed to the detached background process, whose result this run never sees. `--foreground` never reports it |+| `deferred` | Left to the background removal, whose result this run doesn't see. `--foreground` never reports it || `not_attempted` | No deletion was tried: a detached worktree, a sibling checkout, or `--no-delete-branch` || `retained_unmerged` | Declined: the branch was not integrated into the target |-| `retained_checked_out` | Declined: the final topology read found a live worktree with it checked out |-| `retained_raced` | Refused by the compare-and-swap — the branch moved between the integration check and the delete. Re-read the ref and retry |+| `retained_checked_out` | Declined: another worktree has the branch checked out |+| `retained_raced` | Declined: the branch moved during the removal. Retry || `retained_failed` | The delete command itself failed |## Hooksdiff --git a/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md b/plugins/worktrunk/skills/worktrunk/reference/shell-integration.mdindex 2d41a6022..b4680475d 100644--- a/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md+++ b/plugins/worktrunk/skills/worktrunk/reference/shell-integration.md@@ -64,7 +64,7 @@ When shell integration isn't working, `wt switch` shows a warning explaining why### "shell wrapper is out of date"-**Meaning**: The active shell still has a retired wrapper loaded. Current versions no longer write to that wrapper's single directive file, so the parent shell cannot follow a directory change.+**Meaning**: The active shell has a wrapper from an older Worktrunk version loaded, which can't follow a directory change.**Fix**: Run `wt config shell install`, then restart the shell (or reload its config) to activate the current wrapper.@@ -239,8 +239,6 @@ eval "$(wt config shell init zsh)"### Windows Git Bash issues-Git Bash uses MSYS2, which automatically converts POSIX paths in environment variables. The directive file path is handled correctly without manual conversion.-If you see path issues, make sure you're on a recent Git for Windows version.## Environment variablesdiff --git a/plugins/worktrunk/skills/worktrunk/reference/step.md b/plugins/worktrunk/skills/worktrunk/reference/step.mdindex f9e82024e..b8770dabb 100644--- a/plugins/worktrunk/skills/worktrunk/reference/step.md+++ b/plugins/worktrunk/skills/worktrunk/reference/step.md@@ -101,7 +101,7 @@ See [LLM-generated commit messages](https://worktrunk.dev/llm-commits/) for conf$ wt step commit --branch feature```-The branch must have a checked-out worktree. `--branch` re-roots the whole command: staging, hooks, and the commit all happen there. It selects the previewed worktree the same way, so `--dry-run` describes the commit the same flags would make.+The branch must have a checked-out worktree; staging, hooks, and the commit all happen there.### Hooks@@ -290,13 +290,9 @@ The first matching row wins:| The branch is an ancestor of the target, so it has no commits of its own | `Fast-forwarded to <target>` || Otherwise | The branch's commits replay onto the target's tip — refused outright if the two share no history |-A branch that merged the target into itself still rebases: the target is its ancestor, but the merge commit in between keeps the first row from applying.--When the target's local ref lags its upstream, the rows are measured against that upstream, which the result then names in place of the argument. [`wt merge`](https://worktrunk.dev/merge/) covers why.-### Conflicts-A conflicting commit leaves the rebase open rather than undoing it. The worktree keeps git's conflict markers, and the ways out are `git rebase --continue` once the conflict is resolved, `git rebase --skip`, or `git rebase --abort`. Until the rebase is settled, `wt step rebase`, `wt step squash`, `wt step push`, and `wt merge` refuse to run — as they do while any other git operation is open, a conflicted `git merge` included.+A conflicting commit leaves the rebase open rather than undoing it. The worktree keeps git's conflict markers, and the ways out are `git rebase --continue` once the conflict is resolved, `git rebase --skip`, or `git rebase --abort`. Until the rebase is settled, `wt step rebase`, `wt step squash`, `wt step push`, and `wt merge` refuse to run.### Command reference@@ -343,9 +339,7 @@ $ wt step push --no-ff # Merge commit instead of a fast-forward### Target worktree-When the target branch has a worktree of its own, that worktree's files move to the new commits too. Uncommitted changes there never move: the update carries any file the push doesn't touch — staged or not — exactly where it is, and a change touching a file the push does change is refused upfront, naming the file. If the sync can't be applied for any reason — a conflicting file appearing in the race window after the check, or a busy index — the update is rolled back whole, leaving branch and worktree as they were.--A worktree that is still registered but whose directory is gone is refused as well, since nothing can be synced into it — `git worktree prune` clears the registration.+When the target branch has a worktree of its own, that worktree's files move to the new commits too. Uncommitted changes there never move: the update carries any file the push doesn't touch — staged or not — exactly where it is, and a change touching a file the push does change is refused upfront, naming the file. If the update can't be applied, it is rolled back, leaving branch and worktree as they were.### Command reference@@ -409,18 +403,6 @@ The diff is pipeable to tools like `delta`:$ wt step diff | delta```-### How it works--Equivalent to:--```bash-cp "$(git rev-parse --git-dir)/index" /tmp/idx-GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .-GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))-```--`git diff` ignores untracked files. `git add --intent-to-add .` registers them in the index without staging their content, making them visible to `git diff`. This runs against a copy of the real index so the original is never modified.-### Command reference```@@ -518,18 +500,12 @@ Files are reflinked where the filesystem supports it: APFS (macOS), btrfs and XF| `cp -R` (full copy) | 2m | 14GB || `cp -Rc` / `wt step copy-ignored` | 20s | ~0 |-On ext4 and NTFS, which have no reflink, every file is copied in full. The same byte count therefore costs nothing on one filesystem and 14GB on the other, so the summary says which happened: `Copied 4,812 files · 14.0 GB (reflinked, no extra disk)`, against `(full copy)` where those bytes were written out.+On ext4 and NTFS, which have no reflink, every file is copied in full; the summary says `(reflinked, no extra disk)` or `(full copy)`.Reflinks are per file (like `cp -Rc`), so copy time scales with file count.Use the `post-start` hook so the copy runs in the background. Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.-### Background-hook priority (experimental)--When invoked from a background hook pipeline (`post-*` hooks), `wt step copy-ignored` self-lowers its CPU and I/O priority — `taskpolicy -b` on macOS, `nice -n 19` plus `ionice -c 3` on Linux — so it yields to interactive work. Foreground callers (`pre-*` hooks, direct interactive use) run at normal priority so the user isn't waiting on a throttled copy.--wt signals background-hook context by exporting `WORKTRUNK_FOREGROUND=-1` into every detached hook pipeline; `copy-ignored` inspects that variable on entry. The variable name is experimental and may change.-### Language-specific notes#### Rust@@ -681,7 +657,7 @@ Automation:Run command in each worktree. Executes sequentially with real-time output; continues past command failures.-A summary of successes and failures is shown at the end. A template-expansion error (a malformed `{{ … }}` argument) aborts the whole run; only command failures are tolerated and reported. Context JSON — a flat object of every template variable — is piped to stdin for scripts that need structured data.+A summary of successes and failures is shown at the end. Context JSON — a flat object of every template variable — is piped to stdin for scripts that need structured data.### Arguments@@ -785,8 +761,6 @@ Without an argument, promotes the current branch — or restores the default braGitignored files (build artifacts, `node_modules/`, `.env`) are swapped along with the branches so each worktree keeps the artifacts that belong to its branch. Files are discovered using the same mechanism as [`copy-ignored`](#wt-step-copy-ignored) and can be filtered with `.worktreeinclude`.-The swap uses `rename()` for each entry — fast regardless of entry size, since only filesystem metadata changes. If the worktree is on a different filesystem from `.git/`, it falls back to reflink copy.-### Command reference```@@ -838,7 +812,7 @@ $ wt step prune --min-age=2d # skip candidates younger than 2 days### JSON output-`--format=json` prints one object per candidate to stdout. The two modes report different things, and name their fields accordingly: a live run reports `branch_outcome`, the executed outcome, using the vocabulary [`wt remove`](https://worktrunk.dev/remove/#json-output) documents; `--dry-run` reports `branch_deleted`, its prediction of whether the removal would take the branch, since it runs nothing to have an outcome. A dry run also carries `reason` and `target` (why the candidate qualifies, and what it was measured against).+`--format=json` prints one object per candidate to stdout. A live run reports `branch_outcome`, as [`wt remove`](https://worktrunk.dev/remove/#json-output) does. `--dry-run` reports `branch_deleted` (whether the removal would delete the branch), `reason` (why the candidate qualifies), and `target` (what it was measured against).### Examples@@ -924,9 +898,8 @@ this by using a temporary location.### ClobberingWith `--clobber`, non-worktree paths at target locations are moved to-`<path>.bak.<timestamp>` before relocating. If that name is already taken,-the move counts up (`…-2`, `…-3`, …) until it finds a free name, so an-existing backup is never overwritten.+`<path>.bak.<timestamp>` before relocating, never overwriting an existing+backup.### Main worktree behavior@@ -970,8 +943,7 @@ Options:--clobberBackup non-worktree paths at target locations- Moves blocking paths to <path>.bak.<timestamp>. If that name is taken, counts up (…-2, …-3- , …) to a free name.+ Moves blocking paths to <path>.bak.<timestamp>.-h, --helpPrint help (see a summary with '-h')@@ -1017,9 +989,7 @@ For pipes, redirects, variables, or globs, wrap in `sh -c`:$ wt step tether -- sh -c 'PORT=$P npm run dev | tee dev.log'```-To run the command from a subdirectory, pass the global `-C` flag (teardown-still watches the worktree root, so a server launched with a relative `-C` is-torn down with the worktree):+To run the command from a subdirectory, pass the global `-C` flag:```console$ wt step tether -C frontend -- npm run devdiff --git a/plugins/worktrunk/skills/worktrunk/reference/switch.md b/plugins/worktrunk/skills/worktrunk/reference/switch.mdindex 94d2090e1..eac1f9273 100644--- a/plugins/worktrunk/skills/worktrunk/reference/switch.md+++ b/plugins/worktrunk/skills/worktrunk/reference/switch.md@@ -19,7 +19,7 @@ $ wt switch https://github.com/owner/repo/pull/123 # ...or paste the PR's URLThe `--create` flag creates a new branch from `--base` — the default branch unless specified. Without `--create`, the branch must already exist. Switching to a remote branch (e.g., `wt switch feature` when only `origin/feature` exists) creates a local tracking branch.-One rule decides the upstream, whatever `branch.autoSetupMerge` is set to: a new branch tracks the remote branch it starts from only when the two share a name. Switching to `origin/feature` shares it, so that branch tracks. `--create` need not: `--create release --base origin/release` tracks `origin/release`, while `--create feature --base origin/release` — and the bare `--base release` that resolves to it — gets no upstream. Git's default would have `feature` track `origin/release`, so under `push.default = upstream` a bare `git push` would push the new work to `release`. Publishing such a branch takes `git push --set-upstream origin <branch>`, or git's `push.autoSetupRemote = true` set once, after which a bare `git push` from the new worktree publishes it and configures its tracking.+A new branch tracks the remote branch it starts from only when the two share a name: `--create release --base origin/release` tracks `origin/release`, while `--create feature --base origin/release` gets no upstream. Publish such a branch with `git push --set-upstream origin <branch>`, or set git's `push.autoSetupRemote = true` once.## Creating worktrees@@ -61,7 +61,7 @@ $ wt switch pr:123 # PR #123's branch$ wt switch mr:101 # MR !101's branch```-Shortcuts also apply to `--base`. For a fork PR/MR, the head commit is fetched and used as the base SHA without creating a tracking branch.+Shortcuts also apply to `--base`.## Interactive picker@@ -77,7 +77,7 @@ The CI column shows each row's PR/MR CI and review status, the same as [`wt list| (type) | Filter worktrees || `Enter` | Switch to selected worktree || `Alt-c` | Create new worktree named as entered text |-| `Alt-x` | Remove selected worktree/branch (never forces) |+| `Alt-x` | Remove selected worktree/branch (never forces; not the current worktree) || `Alt-y` | Copy selected branch name to the clipboard || `Alt-o` | Open the selected row's PR/MR URL in the browser || `Alt-r` | Refresh the list (pick up worktrees created elsewhere) |@@ -87,13 +87,7 @@ The CI column shows each row's PR/MR CI and review status, the same as [`wt list| `Alt-p` | Toggle preview panel || `Ctrl-u`/`Ctrl-d` | Scroll preview up/down |-`Alt-o` is a no-op on a row with no PR/MR (or whose status hasn't loaded yet).--`Alt-x` is a no-op on the current worktree (the `@` row) — removing the worktree in use would have to switch elsewhere first, so switch away and remove it from there.--Each row filters by its branch, path, and — when it has a PR/MR — the PR/MR's number, title, and author, the same fields whether the PR is checked out (a worktree row) or listed via `--prs`. Plain digits go to the filter, so a number can be typed directly and the preview tabs move to `Alt`.--Typing a gutter sigil filters by row kind: `+` narrows to linked worktrees and `@` to the current worktree. The other sigils don't filter cleanly — `^` and `|` are skim's prefix-anchor and OR query operators (so `^` matches every row and `|` none), and `/` matches most rows because every worktree path contains it.+The filter matches each row's branch, path, and — when it has a PR/MR — the PR/MR's number, title, and author. Typing `+` narrows to linked worktrees, and `@` to the current worktree.**Preview tabs:**@@ -108,8 +102,6 @@ Typing a gutter sigil filters by row kind: `+` narrows to linked worktrees and `The comparison base is the merge-base with the default branch, or with its upstream when the local default branch lags. The picker opens on **diff** for local rows and **pr** for a PR/MR listed by `--prs` but not available locally. `Tab` and `Shift-Tab` skip tabs without content; `Alt-1` through `Alt-8` open any tab directly. After you choose a tab, that choice stays active while you navigate.-On narrow previews the tab bar compacts to digits — only the active tab keeps its label — so every `Alt-N` accelerator stays visible.-**Pager configuration:** The preview panel pipes diff output through git's pager. Override in user config:```toml@@ -133,7 +125,7 @@ Both work anywhere a branch is accepted, including `--base`. The `--create` flagIf the PR or MR is on a fork, the local branch uses its branch name directly, so `git push` works normally. A pre-existing local branch with that name tracking something else requires renaming first.-The `--prs` flag adds the repository's open PRs (GitHub) or MRs (GitLab) to the interactive picker — only the ones not already there: a PR whose branch is already shown (as a worktree, or a local or remote branch) isn't listed twice, so `--prs` only adds the rest and the two pickers differ solely by those extra rows. Each added row resolves to the same `pr:`/`mr:` shortcut, so selecting one fetches the ref and switches to its branch. A `--prs` row has no local worktree, so its `pr` and `comments` preview tabs load the PR/MR's metadata and comments from the forge in the background. The `log` tab uses a local `git log` — graph and merge-base dimming included — whenever the head commit is already in the object store (a same-repo PR off a fetched remote), falling back to a flat forge-fetched commit list otherwise.+The `--prs` flag adds the repository's open PRs (GitHub) or MRs (GitLab) that aren't already in the interactive picker. Selecting one switches to it as `pr:<number>` / `mr:<number>` would.Requires `gh` (GitHub), `glab` (GitLab), or an equivalent CLI installed and authenticated; see [forge platform](https://worktrunk.dev/config/#forge-platform) for Gitea, Azure DevOps, and other supported platforms.diff --git a/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md b/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.mdindex 67b11c953..4a6a4cdeb 100644--- a/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md+++ b/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md@@ -276,7 +276,7 @@ MY_PACKAGES_PATH = "{{ config_root }}/.packages"`{{ config_root }}` is the project root mise resolves relative paths against ([env directives](https://mise.jdx.dev/environments/)) — the worktree root, not the primary worktree. mise also covers Windows / PowerShell, which direnv doesn't natively.-Both set real environment variables in the shell session, so every child process inherits them — hooks, build tools, subshells — without the `--execute` workaround. Each new worktree is a new path, so it needs its own one-time trust step (`direnv allow` / `mise trust`); worktrunk deliberately doesn't bypass that prompt, the same safety reasoning behind [disabling `--execute` in project alias and hook bodies](https://github.com/max-sixty/worktrunk/issues/2101).+Both set real environment variables in the shell session, so every child process inherits them — hooks, build tools, subshells. Each new worktree is a new path, so it needs its own one-time trust step (`direnv allow` / `mise trust`).### Eliminate cold startsdiff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.mdindex cbb5b1624..d8724c79f 100644--- a/skills/worktrunk/reference/claude-code.md+++ b/skills/worktrunk/reference/claude-code.md@@ -51,7 +51,7 @@ codex plugin add worktrunk@worktrunkwt config plugins opencode install```-This writes the activity-tracking plugin to OpenCode's global plugins directory, `~/.config/opencode/plugins/worktrunk.ts` (honoring `$OPENCODE_CONFIG_DIR` and `$XDG_CONFIG_HOME`). `wt config plugins opencode uninstall` removes it. The one file covers both plugin runtimes — OpenCode 2 loads its `setup` export, OpenCode 1.16 and later its `server` export.+This writes the activity-tracking plugin to OpenCode's global plugins directory, `~/.config/opencode/plugins/worktrunk.ts` (honoring `$OPENCODE_CONFIG_DIR` and `$XDG_CONFIG_HOME`). `wt config plugins opencode uninstall` removes it.### Pi@@ -59,7 +59,7 @@ This writes the activity-tracking plugin to OpenCode's global plugins directory,wt config plugins pi install```-This writes the activity extension to `~/.pi/agent/extensions/worktrunk.ts`, where Pi discovers it on startup; `$PI_CODING_AGENT_DIR` replaces the agent directory. Pi has no profile concept. `wt config plugins pi uninstall` removes the extension.+This writes the activity extension to `~/.pi/agent/extensions/worktrunk.ts`, where Pi discovers it on startup; `$PI_CODING_AGENT_DIR` replaces the agent directory. `wt config plugins pi uninstall` removes the extension.### oh-my-pi@@ -128,12 +128,6 @@ Activity tracking is not plugin-specific. The plugins above only call `wt` on th| Agent finishes a turn and waits for input | `wt config state marker set "💬"` || Session ends | `wt config state marker clear` |-Three things to get right:--- **Run the command inside the worktree.** Each one resolves the branch from its working directory, so a hook that runs elsewhere marks the wrong branch, and one that runs outside a repository silently does nothing. Where the host pins the working directory elsewhere, pass the global `-C <worktree>`, which moves both the repository lookup and the branch resolution. `--branch <branch>` names the branch on its own, but the repository lookup still comes from the working directory — that, not a missing worktree argument, is why a caller pinned outside the repository needs `-C`. Elsewhere, a command that names a branch ([`wt switch`](https://worktrunk.dev/switch/), [`wt remove`](https://worktrunk.dev/remove/), `wt step diff --branch`) already names the worktree it acts on, and `-C` is for reaching a different repository rather than a different worktree.-- **Don't let a failed marker call fail the session.** Outside a repository both `set` and `clear` do nothing and exit 0, but an invalid `--branch` or a failed git config write still exits non-zero, and hosts differ on what a non-zero hook does. Append `|| true` (or the host's equivalent) to every call unless you want that surfaced.-- **Clear on exit.** A marker set on session start persists until something clears it, so pair every set with a clear on the host's session-end event — and expect the same stale marker as above if the process is killed first.-## Worktree isolation (Claude Code only)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.diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.mdindex 8f7bf8c64..fae65d742 100644--- a/skills/worktrunk/reference/config.md+++ b/skills/worktrunk/reference/config.md@@ -220,14 +220,11 @@ Valid built-in names:A selection mixes built-ins with [custom columns](#custom-columns), each namedby its `[list.custom-columns]` header (`columns = ["branch", "Ticket", "ci"]`),and is exhaustive: only the listed columns render. Omit `columns` to keep the-default set, where custom columns append automatically. A built-in name wins a-header collision; the gutter type indicator always shows.+default set, where custom columns append automatically.-Listing a column forces it on, space permitting: `ci` shows without `--full`,-since `--full` only bundles columns into the default table rather than gating a-named one. A column whose data source is missing still stays hidden — `summary`-needs an LLM command (`[commit.generation]`), `url` needs a `[list] url`-template — since listing can't supply the data.+Listing a column forces it on, space permitting: `ci` shows without `--full`. A+column whose data source is missing still stays hidden — `summary` needs an LLM+command (`[commit.generation]`), `url` needs a `[list] url` template.#### Custom columns [experimental]@@ -369,7 +366,7 @@ worktree-path = ".worktrees/{{ branch | sanitize }}"Every matching entry applies, least- to most-specific, following the rule above: a more specific entry — `git.company.example/platform/*` over `git.company.example/*` — wins where both set the same setting, while hooks and aliases from every matching entry all run, least-specific first. A literal key is the most specific of all; specificity is the count of non-`*` characters in the key. End a host-wide key with `/*` — a bare `git.company.example*` also covers hosts whose names merely start with that string.-`approved-commands` matches the same way, so a pattern entry approves its commands for every repository it covers. Only a key written by hand is ever a pattern: `wt config approvals add` and the interactive prompt record under the exact identifier, and `wt config approvals clear` removes only that exact entry, leaving a pattern other repositories share intact.+Entries in `approvals.toml` match the same way, so a hand-written pattern entry approves its commands for every repository it covers.#### Forge platform and hostname@@ -381,9 +378,9 @@ forge.platform = "gitlab" # or "github", "gitea" (experimentaforge.hostname = "api.git.company.example" # API host, when the remote's own host isn't it```-Both fields describe the host rather than the repository, which is why a pattern keyed to a hostname suits them, and why an SSH alias resolved through `~/.ssh/config` — where the name in the remote URL is local to one machine — belongs here rather than in a repository's committed config. A repository's own `[forge]` block still wins over any entry here, field by field: a repository that sets only `platform` still takes a matching entry's `hostname`.+A repository's own `[forge]` block still wins over any entry here, field by field.-Hooks support all three [hook forms](https://worktrunk.dev/hook/#hook-forms). A table runs multiple commands concurrently; an array-of-tables pipeline runs steps in sequence. The dotted-key examples below are equivalent to the table forms — TOML treats `projects."github.com/user/repo".post-start.server = "..."` and a `[projects."github.com/user/repo".post-start]` table the same way:+Hooks support all three [hook forms](https://worktrunk.dev/hook/#hook-forms). A table runs multiple commands concurrently; an array-of-tables pipeline runs steps in sequence:```toml# Single command@@ -526,7 +523,7 @@ template-append = """"""```-How the fragment renders, and the project-config counterpart: [the LLM commits guide](https://worktrunk.dev/llm-commits/#appending-to-the-prompt).+See [the LLM commits guide](https://worktrunk.dev/llm-commits/#appending-to-the-prompt) for how the fragment renders and its project-config counterpart.## User hooks@@ -582,7 +579,7 @@ template-append = """"""```-The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in [user config](https://worktrunk.dev/config/), since they describe per-developer environment (which CLI is installed, which agent the developer prefers). How the fragment renders: [the LLM commits guide](https://worktrunk.dev/llm-commits/#appending-to-the-prompt).+The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in [user config](https://worktrunk.dev/config/). See [the LLM commits guide](https://worktrunk.dev/llm-commits/#appending-to-the-prompt) for how the fragment renders.## Copy-ignored excludes@@ -659,9 +656,6 @@ $ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge| `WORKTRUNK_SYSTEM_CONFIG_PATH` | Override system config file location || `WORKTRUNK_PROJECT_CONFIG_PATH` | Override project config file location (defaults to `.config/wt.toml`); relative paths resolve from the worktree root || `XDG_CONFIG_DIRS` | Colon-separated system config directories (default: `/etc/xdg`) |-| `WORKTRUNK_DIRECTIVE_CD_FILE` | Internal: set by shell wrappers. wt writes a raw path; the wrapper `cd`s to it |-| `WORKTRUNK_SHELL_CWD` | Internal: set by wt on alias and hook bodies, so a nested `wt` preserves the user's subdirectory |-| `WORKTRUNK_COMPLETE_NAME` | Internal: set by shell wrappers to the command name completions register under (defaults to the binary name) || `WORKTRUNK_MAX_CONCURRENT_COMMANDS` | Max parallel git commands (default: 32). Lower if hitting file descriptor limits. || `WORKTRUNK_VERBOSE` | Verbosity level (`0`/`1`/`2`), like `-v`/`-vv` but applied everywhere — including shell completion, which no flag can reach || `RUST_LOG` | Logging directive (e.g. `worktrunk=debug`); overrides the verbosity baseline for what reaches stderr |@@ -894,7 +888,7 @@ Approved commands are saved to `~/.config/worktrunk/approvals.toml`. Re-approval`state` is `no_commands` (the project declares none), `approval_required` (at least one is unapproved), or `approved`. `name` is absent for an unnamed command and for the commit-template fragment.-`stale` is separate rather than a fourth `state`, because it co-occurs with all three: these are approvals recorded earlier whose command has since been edited or removed from the project config. They are what `--yes` would silently re-approve, so an orchestrator preserving the approval model reads them before choosing that flag.+`stale`, which can accompany any `state`, lists approvals whose command has since been edited or removed from the project config.### Command reference@@ -1033,7 +1027,7 @@ View or drop worktrunk's regenerable caches in one place. Everything here is reb### What's cached-- **CI status** — GitHub/GitLab CI per branch (30–60s TTL), shown in [`wt list`](https://worktrunk.dev/list/#ci-status), plus the largest PR/MR number seen (sizes the CI column)+- **CI status** — GitHub/GitLab CI per branch (30–60s TTL), shown in [`wt list`](https://worktrunk.dev/list/#ci-status)- **Summaries** — LLM-generated branch summaries (`wt list --full`, `wt switch` preview)- **Git commands** — cached merge-tree, ancestry, diff-stat, and `wt switch` preview results- **Hints** — one-time hints already shown in this repo@@ -1089,20 +1083,16 @@ In a hook or alias template, prefer the `{{ default_branch }}` [template variablWithout a subcommand, runs `get`. `set` stores the override in the repository's local git config. The override adds no project file and applies to every linked worktree in the clone. `clear` then `get` re-detects. The branch must exist locally for `wt list` comparisons.-`default-branch get` resolves the value and caches it on a miss; the aggregate `wt config state get` only reports the cache (read-only), so it can show `(none)` until something populates it.-### DetectionWorktrunk detects the default branch automatically:1. **Worktrunk cache** — Checks `git config worktrunk.default-branch`2. **Git cache** — Detects primary remote and checks its HEAD (e.g., `origin/HEAD`)-3. **Remote query** — If not cached, queries `git ls-remote` — typically 100ms–2s, abandoned after 10s+3. **Remote query** — If not cached, queries `git ls-remote`, giving up after 10s4. **Local inference** — If no remote, or the query was abandoned, infers from local branches-Once detected, the result is cached in `worktrunk.default-branch` for fast access. The cache isn't re-validated on every command, so a later change to `origin/HEAD` — a renamed default branch followed by `git remote set-head origin -a` — isn't picked up automatically. `wt config state` flags the drift when the cached value differs from the remote's local HEAD — expected for a deliberate override; `set` adopts the new branch and `clear` re-detects.--An abandoned remote query is the one case that isn't cached: the branch it inferred locally answers that command, but a value guessed while the remote was unreachable would otherwise become permanent, so the next command queries again.+Once detected, the result is cached in `worktrunk.default-branch` — except a value inferred after the remote query was abandoned, so an outage can't make a guess permanent. A later change to `origin/HEAD` isn't picked up automatically: `wt config state` flags the mismatch, `set` adopts the new branch, and `clear` re-detects.The local inference fallback uses these heuristics in order:- If only one local branch exists, uses it@@ -1163,7 +1153,7 @@ Hook output lives in per-branch subtrees under `.git/wt/logs/{branch}/`:| Background hooks | `{branch}/{source}/{hook-type}/{name}.log` || Background removal | `{branch}/internal/remove.log` |-All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is `user` or `project`. Branch and hook names are sanitized for filesystem safety (invalid characters → `-`; short collision-avoidance hash appended). Same operation on same branch overwrites the previous log. Removing a branch clears its subtree; orphans from deleted branches can be swept with `wt config state logs clear`.+All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is `user` or `project`. Branch and hook names are sanitized for filesystem safety. Same operation on same branch overwrites the previous log. Removing a branch clears its subtree; orphans from deleted branches can be swept with `wt config state logs clear`.#### Diagnostic files@@ -1174,11 +1164,11 @@ All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the| `subprocess.log` | Running with `-vv` || `diagnostic.md` | Running with `-vv` |-`trace.log` is the human-readable trace at `-vv` — each command's start (`$ …`) and completion (`✓`/`✗ … 12.3ms`), in-process spans, milestones, and bounded subprocess previews. `trace.jsonl` is the same event stream as one JSON object per line, for machines (`jq`, chrome://tracing); `wt config state logs profile` reads it to summarize a performance report (where time went, parallelism, redundant commands). `subprocess.log` holds the raw uncapped subprocess stdout/stderr bodies. `diagnostic.md` is a markdown bug-report bundle that leads with that same performance profile and inlines `trace.log`; `wt` prints a `gh gist create` command pointing at it. All four are overwritten on each `-vv` run.+`trace.log` is the human-readable trace of commands and their timings. `trace.jsonl` holds the same events as JSON lines, which `wt config state logs profile` summarizes into a performance report. `subprocess.log` holds full subprocess output. `diagnostic.md` is a bug-report bundle; `wt` prints a `gh gist create` command for it. All four are overwritten on each `-vv` run.### Location-All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory. Top-level files are shared logs (command audit + diagnostics); top-level directories are per-branch log trees.+All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory.### Structured output@@ -1232,36 +1222,6 @@ Output:Output format (text, json) [default: text]```-## wt config state ci-status--CI status cache.--**Deprecated** — the CI status cache is now part of [`wt config state cache`](https://worktrunk.dev/config/#wt-config-state-cache). This subcommand still works but prints a deprecation notice.--Status values, display symbols, and fetch behavior: [`wt list` CI status](https://worktrunk.dev/list/#ci-status).--Without a subcommand, runs `get` for the current branch. Use `clear` to reset cache for a branch or `clear --all` to reset all.--### Command reference--```-wt config state ci-status - CI status cache--Usage: wt config state ci-status [OPTIONS] [COMMAND]--Commands:- get Get CI status for a branch- clear Clear CI status cache--Options:- -h, --help- Print help (see a summary with '-h')--Output:- --format <FORMAT>- Output format (text, json) [default: text]-```-## wt config state markerBranch markers.@@ -1370,7 +1330,7 @@ dev = "npm start -- --port {{ vars.config.port }}"### Storage format-Stored in git config as `worktrunk.state.<branch>.vars.<key>`. Keys must contain only letters, digits and hyphens — dots conflict with git config's section separator, underscores with its variable name format.+Stored in git config as `worktrunk.state.<branch>.vars.<key>`. Keys may contain only letters, digits, and hyphens.### Command referencediff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.mdindex bef10ddf2..c688d4654 100644--- a/skills/worktrunk/reference/extending.md+++ b/skills/worktrunk/reference/extending.md@@ -152,14 +152,12 @@ git fetch --all --prune; wt step for-each -- sh -c '`wt up` fetches every remote, then brings each worktree up to date with its upstream: skip if there is no upstream or a rebase is already in progress, fast-forward if a tracked file is modified or staged, otherwise rebase, aborting on conflict. It rebases onto git-native `@{u}` rather than a `{{ … }}` template, so git resolves each worktree's own upstream and there is nothing to defer.-A sweep finds each worktree in whatever state you left it, so most of the script is guards:+Two details matter when adapting it:-- `git fetch --all` exits non-zero when any single remote fails. With `&&`, one remote with lapsed credentials is enough to skip the whole sweep, so even worktrees whose refs fetched fine go unrebased. With `;` the sweep runs on what did fetch, and the fetch error still prints.-- `git rebase` refuses to run in a worktree with a modified or staged tracked file, whether or not there is anything to rebase — so a worktree you are editing would fail the sweep. `git merge --ff-only` is the piece of the rebase git will still do there: it advances a branch that is simply behind, and otherwise changes nothing — a diverged branch, or an incoming file that collides with your edits, leaves the worktree exactly as it was, with the reason printed. Untracked files trigger neither the refusal nor the `git diff` guard, so a worktree carrying only new files still rebases — unless one of them has the same name as a file the incoming commits add, which git declines to overwrite.-- `rebasing` tells the two ways `git rebase` fails apart. Conflicting partway leaves a rebase in progress, which the abort winds back. Refusing to start — a tracked file modified under you, an untracked file in the way of an incoming one, a `pre-rebase` hook saying no — leaves nothing to abort and nothing to clean up, so the sweep moves on; an unconditional `git rebase --abort` there would answer `fatal: no rebase in progress` and exit 128 in place of git's own message.-- Both arms pass `--no-autostash`, because a global `rebase.autostash` or `merge.autostash` breaks what each arm relies on. An autostash that pops with conflicts leaves the markers in the worktree and still exits 0, so the sweep would report success on a worktree it had just left in conflict — and an autostashed tree is momentarily clean, so a fast-forward that should have refused goes through and the collision lands on the pop instead.+- `;` after the fetch lets the sweep run even when one remote fails to fetch.+- `--no-autostash` overrides a global `rebase.autostash` or `merge.autostash`, whose conflicting pop would leave markers behind and still exit 0.-So the sweep exits non-zero only when it leaves a worktree needing attention — an abort that itself failed. Everything git declines to do, it declines atomically, and the sweep carries on to the next worktree with git's reason in the output. That matters where the alias is a hook step, since a failing step stops the rest of the pipeline.+The sweep exits non-zero only when it leaves a worktree needing attention, which matters when the alias runs as a hook step: a failing step stops the rest of the pipeline.### Recipe: move or copy in-progress changes to a new worktree@@ -233,7 +231,6 @@ Aside from the differences below, hooks and aliases behave the same.| Reach `{{ args }}` from positionals | Must use `--` (`wt hook pre-merge -- extra`) | Any bare positional lands there || Approval skip flag | Post-subcommand `--yes` / `-y` supported (`wt hook pre-merge --yes`) | Only the global form (`wt -y <alias>`); post-alias `--yes` falls through to `{{ args }}` || Source discrimination | `user:` / `project:` / `user:name` / `project:name` filter syntax | Run user first, then project; no filter syntax |-| Force-bind escape | `--var KEY=VALUE` (deprecated in favor of `--KEY=VALUE`, but still force-binds) | None; smart routing is the only path || `--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 | All template variables as JSON (parse with `json.load(sys.stdin)`) | Inherits parent stdin (pipes pass through; interactive TUIs like `wt switch` keep the tty) |diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.mdindex cf50adfa2..1af900ec4 100644--- a/skills/worktrunk/reference/faq.md+++ b/skills/worktrunk/reference/faq.md@@ -208,10 +208,10 @@ A branch checked out in a second worktree is retained regardless, `-D` included.### Other cleanup- `wt merge` / `wt step push` — the target branch's checked-out worktree is updated to the merged commits, so a file those commits delete disappears from it, and an ignored file at a path they track is overwritten — the same result a `git merge` run in that worktree would produce. Uncommitted changes at paths the merge doesn't touch stay in place, staged or not; one at a path it does touch refuses the merge upfront, naming the file-- `wt remove` — besides the worktree being removed, two cleanup mechanisms run. The removed worktree's own `git fsmonitor--daemon` (git's per-worktree filesystem watcher under `core.fsmonitor=true`, which would leak once its worktree is gone) is sent `git fsmonitor--daemon stop`, then force-terminated (`SIGTERM`, then `SIGKILL`) via the PID resolved from its IPC socket if it didn't exit. A background sweep then deletes `.git/wt/trash/` entries older than 24 hours (directories orphaned when a previous background removal was interrupted) and terminates fsmonitor daemons whose worktree no longer exists (orphans from `git worktree remove`, `rm -rf`, or a crashed `wt`)+- `wt remove` — also stops the removed worktree's `git fsmonitor--daemon` (under `core.fsmonitor=true`), and sweeps `.git/wt/trash/` entries older than 24 hours along with fsmonitor daemons whose worktree no longer exists- `wt config state clear` — removes all worktrunk data from `.git/` (config keys, caches, markers, hints, variables, logs, stale trash)-- `wt config shell install` — when migrating an integration to a new location, removes the file left at the old one: fish `conf.d/wt.fish` (now `functions/wt.fish`) and nushell wrappers stranded under `<config-dir>/vendor/autoload` (now `<data-dir>/vendor/autoload`). The old path is where worktrunk's own wrapper lived and is named after the command being installed, so it's taken back whole without reading it — a `conf.d/wt.fish` left in place would be sourced at startup and shadow the new wrapper anyway. Only that exact filename is touched, and each removal is printed. The same rule covers the path being installed to, so an existing `functions/wt.fish`, `completions/wt.fish`, or `wt.nu` is replaced whole; [Files created](https://worktrunk.dev/shell-integration/#files-created) names the file each shell gets-- `wt config shell uninstall` — removes integration lines from bash/zsh/PowerShell rc files, and deletes worktrunk's wrapper and completion files (fish `functions/`, `conf.d/`, and `completions/`; nushell `vendor/autoload`). Uninstall takes no command name, so it lists those directories and recognizes files by worktrunk's own content markers, whatever binary name they were installed under; files without the markers are left alone. An rc file belongs to the user, so a line qualifies only where it runs the init command: one that merely mentions it, inside a comment, an `echo`, or an alias body, stays. Every line uninstall does take is printed, before removal and again after+- `wt config shell install` — replaces an existing fish or Nushell wrapper file whole, and removes one an older version installed at a previous location (fish `conf.d/wt.fish`, Nushell `<config-dir>/vendor/autoload/wt.nu`), printing each removal; [Files created](https://worktrunk.dev/shell-integration/#files-created) names the file each shell gets+- `wt config shell uninstall` — removes the lines that run `wt config shell init` from bash/zsh/PowerShell rc files, and deletes wrapper and completion files carrying worktrunk's content markers (fish `functions/`, `conf.d/`, and `completions/`; nushell `vendor/autoload`). Every removed line is printed- `wt config plugins opencode uninstall` / `wt config plugins pi uninstall` / `wt config plugins omp uninstall` — deletes that agent's `worktrunk.ts` plugin file. Only worktrunk's own file is touched; the rest of the agent's plugin directory is left aloneSee [What files does Worktrunk create?](#what-files-does-worktrunk-create) for details.@@ -246,7 +246,7 @@ Use `--yes` to bypass prompts (useful for CI/automation).### Command log-All hook executions and LLM commands are recorded in `.git/wt/logs/commands.jsonl` — one JSON object per line. Fields: `ts` (timestamp), `wt` (the wt command that triggered it), `label` (what ran, e.g., `pre-merge user:lint`), `cmd` (shell command), `exit` (exit code, `null` for background), `dur_ms` (duration, `null` for background). The file rotates to `commands.jsonl.old` at 1MB, bounding storage to ~2MB.+All hook executions and LLM commands are recorded in `.git/wt/logs/commands.jsonl`, one JSON object per line; [`wt config state logs`](https://worktrunk.dev/config/#wt-config-state-logs) lists the fields.View the log with `wt config state logs get`, or query directly:@@ -266,7 +266,7 @@ Yes. Core commands, shell integration, and tab completion work in both Git Bash**Git for Windows required** — Hooks use bash syntax and execute via Git Bash, so [Git for Windows](https://gitforwindows.org/) must be installed even when PowerShell is the interactive shell.-The `wt switch` interactive picker runs on Windows too, on [skim](https://github.com/skim-rs/skim)'s crossterm backend.+The `wt switch` interactive picker runs on Windows too.## How does Worktrunk determine the default branch?@@ -290,7 +290,7 @@ Installing with Cargo and the default features also requires a C99 compiler forcargo install worktrunk --no-default-features --features cli```-This disables bash syntax highlighting in command output but keeps all core functionality. The syntax highlighting feature requires C99 compiler support and can fail on older systems or minimal Docker images.+This disables bash syntax highlighting in command output but keeps all core functionality.## How can I contribute?diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex 010bc2233..e3e71c131 100644--- a/skills/worktrunk/reference/hook.md+++ b/skills/worktrunk/reference/hook.md@@ -31,7 +31,7 @@ The most common creation hook is `post-start` — it runs background tasks (dev| `pre-remove` | Cleanup before worktree deletion: saving test artifacts, backing up state. Runs in the worktree being removed || `post-remove` | Stopping dev servers, removing containers, notifying external systems. Template variables reference the removed worktree |-During `wt merge`, the blocking hooks run in this order: pre-commit → pre-merge → pre-remove. The `post-*` hooks all start together once the merge finishes, each in the worktree it is anchored on — post-merge, post-switch and post-remove in the destination, post-commit in the worktree the commit was made in. A merge that removes that worktree reports `post-commit` as skipped instead of running it — the worktree is gone by the time the hook would start. Use `pre-remove` for work that must finish there, or `--no-remove` to keep the worktree. See [`wt merge`](https://worktrunk.dev/merge/#pipeline) for the complete pipeline.+During `wt merge`, the blocking hooks run in this order: pre-commit → pre-merge → pre-remove. The `post-*` hooks start together once the merge finishes. See [`wt merge`](https://worktrunk.dev/merge/#pipeline) for the complete pipeline.# Security@@ -93,7 +93,7 @@ server = "npm run dev"Here `install` runs first, then `build` and `server` run together.-Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](https://worktrunk.dev/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Because an earlier step can still change those values, a preview stands the reference in for its value instead of resolving it: `wt hook <type> --dry-run` and `wt hook show --expanded` render `{{ vars.thing | default('none') }}` as `{{ vars.thing }}` — the reference is defined, so the `default` never fires — while every other variable expands. A filter that transforms its input still runs, against the placeholder text, and its output is shell-escaped like any other value: `{{ vars.thing | upper }}` previews as `'{{ VARS.THING }}'`.+Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](https://worktrunk.dev/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Previews (`wt hook <type> --dry-run`, `wt hook show --expanded`) leave `{{ vars.* }}` references unexpanded for that reason.Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependency chain — typically setup that must complete before later steps, like installing dependencies before running a build and dev server concurrently.@@ -157,9 +157,9 @@ All hooks share the same perspective — `{{ branch | hash_port }}` produces the`cwd` is the worktree root where the hook command runs. It equals `worktree_path` except in three cases:-- `pre-switch`: hook runs in the source worktree; `worktree_path` is the destination when that worktree already exists — a switch that creates one has no destination directory yet, so `worktree_path` stays on the source (use `pre-start` to work in the new worktree)+- `pre-switch`: hook runs in the source worktree; `worktree_path` is the destination, or the source when the switch creates a new worktree (use `pre-start` to work in the new worktree)- `post-remove`: the active worktree is gone, so the hook runs in the primary worktree-- `post-merge`: the hook runs in the target branch's worktree (the primary worktree if the target has none), including under `--no-remove`, where the merged worktree `worktree_path` names is still on disk+- `post-merge`: the hook runs in the target branch's worktree (the primary worktree if the target has none)Undefined variables error — use conditionals or defaults for optional behavior:@@ -169,7 +169,7 @@ Undefined variables error — use conditionals or defaults for optional behaviorsync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"```-A detached worktree is on no branch, so `branch` is undefined there — as are the `base` and `target` names derived from it, whether by a manual `wt hook` or by an operation whose source or destination worktree is detached (`base` in a `pre-switch` fired from one, `target` in a removal that lands in one) — and the same `{% if branch %}` guard applies. This matches `wt list --format=json`, which reports `branch: null` for the same worktree.+A detached worktree has no branch, so `branch` — and a `base` or `target` that names that worktree — is undefined there; guard with `{% if branch %}`.Run any hook-firing command with `-v` to see the resolved variables for the actual invocation — each hook prints a `template variables:` block showing every in-scope variable and its value (`(unset)` for conditional vars that didn't populate, like `target_worktree_path` during `wt switch -`). Aliases do the same under `-v`: `wt -v <alias>` prints the alias's in-scope variables before the pipeline runs.@@ -261,7 +261,7 @@ if ctx.get('branch', '').startswith('feature/') and 'backend' in ctx['repo']:## Copying untracked files-One specific command worth calling out: [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored). Git worktrees share the repository but not untracked files, and this copies gitignored files between worktrees:+Git 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:```toml[post-start]@@ -317,8 +317,6 @@ $ wt hook post-startAny `--KEY=VALUE` whose key isn't referenced by a hook template forwards into `{{ args }}` as a literal `--KEY=VALUE` token. Tokens after `--` also forward into `{{ args }}` verbatim. `{{ args }}` renders as a space-joined, shell-escaped string; index with `{{ args[0] }}`, loop with `{% for a in args %}…{% endfor %}`, count with `{{ args | length }}`.-The long form `--var KEY=VALUE` is deprecated but still supported. It force-binds regardless of whether any hook template references `KEY` — useful when a template only references the key conditionally (e.g. `{% if override %}…{% endif %}`).-# Recipes- [Eliminate cold starts](https://worktrunk.dev/tips-patterns/#eliminate-cold-starts): `wt step copy-ignored` in `post-start` shares build caches and dependencies; use a `[[post-start]]` pipeline when a later hook depends on the copydiff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.mdindex 6e7c8a403..f25a56bcb 100644--- a/skills/worktrunk/reference/list.md+++ b/skills/worktrunk/reference/list.md@@ -8,7 +8,7 @@ The table renders progressively: branch names, paths, and commit hashes appear i## Full mode-`--full` adds the two columns that reach off-machine: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail, over the network) and [LLM-generated summaries](#llm-summaries) of each branch's changes. The `main…±` line diffs are local git, so they show by default.+`--full` adds the two columns that reach off-machine: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail, over the network) and [LLM-generated summaries](#llm-summaries) of each branch's changes.## Examples@@ -63,7 +63,7 @@ $ wt list --format=json| Column | Shows ||--------|-------|-| Branch | Branch name, elided with `…` past 32 characters so one long name can't size the column for every row (`--format=json` keeps it whole); a detached worktree has none, so it shows its short hash in dim yellow |+| Branch | Branch name, elided with `…` past 32 characters; a detached worktree shows its short hash || Status | Compact symbols (see below) || HEAD± | Uncommitted changes, including untracked files: +added -deleted lines || main↕ | Commits ahead/behind default branch |@@ -80,9 +80,7 @@ $ wt list --format=jsonThe `main↕` and `main…±` headers keep the familiar `main` label in every repository.-The table sizes itself to the terminal. When the columns don't all fit, the least important go first — roughly right to left, since the order above runs from identity to nice-to-have — and the summary footer names them (`hidden: Commit, Age, Message`). A column with nothing to show on any row — `Remote⇅` in a repo with no remote — ranks below every populated column, so it goes first. A wider terminal brings them back. To pin a set rather than leave it to the width, name the columns in [`[list] columns`](https://worktrunk.dev/config/#list); `--format=json` carries every field at any width.--`main↕` and `main…±` measure against the default branch's upstream tip when the local copy lags it — so in a fork whose local `main` trails `origin/main`, a branch reads as ahead of the real mainline, not of a stale local checkout. The `↑`/`↓`/`↕` Status symbols derive from these counts, so they track the upstream tip too.+The table sizes itself to the terminal. When the columns don't all fit, the least important go first — roughly right to left, since the order above runs from identity to nice-to-have — and the summary footer names them (`hidden: Commit, Age, Message`). A wider terminal brings them back. To pin a set rather than leave it to the width, name the columns in [`[list] columns`](https://worktrunk.dev/config/#list); `--format=json` carries every field at any width.### Gutter@@ -98,7 +96,7 @@ The leftmost column marks each row by physical presence, from most present to le### CI status-The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and Azure DevOps, `!3035` on GitLab — colored by pipeline status, or a bare `#` when no number is available (e.g. branch workflows without a PR/MR). One color folds two JSON fields: green/blue/red/yellow/gray are the pipeline state, magenta/cyan the review state. The `Value` column names each state; [checks object](#checks-object) and [review states](#review-states) give the JSON spelling — schema 2 reports three of the pipeline values by the shape of `pr` and `checks` rather than as a `checks.status` string:+The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and Azure DevOps, `!3035` on GitLab — colored by pipeline status, or a bare `#` when no number is available (e.g. branch workflows without a PR/MR). Green, blue, red, yellow, and gray show the pipeline state; magenta and cyan show the review state. [checks object](#checks-object) and [review states](#review-states) give the JSON form of each value:| Indicator | Value | Meaning ||-----------|-------|---------|@@ -114,9 +112,9 @@ The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and AzThe two remaining review states have no indicator of their own: `"draft"` only dims the cell and `"approved"` leaves the color unchanged.-Color precedence resolves the fold: changes-requested (magenta) outranks running checks — waiting can't clear it — while an outstanding required review (cyan) only recolors an otherwise green or quiet branch. Cool colors mean waiting, warm colors mean act. An approved PR, or one with no review signal at all (no required reviewers and no reviews), keeps its plain pipeline color — `pr.review` is then `"approved"` or absent, respectively. GitLab MR data carries only `"pending"` and `"draft"` — no approved or changes-requested signal.+Changes requested (magenta) outranks running checks, while a required review (cyan) only recolors an otherwise green or gray branch. GitLab reports only the `"pending"` and `"draft"` review states.-CI cells are clickable links to the PR or pipeline page, and appear dimmed for a draft PR/MR (`"draft"`) or when unpushed local changes make the status stale (`checks.stale`). PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches — visible with `--remotes` — get CI status detection. Results are cached for 30-60 seconds; use `wt config state cache` to view or clear.+CI cells are clickable links to the PR or pipeline page, and appear dimmed for a draft PR/MR (`"draft"`) or when unpushed local changes make the status stale (`checks.stale`). Results are cached for 30-60 seconds; use `wt config state cache` to view or clear.### LLM summaries@@ -131,7 +129,7 @@ Each `[list.custom-columns]` entry in user config adds a column: the key is thetemplate = "{{ vars.ticket }}"```-A custom column that renders empty for every row is dropped from the table outright, rather than merely ranked last as an empty built-in is. Templates, widths, and drop priority: [custom columns config](https://worktrunk.dev/config/#custom-columns).+The [custom columns config](https://worktrunk.dev/config/#custom-columns) covers templates, widths, and drop priority.## Status symbols@@ -157,10 +155,10 @@ An in-progress git operation, a worktree-location attribute, or a branch with no|--------|------|---------|| `✘` | `worktree.changes.conflicted` | Merge conflicts || `↻` | `worktree.operation` `"rebase"`, `"merge"`, `"cherry_pick"`, `"revert"`, `"bisect"` | A git operation is in progress; `git status` names it |-| `⊟` | `worktree.prunable` | Prunable (worktree directory missing); nothing can be read from a directory that isn't there, so the row's data cells stay blank |+| `⊟` | `worktree.prunable` | Prunable (worktree directory missing) || `⊞` | `worktree.locked` | Locked worktree |-| `⊘` | `worktree.detached` | Detached HEAD — the worktree is on a commit, not a branch, which is why its Branch cell holds a short hash |-| `⚑` | `worktree.duplicate_branch` | Branch checked out in more than one worktree, so `wt` resolves it to whichever git lists first; every worktree on the branch is flagged |+| `⊘` | `worktree.detached` | Detached HEAD |+| `⚑` | `worktree.duplicate_branch` | Branch checked out in more than one worktree || `⚑` | `worktree.branch_mismatch` | Worktree isn't at the path its branch implies || `/` | no `worktree` object | Branch without a worktree |@@ -195,13 +193,10 @@ Relation to the tracking branch, derived from the `upstream.ahead` / `upstream.b### Marker-The last subcolumn carries the branch's own marker — whatever-[`wt config state marker set`](https://worktrunk.dev/config/#wt-config-state-marker) stored, usually-an emoji, which is why the subcolumn is two cells wide. Nothing in `wt` writes-it; it is there for agents and scripts to say what a branch is for, and it-reads back as the item's `marker` field. `wt config state marker set 🤖` on a-branch whose default-branch state is `_` renders `_ 🤖` in the column and-`"_🤖"` in `display.symbols`.+The last subcolumn shows the branch's marker, set with+[`wt config state marker set`](https://worktrunk.dev/config/#wt-config-state-marker) — usually an+emoji saying what the branch is for. It reads back as the item's `marker`+field.### Placeholder symbols@@ -363,7 +358,7 @@ Independent facts; the table's priority-collapsed symbol is `display.state`.| `number` | integer/null | PR/MR number || `url` | string/null | URL to the PR/MR page || `review` | string | Review state (see [review states](#review-states)); absent when the forge reports no review signal |-| `mergeable` | boolean/null | False when the forge reports conflicts, null otherwise — the fetch records only the conflicted case |+| `mergeable` | boolean/null | False when the forge reports conflicts, null otherwise || `repo` | object | Structured metadata for the repository the PR/MR targets, the upstream for fork PRs (see [repo object](#repo-object)); absent when the URL doesn't parse |### checks object@@ -427,7 +422,7 @@ The single highest-priority state describing the branch's relation to the defaul### review states-`pr.review` is one of `"changes_requested"`, `"pending"`, `"draft"`, `"approved"`, absent when the forge reports no review signal. The [CI status](#ci-status) section is the single source: its table maps the colored values, and the notes below it cover `"draft"` and `"approved"`. The vocabulary matches Claude Code's statusline `pr.review_state` field.+`pr.review` is one of `"changes_requested"`, `"pending"`, `"draft"`, `"approved"`, absent when the forge reports no review signal. [CI status](#ci-status) shows how each renders. The vocabulary matches Claude Code's statusline `pr.review_state` field.```console# Current worktree path (for scripts)@@ -457,8 +452,6 @@ $ wt list --format=json --full | jq '.items[] | select(.checks.stale) | .branch'A JSON Schema for the envelope is published at[worktrunk.dev/schema/list-v2.json](https://worktrunk.dev/schema/list-v2.json).-It describes what `wt` writes, so a field the absence rule can omit is-optional there rather than required-and-null.### Schema 1@@ -566,9 +559,9 @@ The line carries the same cells as the worktree's row in `wt list`. A stale CI s- `json`: the current [`wt list --format=json`](https://worktrunk.dev/list/#json-output) schema — a one-item envelope by default, or a one-item array with `[list] json-schema = 1`- `claude-code`: the `table` cells, preceded by `dir` and followed by `model context pace`-A cell with nothing to show is left out rather than blanked, so most lines are shorter than that; `claude-code` also drops `branch` where `dir` already ends in `.<branch>`. A line that still overruns the terminal drops whole cells, least important first, starting with the dev server URL.+A cell with nothing to show is left out, so most lines are shorter than that. A line that overruns the terminal drops whole cells, least important first.-The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both are underlined, which is what marks them as clickable. They are OSC 8 links, and a terminal that doesn't support those discards the escape, leaving the underlined text unclickable.+The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both are underlined terminal links.### Claude Code mode@@ -580,7 +573,7 @@ The CI reference links to its PR/MR, and a dev server URL carrying a port shows- `.rate_limits.{five_hour,seven_day}.used_percentage` — rate-limit window usage (0–100)- `.rate_limits.{five_hour,seven_day}.resets_at` — window reset time (Unix epoch seconds)-The pace segment appears only when usage is likely to hit a rate limit before its window resets, and shows the higher-risk window: `2.9×(Tue–Tue 5pm)` reads as 2.9× the pace that would exactly fill that window. Above 90% used it shows usage instead of pace — `93%(Tue–Tue 5pm)` — near the cap, how much is left matters more than how fast it's going. "Likely" is a Bayesian forecast; early-window bursts don't trigger it. Its colour deepens with severity — dim, then dim-yellow, then yellow — as the forecast lockout (how much of the window would be spent capped) grows, so a fast pace that would only tip over near the reset stays dim rather than alarming. With `-vv`, each window's inputs and projection are logged to `.git/wt/logs/trace.log`.+The pace segment appears only when usage is likely to hit a rate limit before its window resets, and shows the higher-risk window: `2.9×(Tue–Tue 5pm)` reads as 2.9× the pace that would exactly fill that window. Above 90% used it shows usage instead of pace — `93%(Tue–Tue 5pm)`. Its color deepens from dim to yellow as more of the window would be spent capped.[Claude Code statusline setup](https://worktrunk.dev/claude-code/#statusline-claude-code-only) has the `~/.claude/settings.json` entry that feeds this mode.diff --git a/skills/worktrunk/reference/merge.md b/skills/worktrunk/reference/merge.mdindex 37d505f0d..fb456e829 100644--- a/skills/worktrunk/reference/merge.md+++ b/skills/worktrunk/reference/merge.md@@ -63,7 +63,7 @@ $ wt merge --no-commit --no-rebase`wt merge` runs these steps:-1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background; when step 7 removes the worktree they are anchored on, the merge reports them rather than running them. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.+1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.3. **Rebase** — Rebases onto target, skipping when nothing needs replaying ([`wt step rebase`](https://worktrunk.dev/step/#wt-step-rebase) gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](https://worktrunk.dev/hook/).@@ -74,7 +74,7 @@ $ wt merge --no-commit --no-rebaseUse `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Combining both flags preserves the exact source graph and requires the target to be its ancestor. Useful after preparing commits manually with `wt step commit`. Requires a clean working tree.-`wt merge` targets the *local* default-branch ref and never fetches. When that ref lags its upstream — e.g. a primary checkout's `main` left behind `origin/main` — a branch based on the newer upstream tip is measured, squashed, and rebased against the upstream (so already-upstream commits are never folded into the squash), and the final fast-forward carries the local ref through the already-fetched upstream commits by their real SHAs. `wt step squash` and `wt step rebase` measure the same way. A local target that has *diverged* from its upstream — its own commits and behind — cannot fast-forward, so the merge is refused until the target is reconciled.+`wt merge` merges into the *local* target branch and never fetches.## Local CIdiff --git a/skills/worktrunk/reference/remove.md b/skills/worktrunk/reference/remove.mdindex f7f81360e..4980b21c1 100644--- a/skills/worktrunk/reference/remove.md+++ b/skills/worktrunk/reference/remove.md@@ -38,7 +38,7 @@ $ wt remove -D experimentalBy default, branches are deleted when they would add no changes to the default branch if merged. This works with both unchanged git histories, and squash-merge or rebase workflows where commit history differs but file changes match.-Worktrunk checks six conditions (in order of cost):+Worktrunk checks six conditions:1. **Same commit** — Branch HEAD equals the default branch. Shows `_` in `wt list`.2. **Ancestor** — Branch is in target's history (fast-forward or rebase case). Shows `⊂`.@@ -53,8 +53,6 @@ The 'same commit' check uses the local default branch; for other checks, 'targetBranches matching these conditions and with empty working trees are dimmed in `wt list` as safe to delete.-Those six ask whether deleting loses work. A branch checked out in a second worktree (only reachable via `git worktree add --force`) fails a different test: deleting the ref would leave that worktree unable to resolve `HEAD`, which is why `git branch -d` refuses the same delete. Such a branch is retained whatever `-D` asks, and the surviving checkout is named.-## Force flagsWorktrunk has two force flags for different situations:@@ -74,9 +72,7 @@ Use `--no-delete-branch` to keep the branch regardless of merge status.## Background removal-Removal runs in the background by default — the command returns immediately. The worktree is renamed into `.git/wt/trash/` (instant same-filesystem rename), git metadata is pruned, the branch is deleted, and a detached `rm -rf` finishes cleanup. Cross-filesystem worktrees fall back to `git worktree remove`. Logs: `.git/wt/logs/{branch}/internal/remove.log`. Use `--foreground` to run in the foreground.--After each `wt remove`, entries in `.git/wt/trash/` older than 24 hours are swept by a detached `rm -rf` — eventual cleanup for directories orphaned when a previous background removal was interrupted (SIGKILL, reboot, disk full).+Removal runs in the background by default — the command returns immediately, and output goes to `.git/wt/logs/{branch}/internal/remove.log`. Use `--foreground` to wait for it.## Reaping processes [experimental]@@ -96,7 +92,7 @@ To avoid killing work the user did not mean to kill, two guards keep `--reap` co- **Interactive processes are spared.** A process holding a controlling terminal — an interactive shell, or a terminal editor such as `vim` with unsaved buffers — is never reaped. Only detached processes remain candidates.- **Discovery is by working directory only.** A process that started in the worktree and later changed directory, or a daemon that reparented to `init`, no longer reports a directory under the worktree and is not found. To reliably reap those, launch them with [`wt step tether`](https://worktrunk.dev/step/#wt-step-tether), which kills the whole process group when the worktree is removed.-Reaping runs before the worktree directory is touched, so it is independent of foreground/background removal and the `--force` flag. Unix only; on Windows `--reap` is rejected.+Unix only; on Windows `--reap` is rejected.## JSON output@@ -107,11 +103,11 @@ Reaping runs before the worktree directory is touched, so it is independent of f| Value | Meaning ||-------|---------|| `deleted` | The branch is gone |-| `deferred` | Handed to the detached background process, whose result this run never sees. `--foreground` never reports it |+| `deferred` | Left to the background removal, whose result this run doesn't see. `--foreground` never reports it || `not_attempted` | No deletion was tried: a detached worktree, a sibling checkout, or `--no-delete-branch` || `retained_unmerged` | Declined: the branch was not integrated into the target |-| `retained_checked_out` | Declined: the final topology read found a live worktree with it checked out |-| `retained_raced` | Refused by the compare-and-swap — the branch moved between the integration check and the delete. Re-read the ref and retry |+| `retained_checked_out` | Declined: another worktree has the branch checked out |+| `retained_raced` | Declined: the branch moved during the removal. Retry || `retained_failed` | The delete command itself failed |## Hooksdiff --git a/skills/worktrunk/reference/shell-integration.md b/skills/worktrunk/reference/shell-integration.mdindex 2d41a6022..b4680475d 100644--- a/skills/worktrunk/reference/shell-integration.md+++ b/skills/worktrunk/reference/shell-integration.md@@ -64,7 +64,7 @@ When shell integration isn't working, `wt switch` shows a warning explaining why### "shell wrapper is out of date"-**Meaning**: The active shell still has a retired wrapper loaded. Current versions no longer write to that wrapper's single directive file, so the parent shell cannot follow a directory change.+**Meaning**: The active shell has a wrapper from an older Worktrunk version loaded, which can't follow a directory change.**Fix**: Run `wt config shell install`, then restart the shell (or reload its config) to activate the current wrapper.@@ -239,8 +239,6 @@ eval "$(wt config shell init zsh)"### Windows Git Bash issues-Git Bash uses MSYS2, which automatically converts POSIX paths in environment variables. The directive file path is handled correctly without manual conversion.-If you see path issues, make sure you're on a recent Git for Windows version.## Environment variablesdiff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.mdindex f9e82024e..b8770dabb 100644--- a/skills/worktrunk/reference/step.md+++ b/skills/worktrunk/reference/step.md@@ -101,7 +101,7 @@ See [LLM-generated commit messages](https://worktrunk.dev/llm-commits/) for conf$ wt step commit --branch feature```-The branch must have a checked-out worktree. `--branch` re-roots the whole command: staging, hooks, and the commit all happen there. It selects the previewed worktree the same way, so `--dry-run` describes the commit the same flags would make.+The branch must have a checked-out worktree; staging, hooks, and the commit all happen there.### Hooks@@ -290,13 +290,9 @@ The first matching row wins:| The branch is an ancestor of the target, so it has no commits of its own | `Fast-forwarded to <target>` || Otherwise | The branch's commits replay onto the target's tip — refused outright if the two share no history |-A branch that merged the target into itself still rebases: the target is its ancestor, but the merge commit in between keeps the first row from applying.--When the target's local ref lags its upstream, the rows are measured against that upstream, which the result then names in place of the argument. [`wt merge`](https://worktrunk.dev/merge/) covers why.-### Conflicts-A conflicting commit leaves the rebase open rather than undoing it. The worktree keeps git's conflict markers, and the ways out are `git rebase --continue` once the conflict is resolved, `git rebase --skip`, or `git rebase --abort`. Until the rebase is settled, `wt step rebase`, `wt step squash`, `wt step push`, and `wt merge` refuse to run — as they do while any other git operation is open, a conflicted `git merge` included.+A conflicting commit leaves the rebase open rather than undoing it. The worktree keeps git's conflict markers, and the ways out are `git rebase --continue` once the conflict is resolved, `git rebase --skip`, or `git rebase --abort`. Until the rebase is settled, `wt step rebase`, `wt step squash`, `wt step push`, and `wt merge` refuse to run.### Command reference@@ -343,9 +339,7 @@ $ wt step push --no-ff # Merge commit instead of a fast-forward### Target worktree-When the target branch has a worktree of its own, that worktree's files move to the new commits too. Uncommitted changes there never move: the update carries any file the push doesn't touch — staged or not — exactly where it is, and a change touching a file the push does change is refused upfront, naming the file. If the sync can't be applied for any reason — a conflicting file appearing in the race window after the check, or a busy index — the update is rolled back whole, leaving branch and worktree as they were.--A worktree that is still registered but whose directory is gone is refused as well, since nothing can be synced into it — `git worktree prune` clears the registration.+When the target branch has a worktree of its own, that worktree's files move to the new commits too. Uncommitted changes there never move: the update carries any file the push doesn't touch — staged or not — exactly where it is, and a change touching a file the push does change is refused upfront, naming the file. If the update can't be applied, it is rolled back, leaving branch and worktree as they were.### Command reference@@ -409,18 +403,6 @@ The diff is pipeable to tools like `delta`:$ wt step diff | delta```-### How it works--Equivalent to:--```bash-cp "$(git rev-parse --git-dir)/index" /tmp/idx-GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .-GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))-```--`git diff` ignores untracked files. `git add --intent-to-add .` registers them in the index without staging their content, making them visible to `git diff`. This runs against a copy of the real index so the original is never modified.-### Command reference```@@ -518,18 +500,12 @@ Files are reflinked where the filesystem supports it: APFS (macOS), btrfs and XF| `cp -R` (full copy) | 2m | 14GB || `cp -Rc` / `wt step copy-ignored` | 20s | ~0 |-On ext4 and NTFS, which have no reflink, every file is copied in full. The same byte count therefore costs nothing on one filesystem and 14GB on the other, so the summary says which happened: `Copied 4,812 files · 14.0 GB (reflinked, no extra disk)`, against `(full copy)` where those bytes were written out.+On ext4 and NTFS, which have no reflink, every file is copied in full; the summary says `(reflinked, no extra disk)` or `(full copy)`.Reflinks are per file (like `cp -Rc`), so copy time scales with file count.Use the `post-start` hook so the copy runs in the background. Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.-### Background-hook priority (experimental)--When invoked from a background hook pipeline (`post-*` hooks), `wt step copy-ignored` self-lowers its CPU and I/O priority — `taskpolicy -b` on macOS, `nice -n 19` plus `ionice -c 3` on Linux — so it yields to interactive work. Foreground callers (`pre-*` hooks, direct interactive use) run at normal priority so the user isn't waiting on a throttled copy.--wt signals background-hook context by exporting `WORKTRUNK_FOREGROUND=-1` into every detached hook pipeline; `copy-ignored` inspects that variable on entry. The variable name is experimental and may change.-### Language-specific notes#### Rust@@ -681,7 +657,7 @@ Automation:Run command in each worktree. Executes sequentially with real-time output; continues past command failures.-A summary of successes and failures is shown at the end. A template-expansion error (a malformed `{{ … }}` argument) aborts the whole run; only command failures are tolerated and reported. Context JSON — a flat object of every template variable — is piped to stdin for scripts that need structured data.+A summary of successes and failures is shown at the end. Context JSON — a flat object of every template variable — is piped to stdin for scripts that need structured data.### Arguments@@ -785,8 +761,6 @@ Without an argument, promotes the current branch — or restores the default braGitignored files (build artifacts, `node_modules/`, `.env`) are swapped along with the branches so each worktree keeps the artifacts that belong to its branch. Files are discovered using the same mechanism as [`copy-ignored`](#wt-step-copy-ignored) and can be filtered with `.worktreeinclude`.-The swap uses `rename()` for each entry — fast regardless of entry size, since only filesystem metadata changes. If the worktree is on a different filesystem from `.git/`, it falls back to reflink copy.-### Command reference```@@ -838,7 +812,7 @@ $ wt step prune --min-age=2d # skip candidates younger than 2 days### JSON output-`--format=json` prints one object per candidate to stdout. The two modes report different things, and name their fields accordingly: a live run reports `branch_outcome`, the executed outcome, using the vocabulary [`wt remove`](https://worktrunk.dev/remove/#json-output) documents; `--dry-run` reports `branch_deleted`, its prediction of whether the removal would take the branch, since it runs nothing to have an outcome. A dry run also carries `reason` and `target` (why the candidate qualifies, and what it was measured against).+`--format=json` prints one object per candidate to stdout. A live run reports `branch_outcome`, as [`wt remove`](https://worktrunk.dev/remove/#json-output) does. `--dry-run` reports `branch_deleted` (whether the removal would delete the branch), `reason` (why the candidate qualifies), and `target` (what it was measured against).### Examples@@ -924,9 +898,8 @@ this by using a temporary location.### ClobberingWith `--clobber`, non-worktree paths at target locations are moved to-`<path>.bak.<timestamp>` before relocating. If that name is already taken,-the move counts up (`…-2`, `…-3`, …) until it finds a free name, so an-existing backup is never overwritten.+`<path>.bak.<timestamp>` before relocating, never overwriting an existing+backup.### Main worktree behavior@@ -970,8 +943,7 @@ Options:--clobberBackup non-worktree paths at target locations- Moves blocking paths to <path>.bak.<timestamp>. If that name is taken, counts up (…-2, …-3- , …) to a free name.+ Moves blocking paths to <path>.bak.<timestamp>.-h, --helpPrint help (see a summary with '-h')@@ -1017,9 +989,7 @@ For pipes, redirects, variables, or globs, wrap in `sh -c`:$ wt step tether -- sh -c 'PORT=$P npm run dev | tee dev.log'```-To run the command from a subdirectory, pass the global `-C` flag (teardown-still watches the worktree root, so a server launched with a relative `-C` is-torn down with the worktree):+To run the command from a subdirectory, pass the global `-C` flag:```console$ wt step tether -C frontend -- npm run devdiff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.mdindex 94d2090e1..eac1f9273 100644--- a/skills/worktrunk/reference/switch.md+++ b/skills/worktrunk/reference/switch.md@@ -19,7 +19,7 @@ $ wt switch https://github.com/owner/repo/pull/123 # ...or paste the PR's URLThe `--create` flag creates a new branch from `--base` — the default branch unless specified. Without `--create`, the branch must already exist. Switching to a remote branch (e.g., `wt switch feature` when only `origin/feature` exists) creates a local tracking branch.-One rule decides the upstream, whatever `branch.autoSetupMerge` is set to: a new branch tracks the remote branch it starts from only when the two share a name. Switching to `origin/feature` shares it, so that branch tracks. `--create` need not: `--create release --base origin/release` tracks `origin/release`, while `--create feature --base origin/release` — and the bare `--base release` that resolves to it — gets no upstream. Git's default would have `feature` track `origin/release`, so under `push.default = upstream` a bare `git push` would push the new work to `release`. Publishing such a branch takes `git push --set-upstream origin <branch>`, or git's `push.autoSetupRemote = true` set once, after which a bare `git push` from the new worktree publishes it and configures its tracking.+A new branch tracks the remote branch it starts from only when the two share a name: `--create release --base origin/release` tracks `origin/release`, while `--create feature --base origin/release` gets no upstream. Publish such a branch with `git push --set-upstream origin <branch>`, or set git's `push.autoSetupRemote = true` once.## Creating worktrees@@ -61,7 +61,7 @@ $ wt switch pr:123 # PR #123's branch$ wt switch mr:101 # MR !101's branch```-Shortcuts also apply to `--base`. For a fork PR/MR, the head commit is fetched and used as the base SHA without creating a tracking branch.+Shortcuts also apply to `--base`.## Interactive picker@@ -77,7 +77,7 @@ The CI column shows each row's PR/MR CI and review status, the same as [`wt list| (type) | Filter worktrees || `Enter` | Switch to selected worktree || `Alt-c` | Create new worktree named as entered text |-| `Alt-x` | Remove selected worktree/branch (never forces) |+| `Alt-x` | Remove selected worktree/branch (never forces; not the current worktree) || `Alt-y` | Copy selected branch name to the clipboard || `Alt-o` | Open the selected row's PR/MR URL in the browser || `Alt-r` | Refresh the list (pick up worktrees created elsewhere) |@@ -87,13 +87,7 @@ The CI column shows each row's PR/MR CI and review status, the same as [`wt list| `Alt-p` | Toggle preview panel || `Ctrl-u`/`Ctrl-d` | Scroll preview up/down |-`Alt-o` is a no-op on a row with no PR/MR (or whose status hasn't loaded yet).--`Alt-x` is a no-op on the current worktree (the `@` row) — removing the worktree in use would have to switch elsewhere first, so switch away and remove it from there.--Each row filters by its branch, path, and — when it has a PR/MR — the PR/MR's number, title, and author, the same fields whether the PR is checked out (a worktree row) or listed via `--prs`. Plain digits go to the filter, so a number can be typed directly and the preview tabs move to `Alt`.--Typing a gutter sigil filters by row kind: `+` narrows to linked worktrees and `@` to the current worktree. The other sigils don't filter cleanly — `^` and `|` are skim's prefix-anchor and OR query operators (so `^` matches every row and `|` none), and `/` matches most rows because every worktree path contains it.+The filter matches each row's branch, path, and — when it has a PR/MR — the PR/MR's number, title, and author. Typing `+` narrows to linked worktrees, and `@` to the current worktree.**Preview tabs:**@@ -108,8 +102,6 @@ Typing a gutter sigil filters by row kind: `+` narrows to linked worktrees and `The comparison base is the merge-base with the default branch, or with its upstream when the local default branch lags. The picker opens on **diff** for local rows and **pr** for a PR/MR listed by `--prs` but not available locally. `Tab` and `Shift-Tab` skip tabs without content; `Alt-1` through `Alt-8` open any tab directly. After you choose a tab, that choice stays active while you navigate.-On narrow previews the tab bar compacts to digits — only the active tab keeps its label — so every `Alt-N` accelerator stays visible.-**Pager configuration:** The preview panel pipes diff output through git's pager. Override in user config:```toml@@ -133,7 +125,7 @@ Both work anywhere a branch is accepted, including `--base`. The `--create` flagIf the PR or MR is on a fork, the local branch uses its branch name directly, so `git push` works normally. A pre-existing local branch with that name tracking something else requires renaming first.-The `--prs` flag adds the repository's open PRs (GitHub) or MRs (GitLab) to the interactive picker — only the ones not already there: a PR whose branch is already shown (as a worktree, or a local or remote branch) isn't listed twice, so `--prs` only adds the rest and the two pickers differ solely by those extra rows. Each added row resolves to the same `pr:`/`mr:` shortcut, so selecting one fetches the ref and switches to its branch. A `--prs` row has no local worktree, so its `pr` and `comments` preview tabs load the PR/MR's metadata and comments from the forge in the background. The `log` tab uses a local `git log` — graph and merge-base dimming included — whenever the head commit is already in the object store (a same-repo PR off a fetched remote), falling back to a flat forge-fetched commit list otherwise.+The `--prs` flag adds the repository's open PRs (GitHub) or MRs (GitLab) that aren't already in the interactive picker. Selecting one switches to it as `pr:<number>` / `mr:<number>` would.Requires `gh` (GitHub), `glab` (GitLab), or an equivalent CLI installed and authenticated; see [forge platform](https://worktrunk.dev/config/#forge-platform) for Gitea, Azure DevOps, and other supported platforms.diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.mdindex 67b11c953..4a6a4cdeb 100644--- a/skills/worktrunk/reference/tips-patterns.md+++ b/skills/worktrunk/reference/tips-patterns.md@@ -276,7 +276,7 @@ MY_PACKAGES_PATH = "{{ config_root }}/.packages"`{{ config_root }}` is the project root mise resolves relative paths against ([env directives](https://mise.jdx.dev/environments/)) — the worktree root, not the primary worktree. mise also covers Windows / PowerShell, which direnv doesn't natively.-Both set real environment variables in the shell session, so every child process inherits them — hooks, build tools, subshells — without the `--execute` workaround. Each new worktree is a new path, so it needs its own one-time trust step (`direnv allow` / `mise trust`); worktrunk deliberately doesn't bypass that prompt, the same safety reasoning behind [disabling `--execute` in project alias and hook bodies](https://github.com/max-sixty/worktrunk/issues/2101).+Both set real environment variables in the shell session, so every child process inherits them — hooks, build tools, subshells. Each new worktree is a new path, so it needs its own one-time trust step (`direnv allow` / `mise trust`).### Eliminate cold startsdiff --git a/src/cli/config.rs b/src/cli/config.rsindex 8607c5388..0e2290df2 100644--- a/src/cli/config.rs+++ b/src/cli/config.rs@@ -769,7 +769,7 @@ Approved commands are saved to `~/.config/worktrunk/approvals.toml`. Re-approval`state` is `no_commands` (the project declares none), `approval_required` (at least one is unapproved), or `approved`. `name` is absent for an unnamed command and for the commit-template fragment.-`stale` is separate rather than a fourth `state`, because it co-occurs with all three: these are approvals recorded earlier whose command has since been edited or removed from the project config. They are what `--yes` would silently re-approve, so an orchestrator preserving the approval model reads them before choosing that flag."#+`stale`, which can accompany any `state`, lists approvals whose command has since been edited or removed from the project config."#)]Approvals {#[command(subcommand)]@@ -881,7 +881,6 @@ $ wt config state clear<!-- subdoc: cache --><!-- subdoc: default-branch --><!-- subdoc: logs -->-<!-- subdoc: ci-status --><!-- subdoc: marker --><!-- subdoc: vars -->"#)]@@ -909,7 +908,7 @@ pub enum StateCommand {- **Previous branch**: Previous branch for `wt switch -`- **Branch markers**: User-defined branch notes- **Vars**: Custom variables per branch-- **CI status**: Cached GitHub/GitLab CI status per branch (30-60s TTL), plus the largest PR/MR number seen (sizes the `wt list` CI column)+- **CI status**: Cached GitHub/GitLab CI status per branch (30-60s TTL)- **Summaries**: Cached LLM-generated branch summaries (shown in `wt list --full` and `wt switch` preview)- **Git commands cache**: Cached merge-tree, ancestry, diff-stat, and `wt switch` preview results- **Hints**: One-time hints that have been shown@@ -952,7 +951,7 @@ untouched."#)]## What's cached-- **CI status** — GitHub/GitLab CI per branch (30–60s TTL), shown in [`wt list`](/list/#ci-status), plus the largest PR/MR number seen (sizes the CI column)+- **CI status** — GitHub/GitLab CI per branch (30–60s TTL), shown in [`wt list`](/list/#ci-status)- **Summaries** — LLM-generated branch summaries (`wt list --full`, `wt switch` preview)- **Git commands** — cached merge-tree, ancestry, diff-stat, and `wt switch` preview results- **Hints** — one-time hints already shown in this repo@@ -995,20 +994,16 @@ In a hook or alias template, prefer the `{{ default_branch }}` [template variablWithout a subcommand, runs `get`. `set` stores the override in the repository's local git config. The override adds no project file and applies to every linked worktree in the clone. `clear` then `get` re-detects. The branch must exist locally for `wt list` comparisons.-`default-branch get` resolves the value and caches it on a miss; the aggregate `wt config state get` only reports the cache (read-only), so it can show `(none)` until something populates it.-## DetectionWorktrunk detects the default branch automatically:1. **Worktrunk cache** — Checks `git config worktrunk.default-branch`2. **Git cache** — Detects primary remote and checks its HEAD (e.g., `origin/HEAD`)-3. **Remote query** — If not cached, queries `git ls-remote` — typically 100ms–2s, abandoned after 10s+3. **Remote query** — If not cached, queries `git ls-remote`, giving up after 10s4. **Local inference** — If no remote, or the query was abandoned, infers from local branches-Once detected, the result is cached in `worktrunk.default-branch` for fast access. The cache isn't re-validated on every command, so a later change to `origin/HEAD` — a renamed default branch followed by `git remote set-head origin -a` — isn't picked up automatically. `wt config state` flags the drift when the cached value differs from the remote's local HEAD — expected for a deliberate override; `set` adopts the new branch and `clear` re-detects.--An abandoned remote query is the one case that isn't cached: the branch it inferred locally answers that command, but a value guessed while the remote was unreachable would otherwise become permanent, so the next command queries again.+Once detected, the result is cached in `worktrunk.default-branch` — except a value inferred after the remote query was abandoned, so an outage can't make a guess permanent. A later change to `origin/HEAD` isn't picked up automatically: `wt config state` flags the mismatch, `set` adopts the new branch, and `clear` re-detects.The local inference fallback uses these heuristics in order:- If only one local branch exists, uses it@@ -1074,7 +1069,7 @@ Hook output lives in per-branch subtrees under `.git/wt/logs/{branch}/`:| Background hooks | `{branch}/{source}/{hook-type}/{name}.log` || Background removal | `{branch}/internal/remove.log` |-All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is `user` or `project`. Branch and hook names are sanitized for filesystem safety (invalid characters → `-`; short collision-avoidance hash appended). Same operation on same branch overwrites the previous log. Removing a branch clears its subtree; orphans from deleted branches can be swept with `wt config state logs clear`.+All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is `user` or `project`. Branch and hook names are sanitized for filesystem safety. Same operation on same branch overwrites the previous log. Removing a branch clears its subtree; orphans from deleted branches can be swept with `wt config state logs clear`.### Diagnostic files@@ -1085,11 +1080,11 @@ All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the| `subprocess.log` | Running with `-vv` || `diagnostic.md` | Running with `-vv` |-`trace.log` is the human-readable trace at `-vv` — each command's start (`$ …`) and completion (`✓`/`✗ … 12.3ms`), in-process spans, milestones, and bounded subprocess previews. `trace.jsonl` is the same event stream as one JSON object per line, for machines (`jq`, chrome://tracing); `wt config state logs profile` reads it to summarize a performance report (where time went, parallelism, redundant commands). `subprocess.log` holds the raw uncapped subprocess stdout/stderr bodies. `diagnostic.md` is a markdown bug-report bundle that leads with that same performance profile and inlines `trace.log`; `wt` prints a `gh gist create` command pointing at it. All four are overwritten on each `-vv` run.+`trace.log` is the human-readable trace of commands and their timings. `trace.jsonl` holds the same events as JSON lines, which `wt config state logs profile` summarizes into a performance report. `subprocess.log` holds full subprocess output. `diagnostic.md` is a bug-report bundle; `wt` prints a `gh gist create` command for it. All four are overwritten on each `-vv` run.## Location-All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory. Top-level files are shared logs (command audit + diagnostics); top-level directories are per-branch log trees.+All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory.## Structured output@@ -1265,7 +1260,7 @@ dev = "npm start -- --port {{ vars.config.port }}"## Storage format-Stored in git config as `worktrunk.state.<branch>.vars.<key>`. Keys must contain only letters, digits and hyphens — dots conflict with git config's section separator, underscores with its variable name format."#+Stored in git config as `worktrunk.state.<branch>.vars.<key>`. Keys may contain only letters, digits, and hyphens."#)]Vars {#[command(subcommand)]diff --git a/src/cli/list.rs b/src/cli/list.rsindex cd21d0791..8bb6b20a9 100644--- a/src/cli/list.rs+++ b/src/cli/list.rs@@ -15,9 +15,9 @@ pub enum ListSubcommand {- `json`: the current [`wt list --format=json`](/list/#json-output) schema — a one-item envelope by default, or a one-item array with `[list] json-schema = 1`- `claude-code`: the `table` cells, preceded by `dir` and followed by `model context pace`-A cell with nothing to show is left out rather than blanked, so most lines are shorter than that; `claude-code` also drops `branch` where `dir` already ends in `.<branch>`. A line that still overruns the terminal drops whole cells, least important first, starting with the dev server URL.+A cell with nothing to show is left out, so most lines are shorter than that. A line that overruns the terminal drops whole cells, least important first.-The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both are underlined, which is what marks them as clickable. They are OSC 8 links, and a terminal that doesn't support those discards the escape, leaving the underlined text unclickable.+The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both are underlined terminal links.## Claude Code mode@@ -29,7 +29,7 @@ The CI reference links to its PR/MR, and a dev server URL carrying a port shows- `.rate_limits.{five_hour,seven_day}.used_percentage` — rate-limit window usage (0–100)- `.rate_limits.{five_hour,seven_day}.resets_at` — window reset time (Unix epoch seconds)-The pace segment appears only when usage is likely to hit a rate limit before its window resets, and shows the higher-risk window: `2.9×(Tue–Tue 5pm)` reads as 2.9× the pace that would exactly fill that window. Above 90% used it shows usage instead of pace — `93%(Tue–Tue 5pm)` — near the cap, how much is left matters more than how fast it's going. "Likely" is a Bayesian forecast; early-window bursts don't trigger it. Its colour deepens with severity — dim, then dim-yellow, then yellow — as the forecast lockout (how much of the window would be spent capped) grows, so a fast pace that would only tip over near the reset stays dim rather than alarming. With `-vv`, each window's inputs and projection are logged to `.git/wt/logs/trace.log`.+The pace segment appears only when usage is likely to hit a rate limit before its window resets, and shows the higher-risk window: `2.9×(Tue–Tue 5pm)` reads as 2.9× the pace that would exactly fill that window. Above 90% used it shows usage instead of pace — `93%(Tue–Tue 5pm)`. Its color deepens from dim to yellow as more of the window would be spent capped.[Claude Code statusline setup](/claude-code/#statusline-claude-code-only) has the `~/.claude/settings.json` entry that feeds this mode."#diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex da6cb9025..94984f03c 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -641,7 +641,7 @@ $ wt switch https://github.com/owner/repo/pull/123 # ...or paste the PR's URLThe `--create` flag creates a new branch from `--base` — the default branch unless specified. Without `--create`, the branch must already exist. Switching to a remote branch (e.g., `wt switch feature` when only `origin/feature` exists) creates a local tracking branch.-One rule decides the upstream, whatever `branch.autoSetupMerge` is set to: a new branch tracks the remote branch it starts from only when the two share a name. Switching to `origin/feature` shares it, so that branch tracks. `--create` need not: `--create release --base origin/release` tracks `origin/release`, while `--create feature --base origin/release` — and the bare `--base release` that resolves to it — gets no upstream. Git's default would have `feature` track `origin/release`, so under `push.default = upstream` a bare `git push` would push the new work to `release`. Publishing such a branch takes `git push --set-upstream origin <branch>`, or git's `push.autoSetupRemote = true` set once, after which a bare `git push` from the new worktree publishes it and configures its tracking.+A new branch tracks the remote branch it starts from only when the two share a name: `--create release --base origin/release` tracks `origin/release`, while `--create feature --base origin/release` gets no upstream. Publish such a branch with `git push --set-upstream origin <branch>`, or set git's `push.autoSetupRemote = true` once.## Creating worktrees@@ -683,7 +683,7 @@ $ wt switch pr:123 # PR #123's branch$ wt switch mr:101 # MR !101's branch```-Shortcuts also apply to `--base`. For a fork PR/MR, the head commit is fetched and used as the base SHA without creating a tracking branch.+Shortcuts also apply to `--base`.## Interactive picker@@ -700,7 +700,7 @@ The CI column shows each row's PR/MR CI and review status, the same as [`wt list| (type) | Filter worktrees || `Enter` | Switch to selected worktree || `Alt-c` | Create new worktree named as entered text |-| `Alt-x` | Remove selected worktree/branch (never forces) |+| `Alt-x` | Remove selected worktree/branch (never forces; not the current worktree) || `Alt-y` | Copy selected branch name to the clipboard || `Alt-o` | Open the selected row's PR/MR URL in the browser || `Alt-r` | Refresh the list (pick up worktrees created elsewhere) |@@ -710,13 +710,7 @@ The CI column shows each row's PR/MR CI and review status, the same as [`wt list| `Alt-p` | Toggle preview panel || `Ctrl-u`/`Ctrl-d` | Scroll preview up/down |-`Alt-o` is a no-op on a row with no PR/MR (or whose status hasn't loaded yet).--`Alt-x` is a no-op on the current worktree (the `@` row) — removing the worktree in use would have to switch elsewhere first, so switch away and remove it from there.--Each row filters by its branch, path, and — when it has a PR/MR — the PR/MR's number, title, and author, the same fields whether the PR is checked out (a worktree row) or listed via `--prs`. Plain digits go to the filter, so a number can be typed directly and the preview tabs move to `Alt`.--Typing a gutter sigil filters by row kind: `+` narrows to linked worktrees and `@` to the current worktree. The other sigils don't filter cleanly — `^` and `|` are skim's prefix-anchor and OR query operators (so `^` matches every row and `|` none), and `/` matches most rows because every worktree path contains it.+The filter matches each row's branch, path, and — when it has a PR/MR — the PR/MR's number, title, and author. Typing `+` narrows to linked worktrees, and `@` to the current worktree.**Preview tabs:**@@ -731,8 +725,6 @@ Typing a gutter sigil filters by row kind: `+` narrows to linked worktrees and `The comparison base is the merge-base with the default branch, or with its upstream when the local default branch lags. The picker opens on **diff** for local rows and **pr** for a PR/MR listed by `--prs` but not available locally. `Tab` and `Shift-Tab` skip tabs without content; `Alt-1` through `Alt-8` open any tab directly. After you choose a tab, that choice stays active while you navigate.-On narrow previews the tab bar compacts to digits — only the active tab keeps its label — so every `Alt-N` accelerator stays visible.-**Pager configuration:** The preview panel pipes diff output through git's pager. Override in user config:```toml@@ -756,7 +748,7 @@ Both work anywhere a branch is accepted, including `--base`. The `--create` flagIf the PR or MR is on a fork, the local branch uses its branch name directly, so `git push` works normally. A pre-existing local branch with that name tracking something else requires renaming first.-The `--prs` flag adds the repository's open PRs (GitHub) or MRs (GitLab) to the interactive picker — only the ones not already there: a PR whose branch is already shown (as a worktree, or a local or remote branch) isn't listed twice, so `--prs` only adds the rest and the two pickers differ solely by those extra rows. Each added row resolves to the same `pr:`/`mr:` shortcut, so selecting one fetches the ref and switches to its branch. A `--prs` row has no local worktree, so its `pr` and `comments` preview tabs load the PR/MR's metadata and comments from the forge in the background. The `log` tab uses a local `git log` — graph and merge-base dimming included — whenever the head commit is already in the object store (a same-repo PR off a fetched remote), falling back to a flat forge-fetched commit list otherwise.+The `--prs` flag adds the repository's open PRs (GitHub) or MRs (GitLab) that aren't already in the interactive picker. Selecting one switches to it as `pr:<number>` / `mr:<number>` would.Requires `gh` (GitHub), `glab` (GitLab), or an equivalent CLI installed and authenticated; see [forge platform](/config/#forge-platform) for Gitea, Azure DevOps, and other supported platforms.@@ -786,7 +778,7 @@ The table renders progressively: branch names, paths, and commit hashes appear i## Full mode-`--full` adds the two columns that reach off-machine: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail, over the network) and [LLM-generated summaries](#llm-summaries) of each branch's changes. The `main…±` line diffs are local git, so they show by default.+`--full` adds the two columns that reach off-machine: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail, over the network) and [LLM-generated summaries](#llm-summaries) of each branch's changes.## Examples@@ -844,7 +836,7 @@ $ wt list --format=json| Column | Shows ||--------|-------|-| Branch | Branch name, elided with `…` past 32 characters so one long name can't size the column for every row (`--format=json` keeps it whole); a detached worktree has none, so it shows its short hash in dim yellow |+| Branch | Branch name, elided with `…` past 32 characters; a detached worktree shows its short hash || Status | Compact symbols (see below) || HEAD± | Uncommitted changes, including untracked files: +added -deleted lines || main↕ | Commits ahead/behind default branch |@@ -861,9 +853,7 @@ $ wt list --format=jsonThe `main↕` and `main…±` headers keep the familiar `main` label in every repository.-The table sizes itself to the terminal. When the columns don't all fit, the least important go first — roughly right to left, since the order above runs from identity to nice-to-have — and the summary footer names them (`hidden: Commit, Age, Message`). A column with nothing to show on any row — `Remote⇅` in a repo with no remote — ranks below every populated column, so it goes first. A wider terminal brings them back. To pin a set rather than leave it to the width, name the columns in [`[list] columns`](/config/#list); `--format=json` carries every field at any width.--`main↕` and `main…±` measure against the default branch's upstream tip when the local copy lags it — so in a fork whose local `main` trails `origin/main`, a branch reads as ahead of the real mainline, not of a stale local checkout. The `↑`/`↓`/`↕` Status symbols derive from these counts, so they track the upstream tip too.+The table sizes itself to the terminal. When the columns don't all fit, the least important go first — roughly right to left, since the order above runs from identity to nice-to-have — and the summary footer names them (`hidden: Commit, Age, Message`). A wider terminal brings them back. To pin a set rather than leave it to the width, name the columns in [`[list] columns`](/config/#list); `--format=json` carries every field at any width.### Gutter@@ -879,7 +869,7 @@ The leftmost column marks each row by physical presence, from most present to le### CI status-The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and Azure DevOps, `!3035` on GitLab — colored by pipeline status, or a bare `#` when no number is available (e.g. branch workflows without a PR/MR). One color folds two JSON fields: green/blue/red/yellow/gray are the pipeline state, magenta/cyan the review state. The `Value` column names each state; [checks object](#checks-object) and [review states](#review-states) give the JSON spelling — schema 2 reports three of the pipeline values by the shape of `pr` and `checks` rather than as a `checks.status` string:+The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and Azure DevOps, `!3035` on GitLab — colored by pipeline status, or a bare `#` when no number is available (e.g. branch workflows without a PR/MR). Green, blue, red, yellow, and gray show the pipeline state; magenta and cyan show the review state. [checks object](#checks-object) and [review states](#review-states) give the JSON form of each value:| Indicator | Value | Meaning ||-----------|-------|---------|@@ -895,9 +885,9 @@ The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and AzThe two remaining review states have no indicator of their own: `"draft"` only dims the cell and `"approved"` leaves the color unchanged.-Color precedence resolves the fold: changes-requested (magenta) outranks running checks — waiting can't clear it — while an outstanding required review (cyan) only recolors an otherwise green or quiet branch. Cool colors mean waiting, warm colors mean act. An approved PR, or one with no review signal at all (no required reviewers and no reviews), keeps its plain pipeline color — `pr.review` is then `"approved"` or absent, respectively. GitLab MR data carries only `"pending"` and `"draft"` — no approved or changes-requested signal.+Changes requested (magenta) outranks running checks, while a required review (cyan) only recolors an otherwise green or gray branch. GitLab reports only the `"pending"` and `"draft"` review states.-CI cells are clickable links to the PR or pipeline page, and appear dimmed for a draft PR/MR (`"draft"`) or when unpushed local changes make the status stale (`checks.stale`). PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches — visible with `--remotes` — get CI status detection. Results are cached for 30-60 seconds; use `wt config state cache` to view or clear.+CI cells are clickable links to the PR or pipeline page, and appear dimmed for a draft PR/MR (`"draft"`) or when unpushed local changes make the status stale (`checks.stale`). Results are cached for 30-60 seconds; use `wt config state cache` to view or clear.### LLM summaries@@ -912,7 +902,7 @@ Each `[list.custom-columns]` entry in user config adds a column: the key is thetemplate = "{{ vars.ticket }}"```-A custom column that renders empty for every row is dropped from the table outright, rather than merely ranked last as an empty built-in is. Templates, widths, and drop priority: [custom columns config](/config/#custom-columns).+The [custom columns config](/config/#custom-columns) covers templates, widths, and drop priority.## Status symbols@@ -938,10 +928,10 @@ An in-progress git operation, a worktree-location attribute, or a branch with no|--------|------|---------|| `✘` | `worktree.changes.conflicted` | Merge conflicts || `↻` | `worktree.operation` `"rebase"`, `"merge"`, `"cherry_pick"`, `"revert"`, `"bisect"` | A git operation is in progress; `git status` names it |-| `⊟` | `worktree.prunable` | Prunable (worktree directory missing); nothing can be read from a directory that isn't there, so the row's data cells stay blank |+| `⊟` | `worktree.prunable` | Prunable (worktree directory missing) || `⊞` | `worktree.locked` | Locked worktree |-| `⊘` | `worktree.detached` | Detached HEAD — the worktree is on a commit, not a branch, which is why its Branch cell holds a short hash |-| `⚑` | `worktree.duplicate_branch` | Branch checked out in more than one worktree, so `wt` resolves it to whichever git lists first; every worktree on the branch is flagged |+| `⊘` | `worktree.detached` | Detached HEAD |+| `⚑` | `worktree.duplicate_branch` | Branch checked out in more than one worktree || `⚑` | `worktree.branch_mismatch` | Worktree isn't at the path its branch implies || `/` | no `worktree` object | Branch without a worktree |@@ -976,13 +966,10 @@ Relation to the tracking branch, derived from the `upstream.ahead` / `upstream.b### Marker-The last subcolumn carries the branch's own marker — whatever-[`wt config state marker set`](/config/#wt-config-state-marker) stored, usually-an emoji, which is why the subcolumn is two cells wide. Nothing in `wt` writes-it; it is there for agents and scripts to say what a branch is for, and it-reads back as the item's `marker` field. `wt config state marker set 🤖` on a-branch whose default-branch state is `_` renders `_ 🤖` in the column and-`"_🤖"` in `display.symbols`.+The last subcolumn shows the branch's marker, set with+[`wt config state marker set`](/config/#wt-config-state-marker) — usually an+emoji saying what the branch is for. It reads back as the item's `marker`+field.### Placeholder symbols@@ -1144,7 +1131,7 @@ Independent facts; the table's priority-collapsed symbol is `display.state`.| `number` | integer/null | PR/MR number || `url` | string/null | URL to the PR/MR page || `review` | string | Review state (see [review states](#review-states)); absent when the forge reports no review signal |-| `mergeable` | boolean/null | False when the forge reports conflicts, null otherwise — the fetch records only the conflicted case |+| `mergeable` | boolean/null | False when the forge reports conflicts, null otherwise || `repo` | object | Structured metadata for the repository the PR/MR targets, the upstream for fork PRs (see [repo object](#repo-object)); absent when the URL doesn't parse |### checks object@@ -1208,7 +1195,7 @@ The single highest-priority state describing the branch's relation to the defaul### review states-`pr.review` is one of `"changes_requested"`, `"pending"`, `"draft"`, `"approved"`, absent when the forge reports no review signal. The [CI status](#ci-status) section is the single source: its table maps the colored values, and the notes below it cover `"draft"` and `"approved"`. The vocabulary matches Claude Code's statusline `pr.review_state` field.+`pr.review` is one of `"changes_requested"`, `"pending"`, `"draft"`, `"approved"`, absent when the forge reports no review signal. [CI status](#ci-status) shows how each renders. The vocabulary matches Claude Code's statusline `pr.review_state` field.```console# Current worktree path (for scripts)@@ -1238,8 +1225,6 @@ $ wt list --format=json --full | jq '.items[] | select(.checks.stale) | .branch'A JSON Schema for the envelope is published at[worktrunk.dev/schema/list-v2.json](https://worktrunk.dev/schema/list-v2.json).-It describes what `wt` writes, so a field the absence rule can omit is-optional there rather than required-and-null.### Schema 1@@ -1329,7 +1314,7 @@ $ wt remove -D experimentalBy default, branches are deleted when they would add no changes to the default branch if merged. This works with both unchanged git histories, and squash-merge or rebase workflows where commit history differs but file changes match.-Worktrunk checks six conditions (in order of cost):+Worktrunk checks six conditions:1. **Same commit** — Branch HEAD equals the default branch. Shows `_` in `wt list`.2. **Ancestor** — Branch is in target's history (fast-forward or rebase case). Shows `⊂`.@@ -1344,8 +1329,6 @@ The 'same commit' check uses the local default branch; for other checks, 'targetBranches matching these conditions and with empty working trees are dimmed in `wt list` as safe to delete.-Those six ask whether deleting loses work. A branch checked out in a second worktree (only reachable via `git worktree add --force`) fails a different test: deleting the ref would leave that worktree unable to resolve `HEAD`, which is why `git branch -d` refuses the same delete. Such a branch is retained whatever `-D` asks, and the surviving checkout is named.-## Force flagsWorktrunk has two force flags for different situations:@@ -1365,9 +1348,7 @@ Use `--no-delete-branch` to keep the branch regardless of merge status.## Background removal-Removal runs in the background by default — the command returns immediately. The worktree is renamed into `.git/wt/trash/` (instant same-filesystem rename), git metadata is pruned, the branch is deleted, and a detached `rm -rf` finishes cleanup. Cross-filesystem worktrees fall back to `git worktree remove`. Logs: `.git/wt/logs/{branch}/internal/remove.log`. Use `--foreground` to run in the foreground.--After each `wt remove`, entries in `.git/wt/trash/` older than 24 hours are swept by a detached `rm -rf` — eventual cleanup for directories orphaned when a previous background removal was interrupted (SIGKILL, reboot, disk full).+Removal runs in the background by default — the command returns immediately, and output goes to `.git/wt/logs/{branch}/internal/remove.log`. Use `--foreground` to wait for it.## Reaping processes [experimental]@@ -1387,7 +1368,7 @@ To avoid killing work the user did not mean to kill, two guards keep `--reap` co- **Interactive processes are spared.** A process holding a controlling terminal — an interactive shell, or a terminal editor such as `vim` with unsaved buffers — is never reaped. Only detached processes remain candidates.- **Discovery is by working directory only.** A process that started in the worktree and later changed directory, or a daemon that reparented to `init`, no longer reports a directory under the worktree and is not found. To reliably reap those, launch them with [`wt step tether`](/step/#wt-step-tether), which kills the whole process group when the worktree is removed.-Reaping runs before the worktree directory is touched, so it is independent of foreground/background removal and the `--force` flag. Unix only; on Windows `--reap` is rejected.+Unix only; on Windows `--reap` is rejected.## JSON output@@ -1398,11 +1379,11 @@ Reaping runs before the worktree directory is touched, so it is independent of f| Value | Meaning ||-------|---------|| `deleted` | The branch is gone |-| `deferred` | Handed to the detached background process, whose result this run never sees. `--foreground` never reports it |+| `deferred` | Left to the background removal, whose result this run doesn't see. `--foreground` never reports it || `not_attempted` | No deletion was tried: a detached worktree, a sibling checkout, or `--no-delete-branch` || `retained_unmerged` | Declined: the branch was not integrated into the target |-| `retained_checked_out` | Declined: the final topology read found a live worktree with it checked out |-| `retained_raced` | Refused by the compare-and-swap — the branch moved between the integration check and the delete. Re-read the ref and retry |+| `retained_checked_out` | Declined: another worktree has the branch checked out |+| `retained_raced` | Declined: the branch moved during the removal. Retry || `retained_failed` | The delete command itself failed |## Hooks@@ -1487,7 +1468,7 @@ $ wt merge --no-commit --no-rebase`wt merge` runs these steps:-1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background; when step 7 removes the worktree they are anchored on, the merge reports them rather than running them. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.+1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.3. **Rebase** — Rebases onto target, skipping when nothing needs replaying ([`wt step rebase`](/step/#wt-step-rebase) gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](/hook/).@@ -1498,7 +1479,7 @@ $ wt merge --no-commit --no-rebaseUse `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Combining both flags preserves the exact source graph and requires the target to be its ancestor. Useful after preparing commits manually with `wt step commit`. Requires a clean working tree.-`wt merge` targets the *local* default-branch ref and never fetches. When that ref lags its upstream — e.g. a primary checkout's `main` left behind `origin/main` — a branch based on the newer upstream tip is measured, squashed, and rebased against the upstream (so already-upstream commits are never folded into the squash), and the final fast-forward carries the local ref through the already-fetched upstream commits by their real SHAs. `wt step squash` and `wt step rebase` measure the same way. A local target that has *diverged* from its upstream — its own commits and behind — cannot fast-forward, so the merge is refused until the target is reconciled.+`wt merge` merges into the *local* target branch and never fetches.## Local CI@@ -1634,7 +1615,7 @@ The most common creation hook is `post-start` — it runs background tasks (dev| `pre-remove` | Cleanup before worktree deletion: saving test artifacts, backing up state. Runs in the worktree being removed || `post-remove` | Stopping dev servers, removing containers, notifying external systems. Template variables reference the removed worktree |-During `wt merge`, the blocking hooks run in this order: pre-commit → pre-merge → pre-remove. The `post-*` hooks all start together once the merge finishes, each in the worktree it is anchored on — post-merge, post-switch and post-remove in the destination, post-commit in the worktree the commit was made in. A merge that removes that worktree reports `post-commit` as skipped instead of running it — the worktree is gone by the time the hook would start. Use `pre-remove` for work that must finish there, or `--no-remove` to keep the worktree. See [`wt merge`](/merge/#pipeline) for the complete pipeline.+During `wt merge`, the blocking hooks run in this order: pre-commit → pre-merge → pre-remove. The `post-*` hooks start together once the merge finishes. See [`wt merge`](/merge/#pipeline) for the complete pipeline.# Security@@ -1696,7 +1677,7 @@ server = "npm run dev"Here `install` runs first, then `build` and `server` run together.-Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Because an earlier step can still change those values, a preview stands the reference in for its value instead of resolving it: `wt hook <type> --dry-run` and `wt hook show --expanded` render `{{ vars.thing | default('none') }}` as `{{ vars.thing }}` — the reference is defined, so the `default` never fires — while every other variable expands. A filter that transforms its input still runs, against the placeholder text, and its output is shell-escaped like any other value: `{{ vars.thing | upper }}` previews as `'{{ VARS.THING }}'`.+Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Previews (`wt hook <type> --dry-run`, `wt hook show --expanded`) leave `{{ vars.* }}` references unexpanded for that reason.Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependency chain — typically setup that must complete before later steps, like installing dependencies before running a build and dev server concurrently.@@ -1760,9 +1741,9 @@ All hooks share the same perspective — `{{ branch | hash_port }}` produces the`cwd` is the worktree root where the hook command runs. It equals `worktree_path` except in three cases:-- `pre-switch`: hook runs in the source worktree; `worktree_path` is the destination when that worktree already exists — a switch that creates one has no destination directory yet, so `worktree_path` stays on the source (use `pre-start` to work in the new worktree)+- `pre-switch`: hook runs in the source worktree; `worktree_path` is the destination, or the source when the switch creates a new worktree (use `pre-start` to work in the new worktree)- `post-remove`: the active worktree is gone, so the hook runs in the primary worktree-- `post-merge`: the hook runs in the target branch's worktree (the primary worktree if the target has none), including under `--no-remove`, where the merged worktree `worktree_path` names is still on disk+- `post-merge`: the hook runs in the target branch's worktree (the primary worktree if the target has none)Undefined variables error — use conditionals or defaults for optional behavior:@@ -1772,7 +1753,7 @@ Undefined variables error — use conditionals or defaults for optional behaviorsync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"```-A detached worktree is on no branch, so `branch` is undefined there — as are the `base` and `target` names derived from it, whether by a manual `wt hook` or by an operation whose source or destination worktree is detached (`base` in a `pre-switch` fired from one, `target` in a removal that lands in one) — and the same `{% if branch %}` guard applies. This matches `wt list --format=json`, which reports `branch: null` for the same worktree.+A detached worktree has no branch, so `branch` — and a `base` or `target` that names that worktree — is undefined there; guard with `{% if branch %}`.Run any hook-firing command with `-v` to see the resolved variables for the actual invocation — each hook prints a `template variables:` block showing every in-scope variable and its value (`(unset)` for conditional vars that didn't populate, like `target_worktree_path` during `wt switch -`). Aliases do the same under `-v`: `wt -v <alias>` prints the alias's in-scope variables before the pipeline runs.@@ -1864,7 +1845,7 @@ if ctx.get('branch', '').startswith('feature/') and 'backend' in ctx['repo']:## Copying untracked files-One specific command worth calling out: [`wt step copy-ignored`](/step/#wt-step-copy-ignored). Git worktrees share the repository but not untracked files, and this copies gitignored files between worktrees:+Git worktrees share the repository but not untracked files. [`wt step copy-ignored`](/step/#wt-step-copy-ignored) copies gitignored files between worktrees:```toml[post-start]@@ -1921,8 +1902,6 @@ $ wt hook post-startAny `--KEY=VALUE` whose key isn't referenced by a hook template forwards into `{{ args }}` as a literal `--KEY=VALUE` token. Tokens after `--` also forward into `{{ args }}` verbatim. `{{ args }}` renders as a space-joined, shell-escaped string; index with `{{ args[0] }}`, loop with `{% for a in args %}…{% endfor %}`, count with `{{ args | length }}`.-The long form `--var KEY=VALUE` is deprecated but still supported. It force-binds regardless of whether any hook template references `KEY` — useful when a template only references the key conditionally (e.g. `{% if override %}…{% endif %}`).-# Recipes- [Eliminate cold starts](/tips-patterns/#eliminate-cold-starts): `wt step copy-ignored` in `post-start` shares build caches and dependencies; use a `[[post-start]]` pipeline when a later hook depends on the copy@@ -2165,14 +2144,11 @@ Valid built-in names:A selection mixes built-ins with [custom columns](#custom-columns), each namedby its `[list.custom-columns]` header (`columns = ["branch", "Ticket", "ci"]`),and is exhaustive: only the listed columns render. Omit `columns` to keep the-default set, where custom columns append automatically. A built-in name wins a-header collision; the gutter type indicator always shows.+default set, where custom columns append automatically.-Listing a column forces it on, space permitting: `ci` shows without `--full`,-since `--full` only bundles columns into the default table rather than gating a-named one. A column whose data source is missing still stays hidden — `summary`-needs an LLM command (`[commit.generation]`), `url` needs a `[list] url`-template — since listing can't supply the data.+Listing a column forces it on, space permitting: `ci` shows without `--full`. A+column whose data source is missing still stays hidden — `summary` needs an LLM+command (`[commit.generation]`), `url` needs a `[list] url` template.#### Custom columns [experimental]@@ -2314,7 +2290,7 @@ worktree-path = ".worktrees/{{ branch | sanitize }}"Every matching entry applies, least- to most-specific, following the rule above: a more specific entry — `git.company.example/platform/*` over `git.company.example/*` — wins where both set the same setting, while hooks and aliases from every matching entry all run, least-specific first. A literal key is the most specific of all; specificity is the count of non-`*` characters in the key. End a host-wide key with `/*` — a bare `git.company.example*` also covers hosts whose names merely start with that string.-`approved-commands` matches the same way, so a pattern entry approves its commands for every repository it covers. Only a key written by hand is ever a pattern: `wt config approvals add` and the interactive prompt record under the exact identifier, and `wt config approvals clear` removes only that exact entry, leaving a pattern other repositories share intact.+Entries in `approvals.toml` match the same way, so a hand-written pattern entry approves its commands for every repository it covers.#### Forge platform and hostname@@ -2326,9 +2302,9 @@ forge.platform = "gitlab" # or "github", "gitea" (experimentaforge.hostname = "api.git.company.example" # API host, when the remote's own host isn't it```-Both fields describe the host rather than the repository, which is why a pattern keyed to a hostname suits them, and why an SSH alias resolved through `~/.ssh/config` — where the name in the remote URL is local to one machine — belongs here rather than in a repository's committed config. A repository's own `[forge]` block still wins over any entry here, field by field: a repository that sets only `platform` still takes a matching entry's `hostname`.+A repository's own `[forge]` block still wins over any entry here, field by field.-Hooks support all three [hook forms](/hook/#hook-forms). A table runs multiple commands concurrently; an array-of-tables pipeline runs steps in sequence. The dotted-key examples below are equivalent to the table forms — TOML treats `projects."github.com/user/repo".post-start.server = "..."` and a `[projects."github.com/user/repo".post-start]` table the same way:+Hooks support all three [hook forms](/hook/#hook-forms). A table runs multiple commands concurrently; an array-of-tables pipeline runs steps in sequence:```toml# Single command@@ -2471,7 +2447,7 @@ template-append = """"""```-How the fragment renders, and the project-config counterpart: [the LLM commits guide](/llm-commits/#appending-to-the-prompt).+See [the LLM commits guide](/llm-commits/#appending-to-the-prompt) for how the fragment renders and its project-config counterpart.## User hooks@@ -2527,7 +2503,7 @@ template-append = """"""```-The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in [user config](/config/), since they describe per-developer environment (which CLI is installed, which agent the developer prefers). How the fragment renders: [the LLM commits guide](/llm-commits/#appending-to-the-prompt).+The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in [user config](/config/). See [the LLM commits guide](/llm-commits/#appending-to-the-prompt) for how the fragment renders.## Copy-ignored excludes@@ -2604,9 +2580,6 @@ $ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge| `WORKTRUNK_SYSTEM_CONFIG_PATH` | Override system config file location || `WORKTRUNK_PROJECT_CONFIG_PATH` | Override project config file location (defaults to `.config/wt.toml`); relative paths resolve from the worktree root || `XDG_CONFIG_DIRS` | Colon-separated system config directories (default: `/etc/xdg`) |-| `WORKTRUNK_DIRECTIVE_CD_FILE` | Internal: set by shell wrappers. wt writes a raw path; the wrapper `cd`s to it |-| `WORKTRUNK_SHELL_CWD` | Internal: set by wt on alias and hook bodies, so a nested `wt` preserves the user's subdirectory |-| `WORKTRUNK_COMPLETE_NAME` | Internal: set by shell wrappers to the command name completions register under (defaults to the binary name) || `WORKTRUNK_MAX_CONCURRENT_COMMANDS` | Max parallel git commands (default: 32). Lower if hitting file descriptor limits. || `WORKTRUNK_VERBOSE` | Verbosity level (`0`/`1`/`2`), like `-v`/`-vv` but applied everywhere — including shell completion, which no flag can reach || `RUST_LOG` | Logging directive (e.g. `worktrunk=debug`); overrides the verbosity baseline for what reaches stderr |diff --git a/src/cli/step.rs b/src/cli/step.rsindex 44d35f3f6..1e43365f4 100644--- a/src/cli/step.rs+++ b/src/cli/step.rs@@ -79,7 +79,7 @@ pub enum StepCommand {$ wt step commit --branch feature```-The branch must have a checked-out worktree. `--branch` re-roots the whole command: staging, hooks, and the commit all happen there. It selects the previewed worktree the same way, so `--dry-run` describes the commit the same flags would make.+The branch must have a checked-out worktree; staging, hooks, and the commit all happen there.## Hooks@@ -191,13 +191,9 @@ The first matching row wins:| The branch is an ancestor of the target, so it has no commits of its own | `Fast-forwarded to <target>` || Otherwise | The branch's commits replay onto the target's tip — refused outright if the two share no history |-A branch that merged the target into itself still rebases: the target is its ancestor, but the merge commit in between keeps the first row from applying.--When the target's local ref lags its upstream, the rows are measured against that upstream, which the result then names in place of the argument. [`wt merge`](/merge/) covers why.-## Conflicts-A conflicting commit leaves the rebase open rather than undoing it. The worktree keeps git's conflict markers, and the ways out are `git rebase --continue` once the conflict is resolved, `git rebase --skip`, or `git rebase --abort`. Until the rebase is settled, `wt step rebase`, `wt step squash`, `wt step push`, and `wt merge` refuse to run — as they do while any other git operation is open, a conflicted `git merge` included.+A conflicting commit leaves the rebase open rather than undoing it. The worktree keeps git's conflict markers, and the ways out are `git rebase --continue` once the conflict is resolved, `git rebase --skip`, or `git rebase --abort`. Until the rebase is settled, `wt step rebase`, `wt step squash`, `wt step push`, and `wt merge` refuse to run."#)]Rebase {@@ -230,9 +226,7 @@ $ wt step push --no-ff # Merge commit instead of a fast-forward## Target worktree-When the target branch has a worktree of its own, that worktree's files move to the new commits too. Uncommitted changes there never move: the update carries any file the push doesn't touch — staged or not — exactly where it is, and a change touching a file the push does change is refused upfront, naming the file. If the sync can't be applied for any reason — a conflicting file appearing in the race window after the check, or a busy index — the update is rolled back whole, leaving branch and worktree as they were.--A worktree that is still registered but whose directory is gone is refused as well, since nothing can be synced into it — `git worktree prune` clears the registration.+When the target branch has a worktree of its own, that worktree's files move to the new commits too. Uncommitted changes there never move: the update carries any file the push doesn't touch — staged or not — exactly where it is, and a change touching a file the push does change is refused upfront, naming the file. If the update can't be applied, it is rolled back, leaving branch and worktree as they were."#)]Push {@@ -288,18 +282,6 @@ The diff is pipeable to tools like `delta`:```console$ wt step diff | delta```--## How it works--Equivalent to:--```bash-cp "$(git rev-parse --git-dir)/index" /tmp/idx-GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .-GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))-```--`git diff` ignores untracked files. `git add --intent-to-add .` registers them in the index without staging their content, making them visible to `git diff`. This runs against a copy of the real index so the original is never modified."#)]Diff {@@ -388,18 +370,12 @@ Files are reflinked where the filesystem supports it: APFS (macOS), btrfs and XF| `cp -R` (full copy) | 2m | 14GB || `cp -Rc` / `wt step copy-ignored` | 20s | ~0 |-On ext4 and NTFS, which have no reflink, every file is copied in full. The same byte count therefore costs nothing on one filesystem and 14GB on the other, so the summary says which happened: `Copied 4,812 files · 14.0 GB (reflinked, no extra disk)`, against `(full copy)` where those bytes were written out.+On ext4 and NTFS, which have no reflink, every file is copied in full; the summary says `(reflinked, no extra disk)` or `(full copy)`.Reflinks are per file (like `cp -Rc`), so copy time scales with file count.Use the `post-start` hook so the copy runs in the background. Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.-## Background-hook priority (experimental)--When invoked from a background hook pipeline (`post-*` hooks), `wt step copy-ignored` self-lowers its CPU and I/O priority — `taskpolicy -b` on macOS, `nice -n 19` plus `ionice -c 3` on Linux — so it yields to interactive work. Foreground callers (`pre-*` hooks, direct interactive use) run at normal priority so the user isn't waiting on a throttled copy.--wt signals background-hook context by exporting `WORKTRUNK_FOREGROUND=-1` into every detached hook pipeline; `copy-ignored` inspects that variable on entry. The variable name is experimental and may change.-## Language-specific notes### Rust@@ -526,7 +502,7 @@ feature/auth////// Executes sequentially with real-time output; continues past command failures.#[command(- after_long_help = r#"A summary of successes and failures is shown at the end. A template-expansion error (a malformed `{{ … }}` argument) aborts the whole run; only command failures are tolerated and reported. Context JSON — a flat object of every template variable — is piped to stdin for scripts that need structured data.+ after_long_help = r#"A summary of successes and failures is shown at the end. Context JSON — a flat object of every template variable — is piped to stdin for scripts that need structured data.## Arguments@@ -614,8 +590,6 @@ Without an argument, promotes the current branch — or restores the default bra## Gitignored filesGitignored files (build artifacts, `node_modules/`, `.env`) are swapped along with the branches so each worktree keeps the artifacts that belong to its branch. Files are discovered using the same mechanism as [`copy-ignored`](#wt-step-copy-ignored) and can be filtered with `.worktreeinclude`.--The swap uses `rename()` for each entry — fast regardless of entry size, since only filesystem metadata changes. If the worktree is on a different filesystem from `.git/`, it falls back to reflink copy."#)]Promote {@@ -652,7 +626,7 @@ $ wt step prune --min-age=2d # skip candidates younger than 2 days## JSON output-`--format=json` prints one object per candidate to stdout. The two modes report different things, and name their fields accordingly: a live run reports `branch_outcome`, the executed outcome, using the vocabulary [`wt remove`](/remove/#json-output) documents; `--dry-run` reports `branch_deleted`, its prediction of whether the removal would take the branch, since it runs nothing to have an outcome. A dry run also carries `reason` and `target` (why the candidate qualifies, and what it was measured against).+`--format=json` prints one object per candidate to stdout. A live run reports `branch_outcome`, as [`wt remove`](/remove/#json-output) does. `--dry-run` reports `branch_deleted` (whether the removal would delete the branch), `reason` (why the candidate qualifies), and `target` (what it was measured against).## Examples@@ -725,9 +699,8 @@ this by using a temporary location.## ClobberingWith `--clobber`, non-worktree paths at target locations are moved to-`<path>.bak.<timestamp>` before relocating. If that name is already taken,-the move counts up (`…-2`, `…-3`, …) until it finds a free name, so an-existing backup is never overwritten.+`<path>.bak.<timestamp>` before relocating, never overwriting an existing+backup.## Main worktree behavior@@ -763,8 +736,7 @@ refuses), unless `--commit` is passed./// Backup non-worktree paths at target locations///- /// Moves blocking paths to `<path>.bak.<timestamp>`. If that name is- /// taken, counts up (`…-2`, `…-3`, …) to a free name.+ /// Moves blocking paths to `<path>.bak.<timestamp>`.#[arg(long)]clobber: bool,@@ -803,9 +775,7 @@ For pipes, redirects, variables, or globs, wrap in `sh -c`:$ wt step tether -- sh -c 'PORT=$P npm run dev | tee dev.log'```-To run the command from a subdirectory, pass the global `-C` flag (teardown-still watches the worktree root, so a server launched with a relative `-C` is-torn down with the worktree):+To run the command from a subdirectory, pass the global `-C` flag:```console$ wt step tether -C frontend -- npm run devdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_approvals.snap b/tests/snapshots/integration__integration_tests__help__help_config_approvals.snapindex aa57b17fd..c661bd3ad 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_approvals.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_approvals.snap@@ -118,6 +118,6 @@ Approved commands are saved to [2m~/.config/worktrunk/approvals.toml[0m. Re-ap[2mstate[0m is [2mno_commands[0m (the project declares none), [2mapproval_required[0m (at least one is unapproved), or [2mapproved[0m. [2mname[0m is absent for an unnamed command and for the commit-template fragment.-[2mstale[0m is separate rather than a fourth [2mstate[0m, because it co-occurs with all three: these are approvals recorded earlier whose command has since been edited or removed from the project config. They are what [2m--yes[0m would silently re-approve, so an orchestrator preserving the approval model reads them before choosing that flag.+[2mstale[0m, which can accompany any [2mstate[0m, lists approvals whose command has since been edited or removed from the project config.----- stderr -----diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snapindex a9a8df4df..59326ac4c 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap@@ -209,14 +209,11 @@ Creates [2m~/.config/worktrunk/config.toml[0m with the following content:[107m [0m [2m# A selection mixes built-ins with custom columns (#custom-columns), each named[0m[107m [0m [2m# by its `[list.custom-columns]` header (`columns = ["branch", "Ticket", "ci"]`),[0m[107m [0m [2m# and is exhaustive: only the listed columns render. Omit `columns` to keep the[0m-[107m [0m [2m# default set, where custom columns append automatically. A built-in name wins a[0m-[107m [0m [2m# header collision; the gutter type indicator always shows.[0m+[107m [0m [2m# default set, where custom columns append automatically.[0m[107m [0m [2m#[0m-[107m [0m [2m# Listing a column forces it on, space permitting: `ci` shows without `--full`,[0m-[107m [0m [2m# since `--full` only bundles columns into the default table rather than gating a[0m-[107m [0m [2m# named one. A column whose data source is missing still stays hidden — `summary`[0m-[107m [0m [2m# needs an LLM command (`[commit.generation]`), `url` needs a `[list] url`[0m-[107m [0m [2m# template — since listing can't supply the data.[0m+[107m [0m [2m# Listing a column forces it on, space permitting: `ci` shows without `--full`. A[0m+[107m [0m [2m# column whose data source is missing still stays hidden — `summary` needs an LLM[0m+[107m [0m [2m# command (`[commit.generation]`), `url` needs a `[list] url` template.[0m[107m [0m [2m#[0m[107m [0m [2m# #### Custom columns [experimental][0m[107m [0m [2m#[0m@@ -339,7 +336,7 @@ Creates [2m~/.config/worktrunk/config.toml[0m with the following content:[107m [0m [2m# Every matching entry applies, least- to most-specific, following the rule above: a more specific entry — `git.company.example/platform/*` over `git.company.example/*` — wins where both set the same setting, while hooks and aliases from every matching entry all run, least-specific first. A literal key is the most specific of all; specificity is the count of non-`*` characters in the key. End a host-wide key with `/*` — a bare `git.company.example*` also covers hosts whose names merely start[107m [0m with that string.[0m[107m [0m [2m#[0m-[107m [0m [2m# `approved-commands` matches the same way, so a pattern entry approves its commands for every repository it covers. Only a key written by hand is ever a pattern: `wt config approvals add` and the interactive prompt record under the exact identifier, and `wt config approvals clear` removes only that exact entry, leaving a pattern other repositories share intact.[0m+[107m [0m [2m# Entries in `approvals.toml` match the same way, so a hand-written pattern entry approves its commands for every repository it covers.[0m[107m [0m [2m#[0m[107m [0m [2m# #### Forge platform and hostname[0m[107m [0m [2m#[0m@@ -349,9 +346,9 @@ Creates [2m~/.config/worktrunk/config.toml[0m with the following content:[107m [0m [2m# forge.platform = "gitlab" # or "github", "gitea" (experimental), "azure-devops" (experimental)[0m[107m [0m [2m# forge.hostname = "api.git.company.example" # API host, when the remote's own host isn't it[0m[107m [0m [2m#[0m-[107m [0m [2m# Both fields describe the host rather than the repository, which is why a pattern keyed to a hostname suits them, and why an SSH alias resolved through `~/.ssh/config` — where the name in the remote URL is local to one machine — belongs here rather than in a repository's committed config. A repository's own `[forge]` block still wins over any entry here, field by field: a repository that sets only `platform` still takes a matching entry's `hostname`.[0m+[107m [0m [2m# A repository's own `[forge]` block still wins over any entry here, field by field.[0m[107m [0m [2m#[0m-[107m [0m [2m# Hooks support all three hook forms (https://worktrunk.dev/hook/#hook-forms). A table runs multiple commands concurrently; an array-of-tables pipeline runs steps in sequence. The dotted-key examples below are equivalent to the table forms — TOML treats `projects."github.com/user/repo".post-start.server = "..."` and a `[projects."github.com/user/repo".post-start]` table the same way:[0m+[107m [0m [2m# Hooks support all three hook forms (https://worktrunk.dev/hook/#hook-forms). A table runs multiple commands concurrently; an array-of-tables pipeline runs steps in sequence:[0m[107m [0m [2m#[0m[107m [0m [2m# # Single command[0m[107m [0m [2m# [projects."github.com/user/repo"][0m@@ -486,7 +483,7 @@ Creates [2m~/.config/worktrunk/config.toml[0m with the following content:[107m [0m [2m# - Explain the rationale in the body, not just the change[0m[107m [0m [2m# """[0m[107m [0m [2m#[0m-[107m [0m [2m# How the fragment renders, and the project-config counterpart: the LLM commits guide (https://worktrunk.dev/llm-commits/#appending-to-the-prompt).[0m+[107m [0m [2m# See the LLM commits guide (https://worktrunk.dev/llm-commits/#appending-to-the-prompt) for how the fragment renders and its project-config counterpart.[0m[107m [0m [2m#[0m[107m [0m [2m# ## User hooks[0m[107m [0m [2m#[0m@@ -537,8 +534,7 @@ With [2m--project[0m, creates [2m.config/wt.toml[0m in the current repositor[107m [0m [2m# - Reference the relevant issue ID in the body[0m[107m [0m [2m# """[0m[107m [0m [2m#[0m-[107m [0m [2m# The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in user config (https://worktrunk.dev/config/), since they describe per-developer environment (which CLI is installed, which agent the developer prefers). How the fragment renders: the LLM commits guide-[107m [0m (https://worktrunk.dev/llm-commits/#appending-to-the-prompt).[0m+[107m [0m [2m# The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in user config (https://worktrunk.dev/config/). See the LLM commits guide (https://worktrunk.dev/llm-commits/#appending-to-the-prompt) for how the fragment renders.[0m[107m [0m [2m#[0m[107m [0m [2m# ## Copy-ignored excludes[0m[107m [0m [2m#[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snapindex 222feaacb..b93d1e51d 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap@@ -257,14 +257,11 @@ Valid built-in names:A selection mixes built-ins with custom columns, each namedby its [2m[list.custom-columns][0m header ([2mcolumns = ["branch", "Ticket", "ci"][0m),and is exhaustive: only the listed columns render. Omit [2mcolumns[0m to keep the-default set, where custom columns append automatically. A built-in name wins a-header collision; the gutter type indicator always shows.+default set, where custom columns append automatically.-Listing a column forces it on, space permitting: [2mci[0m shows without [2m--full[0m,-since [2m--full[0m only bundles columns into the default table rather than gating a-named one. A column whose data source is missing still stays hidden — [2msummary[0m-needs an LLM command ([2m[commit.generation][0m), [2murl[0m needs a [2m[list] url[0m-template — since listing can't supply the data.+Listing a column forces it on, space permitting: [2mci[0m shows without [2m--full[0m. A+column whose data source is missing still stays hidden — [2msummary[0m needs an LLM+command ([2m[commit.generation][0m), [2murl[0m needs a [2m[list] url[0m template.[1mCustom columns [experimental][0m@@ -387,7 +384,7 @@ A key containing [2m*[0m matches any run of characters, [2m/[0m included, soEvery matching entry applies, least- to most-specific, following the rule above: a more specific entry — [2mgit.company.example/platform/*[0m over [2mgit.company.example/*[0m — wins where both set the same setting, while hooks and aliases from every matching entry all run, least-specific first. A literal key is the most specific of all; specificity is the count of non-[2m*[0m characters in the key. End a host-wide key with [2m/*[0m — a bare [2mgit.company.example*[0m also covers hosts whose names merely start with thatstring.-[2mapproved-commands[0m matches the same way, so a pattern entry approves its commands for every repository it covers. Only a key written by hand is ever a pattern: [2mwt config approvals add[0m and the interactive prompt record under the exact identifier, and [2mwt config approvals clear[0m removes only that exact entry, leaving a pattern other repositories share intact.+Entries in [2mapprovals.toml[0m match the same way, so a hand-written pattern entry approves its commands for every repository it covers.[1mForge platform and hostname[0m@@ -397,9 +394,9 @@ string.[107m [0m [2mforge.platform = [0m[2m[32m"gitlab"[0m[2m [0m[2m# or "github", "gitea" (experimental), "azure-devops" (experimental)[0m[107m [0m [2mforge.hostname = [0m[2m[32m"api.git.company.example"[0m[2m [0m[2m# API host, when the remote's own host isn't it[0m-Both fields describe the host rather than the repository, which is why a pattern keyed to a hostname suits them, and why an SSH alias resolved through [2m~/.ssh/config[0m — where the name in the remote URL is local to one machine — belongs here rather than in a repository's committed config. A repository's own [2m[forge][0m block still wins over any entry here, field by field: a repository that sets only [2mplatform[0m still takes a matching entry's [2mhostname[0m.+A repository's own [2m[forge][0m block still wins over any entry here, field by field.-Hooks support all three hook forms. A table runs multiple commands concurrently; an array-of-tables pipeline runs steps in sequence. The dotted-key examples below are equivalent to the table forms — TOML treats [2mprojects."github.com/user/repo".post-start.server = "..."[0m and a [2m[projects."github.com/user/repo".post-start][0m table the same way:+Hooks support all three hook forms. A table runs multiple commands concurrently; an array-of-tables pipeline runs steps in sequence:[107m [0m [2m# Single command[0m[107m [0m [2m[36m[projects."github.com/user/repo"][0m@@ -530,7 +527,7 @@ Default template:[107m [0m [2m[32m- Explain the rationale in the body, not just the change[0m[107m [0m [2m[32m"[0m[2m[32m""[0m-How the fragment renders, and the project-config counterpart: the LLM commits guide.+See the LLM commits guide for how the fragment renders and its project-config counterpart.[1m[32mUser hooks[0m@@ -576,7 +573,7 @@ When many repositories share one self-hosted host, name it once in user config w[107m [0m [2m[32m- Reference the relevant issue ID in the body[0m[107m [0m [2m[32m"[0m[2m[32m""[0m-The first time the fragment is used (and whenever it changes), [2mwt[0m prompts the user to approve it — the same one-shot gate as project-defined hooks. Only [2mtemplate-append[0m is honored from the project file; the LLM command and the main prompt template stay in user config, since they describe per-developer environment (which CLI is installed, which agent the developer prefers). How the fragment renders: the LLM commits guide.+The first time the fragment is used (and whenever it changes), [2mwt[0m prompts the user to approve it — the same one-shot gate as project-defined hooks. Only [2mtemplate-append[0m is honored from the project file; the LLM command and the main prompt template stay in user config. See the LLM commits guide for how the fragment renders.[1m[32mCopy-ignored excludes[0m@@ -644,9 +641,6 @@ Override the LLM command in CI to use a mock:[2mWORKTRUNK_SYSTEM_CONFIG_PATH[0m Override system config file location[2mWORKTRUNK_PROJECT_CONFIG_PATH[0m Override project config file location (defaults to [2m.config/wt.toml[0m); relative paths resolve from the worktree root[2mXDG_CONFIG_DIRS[0m Colon-separated system config directories (default: [2m/etc/xdg[0m)- [2mWORKTRUNK_DIRECTIVE_CD_FILE[0m Internal: set by shell wrappers. wt writes a raw path; the wrapper [2mcd[0ms to it- [2mWORKTRUNK_SHELL_CWD[0m Internal: set by wt on alias and hook bodies, so a nested [2mwt[0m preserves the user's subdirectory- [2mWORKTRUNK_COMPLETE_NAME[0m Internal: set by shell wrappers to the command name completions register under (defaults to the binary name)[2mWORKTRUNK_MAX_CONCURRENT_COMMANDS[0m Max parallel git commands (default: 32). Lower if hitting file descriptor limits.[2mWORKTRUNK_VERBOSE[0m Verbosity level ([2m0[0m/[2m1[0m/[2m2[0m), like [2m-v[0m/[2m-vv[0m but applied everywhere — including shell completion, which no flag can reach[2mRUST_LOG[0m Logging directive (e.g. [2mworktrunk=debug[0m); overrides the verbosity baseline for what reaches stderrdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_cache.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_cache.snapindex 2b416189c..d648e8e5b 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_state_cache.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_cache.snap@@ -80,7 +80,7 @@ View or drop worktrunk's regenerable caches in one place. Everything here is reb[1m[32mWhat's cached[0m-- [1mCI status[0m — GitHub/GitLab CI per branch (30–60s TTL), shown in [2mwt list[0m, plus the largest PR/MR number seen (sizes the CI column)+- [1mCI status[0m — GitHub/GitLab CI per branch (30–60s TTL), shown in [2mwt list[0m- [1mSummaries[0m — LLM-generated branch summaries ([2mwt list --full[0m, [2mwt switch[0m preview)- [1mGit commands[0m — cached merge-tree, ancestry, diff-stat, and [2mwt switch[0m preview results- [1mHints[0m — one-time hints already shown in this repodiff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snapindex 99eb5448e..783339e85 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap@@ -81,20 +81,16 @@ In a hook or alias template, prefer the [2m{{ default_branch }}[0m template vaWithout a subcommand, runs [2mget[0m. [2mset[0m stores the override in the repository's local git config. The override adds no project file and applies to every linked worktree in the clone. [2mclear[0m then [2mget[0m re-detects. The branch must exist locally for [2mwt list[0m comparisons.-[2mdefault-branch get[0m resolves the value and caches it on a miss; the aggregate [2mwt config state get[0m only reports the cache (read-only), so it can show [2m(none)[0m until something populates it.-[1m[32mDetection[0mWorktrunk detects the default branch automatically:1. [1mWorktrunk cache[0m — Checks [2mgit config worktrunk.default-branch[0m2. [1mGit cache[0m — Detects primary remote and checks its HEAD (e.g., [2morigin/HEAD[0m)-3. [1mRemote query[0m — If not cached, queries [2mgit ls-remote[0m — typically 100ms–2s, abandoned after 10s+3. [1mRemote query[0m — If not cached, queries [2mgit ls-remote[0m, giving up after 10s4. [1mLocal inference[0m — If no remote, or the query was abandoned, infers from local branches-Once detected, the result is cached in [2mworktrunk.default-branch[0m for fast access. The cache isn't re-validated on every command, so a later change to [2morigin/HEAD[0m — a renamed default branch followed by [2mgit remote set-head origin -a[0m — isn't picked up automatically. [2mwt config state[0m flags the drift when the cached value differs from the remote's local HEAD — expected for a deliberate override; [2mset[0m adopts the new branch and [2mclear[0m re-detects.--An abandoned remote query is the one case that isn't cached: the branch it inferred locally answers that command, but a value guessed while the remote was unreachable would otherwise become permanent, so the next command queries again.+Once detected, the result is cached in [2mworktrunk.default-branch[0m — except a value inferred after the remote query was abandoned, so an outage can't make a guess permanent. A later change to [2morigin/HEAD[0m isn't picked up automatically: [2mwt config state[0m flags the mismatch, [2mset[0m adopts the new branch, and [2mclear[0m re-detects.The local inference fallback uses these heuristics in order:- If only one local branch exists, uses itdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_get.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_get.snapindex c67b72840..f9e9f4623 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_state_get.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_get.snap@@ -80,7 +80,7 @@ Shows all stored state including:- [1mPrevious branch[0m: Previous branch for [2mwt switch -[0m- [1mBranch markers[0m: User-defined branch notes- [1mVars[0m: Custom variables per branch-- [1mCI status[0m: Cached GitHub/GitLab CI status per branch (30-60s TTL), plus the largest PR/MR number seen (sizes the [2mwt list[0m CI column)+- [1mCI status[0m: Cached GitHub/GitLab CI status per branch (30-60s TTL)- [1mSummaries[0m: Cached LLM-generated branch summaries (shown in [2mwt list --full[0m and [2mwt switch[0m preview)- [1mGit commands cache[0m: Cached merge-tree, ancestry, diff-stat, and [2mwt switch[0m preview results- [1mHints[0m: One-time hints that have been showndiff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snapindex 4ba55b992..5d5cc2a78 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snap@@ -107,7 +107,7 @@ Hook output lives in per-branch subtrees under [2m.git/wt/logs/{branch}/[0m:Background hooks [2m{branch}/{source}/{hook-type}/{name}.log[0mBackground removal [2m{branch}/internal/remove.log[0m-All [2mpost-*[0m hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is [2muser[0m or [2mproject[0m. Branch and hook names are sanitized for filesystem safety (invalid characters → [2m-[0m; short collision-avoidance hash appended). Same operation on same branch overwrites the previous log. Removing a branch clears its subtree; orphans from deleted branches can be swept with [2mwt config state logs clear[0m.+All [2mpost-*[0m hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is [2muser[0m or [2mproject[0m. Branch and hook names are sanitized for filesystem safety. Same operation on same branch overwrites the previous log. Removing a branch clears its subtree; orphans from deleted branches can be swept with [2mwt config state logs clear[0m.[32mDiagnostic files[0m@@ -118,12 +118,11 @@ All [2mpost-*[0m hooks (post-start, post-switch, post-commit, post-merge) run[2msubprocess.log[0m Running with [2m-vv[0m[2mdiagnostic.md[0m Running with [2m-vv[0m-[2mtrace.log[0m is the human-readable trace at [2m-vv[0m — each command's start ([2m$ …[0m) and completion ([2m✓[0m/[2m✗ … 12.3ms[0m), in-process spans, milestones, and bounded subprocess previews. [2mtrace.jsonl[0m is the same event stream as one JSON object per line, for machines ([2mjq[0m, chrome://tracing); [2mwt config state logs profile[0m reads it to summarize a performance report (where time went, parallelism, redundant commands). [2msubprocess.log[0m holds the raw uncapped subprocess stdout/stderr bodies. [2mdiagnostic.md[0m is a markdown-bug-report bundle that leads with that same performance profile and inlines [2mtrace.log[0m; [2mwt[0m prints a [2mgh gist create[0m command pointing at it. All four are overwritten on each [2m-vv[0m run.+[2mtrace.log[0m is the human-readable trace of commands and their timings. [2mtrace.jsonl[0m holds the same events as JSON lines, which [2mwt config state logs profile[0m summarizes into a performance report. [2msubprocess.log[0m holds full subprocess output. [2mdiagnostic.md[0m is a bug-report bundle; [2mwt[0m prints a [2mgh gist create[0m command for it. All four are overwritten on each [2m-vv[0m run.[1m[32mLocation[0m-All logs are stored in [2m.git/wt/logs/[0m (in the main worktree's git directory). All worktrees write to the same directory. Top-level files are shared logs (command audit + diagnostics); top-level directories are per-branch log trees.+All logs are stored in [2m.git/wt/logs/[0m (in the main worktree's git directory). All worktrees write to the same directory.[1m[32mStructured output[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snapindex 0be2f4a16..4a3a58621 100644--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap@@ -96,7 +96,7 @@ The table renders progressively: branch names, paths, and commit hashes appear i[1m[32mFull mode[0m-[2m--full[0m adds the two columns that reach off-machine: CI status (GitHub/GitLab pipeline pass/fail, over the network) and LLM-generated summaries of each branch's changes. The [2mmain…±[0m line diffs are local git, so they show by default.+[2m--full[0m adds the two columns that reach off-machine: CI status (GitHub/GitLab pipeline pass/fail, over the network) and LLM-generated summaries of each branch's changes.[1m[32mExamples[0m@@ -141,29 +141,26 @@ Output as JSON for scripting:[1m[32mColumns[0m- Column Shows- ──────── ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────- Branch Branch name, elided with … past 32 characters so one long name can't size the column for every row ([2m--format=json[0m keeps it whole); a detached worktree has none, so it shows its short hash in dim yellow- Status Compact symbols (see below)- HEAD± Uncommitted changes, including untracked files: +added -deleted lines- main↕ Commits ahead/behind default branch- main…± Line diffs since the merge-base (three-dot) with the default branch- Summary LLM-generated branch summary; requires [2m--full[0m, [2msummary = true[0m, and [2mcommit.generation[0m- Remote⇅ Commits ahead/behind tracking branch- CI PR/MR number colored by pipeline status; [2m--full[0m only- Path Worktree directory- URL Dev server URL from project config; dimmed if port is not listening- (custom) User-defined custom columns from [2m[list.custom-columns][0m user config [experimental]- Commit Short hash, abbreviated per [2mcore.abbrev[0m- Age Time since last commit- Message Last commit message (truncated)+ Column Shows+ ──────── ───────────────────────────────────────────────────────────────────────────────────────+ Branch Branch name, elided with … past 32 characters; a detached worktree shows its short hash+ Status Compact symbols (see below)+ HEAD± Uncommitted changes, including untracked files: +added -deleted lines+ main↕ Commits ahead/behind default branch+ main…± Line diffs since the merge-base (three-dot) with the default branch+ Summary LLM-generated branch summary; requires [2m--full[0m, [2msummary = true[0m, and [2mcommit.generation[0m+ Remote⇅ Commits ahead/behind tracking branch+ CI PR/MR number colored by pipeline status; [2m--full[0m only+ Path Worktree directory+ URL Dev server URL from project config; dimmed if port is not listening+ (custom) User-defined custom columns from [2m[list.custom-columns][0m user config [experimental]+ Commit Short hash, abbreviated per [2mcore.abbrev[0m+ Age Time since last commit+ Message Last commit message (truncated)The [2mmain↕[0m and [2mmain…±[0m headers keep the familiar [2mmain[0m label in every repository.-The table sizes itself to the terminal. When the columns don't all fit, the least important go first — roughly right to left, since the order above runs from identity to nice-to-have — and the summary footer names them ([2mhidden: Commit, Age, Message[0m). A column with nothing to show on any row — [2mRemote⇅[0m in a repo with no remote — ranks below every populated column, so it goes first. A wider terminal brings them back. To pin a set rather than leave it to the width, name the columns in [2m[list]-[2mcolumns[0m; [2m--format=json[0m carries every field at any width.--[2mmain↕[0m and [2mmain…±[0m measure against the default branch's upstream tip when the local copy lags it — so in a fork whose local [2mmain[0m trails [2morigin/main[0m, a branch reads as ahead of the real mainline, not of a stale local checkout. The [2m↑[0m/[2m↓[0m/[2m↕[0m Status symbols derive from these counts, so they track the upstream tip too.+The table sizes itself to the terminal. When the columns don't all fit, the least important go first — roughly right to left, since the order above runs from identity to nice-to-have — and the summary footer names them ([2mhidden: Commit, Age, Message[0m). A wider terminal brings them back. To pin a set rather than leave it to the width, name the columns in [2m[list] columns[0m; [2m--format=json[0m carries every field at any width.[32mGutter[0m@@ -179,8 +176,7 @@ The leftmost column marks each row by physical presence, from most present to le[32mCI status[0m-The CI column shows the branch's open PR/MR — [2m#3035[0m on GitHub, Gitea, and Azure DevOps, [2m!3035[0m on GitLab — colored by pipeline status, or a bare [2m#[0m when no number is available (e.g. branch workflows without a PR/MR). One color folds two JSON fields: green/blue/red/yellow/gray are the pipeline state, magenta/cyan the review state. The [2mValue[0m column names each state; checks object and review states give the JSON spelling — schema 2 reports three of the pipeline values by the shape of [2mpr[0m and [2mchecks[0m-rather than as a [2mchecks.status[0m string:+The CI column shows the branch's open PR/MR — [2m#3035[0m on GitHub, Gitea, and Azure DevOps, [2m!3035[0m on GitLab — colored by pipeline status, or a bare [2m#[0m when no number is available (e.g. branch workflows without a PR/MR). Green, blue, red, yellow, and gray show the pipeline state; magenta and cyan show the review state. checks object and review states give the JSON form of each value:Indicator Value Meaning───────── ──────────────────── ───────────────────────────────────────────────────────────────@@ -196,10 +192,9 @@ rather than as a [2mchecks.status[0m string:The two remaining review states have no indicator of their own: [2m"draft"[0m only dims the cell and [2m"approved"[0m leaves the color unchanged.-Color precedence resolves the fold: changes-requested (magenta) outranks running checks — waiting can't clear it — while an outstanding required review (cyan) only recolors an otherwise green or quiet branch. Cool colors mean waiting, warm colors mean act. An approved PR, or one with no review signal at all (no required reviewers and no reviews), keeps its plain pipeline color — [2mpr.review[0m is then [2m"approved"[0m or absent, respectively. GitLab MR data carries only [2m"pending"[0m and [2m"draft"[0m — no approved-or changes-requested signal.+Changes requested (magenta) outranks running checks, while a required review (cyan) only recolors an otherwise green or gray branch. GitLab reports only the [2m"pending"[0m and [2m"draft"[0m review states.-CI cells are clickable links to the PR or pipeline page, and appear dimmed for a draft PR/MR ([2m"draft"[0m) or when unpushed local changes make the status stale ([2mchecks.stale[0m). PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches — visible with [2m--remotes[0m — get CI status detection. Results are cached for 30-60 seconds; use [2mwt config state cache[0m to view or clear.+CI cells are clickable links to the PR or pipeline page, and appear dimmed for a draft PR/MR ([2m"draft"[0m) or when unpushed local changes make the status stale ([2mchecks.stale[0m). Results are cached for 30-60 seconds; use [2mwt config state cache[0m to view or clear.[32mLLM summaries[0m@@ -212,7 +207,7 @@ Each [2m[list.custom-columns][0m entry in user config adds a column: the key i[107m [0m [2m[36m[list.custom-columns.Ticket][0m[107m [0m [2mtemplate = [0m[2m[32m"{{ vars.ticket }}"[0m-A custom column that renders empty for every row is dropped from the table outright, rather than merely ranked last as an empty built-in is. Templates, widths, and drop priority: custom columns config.+The custom columns config covers templates, widths, and drop priority.[1m[32mStatus symbols[0m@@ -234,16 +229,16 @@ Independent flags from [2mgit status[0m; several can show at once (e.g. [2m+!An in-progress git operation, a worktree-location attribute, or a branch with no worktree. One symbol shows, highest priority first ([2m✘ > ↻ > ⊟ > ⊞ > ⊘ > ⚑ > /[0m):- Symbol JSON Meaning- ────── ─────────────────────────────────────────────────────────────────────── ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────- [31m✘[0m [2mworktree.changes.conflicted[0m Merge conflicts- [33m↻[0m [2mworktree.operation[0m [2m"rebase"[0m, [2m"merge"[0m, [2m"cherry_pick"[0m, [2m"revert"[0m, [2m"bisect"[0m A git operation is in progress; [2mgit status[0m names it- [33m⊟[0m [2mworktree.prunable[0m Prunable (worktree directory missing); nothing can be read from a directory that isn't there, so the row's data cells stay blank- [33m⊞[0m [2mworktree.locked[0m Locked worktree- [2m⊘[0m [2mworktree.detached[0m Detached HEAD — the worktree is on a commit, not a branch, which is why its Branch cell holds a short hash- [2m[33m⚑[0m [2mworktree.duplicate_branch[0m Branch checked out in more than one worktree, so [2mwt[0m resolves it to whichever git lists first; every worktree on the branch is flagged- [2m[33m⚑[0m [2mworktree.branch_mismatch[0m Worktree isn't at the path its branch implies- [2m/[0m no [2mworktree[0m object Branch without a worktree+ Symbol JSON Meaning+ ────── ─────────────────────────────────────────────────────────────────────── ───────────────────────────────────────────────────+ [31m✘[0m [2mworktree.changes.conflicted[0m Merge conflicts+ [33m↻[0m [2mworktree.operation[0m [2m"rebase"[0m, [2m"merge"[0m, [2m"cherry_pick"[0m, [2m"revert"[0m, [2m"bisect"[0m A git operation is in progress; [2mgit status[0m names it+ [33m⊟[0m [2mworktree.prunable[0m Prunable (worktree directory missing)+ [33m⊞[0m [2mworktree.locked[0m Locked worktree+ [2m⊘[0m [2mworktree.detached[0m Detached HEAD+ [2m[33m⚑[0m [2mworktree.duplicate_branch[0m Branch checked out in more than one worktree+ [2m[33m⚑[0m [2mworktree.branch_mismatch[0m Worktree isn't at the path its branch implies+ [2m/[0m no [2mworktree[0m object Branch without a worktree[32mDefault branch[0m@@ -276,13 +271,10 @@ Relation to the tracking branch, derived from the [2mupstream.ahead[0m / [2mu[32mMarker[0m-The last subcolumn carries the branch's own marker — whatever-[2mwt config state marker set[0m stored, usually-an emoji, which is why the subcolumn is two cells wide. Nothing in [2mwt[0m writes-it; it is there for agents and scripts to say what a branch is for, and it-reads back as the item's [2mmarker[0m field. [2mwt config state marker set 🤖[0m on a-branch whose default-branch state is [2m_[0m renders [2m_ 🤖[0m in the column and-[2m"_🤖"[0m in [2mdisplay.symbols[0m.+The last subcolumn shows the branch's marker, set with+[2mwt config state marker set[0m — usually an+emoji saying what the branch is for. It reads back as the item's [2mmarker[0m+field.[32mPlaceholder symbols[0m@@ -442,7 +434,7 @@ Independent facts; the table's priority-collapsed symbol is [2mdisplay.state[0[2mnumber[0m integer/null PR/MR number[2murl[0m string/null URL to the PR/MR page[2mreview[0m string Review state (see review states); absent when the forge reports no review signal- [2mmergeable[0m boolean/null False when the forge reports conflicts, null otherwise — the fetch records only the conflicted case+ [2mmergeable[0m boolean/null False when the forge reports conflicts, null otherwise[2mrepo[0m object Structured metadata for the repository the PR/MR targets, the upstream for fork PRs (see repo object); absent when the URL doesn't parse[32mchecks object[0m@@ -506,7 +498,7 @@ The single highest-priority state describing the branch's relation to the defaul[32mreview states[0m-[2mpr.review[0m is one of [2m"changes_requested"[0m, [2m"pending"[0m, [2m"draft"[0m, [2m"approved"[0m, absent when the forge reports no review signal. The CI status section is the single source: its table maps the colored values, and the notes below it cover [2m"draft"[0m and [2m"approved"[0m. The vocabulary matches Claude Code's statusline [2mpr.review_state[0m field.+[2mpr.review[0m is one of [2m"changes_requested"[0m, [2m"pending"[0m, [2m"draft"[0m, [2m"approved"[0m, absent when the forge reports no review signal. CI status shows how each renders. The vocabulary matches Claude Code's statusline [2mpr.review_state[0m field.[107m [0m [2m# Current worktree path (for scripts)[0m[107m [0m [2m[0m[2m[34mwt[0m[2m list [0m[2m[36m--format=json[0m[2m [0m[2m[36m|[0m[2m [0m[2m[34mjq[0m[2m [0m[2m[36m-r[0m[2m [0m[2m[32m'.items[] | select(.worktree.current) | .worktree.path'[0m@@ -534,8 +526,6 @@ The single highest-priority state describing the branch's relation to the defaulA JSON Schema for the envelope is published atworktrunk.dev/schema/list-v2.json.-It describes what [2mwt[0m writes, so a field the absence rule can omit is-optional there rather than required-and-null.[32mSchema 1[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snapindex 7f74da4e7..43c48de20 100644--- a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap+++ b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap@@ -107,7 +107,7 @@ git operations complete.[2m--full[0m adds the two columns that reach off-machine: CI status (GitHub/GitLabpipeline pass/fail, over the network) and LLM-generated summaries of each-branch's changes. The [2mmain…±[0m line diffs are local git, so they show by default.+branch's changes.[1m[32mExamples[0m@@ -154,9 +154,8 @@ Output as JSON for scripting:Column Shows──────── ─────────────────────────────────────────────────────────────────────- Branch Branch name, elided with … past 32 characters so one long name can't- size the column for every row ([2m--format=json[0m keeps it whole); a- detached worktree has none, so it shows its short hash in dim yellow+ Branch Branch name, elided with … past 32 characters; a detached worktree+ shows its short hashStatus Compact symbols (see below)HEAD± Uncommitted changes, including untracked files: +added -deleted linesmain↕ Commits ahead/behind default branch@@ -178,16 +177,9 @@ The [2mmain↕[0m and [2mmain…±[0m headers keep the familiar [2mmain[0mThe table sizes itself to the terminal. When the columns don't all fit, theleast important go first — roughly right to left, since the order above runsfrom identity to nice-to-have — and the summary footer names them ([2mhidden:-[2mCommit, Age, Message[0m). A column with nothing to show on any row — [2mRemote⇅[0m in a-repo with no remote — ranks below every populated column, so it goes first. A-wider terminal brings them back. To pin a set rather than leave it to the width,- name the columns in [2m[list] columns[0m; [2m--format=json[0m carries every field at any-width.--[2mmain↕[0m and [2mmain…±[0m measure against the default branch's upstream tip when the-local copy lags it — so in a fork whose local [2mmain[0m trails [2morigin/main[0m, a branch-reads as ahead of the real mainline, not of a stale local checkout. The [2m↑[0m/[2m↓[0m/[2m↕[0m-Status symbols derive from these counts, so they track the upstream tip too.+[2mCommit, Age, Message[0m). A wider terminal brings them back. To pin a set rather+than leave it to the width, name the columns in [2m[list] columns[0m; [2m--format=json[0m+carries every field at any width.[32mGutter[0m@@ -206,11 +198,9 @@ least:The CI column shows the branch's open PR/MR — [2m#3035[0m on GitHub, Gitea, and AzureDevOps, [2m!3035[0m on GitLab — colored by pipeline status, or a bare [2m#[0m when no number- is available (e.g. branch workflows without a PR/MR). One color folds two JSON-fields: green/blue/red/yellow/gray are the pipeline state, magenta/cyan the-review state. The [2mValue[0m column names each state; checks object and review states- give the JSON spelling — schema 2 reports three of the pipeline values by the-shape of [2mpr[0m and [2mchecks[0m rather than as a [2mchecks.status[0m string:+ is available (e.g. branch workflows without a PR/MR). Green, blue, red, yellow,+ and gray show the pipeline state; magenta and cyan show the review state.+checks object and review states give the JSON form of each value:Indicator Value Meaning───────── ──────────────────── ───────────────────────────────────────────────@@ -229,20 +219,14 @@ shape of [2mpr[0m and [2mchecks[0m rather than as a [2mchecks.status[0m stThe two remaining review states have no indicator of their own: [2m"draft"[0m onlydims the cell and [2m"approved"[0m leaves the color unchanged.-Color precedence resolves the fold: changes-requested (magenta) outranks running- checks — waiting can't clear it — while an outstanding required review (cyan)-only recolors an otherwise green or quiet branch. Cool colors mean waiting, warm- colors mean act. An approved PR, or one with no review signal at all (no-required reviewers and no reviews), keeps its plain pipeline color — [2mpr.review[0m-is then [2m"approved"[0m or absent, respectively. GitLab MR data carries only-[2m"pending"[0m and [2m"draft"[0m — no approved or changes-requested signal.+Changes requested (magenta) outranks running checks, while a required review+(cyan) only recolors an otherwise green or gray branch. GitLab reports only the+[2m"pending"[0m and [2m"draft"[0m review states.CI cells are clickable links to the PR or pipeline page, and appear dimmed for adraft PR/MR ([2m"draft"[0m) or when unpushed local changes make the status stale-([2mchecks.stale[0m). PRs/MRs are checked first, then branch workflows/pipelines for-branches with an upstream. Local-only branches show blank; remote-only branches-— visible with [2m--remotes[0m — get CI status detection. Results are cached for 30-60- seconds; use [2mwt config state cache[0m to view or clear.+([2mchecks.stale[0m). Results are cached for 30-60 seconds; use [2mwt config state cache[0m+to view or clear.[32mLLM summaries[0m@@ -262,9 +246,7 @@ you set yourself, or the git-native [2mdescription[0m) — useful for tracking[107m [0m [2m[36m[list.custom-columns.Ticket][0m[107m [0m [2mtemplate = [0m[2m[32m"{{ vars.ticket }}"[0m-A custom column that renders empty for every row is dropped from the table-outright, rather than merely ranked last as an empty built-in is. Templates,-widths, and drop priority: custom columns config.+The custom columns config covers templates, widths, and drop priority.[1m[32mStatus symbols[0m@@ -294,27 +276,20 @@ symbol in the column.An in-progress git operation, a worktree-location attribute, or a branch with noworktree. One symbol shows, highest priority first ([2m✘ > ↻ > ⊟ > ⊞ > ⊘ > ⚑ > /[0m):- Symb JSON Meaning- ol- ──── ───────────────────────── ───────────────────────────────────────────────- [31m✘[0m [2mworktree.changes.conflict[0m Merge conflicts- [2med[0m- [33m↻[0m [2mworktree.operation[0m A git operation is in progress; [2mgit status[0m- [2m"rebase"[0m, [2m"merge"[0m, names it- [2m"cherry_pick"[0m, [2m"revert"[0m,- [2m"bisect"[0m- [33m⊟[0m [2mworktree.prunable[0m Prunable (worktree directory missing); nothing- can be read from a directory that isn't there,- so the row's data cells stay blank- [33m⊞[0m [2mworktree.locked[0m Locked worktree- [2m⊘[0m [2mworktree.detached[0m Detached HEAD — the worktree is on a commit,- not a branch, which is why its Branch cell- holds a short hash- [2m[33m⚑[0m [2mworktree.duplicate_branch[0m Branch checked out in more than one worktree,- so [2mwt[0m resolves it to whichever git lists first;- every worktree on the branch is flagged- [2m[33m⚑[0m [2mworktree.branch_mismatch[0m Worktree isn't at the path its branch implies- [2m/[0m no [2mworktree[0m object Branch without a worktree+ Symbol JSON Meaning+ ────── ───────────────────────── ─────────────────────────────────────────────+ [31m✘[0m [2mworktree.changes.conflict[0m Merge conflicts+ [2med[0m+ [33m↻[0m [2mworktree.operation[0m A git operation is in progress; [2mgit status[0m+ [2m"rebase"[0m, [2m"merge"[0m, names it+ [2m"cherry_pick"[0m, [2m"revert"[0m,+ [2m"bisect"[0m+ [33m⊟[0m [2mworktree.prunable[0m Prunable (worktree directory missing)+ [33m⊞[0m [2mworktree.locked[0m Locked worktree+ [2m⊘[0m [2mworktree.detached[0m Detached HEAD+ [2m[33m⚑[0m [2mworktree.duplicate_branch[0m Branch checked out in more than one worktree+ [2m[33m⚑[0m [2mworktree.branch_mismatch[0m Worktree isn't at the path its branch implies+ [2m/[0m no [2mworktree[0m object Branch without a worktree[32mDefault branch[0m@@ -357,13 +332,10 @@ Relation to the tracking branch, derived from the [2mupstream.ahead[0m /[32mMarker[0m-The last subcolumn carries the branch's own marker — whatever-[2mwt config state marker set[0m stored, usually-an emoji, which is why the subcolumn is two cells wide. Nothing in [2mwt[0m writes-it; it is there for agents and scripts to say what a branch is for, and it-reads back as the item's [2mmarker[0m field. [2mwt config state marker set 🤖[0m on a-branch whose default-branch state is [2m_[0m renders [2m_ 🤖[0m in the column and-[2m"_🤖"[0m in [2mdisplay.symbols[0m.+The last subcolumn shows the branch's marker, set with+[2mwt config state marker set[0m — usually an+emoji saying what the branch is for. It reads back as the item's [2mmarker[0m+field.[32mPlaceholder symbols[0m@@ -547,19 +519,16 @@ Independent facts; the table's priority-collapsed symbol is [2mdisplay.state[0[32mpr object[0m- Field Type Description- ─────── ───────── ────────────────────────────────────────────────────────────- [2mnumber[0m integer/n PR/MR number- ull- [2murl[0m string/nu URL to the PR/MR page- ll- [2mreview[0m string Review state (see review states); absent when the forge- reports no review signal- [2mmergeab[0m boolean/n False when the forge reports conflicts, null otherwise — the- [2mle[0m ull fetch records only the conflicted case- [2mrepo[0m object Structured metadata for the repository the PR/MR targets,- the upstream for fork PRs (see repo object); absent when the- URL doesn't parse+ Field Type Description+ ───────── ──────────── ───────────────────────────────────────────────────────+ [2mnumber[0m integer/null PR/MR number+ [2murl[0m string/null URL to the PR/MR page+ [2mreview[0m string Review state (see review states); absent when the forge+ reports no review signal+ [2mmergeable[0m boolean/null False when the forge reports conflicts, null otherwise+ [2mrepo[0m object Structured metadata for the repository the PR/MR+ targets, the upstream for fork PRs (see repo object);+ absent when the URL doesn't parse[32mchecks object[0m@@ -644,10 +613,8 @@ cheapest-first and the first match wins. JSON-only — every reason renders as t[32mreview states[0m[2mpr.review[0m is one of [2m"changes_requested"[0m, [2m"pending"[0m, [2m"draft"[0m, [2m"approved"[0m, absent-when the forge reports no review signal. The CI status section is the single-source: its table maps the colored values, and the notes below it cover [2m"draft"[0m-and [2m"approved"[0m. The vocabulary matches Claude Code's statusline [2mpr.review_state[0m-field.+when the forge reports no review signal. CI status shows how each renders. The+vocabulary matches Claude Code's statusline [2mpr.review_state[0m field.[107m [0m [2m# Current worktree path (for scripts)[0m[107m [0m [2m[0m[2m[34mwt[0m[2m list [0m[2m[36m--format=json[0m[2m [0m[2m[36m|[0m[2m [0m[2m[34mjq[0m[2m [0m[2m[36m-r[0m[2m [0m[2m[32m'.items[] | select(.worktree.current) | [0m@@ -680,8 +647,6 @@ field.A JSON Schema for the envelope is published atworktrunk.dev/schema/list-v2.json.-It describes what [2mwt[0m writes, so a field the absence rule can omit is-optional there rather than required-and-null.[32mSchema 1[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap b/tests/snapshots/integration__integration_tests__help__help_md_merge.snapindex 515eff98d..f6e4337f6 100644--- a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap@@ -172,7 +172,7 @@ $ wt merge --no-commit --no-rebase`wt merge` runs these steps:-1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background; when step 7 removes the worktree they are anchored on, the merge reports them rather than running them. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.+1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.3. **Rebase** — Rebases onto target, skipping when nothing needs replaying ([`wt step rebase`](/step/#wt-step-rebase) gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](/hook/).@@ -183,7 +183,7 @@ $ wt merge --no-commit --no-rebaseUse `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Combining both flags preserves the exact source graph and requires the target to be its ancestor. Useful after preparing commits manually with `wt step commit`. Requires a clean working tree.-`wt merge` targets the *local* default-branch ref and never fetches. When that ref lags its upstream — e.g. a primary checkout's `main` left behind `origin/main` — a branch based on the newer upstream tip is measured, squashed, and rebased against the upstream (so already-upstream commits are never folded into the squash), and the final fast-forward carries the local ref through the already-fetched upstream commits by their real SHAs. `wt step squash` and `wt step rebase` measure the same way. A local target that has *diverged* from its upstream — its own commits and behind — cannot fast-forward, so the merge is refused until the target is reconciled.+`wt merge` merges into the *local* target branch and never fetches.## Local CIdiff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snapindex d4cc8e07f..520eb0062 100644--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap@@ -156,7 +156,7 @@ Preserve the exact clean commit graph and tip:[2mwt merge[0m runs these steps:-1. [1mCommit[0m — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background; when step 7 removes the worktree they are anchored on, the merge reports them rather than running them. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With [2m--no-squash[0m, this is the only commit step.+1. [1mCommit[0m — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With [2m--no-squash[0m, this is the only commit step.2. [1mSquash[0m — Combines all commits since target into one (like GitHub's "Squash and merge"). Use [2m--stage[0m to control what gets staged: [2mall[0m (default), [2mtracked[0m, or [2mnone[0m. Working-tree changes swept into the squash are backed up first to [2mrefs/wt-backup/<branch>[0m. With [2m--no-squash[0m, individual commits are preserved.3. [1mRebase[0m — Rebases onto target, skipping when nothing needs replaying ([2mwt step rebase[0m gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With [2m--no-rebase[0m, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.4. [1mPre-merge hooks[0m — Hooks run after rebase, before merge. Failures abort. See [2mwt hook[0m.@@ -167,8 +167,7 @@ Preserve the exact clean commit graph and tip:Use [2m--no-commit[0m to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless [2m--no-rebase[0m is passed. Combining both flags preserves the exact source graph and requires the target to be its ancestor. Useful after preparing commits manually with [2mwt step commit[0m. Requires a clean working tree.-[2mwt merge[0m targets the *local* default-branch ref and never fetches. When that ref lags its upstream — e.g. a primary checkout's [2mmain[0m left behind [2morigin/main[0m — a branch based on the newer upstream tip is measured, squashed, and rebased against the upstream (so already-upstream commits are never folded into the squash), and the final fast-forward carries the local ref through the already-fetched upstream commits by their real SHAs. [2mwt step squash[0m and [2mwt step rebase[0m measure the same way. A local-target that has *diverged* from its upstream — its own commits and behind — cannot fast-forward, so the merge is refused until the target is reconciled.+[2mwt merge[0m merges into the *local* target branch and never fetches.[1m[32mLocal CI[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snapindex ed6a63514..be271b0a3 100644--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap@@ -131,7 +131,7 @@ Force-delete an unmerged branch:By default, branches are deleted when they would add no changes to the default branch if merged. This works with both unchanged git histories, and squash-merge or rebase workflows where commit history differs but file changes match.-Worktrunk checks six conditions (in order of cost):+Worktrunk checks six conditions:1. [1mSame commit[0m — Branch HEAD equals the default branch. Shows [2m_[0m in [2mwt list[0m.2. [1mAncestor[0m — Branch is in target's history (fast-forward or rebase case). Shows [2m⊂[0m.@@ -146,8 +146,6 @@ The 'same commit' check uses the local default branch; for other checks, 'targetBranches matching these conditions and with empty working trees are dimmed in [2mwt list[0m as safe to delete.-Those six ask whether deleting loses work. A branch checked out in a second worktree (only reachable via [2mgit worktree add --force[0m) fails a different test: deleting the ref would leave that worktree unable to resolve [2mHEAD[0m, which is why [2mgit branch -d[0m refuses the same delete. Such a branch is retained whatever [2m-D[0m asks, and the surviving checkout is named.-[1m[32mForce flags[0mWorktrunk has two force flags for different situations:@@ -165,9 +163,7 @@ Use [2m--no-delete-branch[0m to keep the branch regardless of merge status.[1m[32mBackground removal[0m-Removal runs in the background by default — the command returns immediately. The worktree is renamed into [2m.git/wt/trash/[0m (instant same-filesystem rename), git metadata is pruned, the branch is deleted, and a detached [2mrm -rf[0m finishes cleanup. Cross-filesystem worktrees fall back to [2mgit worktree remove[0m. Logs: [2m.git/wt/logs/{branch}/internal/remove.log[0m. Use [2m--foreground[0m to run in the foreground.--After each [2mwt remove[0m, entries in [2m.git/wt/trash/[0m older than 24 hours are swept by a detached [2mrm -rf[0m — eventual cleanup for directories orphaned when a previous background removal was interrupted (SIGKILL, reboot, disk full).+Removal runs in the background by default — the command returns immediately, and output goes to [2m.git/wt/logs/{branch}/internal/remove.log[0m. Use [2m--foreground[0m to wait for it.[1m[32mReaping processes [experimental][0m@@ -185,7 +181,7 @@ To avoid killing work the user did not mean to kill, two guards keep [2m--reap- [1mInteractive processes are spared.[0m A process holding a controlling terminal — an interactive shell, or a terminal editor such as [2mvim[0m with unsaved buffers — is never reaped. Only detached processes remain candidates.- [1mDiscovery is by working directory only.[0m A process that started in the worktree and later changed directory, or a daemon that reparented to [2minit[0m, no longer reports a directory under the worktree and is not found. To reliably reap those, launch them with [2mwt step tether[0m, which kills the whole process group when the worktree is removed.-Reaping runs before the worktree directory is touched, so it is independent of foreground/background removal and the [2m--force[0m flag. Unix only; on Windows [2m--reap[0m is rejected.+Unix only; on Windows [2m--reap[0m is rejected.[1m[32mJSON output[0m@@ -193,15 +189,15 @@ Reaping runs before the worktree directory is touched, so it is independent of f[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:- Value Meaning- ──────────────────── ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────- [2mdeleted[0m The branch is gone- [2mdeferred[0m Handed to the detached background process, whose result this run never sees. [2m--foreground[0m never reports it- [2mnot_attempted[0m No deletion was tried: a detached worktree, a sibling checkout, or [2m--no-delete-branch[0m- [2mretained_unmerged[0m Declined: the branch was not integrated into the target- [2mretained_checked_out[0m Declined: the final topology read found a live worktree with it checked out- [2mretained_raced[0m Refused by the compare-and-swap — the branch moved between the integration check and the delete. Re-read the ref and retry- [2mretained_failed[0m The delete command itself failed+ Value Meaning+ ──────────────────── ────────────────────────────────────────────────────────────────────────────────────────────────+ [2mdeleted[0m The branch is gone+ [2mdeferred[0m Left to the background removal, whose result this run doesn't see. [2m--foreground[0m never reports it+ [2mnot_attempted[0m No deletion was tried: a detached worktree, a sibling checkout, or [2m--no-delete-branch[0m+ [2mretained_unmerged[0m Declined: the branch was not integrated into the target+ [2mretained_checked_out[0m Declined: another worktree has the branch checked out+ [2mretained_raced[0m Declined: the branch moved during the removal. Retry+ [2mretained_failed[0m The delete command itself failed[1m[32mHooks[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap b/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snapindex adcde47a1..6fdc90db7 100644--- a/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap+++ b/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap@@ -154,18 +154,12 @@ Files are reflinked where the filesystem supports it: APFS (macOS), btrfs and XF[2mcp -R[0m (full copy) 2m 14GB[2mcp -Rc[0m / [2mwt step copy-ignored[0m 20s ~0-On ext4 and NTFS, which have no reflink, every file is copied in full. The same byte count therefore costs nothing on one filesystem and 14GB on the other, so the summary says which happened: [2mCopied 4,812 files · 14.0 GB (reflinked, no extra disk)[0m, against [2m(full copy)[0m where those bytes were written out.+On ext4 and NTFS, which have no reflink, every file is copied in full; the summary says [2m(reflinked, no extra disk)[0m or [2m(full copy)[0m.Reflinks are per file (like [2mcp -Rc[0m), so copy time scales with file count.Use the [2mpost-start[0m hook so the copy runs in the background. Use [2mpre-start[0m instead if subsequent hooks or [2m--execute[0m command need the copied files immediately.-[1m[32mBackground-hook priority (experimental)[0m--When invoked from a background hook pipeline ([2mpost-*[0m hooks), [2mwt step copy-ignored[0m self-lowers its CPU and I/O priority — [2mtaskpolicy -b[0m on macOS, [2mnice -n 19[0m plus [2mionice -c 3[0m on Linux — so it yields to interactive work. Foreground callers ([2mpre-*[0m hooks, direct interactive use) run at normal priority so the user isn't waiting on a throttled copy.--wt signals background-hook context by exporting [2mWORKTRUNK_FOREGROUND=-1[0m into every detached hook pipeline; [2mcopy-ignored[0m inspects that variable on entry. The variable name is experimental and may change.-[1m[32mLanguage-specific notes[0m[32mRust[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_step_promote.snap b/tests/snapshots/integration__integration_tests__help__help_step_promote.snapindex e6e66225e..12f08aa6f 100644--- a/tests/snapshots/integration__integration_tests__help__help_step_promote.snap+++ b/tests/snapshots/integration__integration_tests__help__help_step_promote.snap@@ -116,6 +116,4 @@ Without an argument, promotes the current branch — or restores the default braGitignored files (build artifacts, [2mnode_modules/[0m, [2m.env[0m) are swapped along with the branches so each worktree keeps the artifacts that belong to its branch. Files are discovered using the same mechanism as [2mcopy-ignored[0m and can be filtered with [2m.worktreeinclude[0m.-The swap uses [2mrename()[0m for each entry — fast regardless of entry size, since only filesystem metadata changes. If the worktree is on a different filesystem from [2m.git/[0m, it falls back to reflink copy.------ stderr -----diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex ad5176d19..a92390cf9 100644--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap@@ -152,8 +152,7 @@ Worktrees are addressed by branch name; paths are computed from a configurable tThe [2m--create[0m flag creates a new branch from [2m--base[0m — the default branch unless specified. Without [2m--create[0m, the branch must already exist. Switching to a remote branch (e.g., [2mwt switch feature[0m when only [2morigin/feature[0m exists) creates a local tracking branch.-One rule decides the upstream, whatever [2mbranch.autoSetupMerge[0m is set to: a new branch tracks the remote branch it starts from only when the two share a name. Switching to [2morigin/feature[0m shares it, so that branch tracks. [2m--create[0m need not: [2m--create release --base origin/release[0m tracks [2morigin/release[0m, while [2m--create feature --base origin/release[0m — and the bare [2m--base release[0m that resolves to it — gets no upstream. Git's default would have [2mfeature[0m track [2morigin/release[0m, so under [2mpush.default =-[2mupstream[0m a bare [2mgit push[0m would push the new work to [2mrelease[0m. Publishing such a branch takes [2mgit push --set-upstream origin <branch>[0m, or git's [2mpush.autoSetupRemote = true[0m set once, after which a bare [2mgit push[0m from the new worktree publishes it and configures its tracking.+A new branch tracks the remote branch it starts from only when the two share a name: [2m--create release --base origin/release[0m tracks [2morigin/release[0m, while [2m--create feature --base origin/release[0m gets no upstream. Publish such a branch with [2mgit push --set-upstream origin <branch>[0m, or set git's [2mpush.autoSetupRemote = true[0m once.[1m[32mCreating worktrees[0m@@ -191,7 +190,7 @@ Worktrees are addressed by branch name, and every argument that takes one also a[107m [0m [2m[0m[2m[34mwt[0m[2m switch pr:123 # PR #123's branch[0m[107m [0m [2m[0m[2m[34mwt[0m[2m switch mr:101 # MR !101's branch[0m-Shortcuts also apply to [2m--base[0m. For a fork PR/MR, the head commit is fetched and used as the base SHA without creating a tracking branch.+Shortcuts also apply to [2m--base[0m.[1m[32mInteractive picker[0m@@ -201,29 +200,23 @@ The CI column shows each row's PR/MR CI and review status, the same as [2mwt li[1mKeybindings:[0m- Key Action- ───────────── ──────────────────────────────────────────────────────- [2m↑[0m/[2m↓[0m Navigate worktree list- (type) Filter worktrees- [2mEnter[0m Switch to selected worktree- [2mAlt-c[0m Create new worktree named as entered text- [2mAlt-x[0m Remove selected worktree/branch (never forces)- [2mAlt-y[0m Copy selected branch name to the clipboard- [2mAlt-o[0m Open the selected row's PR/MR URL in the browser- [2mAlt-r[0m Refresh the list (pick up worktrees created elsewhere)- [2mEsc[0m Cancel- [2mAlt-1[0m–[2mAlt-8[0m Jump to a preview tab- [2mTab[0m/[2mShift-Tab[0m Cycle available preview tabs forward/backward- [2mAlt-p[0m Toggle preview panel- [2mCtrl-u[0m/[2mCtrl-d[0m Scroll preview up/down--[2mAlt-o[0m is a no-op on a row with no PR/MR (or whose status hasn't loaded yet).--[2mAlt-x[0m is a no-op on the current worktree (the [2m@[0m row) — removing the worktree in use would have to switch elsewhere first, so switch away and remove it from there.--Each row filters by its branch, path, and — when it has a PR/MR — the PR/MR's number, title, and author, the same fields whether the PR is checked out (a worktree row) or listed via [2m--prs[0m. Plain digits go to the filter, so a number can be typed directly and the preview tabs move to [2mAlt[0m.--Typing a gutter sigil filters by row kind: [36m+[0m narrows to linked worktrees and [2m@[0m to the current worktree. The other sigils don't filter cleanly — [2m^[0m and [2m|[0m are skim's prefix-anchor and OR query operators (so [2m^[0m matches every row and [2m|[0m none), and [2m/[0m matches most rows because every worktree path contains it.+ Key Action+ ───────────── ────────────────────────────────────────────────────────────────────────+ [2m↑[0m/[2m↓[0m Navigate worktree list+ (type) Filter worktrees+ [2mEnter[0m Switch to selected worktree+ [2mAlt-c[0m Create new worktree named as entered text+ [2mAlt-x[0m Remove selected worktree/branch (never forces; not the current worktree)+ [2mAlt-y[0m Copy selected branch name to the clipboard+ [2mAlt-o[0m Open the selected row's PR/MR URL in the browser+ [2mAlt-r[0m Refresh the list (pick up worktrees created elsewhere)+ [2mEsc[0m Cancel+ [2mAlt-1[0m–[2mAlt-8[0m Jump to a preview tab+ [2mTab[0m/[2mShift-Tab[0m Cycle available preview tabs forward/backward+ [2mAlt-p[0m Toggle preview panel+ [2mCtrl-u[0m/[2mCtrl-d[0m Scroll preview up/down++The filter matches each row's branch, path, and — when it has a PR/MR — the PR/MR's number, title, and author. Typing [36m+[0m narrows to linked worktrees, and [2m@[0m to the current worktree.[1mPreview tabs:[0m@@ -238,8 +231,6 @@ Typing a gutter sigil filters by row kind: [36m+[0m narrows to linked worktreeThe comparison base is the merge-base with the default branch, or with its upstream when the local default branch lags. The picker opens on [1mdiff[0m for local rows and [1mpr[0m for a PR/MR listed by [2m--prs[0m but not available locally. [2mTab[0m and [2mShift-Tab[0m skip tabs without content; [2mAlt-1[0m through [2mAlt-8[0m open any tab directly. After you choose a tab, that choice stays active while you navigate.-On narrow previews the tab bar compacts to digits — only the active tab keeps its label — so every [2mAlt-N[0m accelerator stays visible.-[1mPager configuration:[0m The preview panel pipes diff output through git's pager. Override in user config:[107m [0m [2m[36m[switch.picker][0m@@ -259,8 +250,7 @@ Both work anywhere a branch is accepted, including [2m--base[0m. The [2m--creIf the PR or MR is on a fork, the local branch uses its branch name directly, so [2mgit push[0m works normally. A pre-existing local branch with that name tracking something else requires renaming first.-The [2m--prs[0m flag adds the repository's open PRs (GitHub) or MRs (GitLab) to the interactive picker — only the ones not already there: a PR whose branch is already shown (as a worktree, or a local or remote branch) isn't listed twice, so [2m--prs[0m only adds the rest and the two pickers differ solely by those extra rows. Each added row resolves to the same [2mpr:[0m/[2mmr:[0m shortcut, so selecting one fetches the ref and switches to its branch. A [2m--prs[0m row has no local worktree, so its [2mpr[0m and [2mcomments[0m preview tabs- load the PR/MR's metadata and comments from the forge in the background. The [2mlog[0m tab uses a local [2mgit log[0m — graph and merge-base dimming included — whenever the head commit is already in the object store (a same-repo PR off a fetched remote), falling back to a flat forge-fetched commit list otherwise.+The [2m--prs[0m flag adds the repository's open PRs (GitHub) or MRs (GitLab) that aren't already in the interactive picker. Selecting one switches to it as [2mpr:<number>[0m / [2mmr:<number>[0m would.Requires [2mgh[0m (GitHub), [2mglab[0m (GitLab), or an equivalent CLI installed and authenticated; see forge platform for Gitea, Azure DevOps, and other supported platforms.