Skip to content

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

docs: changelog and migration note for template variable redesign (#1666)

Maximilian Roos38bf4abdc57f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2b9ce7e3f..e13660b65 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,15 @@
# Changelog
+## Unreleased
+
+### Breaking
+
+- **Hook template variable `worktree_path` changed meaning** in two hook types: in **pre-switch** (existing worktrees), `{{ worktree_path }}` now points to the destination worktree instead of the source; in **post-merge**, it now points to the feature worktree (active) instead of the merge target. Use `{{ base_worktree_path }}` or `{{ cwd }}` for the previous behavior. ([#1655](https://github.com/max-sixty/worktrunk/pull/1655), [#1660](https://github.com/max-sixty/worktrunk/pull/1660))
+
+### Improved
+
+- **Directional template variables for hooks**: New `{{ base }}`, `{{ base_worktree_path }}`, `{{ target }}`, `{{ target_worktree_path }}`, and `{{ cwd }}` variables give hooks explicit access to both sides of two-worktree operations (switch, merge, remove). Bare variables (`branch`, `worktree_path`, `commit`) consistently point to the active branch — the destination for switch/create, the source for merge/remove. ([#1655](https://github.com/max-sixty/worktrunk/pull/1655), [#1660](https://github.com/max-sixty/worktrunk/pull/1660), [#1663](https://github.com/max-sixty/worktrunk/pull/1663))
+
## 0.30.1
### Fixed
diff --git a/docs/content/hook.md b/docs/content/hook.md
index f9f8b0994..df2c42785 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -240,6 +240,15 @@ Some variables are conditional: `upstream` requires remote tracking; `base`/`tar
sync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"
```
+### Migration from earlier versions
+
+`worktree_path` changed meaning in two hook types:
+
+- **pre-switch** (existing worktrees): previously the source worktree, now the destination. Use `{{ base_worktree_path }}` or `{{ cwd }}` for the source.
+- **post-merge**: previously the merge target worktree, now the feature worktree (active). Use `{{ target_worktree_path }}` or `{{ cwd }}` for where code landed.
+
+New variables `cwd`, `target_worktree_path`, `base`, and `base_worktree_path` are available in more hook types than before.
+
## Worktrunk filters
Templates support Jinja2 filters for transforming values:
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index f94c65c4e..f04298fd7 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -231,6 +231,15 @@ Some variables are conditional: `upstream` requires remote tracking; `base`/`tar
sync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"
```
+### Migration from earlier versions
+
+`worktree_path` changed meaning in two hook types:
+
+- **pre-switch** (existing worktrees): previously the source worktree, now the destination. Use `{{ base_worktree_path }}` or `{{ cwd }}` for the source.
+- **post-merge**: previously the merge target worktree, now the feature worktree (active). Use `{{ target_worktree_path }}` or `{{ cwd }}` for where code landed.
+
+New variables `cwd`, `target_worktree_path`, `base`, and `base_worktree_path` are available in more hook types than before.
+
## Worktrunk filters
Templates support Jinja2 filters for transforming values:
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index e5c06658e..08f41c63e 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1327,6 +1327,15 @@ Some variables are conditional: `upstream` requires remote tracking; `base`/`tar
sync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"
```
+### Migration from earlier versions
+
+`worktree_path` changed meaning in two hook types:
+
+- **pre-switch** (existing worktrees): previously the source worktree, now the destination. Use `{{ base_worktree_path }}` or `{{ cwd }}` for the source.
+- **post-merge**: previously the merge target worktree, now the feature worktree (active). Use `{{ target_worktree_path }}` or `{{ cwd }}` for where code landed.
+
+New variables `cwd`, `target_worktree_path`, `base`, and `base_worktree_path` are available in more hook types than before.
+
## Worktrunk filters
Templates support Jinja2 filters for transforming values: