Skip to content

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

refactor: rename main_worktree_path template var to primary_worktree_path (#613)

Maximilian Roosa9ed5344ed04
diff --git a/.claude-plugin/skills/worktrunk/reference/config.md b/.claude-plugin/skills/worktrunk/reference/config.md
index 4cdac22a9..22fb6edaf 100644
--- a/.claude-plugin/skills/worktrunk/reference/config.md
+++ b/.claude-plugin/skills/worktrunk/reference/config.md
@@ -530,7 +530,7 @@ With `--project`, creates `.config/wt.toml` in the current repository:
# {{ repo }} - Repository directory name (e.g., "myproject")
# {{ branch }} - Branch name (e.g., "feature/auth")
# {{ worktree_path }} - Absolute path to worktree
-# {{ main_worktree_path }} - Absolute path to main worktree
+# {{ primary_worktree_path }} - Main worktree (or default branch worktree for bare repos)
# {{ default_branch }} - Default branch name (e.g., "main")
# {{ target }} - Target branch (merge hooks only)
#
diff --git a/.claude-plugin/skills/worktrunk/reference/hook.md b/.claude-plugin/skills/worktrunk/reference/hook.md
index 2dba00202..f0034ab7e 100644
--- a/.claude-plugin/skills/worktrunk/reference/hook.md
+++ b/.claude-plugin/skills/worktrunk/reference/hook.md
@@ -137,7 +137,7 @@ Hooks can use template variables that expand at runtime:
| `{{ branch }}` | feature/auth | Branch name |
| `{{ worktree_name }}` | myproject.feature-auth | Worktree directory name |
| `{{ worktree_path }}` | /path/to/myproject.feature-auth | Absolute worktree path |
-| `{{ main_worktree_path }}` | /path/to/myproject | Default branch worktree |
+| `{{ primary_worktree_path }}` | /path/to/myproject | Main worktree path (or for bare repos, the default branch worktree) |
| `{{ default_branch }}` | main | Default branch name |
| `{{ commit }}` | a1b2c3d4e5f6... | Full HEAD commit SHA |
| `{{ short_commit }}` | a1b2c3d | Short HEAD commit SHA |
@@ -148,8 +148,6 @@ Hooks can use template variables that expand at runtime:
| `{{ base }}` | main | Base branch (creation hooks only) |
| `{{ base_worktree_path }}` | /path/to/myproject | Base branch worktree (creation hooks only) |
-See [Designing effective hooks](#designing-effective-hooks) for `main_worktree_path` patterns.
-
### Worktrunk Filters
Templates support Jinja2 filters for transforming values:
diff --git a/.claude-plugin/skills/worktrunk/reference/step.md b/.claude-plugin/skills/worktrunk/reference/step.md
index af83502b3..3dbbcb4ec 100644
--- a/.claude-plugin/skills/worktrunk/reference/step.md
+++ b/.claude-plugin/skills/worktrunk/reference/step.md
@@ -159,7 +159,7 @@ The `target/` directory is huge (often 1-10GB). Copying with reflink cuts first
```toml
[post-create]
-deps = "ln -sf {{ main_worktree_path }}/node_modules ."
+deps = "ln -sf {{ primary_worktree_path }}/node_modules ."
```
#### Python
diff --git a/dev/wt.example.toml b/dev/wt.example.toml
index 87d5b1c53..efb060a72 100644
--- a/dev/wt.example.toml
+++ b/dev/wt.example.toml
@@ -26,7 +26,7 @@
# {{ repo }} - Repository directory name (e.g., "myproject")
# {{ branch }} - Branch name (e.g., "feature/auth")
# {{ worktree_path }} - Absolute path to worktree
-# {{ main_worktree_path }} - Absolute path to main worktree
+# {{ primary_worktree_path }} - Main worktree (or default branch worktree for bare repos)
# {{ default_branch }} - Default branch name (e.g., "main")
# {{ target }} - Target branch (merge hooks only)
#
diff --git a/docs/content/config.md b/docs/content/config.md
index cf73aadb3..9d7233461 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -540,7 +540,7 @@ With `--project`, creates `.config/wt.toml` in the current repository:
# {{ repo }} - Repository directory name (e.g., "myproject")
# {{ branch }} - Branch name (e.g., "feature/auth")
# {{ worktree_path }} - Absolute path to worktree
-# {{ main_worktree_path }} - Absolute path to main worktree
+# {{ primary_worktree_path }} - Main worktree (or default branch worktree for bare repos)
# {{ default_branch }} - Default branch name (e.g., "main")
# {{ target }} - Target branch (merge hooks only)
#
diff --git a/docs/content/hook.md b/docs/content/hook.md
index f034229d8..4e159015f 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -145,7 +145,7 @@ Hooks can use template variables that expand at runtime:
| `{{ branch }}` | feature/auth | Branch name |
| `{{ worktree_name }}` | myproject.feature-auth | Worktree directory name |
| `{{ worktree_path }}` | /path/to/myproject.feature-auth | Absolute worktree path |
-| `{{ main_worktree_path }}` | /path/to/myproject | Default branch worktree |
+| `{{ primary_worktree_path }}` | /path/to/myproject | Main worktree path (or for bare repos, the default branch worktree) |
| `{{ default_branch }}` | main | Default branch name |
| `{{ commit }}` | a1b2c3d4e5f6... | Full HEAD commit SHA |
| `{{ short_commit }}` | a1b2c3d | Short HEAD commit SHA |
@@ -156,8 +156,6 @@ Hooks can use template variables that expand at runtime:
| `{{ base }}` | main | Base branch (creation hooks only) |
| `{{ base_worktree_path }}` | /path/to/myproject | Base branch worktree (creation hooks only) |
-See [Designing effective hooks](#designing-effective-hooks) for `main_worktree_path` patterns.
-
### Worktrunk Filters
Templates support Jinja2 filters for transforming values:
diff --git a/docs/content/step.md b/docs/content/step.md
index 264d148a0..e88f5d7a6 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -174,7 +174,7 @@ The `target/` directory is huge (often 1-10GB). Copying with reflink cuts first
```toml
[post-create]
-deps = "ln -sf {{ main_worktree_path }}/node_modules ."
+deps = "ln -sf {{ primary_worktree_path }}/node_modules ."
```
#### Python
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index cb6af2998..e4456acb3 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1173,7 +1173,7 @@ Hooks can use template variables that expand at runtime:
| `{{ branch }}` | feature/auth | Branch name |
| `{{ worktree_name }}` | myproject.feature-auth | Worktree directory name |
| `{{ worktree_path }}` | /path/to/myproject.feature-auth | Absolute worktree path |
-| `{{ main_worktree_path }}` | /path/to/myproject | Default branch worktree |
+| `{{ primary_worktree_path }}` | /path/to/myproject | Main worktree path (or for bare repos, the default branch worktree) |
| `{{ default_branch }}` | main | Default branch name |
| `{{ commit }}` | a1b2c3d4e5f6... | Full HEAD commit SHA |
| `{{ short_commit }}` | a1b2c3d | Short HEAD commit SHA |
@@ -1184,8 +1184,6 @@ Hooks can use template variables that expand at runtime:
| `{{ base }}` | main | Base branch (creation hooks only) |
| `{{ base_worktree_path }}` | /path/to/myproject | Base branch worktree (creation hooks only) |
-See [Designing effective hooks](#designing-effective-hooks) for `main_worktree_path` patterns.
-
### Worktrunk Filters
Templates support Jinja2 filters for transforming values:
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 0444397a1..9a87c9d16 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -148,7 +148,7 @@ The `target/` directory is huge (often 1-10GB). Copying with reflink cuts first
```toml
[post-create]
-deps = "ln -sf {{ main_worktree_path }}/node_modules ."
+deps = "ln -sf {{ primary_worktree_path }}/node_modules ."
```
### Python
diff --git a/src/commands/command_executor.rs b/src/commands/command_executor.rs
index 1c48e9904..ac22cd824 100644
--- a/src/commands/command_executor.rs
+++ b/src/commands/command_executor.rs
@@ -87,17 +87,17 @@ pub fn build_hook_context(
map.insert("repo_root".into(), repo_path);
map.insert("worktree".into(), worktree);
- // Default branch and its worktree path
+ // Default branch
if let Some(default_branch) = ctx.repo.default_branch() {
map.insert("default_branch".into(), default_branch);
+ }
- // main_worktree_path: path to the worktree with the default branch checked out
- if let Ok(Some(path)) = ctx.repo.default_branch_worktree() {
- map.insert(
- "main_worktree_path".into(),
- to_posix_path(&path.to_string_lossy()),
- );
- }
+ // Primary worktree path (where established files live)
+ if let Ok(Some(path)) = ctx.repo.primary_worktree() {
+ let path_str = to_posix_path(&path.to_string_lossy());
+ map.insert("primary_worktree_path".into(), path_str.clone());
+ // Deprecated alias
+ map.insert("main_worktree_path".into(), path_str);
}
if let Ok(commit) = ctx.repo.run_command(&["rev-parse", "HEAD"]) {
diff --git a/src/config/deprecation.rs b/src/config/deprecation.rs
index 61661c0c0..690aa0d0e 100644
--- a/src/config/deprecation.rs
+++ b/src/config/deprecation.rs
@@ -33,6 +33,7 @@ const DEPRECATED_VARS: &[(&str, &str)] = &[
("repo_root", "repo_path"),
("worktree", "worktree_path"),
("main_worktree", "repo"),
+ ("main_worktree_path", "primary_worktree_path"),
];
/// Normalize a template string by replacing deprecated variables with their canonical names.
@@ -312,6 +313,15 @@ worktree-path = "../{{ main_worktree }}.{{ branch | sanitize }}"
assert_eq!(found, vec![("main_worktree", "repo")]);
}
+ #[test]
+ fn test_find_deprecated_vars_main_worktree_path() {
+ let content = r#"
+post-create = "ln -sf {{ main_worktree_path }}/node_modules ."
+"#;
+ let found = find_deprecated_vars(content);
+ assert_eq!(found, vec![("main_worktree_path", "primary_worktree_path")]);
+ }
+
#[test]
fn test_find_deprecated_vars_multiple() {
let content = r#"
diff --git a/src/config/expansion.rs b/src/config/expansion.rs
index 9112ffc80..cc46dd37b 100644
--- a/src/config/expansion.rs
+++ b/src/config/expansion.rs
@@ -26,7 +26,7 @@ pub const TEMPLATE_VARS: &[&str] = &[
"repo_path",
"worktree_path",
"default_branch",
- "main_worktree_path",
+ "primary_worktree_path",
"commit",
"short_commit",
"remote",
@@ -41,7 +41,13 @@ pub const TEMPLATE_VARS: &[&str] = &[
/// - `main_worktree` → `repo`
/// - `repo_root` → `repo_path`
/// - `worktree` → `worktree_path`
-pub const DEPRECATED_TEMPLATE_VARS: &[&str] = &["main_worktree", "repo_root", "worktree"];
+/// - `main_worktree_path` → `primary_worktree_path`
+pub const DEPRECATED_TEMPLATE_VARS: &[&str] = &[
+ "main_worktree",
+ "repo_root",
+ "worktree",
+ "main_worktree_path",
+];
use std::collections::HashMap;
use std::hash::{Hash, Hasher};
diff --git a/src/config/project.rs b/src/config/project.rs
index 2b320449b..ac5a22e7b 100644
--- a/src/config/project.rs
+++ b/src/config/project.rs
@@ -80,7 +80,7 @@ impl ProjectConfig {
/// - `{{ branch }}` - Branch name (e.g., "feature/auth")
/// - `{{ worktree_name }}` - Worktree directory name (e.g., "myproject.feature-auth")
/// - `{{ worktree_path }}` - Absolute path to the worktree (e.g., "/path/to/myproject.feature-auth")
-/// - `{{ main_worktree_path }}` - Absolute path to main worktree (e.g., "/path/to/myproject")
+/// - `{{ primary_worktree_path }}` - Main worktree path (or for bare repos, the default branch worktree)
/// - `{{ default_branch }}` - Default branch name (e.g., "main")
/// - `{{ commit }}` - Current HEAD commit SHA (full 40-character hash)
/// - `{{ short_commit }}` - Current HEAD commit SHA (short 7-character hash)
diff --git a/src/git/repository/mod.rs b/src/git/repository/mod.rs
index 667df8980..ed438fb16 100644
--- a/src/git/repository/mod.rs
+++ b/src/git/repository/mod.rs
@@ -305,8 +305,7 @@ impl Repository {
/// For bare repositories: the bare repository directory itself.
///
/// This is the base for template expansion (`{{ repo }}`, `{{ repo_path }}`).
- /// NOT necessarily where the default branch is checked out — use
- /// `default_branch_worktree()` for that.
+ /// NOT necessarily where established files live — use `primary_worktree()` for that.
///
/// Result is cached in the repository's shared cache (same for all clones).
pub fn repo_path(&self) -> anyhow::Result<PathBuf> {
diff --git a/src/git/repository/worktrees.rs b/src/git/repository/worktrees.rs
index a6c4dd52a..44a1763f6 100644
--- a/src/git/repository/worktrees.rs
+++ b/src/git/repository/worktrees.rs
@@ -47,35 +47,20 @@ impl Repository {
.map(|wt| wt.path.clone()))
}
- /// The worktree with the default branch checked out, if one exists.
- ///
- /// Returns `None` if no worktree has the default branch (e.g., user
- /// switched all worktrees to feature branches, or the default branch
- /// cannot be determined).
- ///
- /// This is distinct from `repo_path()` which returns the repository root.
- /// For normal repos where the main worktree has the default branch,
- /// these are the same. They differ when:
- /// - The main worktree is switched to a different branch
- /// - The repo is bare (no main worktree exists)
- ///
- /// For template var `{{ main_worktree_path }}`.
- pub fn default_branch_worktree(&self) -> anyhow::Result<Option<PathBuf>> {
- let Some(branch) = self.default_branch() else {
- return Ok(None);
- };
- self.worktree_for_branch(&branch)
- }
-
/// The primary worktree — where established files (ignored files, configs) typically live.
///
/// - Normal repos: the main worktree (repo root) — this is where you cloned and set things up
/// - Bare repos: the default branch's worktree — no main worktree exists
///
/// Returns `None` for bare repos when no worktree has the default branch.
+ ///
+ /// For template var `{{ primary_worktree_path }}`.
pub fn primary_worktree(&self) -> anyhow::Result<Option<PathBuf>> {
if self.is_bare()? {
- self.default_branch_worktree()
+ let Some(branch) = self.default_branch() else {
+ return Ok(None);
+ };
+ self.worktree_for_branch(&branch)
} else {
Ok(Some(self.repo_path()?))
}
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index 3538e15a2..5df514a28 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -277,7 +277,7 @@ With --project, creates .config/wt.toml in the current repositor
# {{ repo }} - Repository directory name (e.g., "myproject")
# {{ branch }} - Branch name (e.g., "feature/auth")
# {{ worktree_path }} - Absolute path to worktree
- # {{ main_worktree_path }} - Absolute path to main worktree
+ # {{ primary_worktree_path }} - Main worktree (or default branch worktree for bare repos)
# {{ default_branch }} - Default branch name (e.g., "main")
# {{ target }} - Target branch (merge hooks only)
#