Skip to content

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

docs: fix documentation correctness issues (#687)

Maximilian Roos089ded351dfb
diff --git a/.claude-plugin/skills/worktrunk/reference/list.md b/.claude-plugin/skills/worktrunk/reference/list.md
index af6d0ae29..fb3273cfa 100644
--- a/.claude-plugin/skills/worktrunk/reference/list.md
+++ b/.claude-plugin/skills/worktrunk/reference/list.md
@@ -98,6 +98,7 @@ The Status column has multiple subcolumns. Within each, only the first matching
| | `⊟` | 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 |
@@ -209,7 +210,7 @@ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
| Field | Type | Description |
|-------|------|-------------|
-| `state` | string | `"branch_worktree_mismatch"`, `"prunable"`, `"locked"` (absent when normal) |
+| `state` | string | `"no_worktree"`, `"branch_worktree_mismatch"`, `"prunable"`, `"locked"` (absent when normal) |
| `reason` | string | Reason for locked/prunable state |
| `detached` | boolean | HEAD is detached |
@@ -226,7 +227,7 @@ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
These values describe relation to the default branch.
-`"is_main"` `"would_conflict"` `"empty"` `"same_commit"` `"integrated"` `"diverged"` `"ahead"` `"behind"`
+`"is_main"` `"orphan"` `"would_conflict"` `"empty"` `"same_commit"` `"integrated"` `"diverged"` `"ahead"` `"behind"`
### integration_reason values
diff --git a/docs/content/list.md b/docs/content/list.md
index 53540bbef..11aaacdf3 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -131,6 +131,7 @@ The Status column has multiple subcolumns. Within each, only the first matching
| | `⊟` | 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 |
@@ -242,7 +243,7 @@ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
| Field | Type | Description |
|-------|------|-------------|
-| `state` | string | `"branch_worktree_mismatch"`, `"prunable"`, `"locked"` (absent when normal) |
+| `state` | string | `"no_worktree"`, `"branch_worktree_mismatch"`, `"prunable"`, `"locked"` (absent when normal) |
| `reason` | string | Reason for locked/prunable state |
| `detached` | boolean | HEAD is detached |
@@ -259,7 +260,7 @@ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
These values describe relation to the default branch.
-`"is_main"` `"would_conflict"` `"empty"` `"same_commit"` `"integrated"` `"diverged"` `"ahead"` `"behind"`
+`"is_main"` `"orphan"` `"would_conflict"` `"empty"` `"same_commit"` `"integrated"` `"diverged"` `"ahead"` `"behind"`
### integration_reason values
diff --git a/docs/content/select.md b/docs/content/select.md
index b7448f64b..08a078cec 100644
--- a/docs/content/select.md
+++ b/docs/content/select.md
@@ -66,6 +66,8 @@ This is useful when the default pager doesn't render correctly in the embedded p
- [`wt list`](@/list.md) — Static table view with all worktree metadata
- [`wt switch`](@/switch.md) — Direct switching to a known target branch
+Available on Unix only (macOS, Linux). On Windows, use `wt list` or `wt switch` directly.
+
## Command reference
{% terminal() %}
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 852148aa4..c519caed3 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -479,6 +479,7 @@ The Status column has multiple subcolumns. Within each, only the first matching
| | `⊟` | 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 |
@@ -590,7 +591,7 @@ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
| Field | Type | Description |
|-------|------|-------------|
-| `state` | string | `"branch_worktree_mismatch"`, `"prunable"`, `"locked"` (absent when normal) |
+| `state` | string | `"no_worktree"`, `"branch_worktree_mismatch"`, `"prunable"`, `"locked"` (absent when normal) |
| `reason` | string | Reason for locked/prunable state |
| `detached` | boolean | HEAD is detached |
@@ -607,7 +608,7 @@ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
These values describe relation to the default branch.
-`"is_main"` `"would_conflict"` `"empty"` `"same_commit"` `"integrated"` `"diverged"` `"ahead"` `"behind"`
+`"is_main"` `"orphan"` `"would_conflict"` `"empty"` `"same_commit"` `"integrated"` `"diverged"` `"ahead"` `"behind"`
### integration_reason values
@@ -954,6 +955,8 @@ This is useful when the default pager doesn't render correctly in the embedded p
- [`wt list`](@/list.md) — Static table view with all worktree metadata
- [`wt switch`](@/switch.md) — Direct switching to a known target branch
+
+Available on Unix only (macOS, Linux). On Windows, use `wt list` or `wt switch` directly.
"#)]
Select {
/// Include branches without worktrees
diff --git a/src/config/expansion.rs b/src/config/expansion.rs
index 2991d481a..7f0d20203 100644
--- a/src/config/expansion.rs
+++ b/src/config/expansion.rs
@@ -32,7 +32,9 @@ pub const TEMPLATE_VARS: &[&str] = &[
"remote",
"remote_url",
"upstream",
- "target", // Added by merge/rebase hooks via extra_vars
+ "target", // Added by merge/rebase hooks via extra_vars
+ "base", // Added by creation hooks via extra_vars
+ "base_worktree_path", // Added by creation hooks via extra_vars
];
/// Deprecated template variable aliases (still valid for backward compatibility).
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 056d25395..cf27bbcc0 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -10,6 +10,7 @@ info:
COLUMNS: "500"
GIT_EDITOR: ""
RUST_LOG: warn
+ SHELL: ""
SOURCE_DATE_EPOCH: "1735776000"
TERM: alacritty
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
@@ -136,6 +137,7 @@ The Status column has multiple subcolumns. Within each, only the first matching
⊟ 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
@@ -243,11 +245,11 @@ Query structured data with --format=json:
worktree object
- Field Type Description
- ──────── ─────── ─────────────────────────────────────────────────────────────────────
- state string "branch_worktree_mismatch", "prunable", "locked" (absent when normal)
- reason string Reason for locked/prunable state
- detached boolean HEAD is detached
+ Field Type Description
+ ──────── ─────── ────────────────────────────────────────────────────────────────────────────────────
+ state string "no_worktree", "branch_worktree_mismatch", "prunable", "locked" (absent when normal)
+ reason string Reason for locked/prunable state
+ detached boolean HEAD is detached
ci object
@@ -262,7 +264,7 @@ Query structured data with --format=json:
These values describe relation to the default branch.
-"is_main" "would_conflict" "empty" "same_commit" "integrated" "diverged" "ahead" "behind"
+"is_main" "orphan" "would_conflict" "empty" "same_commit" "integrated" "diverged" "ahead" "behind"
integration_reason values
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 8bb729338..9358a74d0 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
@@ -10,6 +10,7 @@ info:
COLUMNS: "80"
GIT_EDITOR: ""
RUST_LOG: warn
+ SHELL: ""
SOURCE_DATE_EPOCH: "1735776000"
TERM: alacritty
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
@@ -148,6 +149,8 @@ symbol is shown (listed in priority order):
⊟ 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
@@ -267,8 +270,8 @@ Query structured data with --format=json:
Field Type Description
──────── ─────── ───────────────────────────────────────────────────────────
- state string "branch_worktree_mismatch", "prunable", "locked" (absent
- when normal)
+ state string "no_worktree", "branch_worktree_mismatch", "prunable",
+ "locked" (absent when normal)
reason string Reason for locked/prunable state
detached boolean HEAD is detached
@@ -285,8 +288,8 @@ Query structured data with --format=json:
These values describe relation to the default branch.
-"is_main" "would_conflict" "empty" "same_commit" "integrated" "diverged" "ahead"
- "behind"
+"is_main" "orphan" "would_conflict" "empty" "same_commit" "integrated"
+"diverged" "ahead" "behind"
integration_reason values