Skip to content

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

docs: release 0.81 documentation review fixes (#4531)

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