Skip to content

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

Age branches by reflog entry in wt step prune; fix four doc claims (#4077)

Maximilian Roosf194d5a13c3f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6131391d6..17f820862 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,8 @@
### Fixed
+- **`wt step prune` no longer deletes a branch created minutes ago from an older commit**: the min-age guard aged a branch with no worktree by the committer date of the commit it points at, so `git branch <name> main` on a default branch whose last commit was over a day old was pruned on the next run — the case `--min-age` exists to prevent. The branch's age now comes from its oldest reflog entry, written when the branch was created.
+
- **`wt config update` migrates `[ci] platform` into a `[forge]` section that only sets `hostname`**: the migration stood down whenever a `[forge]` section existed at all, so the config a GitHub Enterprise or self-hosted GitLab user ends up with — `[ci] platform` from before the rename, `[forge] hostname` added later for an SSH host alias — kept the deprecated key with no warning and nothing `wt config update` would do about it. The platform still resolved, so nothing broke; the deprecation notice that precedes `[ci]`'s eventual removal simply never arrived. A `[forge]` that already sets `platform`, or a `forge` that isn't a section, still stands down.
- **`wt config shell install` migrates a fish wrapper at the deprecated `conf.d` path even when `~/.config/fish/functions` doesn't exist yet**: fish was skipped for want of a config location, so the bare command left the deprecated wrapper running and only `wt config shell install fish` migrated it. A worktrunk wrapper at the old path now counts as fish being configured, just at the old path. `wt config show` reports that wrapper too, where before it showed nothing at all for fish unless fish was on `PATH`.
diff --git a/docs/public/.well-known/agent-skills/index.json b/docs/public/.well-known/agent-skills/index.json
index 037aefb0c..39f3a328b 100644
--- a/docs/public/.well-known/agent-skills/index.json
+++ b/docs/public/.well-known/agent-skills/index.json
@@ -6,7 +6,7 @@
"type": "skill-md",
"description": "Guidance for Worktrunk (the `wt` CLI) — git worktree management, hooks, and config. Load when working out which worktree a `wt` command will act on, or reaching for the global `-C <path>` to target one; editing .config/wt.toml or ~/.config/worktrunk/config.toml; adding, modifying, or debugging hooks (post-merge, post-start, pre-commit, pre-merge, post-switch, etc.); configuring commit message generation or command aliases; or troubleshooting wt behavior. Also answers general worktrunk/wt questions.",
"url": "./worktrunk/SKILL.md",
- "digest": "sha256:f8102f3e9c1909fd75f57599f8a84696c635cf41edd747d728c54abe7d585272"
+ "digest": "sha256:1b69b7e3e6fcb3dcedec6f58a633ff8ac543002f5aeb365f9686634bf5b89d5b"
}
]
}
diff --git a/docs/src/content/docs/claude-code.md b/docs/src/content/docs/claude-code.md
index 4a87911be..e88477e95 100644
--- a/docs/src/content/docs/claude-code.md
+++ b/docs/src/content/docs/claude-code.md
@@ -11,9 +11,9 @@ Worktrunk ships a plugin for each supported agent CLI. What a plugin provides de
| Configuration skill | ✓ | ✓ | | | ✓ |
| Activity tracking (🤖/💬 in `wt list`) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Worktree isolation | ✓ | | | | |
-| `/wt-switch-create` skill | ✓ | ✓\* | | | ✓\* |
+| `/wt-switch-create` skill\* | ✓ | | | | |
-\* Codex and Gemini load the `/wt-switch-create` skill from the same shared skill set, but neither lets a skill change the session's working directory, so it does nothing there.
+\* Codex and Gemini also load the `/wt-switch-create` skill from the shared skill set, but neither lets a skill change the session's working directory, so it does nothing there.
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 exposes, so Codex, OpenCode, Pi, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex tracks activity through its own `Stop` and `SessionEnd` hooks.
diff --git a/docs/src/content/docs/hook.md b/docs/src/content/docs/hook.md
index 31389e78d..8d1cadd92 100644
--- a/docs/src/content/docs/hook.md
+++ b/docs/src/content/docs/hook.md
@@ -99,7 +99,7 @@ server = "npm run dev"
Here `install` runs first, then `build` and `server` run together.
-Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Because an earlier step can still change those values, a preview stands the reference in for its value instead of resolving it: `wt hook <type> --dry-run` and `wt hook show --expanded` render `{{ vars.thing | default('none') }}` as `{{ vars.thing }}` — the reference is defined, so the `default` never fires — while every other variable expands. A filter that transforms its input still runs, against the placeholder text: `{{ vars.thing | upper }}` previews as `{{ VARS.THING }}`.
+Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Because an earlier step can still change those values, a preview stands the reference in for its value instead of resolving it: `wt hook <type> --dry-run` and `wt hook show --expanded` render `{{ vars.thing | default('none') }}` as `{{ vars.thing }}` — the reference is defined, so the `default` never fires — while every other variable expands. A filter that transforms its input still runs, against the placeholder text, and its output is shell-escaped like any other value: `{{ vars.thing | upper }}` previews as `'{{ VARS.THING }}'`.
Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependency chain — typically setup that must complete before later steps, like installing dependencies before running a build and dev server concurrently.
diff --git a/plugins/worktrunk/skills/worktrunk/SKILL.md b/plugins/worktrunk/skills/worktrunk/SKILL.md
index cac788b99..8431cc473 100644
--- a/plugins/worktrunk/skills/worktrunk/SKILL.md
+++ b/plugins/worktrunk/skills/worktrunk/SKILL.md
@@ -137,7 +137,7 @@ The resolution is for the user to make the trust decision themselves:
## Advanced: agent handoffs
-When the user requests spawning a worktree with an agent in a background session ("spawn a worktree for...", "hand off to another agent"), use the tmux or Zellij command from `reference/tips-patterns.md#agent-handoffs`, substituting the CLI you are running as for `claude`.
+When the user requests spawning a worktree with an agent in a background session ("spawn a worktree for...", "hand off to another agent"), use the tmux or Zellij command from `reference/tips-patterns.md#agent-handoffs` with the CLI you are running as in place of `claude`, following that section's note on where a subcommand such as OpenCode's `run` goes.
**Requirements** (all must be true):
- User explicitly requests spawning/handoff
diff --git a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md b/plugins/worktrunk/skills/worktrunk/reference/claude-code.md
index bf30e02fe..1fd332742 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/claude-code.md
@@ -7,9 +7,9 @@ Worktrunk ships a plugin for each supported agent CLI. What a plugin provides de
| Configuration skill | ✓ | ✓ | | | ✓ |
| Activity tracking (🤖/💬 in `wt list`) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Worktree isolation | ✓ | | | | |
-| `/wt-switch-create` skill | ✓ | ✓\* | | | ✓\* |
+| `/wt-switch-create` skill\* | ✓ | | | | |
-\* Codex and Gemini load the `/wt-switch-create` skill from the same shared skill set, but neither lets a skill change the session's working directory, so it does nothing there.
+\* Codex and Gemini also load the `/wt-switch-create` skill from the shared skill set, but neither lets a skill change the session's working directory, so it does nothing there.
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 exposes, so Codex, OpenCode, Pi, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex tracks activity through its own `Stop` and `SessionEnd` hooks.
diff --git a/plugins/worktrunk/skills/worktrunk/reference/hook.md b/plugins/worktrunk/skills/worktrunk/reference/hook.md
index 2c7314ad0..010bc2233 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/hook.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/hook.md
@@ -93,7 +93,7 @@ server = "npm run dev"
Here `install` runs first, then `build` and `server` run together.
-Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](https://worktrunk.dev/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Because an earlier step can still change those values, a preview stands the reference in for its value instead of resolving it: `wt hook <type> --dry-run` and `wt hook show --expanded` render `{{ vars.thing | default('none') }}` as `{{ vars.thing }}` — the reference is defined, so the `default` never fires — while every other variable expands. A filter that transforms its input still runs, against the placeholder text: `{{ vars.thing | upper }}` previews as `{{ VARS.THING }}`.
+Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](https://worktrunk.dev/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Because an earlier step can still change those values, a preview stands the reference in for its value instead of resolving it: `wt hook <type> --dry-run` and `wt hook show --expanded` render `{{ vars.thing | default('none') }}` as `{{ vars.thing }}` — the reference is defined, so the `default` never fires — while every other variable expands. A filter that transforms its input still runs, against the placeholder text, and its output is shell-escaped like any other value: `{{ vars.thing | upper }}` previews as `'{{ VARS.THING }}'`.
Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependency chain — typically setup that must complete before later steps, like installing dependencies before running a build and dev server concurrently.
diff --git a/skills/worktrunk/SKILL.md b/skills/worktrunk/SKILL.md
index cac788b99..8431cc473 100644
--- a/skills/worktrunk/SKILL.md
+++ b/skills/worktrunk/SKILL.md
@@ -137,7 +137,7 @@ The resolution is for the user to make the trust decision themselves:
## Advanced: agent handoffs
-When the user requests spawning a worktree with an agent in a background session ("spawn a worktree for...", "hand off to another agent"), use the tmux or Zellij command from `reference/tips-patterns.md#agent-handoffs`, substituting the CLI you are running as for `claude`.
+When the user requests spawning a worktree with an agent in a background session ("spawn a worktree for...", "hand off to another agent"), use the tmux or Zellij command from `reference/tips-patterns.md#agent-handoffs` with the CLI you are running as in place of `claude`, following that section's note on where a subcommand such as OpenCode's `run` goes.
**Requirements** (all must be true):
- User explicitly requests spawning/handoff
diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.md
index bf30e02fe..1fd332742 100644
--- a/skills/worktrunk/reference/claude-code.md
+++ b/skills/worktrunk/reference/claude-code.md
@@ -7,9 +7,9 @@ Worktrunk ships a plugin for each supported agent CLI. What a plugin provides de
| Configuration skill | ✓ | ✓ | | | ✓ |
| Activity tracking (🤖/💬 in `wt list`) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Worktree isolation | ✓ | | | | |
-| `/wt-switch-create` skill | ✓ | ✓\* | | | ✓\* |
+| `/wt-switch-create` skill\* | ✓ | | | | |
-\* Codex and Gemini load the `/wt-switch-create` skill from the same shared skill set, but neither lets a skill change the session's working directory, so it does nothing there.
+\* Codex and Gemini also load the `/wt-switch-create` skill from the shared skill set, but neither lets a skill change the session's working directory, so it does nothing there.
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 exposes, so Codex, OpenCode, Pi, and Gemini users invoke `wt switch --create` and `wt remove` directly. Codex tracks activity through its own `Stop` and `SessionEnd` hooks.
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index 2c7314ad0..010bc2233 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -93,7 +93,7 @@ server = "npm run dev"
Here `install` runs first, then `build` and `server` run together.
-Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](https://worktrunk.dev/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Because an earlier step can still change those values, a preview stands the reference in for its value instead of resolving it: `wt hook <type> --dry-run` and `wt hook show --expanded` render `{{ vars.thing | default('none') }}` as `{{ vars.thing }}` — the reference is defined, so the `default` never fires — while every other variable expands. A filter that transforms its input still runs, against the placeholder text: `{{ vars.thing | upper }}` previews as `{{ VARS.THING }}`.
+Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](https://worktrunk.dev/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Because an earlier step can still change those values, a preview stands the reference in for its value instead of resolving it: `wt hook <type> --dry-run` and `wt hook show --expanded` render `{{ vars.thing | default('none') }}` as `{{ vars.thing }}` — the reference is defined, so the `default` never fires — while every other variable expands. A filter that transforms its input still runs, against the placeholder text, and its output is shell-escaped like any other value: `{{ vars.thing | upper }}` previews as `'{{ VARS.THING }}'`.
Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependency chain — typically setup that must complete before later steps, like installing dependencies before running a build and dev server concurrently.
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index f909d5a26..49ba3019e 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1696,7 +1696,7 @@ server = "npm run dev"
Here `install` runs first, then `build` and `server` run together.
-Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Because an earlier step can still change those values, a preview stands the reference in for its value instead of resolving it: `wt hook <type> --dry-run` and `wt hook show --expanded` render `{{ vars.thing | default('none') }}` as `{{ vars.thing }}` — the reference is defined, so the `default` never fires — while every other variable expands. A filter that transforms its input still runs, against the placeholder text: `{{ vars.thing | upper }}` previews as `{{ VARS.THING }}`.
+Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store [per-branch vars](/config/#wt-config-state-vars) that later steps read via `{{ vars.<key> }}`. Because an earlier step can still change those values, a preview stands the reference in for its value instead of resolving it: `wt hook <type> --dry-run` and `wt hook show --expanded` render `{{ vars.thing | default('none') }}` as `{{ vars.thing }}` — the reference is defined, so the `default` never fires — while every other variable expands. A filter that transforms its input still runs, against the placeholder text, and its output is shell-escaped like any other value: `{{ vars.thing | upper }}` previews as `'{{ VARS.THING }}'`.
Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependency chain — typically setup that must complete before later steps, like installing dependencies before running a build and dev server concurrently.
diff --git a/src/commands/step/prune.rs b/src/commands/step/prune.rs
index 88439e1c5..f688129e0 100644
--- a/src/commands/step/prune.rs
+++ b/src/commands/step/prune.rs
@@ -688,20 +688,32 @@ fn worktree_age(
)))
}
-/// Resolve the age of an orphan branch via its reflog creation timestamp.
+/// Resolve the age of an orphan branch from when its oldest reflog entry was
+/// written.
+///
+/// That is the entry's own timestamp, not the committer date of the commit it
+/// points at: `git branch <name> main` on a days-old tip creates a new branch,
+/// and aging it by the commit would prune it before the guard saw it as young.
+/// `--date=unix` renders each entry's selector as `<name>@{<epoch>}`, and git
+/// forbids `@{` inside a ref name, so the last `@{` opens the timestamp.
///
/// Returns `None` if the reflog is missing or unparsable — callers treat
-/// "unknown age" as "old enough", matching the previous inline behavior.
+/// "unknown age" as "old enough". A bare repository defaults
+/// `core.logAllRefUpdates` to false, so a branch created or updated only from
+/// the bare directory itself has no reflog and no min-age guard; one touched
+/// from inside a linked worktree has a reflog.
fn orphan_branch_age(repo: &Repository, branch: &str, now_secs: u64) -> Option<Duration> {
let ref_name = format!("refs/heads/{branch}");
let stdout = repo
- .run_command(&["reflog", "show", "--format=%ct", &ref_name])
+ .run_command(&["reflog", "show", "--date=unix", "--format=%gd", &ref_name])
.ok()?;
let created_epoch = stdout
.trim()
.lines()
.last()
- .and_then(|s| s.parse::<u64>().ok())?;
+ .and_then(|selector| selector.rsplit_once("@{"))
+ .and_then(|(_, epoch)| epoch.strip_suffix('}'))
+ .and_then(|epoch| epoch.parse::<u64>().ok())?;
Some(Duration::from_secs(now_secs.saturating_sub(created_epoch)))
}
diff --git a/src/help.rs b/src/help.rs
index 3f1fe15e5..49f905a06 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -126,7 +126,7 @@ impl PageMode {
/// and cut it from the rest.
///
/// Clap repeats the same ~20-line `Global Options:` list in every reference it
-/// renders, so a page built from subdocs stacks one copy per subcommand — 11 on
+/// renders, so a page built from subdocs stacks one copy per reference — 12 on
/// `wt config`, 13 on `wt step`. That pads both the site page and the skill
/// mirror, and gives the site's search that many near-identical hits. `kept`
/// carries the state for one page; a reference with no such section leaves it
diff --git a/tests/integration_tests/step_prune.rs b/tests/integration_tests/step_prune.rs
index 9bd1676c4..cfa185ec7 100644
--- a/tests/integration_tests/step_prune.rs
+++ b/tests/integration_tests/step_prune.rs
@@ -396,12 +396,19 @@ fn test_prune_orphan_branches(mut repo: TestRepo) {
/// Orphan branches (no worktree) respect the min-age guard via reflog timestamps.
///
-/// GIT_COMMITTER_DATE=2025-01-01T00:00:00Z makes the branch reflog timestamp
-/// epoch 1735689600. Setting TEST_EPOCH to 30 minutes later (1735691400) means
-/// the branch appears 30 minutes old, which is younger than the default 1d.
+/// The branch is created at GIT_COMMITTER_DATE=2025-01-01T00:00:00Z, so its
+/// reflog entry is epoch 1735689600, and TEST_EPOCH 30 minutes later
+/// (1735691400) makes it 30 minutes old, younger than the default 1d. The
+/// commit it points at is a month older: the guard ages the branch, not the
+/// commit, so `git branch <name> main` on a days-old tip still counts as new.
#[rstest]
fn test_prune_orphan_branch_min_age(repo: TestRepo) {
- repo.commit("initial");
+ repo.git_command()
+ .env("GIT_AUTHOR_DATE", "2024-12-01T00:00:00Z")
+ .env("GIT_COMMITTER_DATE", "2024-12-01T00:00:00Z")
+ .args(["commit", "--allow-empty", "-m", "initial"])
+ .run()
+ .unwrap();
// Create a branch at HEAD (integrated) without a worktree
repo.create_branch("orphan-integrated");