Skip to content

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

Replace parentheticals with prose in after_long_help docs (#1764)

Maximilian Roosacff4cd03b0e
diff --git a/docs/content/config.md b/docs/content/config.md
index 66ad5ba84..dafabcede 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -427,7 +427,7 @@ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge
| Variable | Purpose |
|----------|---------|
-| `WORKTRUNK_BIN` | Override binary path for shell wrappers (useful for testing dev builds) |
+| `WORKTRUNK_BIN` | Override binary path for shell wrappers; useful for testing dev builds |
| `WORKTRUNK_CONFIG_PATH` | Override user config file location |
| `WORKTRUNK_SYSTEM_CONFIG_PATH` | Override system config file location |
| `XDG_CONFIG_DIRS` | Colon-separated system config directories (default: `/etc/xdg`) |
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 146338d2a..417ddb84f 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -15,7 +15,7 @@ Hooks are shell commands that run at key points in the worktree lifecycle — au
# Hook Types
-| Event | `pre-` (blocking) | `post-` (background) |
+| Event | `pre-` — blocking | `post-` — background |
|-------|-------------------|---------------------|
| **switch** | `pre-switch` | `post-switch` |
| **start** | `pre-start` | `post-start` |
@@ -127,7 +127,7 @@ kill-server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/d
remove-db = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
```
-During `wt merge`, hooks run in this order: pre-commit → post-commit (background) → pre-merge → pre-remove → post-remove + post-merge (background). See [`wt merge`](@/merge.md#pipeline) for the complete pipeline.
+During `wt merge`, hooks run in this order: pre-commit → post-commit → pre-merge → pre-remove → post-remove + post-merge. As usual, post-* hooks run in the background. See [`wt merge`](@/merge.md#pipeline) for the complete pipeline.
# Security
@@ -144,7 +144,7 @@ Project commands require approval on first run:
- Approvals are saved to user config (`~/.config/worktrunk/config.toml`)
- If a command changes, new approval is required
-- Use `--yes` to bypass prompts (useful for CI/automation)
+- Use `--yes` to bypass prompts — useful for CI and automation
- Use `--no-verify` to skip hooks
Manage approvals with `wt hook approvals add` and `wt hook approvals clear`.
@@ -210,7 +210,7 @@ Bare variables (`branch`, `worktree_path`, `commit`) refer to the branch the ope
| merge | feature being merged | = bare vars | merge target |
| remove | branch being removed | = bare vars | where you end up |
-Pre and post hooks share the same perspective — `{{ branch | hash_port }}` produces the same port in `post-start` and `post-remove`. `cwd` is the worktree root where the hook command runs. It differs from `worktree_path` in three cases: pre-switch (hook runs in the source, `worktree_path` is the destination), post-remove (active worktree is gone, hook runs in primary), and post-merge with removal (same — active is gone, hook runs in target).
+Pre and post hooks share the same perspective — `{{ branch | hash_port }}` produces the same port in `post-start` and `post-remove`. `cwd` is the worktree root where the hook command runs. It differs from `worktree_path` in three cases: pre-switch, where the hook runs in the source but `worktree_path` is the destination; post-remove, where the active worktree is gone so the hook runs in primary; and post-merge with removal, same — the active worktree is gone, so the hook runs in target.
Some variables are conditional: `upstream` requires remote tracking; `base`/`target` are only in two-worktree hooks. Undefined variables error — use conditionals:
@@ -239,7 +239,7 @@ Templates support Jinja2 filters for transforming values:
| `sanitize_db` | `{{ branch \| sanitize_db }}` | Database-safe identifier with hash suffix (`[a-z0-9_]`, max 63 chars) |
| `hash_port` | `{{ branch \| hash_port }}` | Hash to port 10000-19999 |
-The `sanitize` filter makes branch names safe for filesystem paths. The `sanitize_db` filter produces database-safe identifiers (lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words). The `hash_port` filter is useful for running dev servers on unique ports per worktree:
+The `sanitize` filter makes branch names safe for filesystem paths. The `sanitize_db` filter produces database-safe identifiers — lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words. The `hash_port` filter is useful for running dev servers on unique ports per worktree:
```toml
[post-start]
@@ -490,7 +490,7 @@ fi
## Python virtual environments
-Use `uv sync` to recreate virtual environments (or `python -m venv .venv && .venv/bin/pip install -r requirements.txt` for pip-based projects):
+Use `uv sync` to recreate virtual environments, or `python -m venv .venv && .venv/bin/pip install -r requirements.txt` for pip-based projects:
```toml
[pre-start]
diff --git a/docs/content/list.md b/docs/content/list.md
index 2e59fc6de..46c6962c8 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -89,17 +89,17 @@ $ wt list --format=json
| Status | Compact symbols (see below) |
| HEAD± | Uncommitted changes: +added -deleted lines |
| main↕ | Commits ahead/behind default branch |
-| main…± | Line diffs since the merge-base with the default branch (`--full`) |
-| Summary | LLM-generated branch summary (`--full` + `summary = true`, requires [`commit.generation`](@/config.md#commit)) <span class="badge-experimental"></span> |
+| main…± | Line diffs since the merge-base with the default branch; `--full` only |
+| Summary | LLM-generated branch summary; requires `--full`, `summary = true`, and [`commit.generation`](@/config.md#commit) <span class="badge-experimental"></span> |
| Remote⇅ | Commits ahead/behind tracking branch |
-| CI | Pipeline status (`--full`) |
+| CI | Pipeline status; `--full` only |
| Path | Worktree directory |
-| URL | Dev server URL from project config (dimmed if port not listening) |
+| URL | Dev server URL from project config; dimmed if port is not listening |
| Commit | Short hash (8 chars) |
| Age | Time since last commit |
| Message | Last commit message (truncated) |
-Note: `main↕` and `main…±` refer to the default branch (header label stays `main` for compactness). `main…±` uses a merge-base (three-dot) diff.
+Note: `main↕` and `main…±` refer to the default branch — the header label stays `main` for compactness. `main…±` uses a merge-base (three-dot) diff.
### CI status
@@ -115,7 +115,7 @@ The CI column shows GitHub/GitLab pipeline status:
| <span style='color:#a60'>⚠</span> yellow | Fetch error (rate limit, network) |
| (blank) | No upstream or no PR/MR |
-CI indicators are clickable links to the PR or pipeline page. Any CI dot appears dimmed when there are unpushed local changes (stale status). 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` to view or clear.
+CI indicators are clickable links to the PR or pipeline page. Any CI dot appears dimmed when unpushed local changes make the status 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` to view or clear.
### LLM summaries
@@ -141,7 +141,7 @@ The Status column has multiple subcolumns. Within each, only the first matching
| | `⊞` | Locked worktree |
| Default branch | `^` | Is the default branch |
| | `∅` | Orphan branch (no common ancestor with the default branch) |
-| | `✗` | Would conflict if merged to the default branch (with `--full`, includes uncommitted changes) |
+| | `✗` | Would conflict if merged to the default branch; with `--full`, includes uncommitted changes |
| | `_` | Same commit as the default branch, clean |
| | `–` | Same commit as the default branch, uncommitted changes |
| | `⊂` | Content [integrated](@/remove.md#branch-cleanup) into the default branch or target |
@@ -207,17 +207,17 @@ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
| `working_tree` | object | Working tree state (see below) |
| `main_state` | string | Relation to the default branch (see below) |
| `integration_reason` | string | Why branch is integrated (see below) |
-| `operation_state` | string | `"conflicts"`, `"rebase"`, or `"merge"` (absent when clean) |
-| `main` | object | Relationship to the default branch (see below, absent when is_main) |
-| `remote` | object | Tracking branch info (see below, absent when no tracking) |
+| `operation_state` | string | `"conflicts"`, `"rebase"`, or `"merge"`; absent when clean |
+| `main` | object | Relationship to the default branch (see below); absent when is_main |
+| `remote` | object | Tracking branch info (see below); absent when no tracking |
| `worktree` | object | Worktree metadata (see below) |
| `is_main` | boolean | Is the main worktree |
| `is_current` | boolean | Is the current worktree |
| `is_previous` | boolean | Previous worktree from wt switch |
-| `ci` | object | CI status (see below, absent when no CI) |
-| `url` | string | Dev server URL from project config (absent when not configured) |
-| `url_active` | boolean | Whether the URL's port is listening (absent when not configured) |
-| `summary` | string | LLM-generated branch summary (absent when not configured or no summary) |
+| `ci` | object | CI status (see below); absent when no CI |
+| `url` | string | Dev server URL from project config; absent when not configured |
+| `url_active` | boolean | Whether the URL's port is listening; absent when not configured |
+| `summary` | string | LLM-generated branch summary; absent when not configured or no summary |
| `statusline` | string | Pre-formatted status with ANSI colors |
| `symbols` | string | Raw status symbols without colors (e.g., `"!?↓"`) |
diff --git a/docs/content/merge.md b/docs/content/merge.md
index a21f8f590..cb5b956e4 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -11,7 +11,7 @@ group = "Commands"
Merge current branch into target. Squash & rebase, fast-forward target, remove the worktree.
-Unlike `git merge`, this merges current into target (not target into current). Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
+Unlike `git merge`, this merges current into target — not target into current. Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
<figure class="demo">
<picture>
@@ -46,7 +46,7 @@ Preserve commit history (no squash):
wt merge --no-squash
```
-Create a merge commit (semi-linear history):
+Create a merge commit — semi-linear history:
```bash
wt merge --no-ff
@@ -62,11 +62,11 @@ wt merge --no-commit
`wt merge` runs these steps:
-1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. With `--no-squash`, this is the only commit step; with squash (default), this is skipped and changes are staged during squash instead.
+1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. With `--no-squash`, this is the only commit step; with squash — the default — this is skipped and changes are staged during squash instead.
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`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.
3. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](@/hook.md).
-5. **Merge** — Fast-forward merge to the target branch. With `--no-ff`, a merge commit is created instead (semi-linear history: rebased commits plus a merge commit). Non-fast-forward merges are rejected.
+5. **Merge** — Fast-forward merge to the target branch. With `--no-ff`, a merge commit is created instead — semi-linear history with rebased commits plus a merge commit. Non-fast-forward merges are rejected.
6. **Pre-remove hooks** — Hooks run before removing worktree. Failures abort.
7. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the primary worktree, the worktree is preserved.
8. **Post-remove + post-merge hooks** — Run in background after cleanup.
diff --git a/docs/content/remove.md b/docs/content/remove.md
index a2807579e..94aaeed0a 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -73,7 +73,7 @@ Without `--force`, removal fails if the worktree contains untracked files. Witho
## Background removal
-Removal runs in the background by default (returns immediately). Logs are written to `.git/wt/logs/{branch}-remove.log`. Use `--foreground` to run in the foreground.
+Removal runs in the background by default — the command returns immediately. Logs are written to `.git/wt/logs/{branch}-remove.log`. Use `--foreground` to run in the foreground.
## Hooks
diff --git a/docs/content/step.md b/docs/content/step.md
index 697b43562..c7eeb037f 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -871,7 +871,7 @@ wt step deploy --var env=staging # pass extra template variables
wt step deploy --yes # skip approval prompt
```
-When defined in both user and project config, both run (user first, then project). Project-config aliases require [command approval](@/hook.md#security) on first run (same as project hooks). User-config aliases are trusted.
+When defined in both user and project config, both run — user first, then project. Project-config aliases require [command approval](@/hook.md#security) on first run, same as project hooks. User-config aliases are trusted.
Alias names that match a built-in step command (`commit`, `squash`, etc.) are shadowed by the built-in and will never run.
diff --git a/docs/content/switch.md b/docs/content/switch.md
index 6f148b87f..18cb6b5c5 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -32,7 +32,7 @@ wt switch pr:123 # Switch to PR #123's branch
## Creating a branch
-The `--create` flag creates a new branch from the `--base` branch (defaults to default branch). 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.
+The `--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.
## Creating worktrees
@@ -95,13 +95,13 @@ When called without arguments, `wt switch` opens an interactive picker to browse
| `Alt-p` | Toggle preview panel |
| `Ctrl-u`/`Ctrl-d` | Scroll preview up/down |
-**Preview tabs** (toggle with number keys):
+**Preview tabs** — toggle with number keys:
1. **HEAD±** — Diff of uncommitted changes
2. **log** — Recent commits; commits already on the default branch have dimmed hashes
3. **main…±** — Diff of changes since the merge-base with the default branch
-4. **remote⇅** — Diff vs upstream tracking branch (ahead/behind)
-5. **summary** — LLM-generated branch summary (requires `[list] summary = true` and `[commit.generation]`)
+4. **remote⇅** — Ahead/behind diff vs upstream tracking branch
+5. **summary** — LLM-generated branch summary; requires `[list] summary = true` and `[commit.generation]`
**Pager configuration:** The preview panel pipes diff output through git's pager. Override in user config:
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index 6847149e9..91d98476e 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -418,7 +418,7 @@ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge
| Variable | Purpose |
|----------|---------|
-| `WORKTRUNK_BIN` | Override binary path for shell wrappers (useful for testing dev builds) |
+| `WORKTRUNK_BIN` | Override binary path for shell wrappers; useful for testing dev builds |
| `WORKTRUNK_CONFIG_PATH` | Override user config file location |
| `WORKTRUNK_SYSTEM_CONFIG_PATH` | Override system config file location |
| `XDG_CONFIG_DIRS` | Colon-separated system config directories (default: `/etc/xdg`) |
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index 8f7084c32..e06e38dd1 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -6,7 +6,7 @@ Hooks are shell commands that run at key points in the worktree lifecycle — au
# Hook Types
-| Event | `pre-` (blocking) | `post-` (background) |
+| Event | `pre-` — blocking | `post-` — background |
|-------|-------------------|---------------------|
| **switch** | `pre-switch` | `post-switch` |
| **start** | `pre-start` | `post-start` |
@@ -118,7 +118,7 @@ kill-server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/d
remove-db = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
```
-During `wt merge`, hooks run in this order: pre-commit → post-commit (background) → pre-merge → pre-remove → post-remove + post-merge (background). See [`wt merge`](https://worktrunk.dev/merge/#pipeline) for the complete pipeline.
+During `wt merge`, hooks run in this order: pre-commit → post-commit → pre-merge → pre-remove → post-remove + post-merge. As usual, post-* hooks run in the background. See [`wt merge`](https://worktrunk.dev/merge/#pipeline) for the complete pipeline.
# Security
@@ -135,7 +135,7 @@ Project commands require approval on first run:
- Approvals are saved to user config (`~/.config/worktrunk/config.toml`)
- If a command changes, new approval is required
-- Use `--yes` to bypass prompts (useful for CI/automation)
+- Use `--yes` to bypass prompts — useful for CI and automation
- Use `--no-verify` to skip hooks
Manage approvals with `wt hook approvals add` and `wt hook approvals clear`.
@@ -201,7 +201,7 @@ Bare variables (`branch`, `worktree_path`, `commit`) refer to the branch the ope
| merge | feature being merged | = bare vars | merge target |
| remove | branch being removed | = bare vars | where you end up |
-Pre and post hooks share the same perspective — `{{ branch | hash_port }}` produces the same port in `post-start` and `post-remove`. `cwd` is the worktree root where the hook command runs. It differs from `worktree_path` in three cases: pre-switch (hook runs in the source, `worktree_path` is the destination), post-remove (active worktree is gone, hook runs in primary), and post-merge with removal (same — active is gone, hook runs in target).
+Pre and post hooks share the same perspective — `{{ branch | hash_port }}` produces the same port in `post-start` and `post-remove`. `cwd` is the worktree root where the hook command runs. It differs from `worktree_path` in three cases: pre-switch, where the hook runs in the source but `worktree_path` is the destination; post-remove, where the active worktree is gone so the hook runs in primary; and post-merge with removal, same — the active worktree is gone, so the hook runs in target.
Some variables are conditional: `upstream` requires remote tracking; `base`/`target` are only in two-worktree hooks. Undefined variables error — use conditionals:
@@ -230,7 +230,7 @@ Templates support Jinja2 filters for transforming values:
| `sanitize_db` | `{{ branch \| sanitize_db }}` | Database-safe identifier with hash suffix (`[a-z0-9_]`, max 63 chars) |
| `hash_port` | `{{ branch \| hash_port }}` | Hash to port 10000-19999 |
-The `sanitize` filter makes branch names safe for filesystem paths. The `sanitize_db` filter produces database-safe identifiers (lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words). The `hash_port` filter is useful for running dev servers on unique ports per worktree:
+The `sanitize` filter makes branch names safe for filesystem paths. The `sanitize_db` filter produces database-safe identifiers — lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words. The `hash_port` filter is useful for running dev servers on unique ports per worktree:
```toml
[post-start]
@@ -481,7 +481,7 @@ fi
## Python virtual environments
-Use `uv sync` to recreate virtual environments (or `python -m venv .venv && .venv/bin/pip install -r requirements.txt` for pip-based projects):
+Use `uv sync` to recreate virtual environments, or `python -m venv .venv && .venv/bin/pip install -r requirements.txt` for pip-based projects:
```toml
[pre-start]
diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.md
index 18a55c866..b6cb6121a 100644
--- a/skills/worktrunk/reference/list.md
+++ b/skills/worktrunk/reference/list.md
@@ -61,17 +61,17 @@ $ wt list --format=json
| Status | Compact symbols (see below) |
| HEAD± | Uncommitted changes: +added -deleted lines |
| main↕ | Commits ahead/behind default branch |
-| main…± | Line diffs since the merge-base with the default branch (`--full`) |
-| Summary | LLM-generated branch summary (`--full` + `summary = true`, requires [`commit.generation`](https://worktrunk.dev/config/#commit)) [experimental] |
+| main…± | Line diffs since the merge-base with the default branch; `--full` only |
+| Summary | LLM-generated branch summary; requires `--full`, `summary = true`, and [`commit.generation`](https://worktrunk.dev/config/#commit) [experimental] |
| Remote⇅ | Commits ahead/behind tracking branch |
-| CI | Pipeline status (`--full`) |
+| CI | Pipeline status; `--full` only |
| Path | Worktree directory |
-| URL | Dev server URL from project config (dimmed if port not listening) |
+| URL | Dev server URL from project config; dimmed if port is not listening |
| Commit | Short hash (8 chars) |
| Age | Time since last commit |
| Message | Last commit message (truncated) |
-Note: `main↕` and `main…±` refer to the default branch (header label stays `main` for compactness). `main…±` uses a merge-base (three-dot) diff.
+Note: `main↕` and `main…±` refer to the default branch — the header label stays `main` for compactness. `main…±` uses a merge-base (three-dot) diff.
### CI status
@@ -87,7 +87,7 @@ The CI column shows GitHub/GitLab pipeline status:
| <span style='color:#a60'>⚠</span> yellow | Fetch error (rate limit, network) |
| (blank) | No upstream or no PR/MR |
-CI indicators are clickable links to the PR or pipeline page. Any CI dot appears dimmed when there are unpushed local changes (stale status). 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` to view or clear.
+CI indicators are clickable links to the PR or pipeline page. Any CI dot appears dimmed when unpushed local changes make the status 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` to view or clear.
### LLM summaries
@@ -113,7 +113,7 @@ The Status column has multiple subcolumns. Within each, only the first matching
| | `⊞` | Locked worktree |
| Default branch | `^` | Is the default branch |
| | `∅` | Orphan branch (no common ancestor with the default branch) |
-| | `✗` | Would conflict if merged to the default branch (with `--full`, includes uncommitted changes) |
+| | `✗` | Would conflict if merged to the default branch; with `--full`, includes uncommitted changes |
| | `_` | Same commit as the default branch, clean |
| | `–` | Same commit as the default branch, uncommitted changes |
| | `⊂` | Content [integrated](https://worktrunk.dev/remove/#branch-cleanup) into the default branch or target |
@@ -179,17 +179,17 @@ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
| `working_tree` | object | Working tree state (see below) |
| `main_state` | string | Relation to the default branch (see below) |
| `integration_reason` | string | Why branch is integrated (see below) |
-| `operation_state` | string | `"conflicts"`, `"rebase"`, or `"merge"` (absent when clean) |
-| `main` | object | Relationship to the default branch (see below, absent when is_main) |
-| `remote` | object | Tracking branch info (see below, absent when no tracking) |
+| `operation_state` | string | `"conflicts"`, `"rebase"`, or `"merge"`; absent when clean |
+| `main` | object | Relationship to the default branch (see below); absent when is_main |
+| `remote` | object | Tracking branch info (see below); absent when no tracking |
| `worktree` | object | Worktree metadata (see below) |
| `is_main` | boolean | Is the main worktree |
| `is_current` | boolean | Is the current worktree |
| `is_previous` | boolean | Previous worktree from wt switch |
-| `ci` | object | CI status (see below, absent when no CI) |
-| `url` | string | Dev server URL from project config (absent when not configured) |
-| `url_active` | boolean | Whether the URL's port is listening (absent when not configured) |
-| `summary` | string | LLM-generated branch summary (absent when not configured or no summary) |
+| `ci` | object | CI status (see below); absent when no CI |
+| `url` | string | Dev server URL from project config; absent when not configured |
+| `url_active` | boolean | Whether the URL's port is listening; absent when not configured |
+| `summary` | string | LLM-generated branch summary; absent when not configured or no summary |
| `statusline` | string | Pre-formatted status with ANSI colors |
| `symbols` | string | Raw status symbols without colors (e.g., `"!?↓"`) |
diff --git a/skills/worktrunk/reference/merge.md b/skills/worktrunk/reference/merge.md
index 6e0297e1f..6caa2d589 100644
--- a/skills/worktrunk/reference/merge.md
+++ b/skills/worktrunk/reference/merge.md
@@ -2,7 +2,7 @@
Merge current branch into target. Squash & rebase, fast-forward target, remove the worktree.
-Unlike `git merge`, this merges current into target (not target into current). Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
+Unlike `git merge`, this merges current into target — not target into current. Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
## Examples
@@ -30,7 +30,7 @@ Preserve commit history (no squash):
wt merge --no-squash
```
-Create a merge commit (semi-linear history):
+Create a merge commit — semi-linear history:
```bash
wt merge --no-ff
@@ -46,11 +46,11 @@ wt merge --no-commit
`wt merge` runs these steps:
-1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. With `--no-squash`, this is the only commit step; with squash (default), this is skipped and changes are staged during squash instead.
+1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. With `--no-squash`, this is the only commit step; with squash — the default — this is skipped and changes are staged during squash instead.
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`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.
3. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](https://worktrunk.dev/hook/).
-5. **Merge** — Fast-forward merge to the target branch. With `--no-ff`, a merge commit is created instead (semi-linear history: rebased commits plus a merge commit). Non-fast-forward merges are rejected.
+5. **Merge** — Fast-forward merge to the target branch. With `--no-ff`, a merge commit is created instead — semi-linear history with rebased commits plus a merge commit. Non-fast-forward merges are rejected.
6. **Pre-remove hooks** — Hooks run before removing worktree. Failures abort.
7. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the primary worktree, the worktree is preserved.
8. **Post-remove + post-merge hooks** — Run in background after cleanup.
diff --git a/skills/worktrunk/reference/remove.md b/skills/worktrunk/reference/remove.md
index 688d89156..3ce99b956 100644
--- a/skills/worktrunk/reference/remove.md
+++ b/skills/worktrunk/reference/remove.md
@@ -64,7 +64,7 @@ Without `--force`, removal fails if the worktree contains untracked files. Witho
## Background removal
-Removal runs in the background by default (returns immediately). Logs are written to `.git/wt/logs/{branch}-remove.log`. Use `--foreground` to run in the foreground.
+Removal runs in the background by default — the command returns immediately. Logs are written to `.git/wt/logs/{branch}-remove.log`. Use `--foreground` to run in the foreground.
## Hooks
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 13584580c..85e4873a9 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -837,6 +837,6 @@ wt step deploy --var env=staging # pass extra template variables
wt step deploy --yes # skip approval prompt
```
-When defined in both user and project config, both run (user first, then project). Project-config aliases require [command approval](https://worktrunk.dev/hook/#security) on first run (same as project hooks). User-config aliases are trusted.
+When defined in both user and project config, both run — user first, then project. Project-config aliases require [command approval](https://worktrunk.dev/hook/#security) on first run, same as project hooks. User-config aliases are trusted.
Alias names that match a built-in step command (`commit`, `squash`, etc.) are shadowed by the built-in and will never run.
diff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.md
index 81e559065..55d95a32f 100644
--- a/skills/worktrunk/reference/switch.md
+++ b/skills/worktrunk/reference/switch.md
@@ -16,7 +16,7 @@ wt switch pr:123 # Switch to PR #123's branch
## Creating a branch
-The `--create` flag creates a new branch from the `--base` branch (defaults to default branch). 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.
+The `--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.
## Creating worktrees
@@ -72,13 +72,13 @@ When called without arguments, `wt switch` opens an interactive picker to browse
| `Alt-p` | Toggle preview panel |
| `Ctrl-u`/`Ctrl-d` | Scroll preview up/down |
-**Preview tabs** (toggle with number keys):
+**Preview tabs** — toggle with number keys:
1. **HEAD±** — Diff of uncommitted changes
2. **log** — Recent commits; commits already on the default branch have dimmed hashes
3. **main…±** — Diff of changes since the merge-base with the default branch
-4. **remote⇅** — Diff vs upstream tracking branch (ahead/behind)
-5. **summary** — LLM-generated branch summary (requires `[list] summary = true` and `[commit.generation]`)
+4. **remote⇅** — Ahead/behind diff vs upstream tracking branch
+5. **summary** — LLM-generated branch summary; requires `[list] summary = true` and `[commit.generation]`
**Pager configuration:** The preview panel pipes diff output through git's pager. Override in user config:
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index dc528ef6e..5a8c80786 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -264,7 +264,7 @@ wt switch pr:123 # Switch to PR #123's branch
## Creating a branch
-The `--create` flag creates a new branch from the `--base` branch (defaults to default branch). 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.
+The `--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.
## Creating worktrees
@@ -321,13 +321,13 @@ When called without arguments, `wt switch` opens an interactive picker to browse
| `Alt-p` | Toggle preview panel |
| `Ctrl-u`/`Ctrl-d` | Scroll preview up/down |
-**Preview tabs** (toggle with number keys):
+**Preview tabs** — toggle with number keys:
1. **HEAD±** — Diff of uncommitted changes
2. **log** — Recent commits; commits already on the default branch have dimmed hashes
3. **main…±** — Diff of changes since the merge-base with the default branch
-4. **remote⇅** — Diff vs upstream tracking branch (ahead/behind)
-5. **summary** — LLM-generated branch summary (requires `[list] summary = true` and `[commit.generation]`)
+4. **remote⇅** — Ahead/behind diff vs upstream tracking branch
+5. **summary** — LLM-generated branch summary; requires `[list] summary = true` and `[commit.generation]`
**Pager configuration:** The preview panel pipes diff output through git's pager. Override in user config:
@@ -502,17 +502,17 @@ $ wt list --format=json
| Status | Compact symbols (see below) |
| HEAD± | Uncommitted changes: +added -deleted lines |
| main↕ | Commits ahead/behind default branch |
-| main…± | Line diffs since the merge-base with the default branch (`--full`) |
-| Summary | LLM-generated branch summary (`--full` + `summary = true`, requires [`commit.generation`](@/config.md#commit)) [experimental] |
+| main…± | Line diffs since the merge-base with the default branch; `--full` only |
+| Summary | LLM-generated branch summary; requires `--full`, `summary = true`, and [`commit.generation`](@/config.md#commit) [experimental] |
| Remote⇅ | Commits ahead/behind tracking branch |
-| CI | Pipeline status (`--full`) |
+| CI | Pipeline status; `--full` only |
| Path | Worktree directory |
-| URL | Dev server URL from project config (dimmed if port not listening) |
+| URL | Dev server URL from project config; dimmed if port is not listening |
| Commit | Short hash (8 chars) |
| Age | Time since last commit |
| Message | Last commit message (truncated) |
-Note: `main↕` and `main…±` refer to the default branch (header label stays `main` for compactness). `main…±` uses a merge-base (three-dot) diff.
+Note: `main↕` and `main…±` refer to the default branch — the header label stays `main` for compactness. `main…±` uses a merge-base (three-dot) diff.
### CI status
@@ -528,7 +528,7 @@ The CI column shows GitHub/GitLab pipeline status:
| `⚠` yellow | Fetch error (rate limit, network) |
| (blank) | No upstream or no PR/MR |
-CI indicators are clickable links to the PR or pipeline page. Any CI dot appears dimmed when there are unpushed local changes (stale status). 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` to view or clear.
+CI indicators are clickable links to the PR or pipeline page. Any CI dot appears dimmed when unpushed local changes make the status 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` to view or clear.
### LLM summaries [experimental]
@@ -552,7 +552,7 @@ The Status column has multiple subcolumns. Within each, only the first matching
| | `⊞` | Locked worktree |
| Default branch | `^` | Is the default branch |
| | `∅` | Orphan branch (no common ancestor with the default branch) |
-| | `✗` | Would conflict if merged to the default branch (with `--full`, includes uncommitted changes) |
+| | `✗` | Would conflict if merged to the default branch; with `--full`, includes uncommitted changes |
| | `_` | Same commit as the default branch, clean |
| | `–` | Same commit as the default branch, uncommitted changes |
| | `⊂` | Content [integrated](@/remove.md#branch-cleanup) into the default branch or target |
@@ -618,17 +618,17 @@ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
| `working_tree` | object | Working tree state (see below) |
| `main_state` | string | Relation to the default branch (see below) |
| `integration_reason` | string | Why branch is integrated (see below) |
-| `operation_state` | string | `"conflicts"`, `"rebase"`, or `"merge"` (absent when clean) |
-| `main` | object | Relationship to the default branch (see below, absent when is_main) |
-| `remote` | object | Tracking branch info (see below, absent when no tracking) |
+| `operation_state` | string | `"conflicts"`, `"rebase"`, or `"merge"`; absent when clean |
+| `main` | object | Relationship to the default branch (see below); absent when is_main |
+| `remote` | object | Tracking branch info (see below); absent when no tracking |
| `worktree` | object | Worktree metadata (see below) |
| `is_main` | boolean | Is the main worktree |
| `is_current` | boolean | Is the current worktree |
| `is_previous` | boolean | Previous worktree from wt switch |
-| `ci` | object | CI status (see below, absent when no CI) |
-| `url` | string | Dev server URL from project config (absent when not configured) |
-| `url_active` | boolean | Whether the URL's port is listening (absent when not configured) |
-| `summary` | string | LLM-generated branch summary (absent when not configured or no summary) |
+| `ci` | object | CI status (see below); absent when no CI |
+| `url` | string | Dev server URL from project config; absent when not configured |
+| `url_active` | boolean | Whether the URL's port is listening; absent when not configured |
+| `summary` | string | LLM-generated branch summary; absent when not configured or no summary |
| `statusline` | string | Pre-formatted status with ANSI colors |
| `symbols` | string | Raw status symbols without colors (e.g., `"!?↓"`) |
@@ -810,7 +810,7 @@ Without `--force`, removal fails if the worktree contains untracked files. Witho
## Background removal
-Removal runs in the background by default (returns immediately). Logs are written to `.git/wt/logs/{branch}-remove.log`. Use `--foreground` to run in the foreground.
+Removal runs in the background by default — the command returns immediately. Logs are written to `.git/wt/logs/{branch}-remove.log`. Use `--foreground` to run in the foreground.
## Hooks
@@ -862,7 +862,7 @@ Detached worktrees have no branch name. Pass the worktree path instead: `wt remo
///
/// Squash & rebase, fast-forward target, remove the worktree.
#[command(
- after_long_help = r#"Unlike `git merge`, this merges current into target (not target into current). Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
+ after_long_help = r#"Unlike `git merge`, this merges current into target — not target into current. Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
<!-- demo: wt-merge.gif 1600x900 -->
## Examples
@@ -891,7 +891,7 @@ Preserve commit history (no squash):
wt merge --no-squash
```
-Create a merge commit (semi-linear history):
+Create a merge commit — semi-linear history:
```console
wt merge --no-ff
@@ -907,11 +907,11 @@ wt merge --no-commit
`wt merge` runs these steps:
-1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. With `--no-squash`, this is the only commit step; with squash (default), this is skipped and changes are staged during squash instead.
+1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. With `--no-squash`, this is the only commit step; with squash — the default — this is skipped and changes are staged during squash instead.
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`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.
3. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](@/hook.md).
-5. **Merge** — Fast-forward merge to the target branch. With `--no-ff`, a merge commit is created instead (semi-linear history: rebased commits plus a merge commit). Non-fast-forward merges are rejected.
+5. **Merge** — Fast-forward merge to the target branch. With `--no-ff`, a merge commit is created instead — semi-linear history with rebased commits plus a merge commit. Non-fast-forward merges are rejected.
6. **Pre-remove hooks** — Hooks run before removing worktree. Failures abort.
7. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the primary worktree, the worktree is preserved.
8. **Post-remove + post-merge hooks** — Run in background after cleanup.
@@ -1089,7 +1089,7 @@ wt step deploy --var env=staging # pass extra template variables
wt step deploy --yes # skip approval prompt
```
-When defined in both user and project config, both run (user first, then project). Project-config aliases require [command approval](@/hook.md#security) on first run (same as project hooks). User-config aliases are trusted.
+When defined in both user and project config, both run — user first, then project. Project-config aliases require [command approval](@/hook.md#security) on first run, same as project hooks. User-config aliases are trusted.
Alias names that match a built-in step command (`commit`, `squash`, etc.) are shadowed by the built-in and will never run."#
)]
@@ -1105,7 +1105,7 @@ Alias names that match a built-in step command (`commit`, `squash`, etc.) are sh
# Hook Types
-| Event | `pre-` (blocking) | `post-` (background) |
+| Event | `pre-` — blocking | `post-` — background |
|-------|-------------------|---------------------|
| **switch** | `pre-switch` | `post-switch` |
| **start** | `pre-start` | `post-start` |
@@ -1217,7 +1217,7 @@ kill-server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/d
remove-db = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
```
-During `wt merge`, hooks run in this order: pre-commit → post-commit (background) → pre-merge → pre-remove → post-remove + post-merge (background). See [`wt merge`](@/merge.md#pipeline) for the complete pipeline.
+During `wt merge`, hooks run in this order: pre-commit → post-commit → pre-merge → pre-remove → post-remove + post-merge. As usual, post-* hooks run in the background. See [`wt merge`](@/merge.md#pipeline) for the complete pipeline.
# Security
@@ -1234,7 +1234,7 @@ Project commands require approval on first run:
- Approvals are saved to user config (`~/.config/worktrunk/config.toml`)
- If a command changes, new approval is required
-- Use `--yes` to bypass prompts (useful for CI/automation)
+- Use `--yes` to bypass prompts — useful for CI and automation
- Use `--no-verify` to skip hooks
Manage approvals with `wt hook approvals add` and `wt hook approvals clear`.
@@ -1300,7 +1300,7 @@ Bare variables (`branch`, `worktree_path`, `commit`) refer to the branch the ope
| merge | feature being merged | = bare vars | merge target |
| remove | branch being removed | = bare vars | where you end up |
-Pre and post hooks share the same perspective — `{{ branch | hash_port }}` produces the same port in `post-start` and `post-remove`. `cwd` is the worktree root where the hook command runs. It differs from `worktree_path` in three cases: pre-switch (hook runs in the source, `worktree_path` is the destination), post-remove (active worktree is gone, hook runs in primary), and post-merge with removal (same — active is gone, hook runs in target).
+Pre and post hooks share the same perspective — `{{ branch | hash_port }}` produces the same port in `post-start` and `post-remove`. `cwd` is the worktree root where the hook command runs. It differs from `worktree_path` in three cases: pre-switch, where the hook runs in the source but `worktree_path` is the destination; post-remove, where the active worktree is gone so the hook runs in primary; and post-merge with removal, same — the active worktree is gone, so the hook runs in target.
Some variables are conditional: `upstream` requires remote tracking; `base`/`target` are only in two-worktree hooks. Undefined variables error — use conditionals:
@@ -1329,7 +1329,7 @@ Templates support Jinja2 filters for transforming values:
| `sanitize_db` | `{{ branch \| sanitize_db }}` | Database-safe identifier with hash suffix (`[a-z0-9_]`, max 63 chars) |
| `hash_port` | `{{ branch \| hash_port }}` | Hash to port 10000-19999 |
-The `sanitize` filter makes branch names safe for filesystem paths. The `sanitize_db` filter produces database-safe identifiers (lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words). The `hash_port` filter is useful for running dev servers on unique ports per worktree:
+The `sanitize` filter makes branch names safe for filesystem paths. The `sanitize_db` filter produces database-safe identifiers — lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words. The `hash_port` filter is useful for running dev servers on unique ports per worktree:
```toml
[post-start]
@@ -1578,7 +1578,7 @@ fi
## Python virtual environments
-Use `uv sync` to recreate virtual environments (or `python -m venv .venv && .venv/bin/pip install -r requirements.txt` for pip-based projects):
+Use `uv sync` to recreate virtual environments, or `python -m venv .venv && .venv/bin/pip install -r requirements.txt` for pip-based projects:
```toml
[pre-start]
@@ -2020,7 +2020,7 @@ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge
| Variable | Purpose |
|----------|---------|
-| `WORKTRUNK_BIN` | Override binary path for shell wrappers (useful for testing dev builds) |
+| `WORKTRUNK_BIN` | Override binary path for shell wrappers; useful for testing dev builds |
| `WORKTRUNK_CONFIG_PATH` | Override user config file location |
| `WORKTRUNK_SYSTEM_CONFIG_PATH` | Override system config file location |
| `XDG_CONFIG_DIRS` | Colon-separated system config directories (default: `/etc/xdg`) |
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index f249aa84c..1ff842376 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -418,7 +418,7 @@ Override the LLM command in CI to use a mock:
Variable Purpose
───────────────────────────────── ─────────────────────────────────────────────────────────────────────────────────
- WORKTRUNK_BIN Override binary path for shell wrappers (useful for testing dev builds)
+ WORKTRUNK_BIN Override binary path for shell wrappers; useful for testing dev builds
WORKTRUNK_CONFIG_PATH Override user config file location
WORKTRUNK_SYSTEM_CONFIG_PATH Override system config file location
XDG_CONFIG_DIRS Colon-separated system config directories (default: /etc/xdg)
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index e29e17e1e..d0290b64d 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -100,23 +100,23 @@ Output as JSON for scripting:
Columns
- Column Shows
- ─────── ─────────────────────────────────────────────────────────────────────────────────────────────────
- Branch Branch name
- Status Compact symbols (see below)
- HEAD± Uncommitted changes: +added -deleted lines
- main↕ Commits ahead/behind default branch
- main…± Line diffs since the merge-base with the default branch (--full)
- Summary LLM-generated branch summary (--full + summary = true, requires commit.generation) [experimental]
- Remote⇅ Commits ahead/behind tracking branch
- CI Pipeline status (--full)
- Path Worktree directory
- URL Dev server URL from project config (dimmed if port not listening)
- Commit Short hash (8 chars)
- Age Time since last commit
- Message Last commit message (truncated)
-
-Note: main↕ and main…± refer to the default branch (header label stays main for compactness). main…± uses a merge-base (three-dot) diff.
+ Column Shows
+ ─────── ───────────────────────────────────────────────────────────────────────────────────────────────────
+ Branch Branch name
+ Status Compact symbols (see below)
+ HEAD± Uncommitted changes: +added -deleted lines
+ main↕ Commits ahead/behind default branch
+ main…± Line diffs since the merge-base with the default branch; --full only
+ Summary LLM-generated branch summary; requires --full, summary = true, and commit.generation [experimental]
+ Remote⇅ Commits ahead/behind tracking branch
+ CI Pipeline status; --full only
+ Path Worktree directory
+ URL Dev server URL from project config; dimmed if port is not listening
+ Commit Short hash (8 chars)
+ Age Time since last commit
+ Message Last commit message (truncated)
+
+Note: main↕ and main…± refer to the default branch — the header label stays main for compactness. main…± uses a merge-base (three-dot) diff.
CI status
@@ -132,7 +132,7 @@ The CI column shows GitHub/GitLab pipeline status:
⚠ yellow Fetch error (rate limit, network)
(blank) No upstream or no PR/MR
-CI indicators are clickable links to the PR or pipeline page. Any CI dot appears dimmed when there are unpushed local changes (stale status). 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 to view or clear.
+CI indicators are clickable links to the PR or pipeline page. Any CI dot appears dimmed when unpushed local changes make the status 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 to view or clear.
LLM summaries [experimental]
@@ -142,31 +142,31 @@ Reuses the commit.generation command — the same LLM that generates com
The Status column has multiple subcolumns. Within each, only the first matching symbol is shown (listed in priority order):
- Subcolumn Symbol Meaning
- ──────────────── ────── ──────────────────────────────────────────────────────────────────────────────────────────
- Working tree (1) + Staged files
- Working tree (2) ! Modified files (unstaged)
- Working tree (3) ? Untracked files
- Worktree ✘ Merge conflicts
- ⤴ Rebase in progress
- ⤵ Merge in progress
- / Branch without worktree
- ⚑ Branch-worktree mismatch (branch name doesn't match worktree path)
- ⊟ Prunable (directory missing)
- ⊞ Locked worktree
- Default branch ^ Is the default branch
- ∅ Orphan branch (no common ancestor with the default branch)
- ✗ Would conflict if merged to the default branch (with --full, includes uncommitted changes)
- _ Same commit as the default branch, clean
- – Same commit as the default branch, uncommitted changes
- ⊂ Content integrated into the default branch or target
- ↕ Diverged from the default branch
- ↑ Ahead of the default branch
- ↓ Behind the default branch
- Remote | In sync with remote
- ⇅ Diverged from remote
- ⇡ Ahead of remote
- ⇣ Behind remote
+ Subcolumn Symbol Meaning
+ ──────────────── ────── ─────────────────────────────────────────────────────────────────────────────────────────
+ Working tree (1) + Staged files
+ Working tree (2) ! Modified files (unstaged)
+ Working tree (3) ? Untracked files
+ Worktree ✘ Merge conflicts
+ ⤴ Rebase in progress
+ ⤵ Merge in progress
+ / Branch without worktree
+ ⚑ Branch-worktree mismatch (branch name doesn't match worktree path)
+ ⊟ Prunable (directory missing)
+ ⊞ Locked worktree
+ Default branch ^ Is the default branch
+ ∅ Orphan branch (no common ancestor with the default branch)
+ ✗ Would conflict if merged to the default branch; with --full, includes uncommitted changes
+ _ Same commit as the default branch, clean
+ – Same commit as the default branch, uncommitted changes
+ ⊂ Content integrated into the default branch or target
+ ↕ Diverged from the default branch
+ ↑ Ahead of the default branch
+ ↓ Behind the default branch
+ Remote | In sync with remote
+ ⇅ Diverged from remote
+ ⇡ Ahead of remote
+ ⇣ Behind remote
Rows are dimmed when safe to delete (_ same commit with clean working tree or ⊂ content integrated).
@@ -211,28 +211,28 @@ Query structured data with --format=json:
Fields:
- Field Type Description
- ────────────────── ─────────── ───────────────────────────────────────────────────────────────────────
- branch string/null Branch name (null for detached HEAD)
- path string Worktree path (absent for branches without worktrees)
- kind string "worktree" or "branch"
- commit object Commit info (see below)
- working_tree object Working tree state (see below)
- main_state string Relation to the default branch (see below)
- integration_reason string Why branch is integrated (see below)
- operation_state string "conflicts", "rebase", or "merge" (absent when clean)
- main object Relationship to the default branch (see below, absent when is_main)
- remote object Tracking branch info (see below, absent when no tracking)
- worktree object Worktree metadata (see below)
- is_main boolean Is the main worktree
- is_current boolean Is the current worktree
- is_previous boolean Previous worktree from wt switch
- ci object CI status (see below, absent when no CI)
- url string Dev server URL from project config (absent when not configured)
- url_active boolean Whether the URL's port is listening (absent when not configured)
- summary string LLM-generated branch summary (absent when not configured or no summary)
- statusline string Pre-formatted status with ANSI colors
- symbols string Raw status symbols without colors (e.g., "!?↓")
+ Field Type Description
+ ────────────────── ─────────── ──────────────────────────────────────────────────────────────────────
+ branch string/null Branch name (null for detached HEAD)
+ path string Worktree path (absent for branches without worktrees)
+ kind string "worktree" or "branch"
+ commit object Commit info (see below)
+ working_tree object Working tree state (see below)
+ main_state string Relation to the default branch (see below)
+ integration_reason string Why branch is integrated (see below)
+ operation_state string "conflicts", "rebase", or "merge"; absent when clean
+ main object Relationship to the default branch (see below); absent when is_main
+ remote object Tracking branch info (see below); absent when no tracking
+ worktree object Worktree metadata (see below)
+ is_main boolean Is the main worktree
+ is_current boolean Is the current worktree
+ is_previous boolean Previous worktree from wt switch
+ ci object CI status (see below); absent when no CI
+ url string Dev server URL from project config; absent when not configured
+ url_active boolean Whether the URL's port is listening; absent when not configured
+ summary string LLM-generated branch summary; absent when not configured or no summary
+ statusline string Pre-formatted status with ANSI colors
+ symbols string Raw status symbols without colors (e.g., "!?↓")
Commit object
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
index 4b3a44219..d7fb82e84 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
@@ -114,19 +114,19 @@ Output as JSON for scripting:
Status Compact symbols (see below)
HEAD± Uncommitted changes: +added -deleted lines
main↕ Commits ahead/behind default branch
- main…± Line diffs since the merge-base with the default branch (--full)
- Summary LLM-generated branch summary (--full + summary = true, requires
- commit.generation) [experimental]
+ main…± Line diffs since the merge-base with the default branch; --full only
+ Summary LLM-generated branch summary; requires --full, summary = true, and
+ commit.generation [experimental]
Remote⇅ Commits ahead/behind tracking branch
- CI Pipeline status (--full)
+ CI Pipeline status; --full only
Path Worktree directory
- URL Dev server URL from project config (dimmed if port not listening)
+ URL Dev server URL from project config; dimmed if port is not listening
Commit Short hash (8 chars)
Age Time since last commit
Message Last commit message (truncated)
-Note: main↕ and main…± refer to the default branch (header label stays main for
-compactness). main…± uses a merge-base (three-dot) diff.
+Note: main↕ and main…± refer to the default branch — the header label stays main
+ for compactness. main…± uses a merge-base (three-dot) diff.
CI status
@@ -143,11 +143,11 @@ The CI column shows GitHub/GitLab pipeline status:
(blank) No upstream or no PR/MR
CI indicators are clickable links to the PR or pipeline page. Any CI dot appears
- dimmed when there are unpushed local changes (stale status). 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 to view or clear.
+ dimmed when unpushed local changes make the status 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 to
+view or clear.
LLM summaries [experimental]
@@ -176,8 +176,8 @@ symbol is shown (listed in priority order):
Default branch ^ Is the default branch
∅ Orphan branch (no common ancestor with the default
branch)
- ✗ Would conflict if merged to the default branch (with
- --full, includes uncommitted changes)
+ ✗ Would conflict if merged to the default branch; with
+ --full, includes uncommitted changes
_ Same commit as the default branch, clean
– Same commit as the default branch, uncommitted changes
⊂ Content integrated into the default branch or target
@@ -246,23 +246,23 @@ Query structured data with --format=json:
working_tree object Working tree state (see below)
main_state string Relation to the default branch (see below)
integration_reason string Why branch is integrated (see below)
- operation_state string "conflicts", "rebase", or "merge" (absent when
- clean)
- main object Relationship to the default branch (see below,
- absent when is_main)
- remote object Tracking branch info (see below, absent when no
- tracking)
+ operation_state string "conflicts", "rebase", or "merge"; absent when
+ clean
+ main object Relationship to the default branch (see below);
+ absent when is_main
+ remote object Tracking branch info (see below); absent when
+ no tracking
worktree object Worktree metadata (see below)
is_main boolean Is the main worktree
is_current boolean Is the current worktree
is_previous boolean Previous worktree from wt switch
- ci object CI status (see below, absent when no CI)
- url string Dev server URL from project config (absent when
- not configured)
- url_active boolean Whether the URL's port is listening (absent
- when not configured)
- summary string LLM-generated branch summary (absent when not
- configured or no summary)
+ ci object CI status (see below); absent when no CI
+ url string Dev server URL from project config; absent when
+ not configured
+ url_active boolean Whether the URL's port is listening; absent
+ when not configured
+ summary string LLM-generated branch summary; absent when not
+ configured or no summary
statusline string Pre-formatted status with ANSI colors
symbols string Raw status symbols without colors (e.g., "!?↓")
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 57b3d341f..32388cece 100644
--- a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
@@ -85,7 +85,7 @@ Global Options:
-v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
-Unlike `git merge`, this merges current into target (not target into current). Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
+Unlike `git merge`, this merges current into target — not target into current. Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
<!-- demo: wt-merge.gif 1600x900 -->
## Examples
@@ -114,7 +114,7 @@ Preserve commit history (no squash):
wt merge --no-squash
```
-Create a merge commit (semi-linear history):
+Create a merge commit — semi-linear history:
```bash
wt merge --no-ff
@@ -130,11 +130,11 @@ wt merge --no-commit
`wt merge` runs these steps:
-1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. With `--no-squash`, this is the only commit step; with squash (default), this is skipped and changes are staged during squash instead.
+1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. With `--no-squash`, this is the only commit step; with squash — the default — this is skipped and changes are staged during squash instead.
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`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, individual commits are preserved.
3. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](@/hook.md).
-5. **Merge** — Fast-forward merge to the target branch. With `--no-ff`, a merge commit is created instead (semi-linear history: rebased commits plus a merge commit). Non-fast-forward merges are rejected.
+5. **Merge** — Fast-forward merge to the target branch. With `--no-ff`, a merge commit is created instead — semi-linear history with rebased commits plus a merge commit. Non-fast-forward merges are rejected.
6. **Pre-remove hooks** — Hooks run before removing worktree. Failures abort.
7. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the primary worktree, the worktree is preserved.
8. **Post-remove + post-merge hooks** — Run in background after cleanup.
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 56e211893..3ef8c35f1 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -87,7 +87,7 @@ Usage: wt merge [OPTIONS] [TARGET]
-v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
-Unlike git merge, this merges current into target (not target into current). Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
+Unlike git merge, this merges current into target — not target into current. Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
Examples
@@ -107,7 +107,7 @@ Preserve commit history (no squash):
  wt merge --no-squash
-Create a merge commit (semi-linear history):
+Create a merge commit — semi-linear history:
  wt merge --no-ff
@@ -119,11 +119,11 @@ Skip committing/squashing (rebase still runs unless --no-rebase):
wt merge runs these steps:
-1. Commit — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. With --no-squash, this is the only commit step; with squash (default), this is skipped and changes are staged during squash instead.
+1. Commit — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in background. With --no-squash, this is the only commit step; with squash — the default — this is skipped and changes are staged during squash instead.
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. A backup ref is saved to refs/wt-backup/<branch>. With --no-squash, individual commits are preserved.
3. Rebase — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
4. Pre-merge hooks — Hooks run after rebase, before merge. Failures abort. See wt hook.
-5. Merge — Fast-forward merge to the target branch. With --no-ff, a merge commit is created instead (semi-linear history: rebased commits plus a merge commit). Non-fast-forward merges are rejected.
+5. Merge — Fast-forward merge to the target branch. With --no-ff, a merge commit is created instead — semi-linear history with rebased commits plus a merge commit. Non-fast-forward merges are rejected.
6. Pre-remove hooks — Hooks run before removing worktree. Failures abort.
7. Cleanup — Removes the worktree and branch. Use --no-remove to keep the worktree. When already on the target branch or in the primary worktree, the worktree is preserved.
8. Post-remove + post-merge hooks — Run in background after cleanup.
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 59696c7ce..7cb1c8906 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -128,7 +128,7 @@ Without --force, removal fails if the worktree contains untracked files.
Background removal
-Removal runs in the background by default (returns immediately). Logs are written to .git/wt/logs/{branch}-remove.log. Use --foreground to run in the foreground.
+Removal runs in the background by default — the command returns immediately. Logs are written to .git/wt/logs/{branch}-remove.log. Use --foreground to run in the foreground.
Hooks
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
index 278357b22..fc171dd88 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -111,6 +111,6 @@ Custom command templates configured in user config (~/.config/worktrunk/conf
  wt step deploy --var env=staging # pass extra template variables
  wt step deploy --yes # skip approval prompt
-When defined in both user and project config, both run (user first, then project). Project-config aliases require command approval on first run (same as project hooks). User-config aliases are trusted.
+When defined in both user and project config, both run — user first, then project. Project-config aliases require command approval on first run, same as project hooks. User-config aliases are trusted.
Alias names that match a built-in step command (commit, squash, etc.) are shadowed by the built-in and will never run.
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 728fcc09b..c7f70d6e5 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -120,7 +120,7 @@ Worktrees are addressed by branch name; paths are computed from a configurable t
Creating a branch
-The --create flag creates a new branch from the --base branch (defaults to default branch). 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.
+The --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.
Creating worktrees
@@ -172,13 +172,13 @@ When called without arguments, wt switch opens an interactive picker to
Alt-p Toggle preview panel
Ctrl-u/Ctrl-d Scroll preview up/down
-Preview tabs (toggle with number keys):
+Preview tabs — toggle with number keys:
1. HEAD± — Diff of uncommitted changes
2. log — Recent commits; commits already on the default branch have dimmed hashes
3. main…± — Diff of changes since the merge-base with the default branch
-4. remote⇅ — Diff vs upstream tracking branch (ahead/behind)
-5. summary — LLM-generated branch summary (requires [list] summary = true and [commit.generation])
+4. remote⇅ — Ahead/behind diff vs upstream tracking branch
+5. summary — LLM-generated branch summary; requires [list] summary = true and [commit.generation]
Pager configuration: The preview panel pipes diff output through git's pager. Override in user config: