Skip to content

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

feat(config): support absolute paths in worktree-path template (#904)

Maximilian Roos4bf73ae6fbac
diff --git a/.claude-plugin/skills/worktrunk/reference/config.md b/.claude-plugin/skills/worktrunk/reference/config.md
index f073d9e0c..62f45d1a5 100644
--- a/.claude-plugin/skills/worktrunk/reference/config.md
+++ b/.claude-plugin/skills/worktrunk/reference/config.md
@@ -70,11 +70,12 @@ Location:
## Worktree path template
-Controls where new worktrees are created. Paths are relative to the repository root.
+Controls where new worktrees are created.
**Variables:**
-- `{{ repo }}` — repository directory name
+- `{{ repo_path }}` — absolute path to the repository (e.g., `/Users/me/code/myproject`)
+- `{{ repo }}` — repository directory name (e.g., `myproject`)
- `{{ branch }}` — raw branch name (e.g., `feature/auth`)
- `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)
- `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)
@@ -82,23 +83,21 @@ Controls where new worktrees are created. Paths are relative to the repository r
**Examples** for repo at `~/code/myproject`, branch `feature/auth`:
```toml
-# Default — siblings in parent directory
+# Default — sibling directory
# Creates: ~/code/myproject.feature-auth
-worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
+# worktree-path = "{{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}"
# Inside the repository
# Creates: ~/code/myproject/.worktrees/feature-auth
-worktree-path = ".worktrees/{{ branch | sanitize }}"
-
-# Namespaced (useful when multiple repos share a parent directory)
-# Creates: ~/code/worktrees/myproject/feature-auth
-worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"
+worktree-path = "{{ repo_path }}/.worktrees/{{ branch | sanitize }}"
-# Nested bare repo (git clone --bare <url> project/.git)
-# Creates: ~/code/project/feature-auth (sibling to .git)
-worktree-path = "../{{ branch | sanitize }}"
+# Centralized worktrees directory
+# Creates: ~/worktrees/myproject/feature-auth
+worktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"
```
+`~` expands to the home directory. Relative paths are relative to the repository root.
+
## LLM commit messages
Generate commit messages automatically during merge. Requires an external CLI tool.
diff --git a/dev/config.example.toml b/dev/config.example.toml
index 7702599ad..f72a19978 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -9,32 +9,31 @@
#
# ## Worktree path template
#
-# Controls where new worktrees are created. Paths are relative to the repository root.
+# Controls where new worktrees are created.
#
# **Variables:**
#
-# - `{{ repo }}` — repository directory name
+# - `{{ repo_path }}` — absolute path to the repository (e.g., `/Users/me/code/myproject`)
+# - `{{ repo }}` — repository directory name (e.g., `myproject`)
# - `{{ branch }}` — raw branch name (e.g., `feature/auth`)
# - `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)
# - `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)
#
# **Examples** for repo at `~/code/myproject`, branch `feature/auth`:
#
-# # Default — siblings in parent directory
+# # Default — sibling directory
# # Creates: ~/code/myproject.feature-auth
-# worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
+# # worktree-path = "{{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}"
#
# # Inside the repository
# # Creates: ~/code/myproject/.worktrees/feature-auth
-# worktree-path = ".worktrees/{{ branch | sanitize }}"
+# worktree-path = "{{ repo_path }}/.worktrees/{{ branch | sanitize }}"
#
-# # Namespaced (useful when multiple repos share a parent directory)
-# # Creates: ~/code/worktrees/myproject/feature-auth
-# worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"
+# # Centralized worktrees directory
+# # Creates: ~/worktrees/myproject/feature-auth
+# worktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"
#
-# # Nested bare repo (git clone --bare <url> project/.git)
-# # Creates: ~/code/project/feature-auth (sibling to .git)
-# worktree-path = "../{{ branch | sanitize }}"
+# `~` expands to the home directory. Relative paths are relative to the repository root.
#
# ## LLM commit messages
#
diff --git a/docs/content/config.md b/docs/content/config.md
index d6a79e038..7a3999b95 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -78,11 +78,12 @@ Location:
## Worktree path template
-Controls where new worktrees are created. Paths are relative to the repository root.
+Controls where new worktrees are created.
**Variables:**
-- `{{ repo }}` — repository directory name
+- `{{ repo_path }}` — absolute path to the repository (e.g., `/Users/me/code/myproject`)
+- `{{ repo }}` — repository directory name (e.g., `myproject`)
- `{{ branch }}` — raw branch name (e.g., `feature/auth`)
- `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)
- `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)
@@ -90,23 +91,21 @@ Controls where new worktrees are created. Paths are relative to the repository r
**Examples** for repo at `~/code/myproject`, branch `feature/auth`:
```toml
-# Default — siblings in parent directory
+# Default — sibling directory
# Creates: ~/code/myproject.feature-auth
-worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
+# worktree-path = "{{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}"
# Inside the repository
# Creates: ~/code/myproject/.worktrees/feature-auth
-worktree-path = ".worktrees/{{ branch | sanitize }}"
-
-# Namespaced (useful when multiple repos share a parent directory)
-# Creates: ~/code/worktrees/myproject/feature-auth
-worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"
+worktree-path = "{{ repo_path }}/.worktrees/{{ branch | sanitize }}"
-# Nested bare repo (git clone --bare <url> project/.git)
-# Creates: ~/code/project/feature-auth (sibling to .git)
-worktree-path = "../{{ branch | sanitize }}"
+# Centralized worktrees directory
+# Creates: ~/worktrees/myproject/feature-auth
+worktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"
```
+`~` expands to the home directory. Relative paths are relative to the repository root.
+
## LLM commit messages
Generate commit messages automatically during merge. Requires an external CLI tool.
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index f1f3d845f..b1140ad5a 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1524,11 +1524,12 @@ Location:
## Worktree path template
-Controls where new worktrees are created. Paths are relative to the repository root.
+Controls where new worktrees are created.
**Variables:**
-- `{{ repo }}` — repository directory name
+- `{{ repo_path }}` — absolute path to the repository (e.g., `/Users/me/code/myproject`)
+- `{{ repo }}` — repository directory name (e.g., `myproject`)
- `{{ branch }}` — raw branch name (e.g., `feature/auth`)
- `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)
- `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)
@@ -1536,23 +1537,21 @@ Controls where new worktrees are created. Paths are relative to the repository r
**Examples** for repo at `~/code/myproject`, branch `feature/auth`:
```toml
-# Default — siblings in parent directory
+# Default — sibling directory
# Creates: ~/code/myproject.feature-auth
-worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
+# worktree-path = "{{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}"
# Inside the repository
# Creates: ~/code/myproject/.worktrees/feature-auth
-worktree-path = ".worktrees/{{ branch | sanitize }}"
-
-# Namespaced (useful when multiple repos share a parent directory)
-# Creates: ~/code/worktrees/myproject/feature-auth
-worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"
+worktree-path = "{{ repo_path }}/.worktrees/{{ branch | sanitize }}"
-# Nested bare repo (git clone --bare <url> project/.git)
-# Creates: ~/code/project/feature-auth (sibling to .git)
-worktree-path = "../{{ branch | sanitize }}"
+# Centralized worktrees directory
+# Creates: ~/worktrees/myproject/feature-auth
+worktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"
```
+`~` expands to the home directory. Relative paths are relative to the repository root.
+
## LLM commit messages
Generate commit messages automatically during merge. Requires an external CLI tool.
diff --git a/src/commands/worktree/resolve.rs b/src/commands/worktree/resolve.rs
index 788c52c99..c73d40f3c 100644
--- a/src/commands/worktree/resolve.rs
+++ b/src/commands/worktree/resolve.rs
@@ -107,11 +107,11 @@ pub fn compute_worktree_path(
})?;
let project = repo.project_identifier().ok();
- let relative_path = config
+ let expanded_path = config
.format_path(repo_name, branch, repo, project.as_deref())
.map_err(|e| anyhow::anyhow!("Failed to format worktree path: {e}"))?;
- Ok(repo_root.join(relative_path).normalize())
+ Ok(repo_root.join(expanded_path).normalize())
}
/// Check if a worktree is at its expected path based on config template.
diff --git a/src/config/mod.rs b/src/config/mod.rs
index cd865c4c1..4d244d408 100644
--- a/src/config/mod.rs
+++ b/src/config/mod.rs
@@ -157,7 +157,7 @@ mod tests {
assert!(config.configs.worktree_path.is_none());
assert_eq!(
config.worktree_path(),
- "../{{ repo }}.{{ branch | sanitize }}"
+ "{{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}"
);
// commit_generation is None by default
assert!(config.commit_generation.is_none());
diff --git a/src/config/user/accessors.rs b/src/config/user/accessors.rs
index 81521c0f5..8413fe927 100644
--- a/src/config/user/accessors.rs
+++ b/src/config/user/accessors.rs
@@ -3,7 +3,10 @@
//! These methods on `UserConfig` return the effective configuration for a given
//! project by merging global settings with project-specific overrides.
+use std::collections::HashMap;
+
use crate::config::HooksConfig;
+use crate::config::expansion::expand_template;
use super::UserConfig;
use super::merge::{Merge, merge_optional};
@@ -11,11 +14,9 @@ use super::sections::{
CommitConfig, CommitGenerationConfig, ListConfig, MergeConfig, SelectConfig,
};
-use crate::config::expansion::expand_template;
-
/// Default worktree path template
fn default_worktree_path() -> String {
- "../{{ repo }}.{{ branch | sanitize }}".to_string()
+ "{{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}".to_string()
}
impl UserConfig {
@@ -162,15 +163,18 @@ impl UserConfig {
repo: &crate::git::Repository,
project: Option<&str>,
) -> Result<String, String> {
- use std::collections::HashMap;
let template = match project {
Some(p) => self.worktree_path_for_project(p),
None => self.worktree_path(),
};
+ // Use native path format (not POSIX) since this is used for filesystem operations
+ let repo_path = repo.repo_path().to_string_lossy().to_string();
let mut vars = HashMap::new();
vars.insert("main_worktree", main_worktree);
vars.insert("repo", main_worktree);
vars.insert("branch", branch);
+ vars.insert("repo_path", repo_path.as_str());
expand_template(&template, &vars, false, repo, "worktree-path")
+ .map(|p| shellexpand::tilde(&p).into_owned())
}
}
diff --git a/src/config/user/persistence.rs b/src/config/user/persistence.rs
index 65660fda9..5b19d474b 100644
--- a/src/config/user/persistence.rs
+++ b/src/config/user/persistence.rs
@@ -317,31 +317,21 @@ impl UserConfig {
/// Validate configuration values.
pub(super) fn validate(&self) -> Result<(), ConfigError> {
// Validate worktree path (only if explicitly set - default is always valid)
- if let Some(ref path) = self.configs.worktree_path {
- if path.is_empty() {
- return Err(ConfigError::Message("worktree-path cannot be empty".into()));
- }
- if std::path::Path::new(path).is_absolute() {
- return Err(ConfigError::Message(
- "worktree-path must be relative, not absolute".into(),
- ));
- }
+ if let Some(ref path) = self.configs.worktree_path
+ && path.trim().is_empty()
+ {
+ return Err(ConfigError::Message("worktree-path cannot be empty".into()));
}
// Validate per-project configs
for (project, project_config) in &self.projects {
// Validate worktree path
- if let Some(ref path) = project_config.overrides.worktree_path {
- if path.is_empty() {
- return Err(ConfigError::Message(format!(
- "projects.{project}.worktree-path cannot be empty"
- )));
- }
- if std::path::Path::new(path).is_absolute() {
- return Err(ConfigError::Message(format!(
- "projects.{project}.worktree-path must be relative, not absolute"
- )));
- }
+ if let Some(ref path) = project_config.overrides.worktree_path
+ && path.trim().is_empty()
+ {
+ return Err(ConfigError::Message(format!(
+ "projects.{project}.worktree-path cannot be empty"
+ )));
}
// Validate commit generation config (check both old and new locations)
diff --git a/src/config/user/tests.rs b/src/config/user/tests.rs
index 47cdfc1d4..ea61cddd6 100644
--- a/src/config/user/tests.rs
+++ b/src/config/user/tests.rs
@@ -230,7 +230,7 @@ fn test_worktree_path_for_project_falls_back_to_default() {
// Unknown project should fall back to default template
assert_eq!(
config.worktree_path_for_project("github.com/unknown/project"),
- "../{{ repo }}.{{ branch | sanitize }}"
+ "{{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}"
);
}
@@ -303,7 +303,7 @@ fn test_worktrunk_config_default() {
assert!(config.configs.worktree_path.is_none());
assert_eq!(
config.worktree_path(),
- "../{{ repo }}.{{ branch | sanitize }}"
+ "{{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}"
);
assert!(config.projects.is_empty());
assert!(config.configs.list.is_none());
@@ -416,7 +416,24 @@ fn test_worktrunk_config_format_path() {
let path = config
.format_path("myrepo", "feature/branch", &test.repo, None)
.unwrap();
- assert_eq!(path, "../myrepo.feature-branch");
+ // Default path is now absolute: {{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}
+ // The template uses forward slashes which work on all platforms
+ // Check that the path contains the expected components
+ assert!(
+ path.contains("myrepo.feature-branch"),
+ "Expected path containing 'myrepo.feature-branch', got: {path}"
+ );
+ // Verify it contains parent directory navigation
+ assert!(
+ path.contains("/..") || path.contains("\\.."),
+ "Expected path containing parent navigation, got: {path}"
+ );
+ // The path should start with the repo path (absolute)
+ let repo_path = test.repo.repo_path().to_string_lossy();
+ assert!(
+ path.starts_with(repo_path.as_ref()),
+ "Expected path starting with repo path '{repo_path}', got: {path}"
+ );
}
#[test]
@@ -435,6 +452,68 @@ fn test_worktrunk_config_format_path_custom_template() {
assert_eq!(path, ".worktrees/feature");
}
+#[test]
+fn test_worktrunk_config_format_path_repo_path_variable() {
+ let test = test_repo();
+ let config = UserConfig {
+ configs: OverridableConfig {
+ // Use forward slashes in template (works on all platforms)
+ worktree_path: Some("{{ repo_path }}/worktrees/{{ branch | sanitize }}".to_string()),
+ ..Default::default()
+ },
+ ..Default::default()
+ };
+ let path = config
+ .format_path("myrepo", "feature/branch", &test.repo, None)
+ .unwrap();
+ // Path should contain the expected components
+ assert!(
+ path.contains("worktrees") && path.contains("feature-branch"),
+ "Expected path containing 'worktrees' and 'feature-branch', got: {path}"
+ );
+ // The path should start with the repo path
+ let repo_path = test.repo.repo_path().to_string_lossy();
+ assert!(
+ path.starts_with(repo_path.as_ref()),
+ "Expected path starting with repo path '{repo_path}', got: {path}"
+ );
+ // The path should be absolute since repo_path is absolute
+ assert!(
+ std::path::Path::new(&path).is_absolute() || path.starts_with('/'),
+ "Expected absolute path, got: {path}"
+ );
+}
+
+#[test]
+fn test_worktrunk_config_format_path_tilde_expansion() {
+ let test = test_repo();
+ let config = UserConfig {
+ configs: OverridableConfig {
+ worktree_path: Some("~/worktrees/{{ repo }}/{{ branch | sanitize }}".to_string()),
+ ..Default::default()
+ },
+ ..Default::default()
+ };
+ let path = config
+ .format_path("myrepo", "feature/branch", &test.repo, None)
+ .unwrap();
+ // Tilde should be expanded to home directory
+ assert!(
+ !path.starts_with('~'),
+ "Tilde should be expanded, got: {path}"
+ );
+ // Path should contain expected components
+ assert!(
+ path.contains("worktrees") && path.contains("myrepo") && path.contains("feature-branch"),
+ "Expected path containing 'worktrees/myrepo/feature-branch', got: {path}"
+ );
+ // Path should be absolute after tilde expansion
+ assert!(
+ std::path::Path::new(&path).is_absolute(),
+ "Expected absolute path after tilde expansion, got: {path}"
+ );
+}
+
#[test]
fn test_merge_config_serde() {
let config = MergeConfig {
@@ -1250,17 +1329,19 @@ fn test_validation_empty_worktree_path() {
}
#[test]
-fn test_validation_absolute_worktree_path() {
- // Use platform-appropriate absolute path
+fn test_validation_absolute_worktree_path_allowed() {
+ // Absolute paths should be allowed for worktree-path
let content = if cfg!(windows) {
- r#"worktree-path = "C:\\absolute\\path""#
+ r#"worktree-path = "C:\\worktrees\\{{ branch | sanitize }}""#
} else {
- r#"worktree-path = "/absolute/path""#
+ r#"worktree-path = "/worktrees/{{ branch | sanitize }}""#
};
let result = UserConfig::load_from_str(content);
- assert!(result.is_err());
- let err = result.unwrap_err().to_string();
- assert!(err.contains("must be relative"), "{err}");
+ assert!(
+ result.is_ok(),
+ "Absolute paths should be allowed: {:?}",
+ result.err()
+ );
}
#[test]
@@ -1276,23 +1357,25 @@ worktree-path = ""
}
#[test]
-fn test_validation_project_absolute_worktree_path() {
- // Use platform-appropriate absolute path
+fn test_validation_project_absolute_worktree_path_allowed() {
+ // Absolute paths should be allowed for per-project worktree-path
let content = if cfg!(windows) {
r#"
[projects."github.com/user/repo"]
-worktree-path = "C:\\absolute\\path"
+worktree-path = "C:\\worktrees\\{{ branch | sanitize }}"
"#
} else {
r#"
[projects."github.com/user/repo"]
-worktree-path = "/absolute/path"
+worktree-path = "/worktrees/{{ branch | sanitize }}"
"#
};
let result = UserConfig::load_from_str(content);
- assert!(result.is_err());
- let err = result.unwrap_err().to_string();
- assert!(err.contains("must be relative"), "{err}");
+ assert!(
+ result.is_ok(),
+ "Absolute paths should be allowed: {:?}",
+ result.err()
+ );
}
#[test]
diff --git a/tests/integration_tests/bare_repository.rs b/tests/integration_tests/bare_repository.rs
index 58bfc94a9..27d33cb12 100644
--- a/tests/integration_tests/bare_repository.rs
+++ b/tests/integration_tests/bare_repository.rs
@@ -230,6 +230,56 @@ fn test_bare_repo_path_used_for_worktree_paths() {
);
}
+#[test]
+fn test_bare_repo_with_repo_path_variable() {
+ // Test that {{ repo_path }} resolves correctly in bare repos
+ // For bare repos, repo_path should be the bare repo directory itself
+ let test = BareRepoTest::new();
+
+ // Override config to use {{ repo_path }} explicitly
+ fs::write(
+ test.config_path(),
+ "worktree-path = \"{{ repo_path }}/../worktrees/{{ branch | sanitize }}\"\n",
+ )
+ .unwrap();
+
+ // Create initial worktree
+ let main_worktree = test.create_worktree("main", "main");
+ test.commit_in(&main_worktree, "Initial commit");
+
+ // Create new worktree using wt switch
+ let (directive_path, _guard) = directive_file();
+ let mut cmd = wt_command();
+ test.configure_wt_cmd(&mut cmd);
+ configure_directive_file(&mut cmd, &directive_path);
+ cmd.args(["switch", "--create", "feature/auth"])
+ .current_dir(&main_worktree);
+
+ let output = cmd.output().unwrap();
+
+ if !output.status.success() {
+ panic!(
+ "wt switch failed:\nstdout: {}\nstderr: {}",
+ String::from_utf8_lossy(&output.stdout),
+ String::from_utf8_lossy(&output.stderr)
+ );
+ }
+
+ // Verify worktree was created at sibling path using {{ repo_path }}/../worktrees/
+ // Bare repo is at /tmp/xxx/repo, so worktree should be at /tmp/xxx/worktrees/feature-auth
+ let expected_path = test
+ .bare_repo_path()
+ .parent()
+ .unwrap()
+ .join("worktrees")
+ .join("feature-auth");
+ assert!(
+ expected_path.exists(),
+ "Expected worktree at {:?} (using repo_path variable)",
+ expected_path
+ );
+}
+
#[rstest]
fn test_bare_repo_equivalent_to_normal_repo(repo: TestRepo) {
// This test verifies that bare repos behave identically to normal repos
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 ad48ec0bc..c7a16a189 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -12,10 +12,13 @@ info:
GIT_EDITOR: ""
LANG: C
LC_ALL: C
+ PSModulePath: ""
RUST_LOG: warn
SHELL: ""
TERM: alacritty
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
WT_TEST_DELAYED_STREAM_MS: "-1"
WT_TEST_EPOCH: "1735776000"
@@ -61,32 +64,31 @@ Creates ~/.config/worktrunk/config.toml with the following content:
#
# ## Worktree path template
#
- # Controls where new worktrees are created. Paths are relative to the repository root.
+ # Controls where new worktrees are created.
#
# **Variables:**
#
- # - `{{ repo }}` — repository directory name
+ # - `{{ repo_path }}` — absolute path to the repository (e.g., `/Users/me/code/myproject`)
+ # - `{{ repo }}` — repository directory name (e.g., `myproject`)
# - `{{ branch }}` — raw branch name (e.g., `feature/auth`)
# - `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)
# - `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)
#
# **Examples** for repo at `~/code/myproject`, branch `feature/auth`:
#
- # # Default — siblings in parent directory
+ # # Default — sibling directory
# # Creates: ~/code/myproject.feature-auth
- # worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
+ # # worktree-path = "{{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}"
#
# # Inside the repository
# # Creates: ~/code/myproject/.worktrees/feature-auth
- # worktree-path = ".worktrees/{{ branch | sanitize }}"
+ # worktree-path = "{{ repo_path }}/.worktrees/{{ branch | sanitize }}"
#
- # # Namespaced (useful when multiple repos share a parent directory)
- # # Creates: ~/code/worktrees/myproject/feature-auth
- # worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"
+ # # Centralized worktrees directory
+ # # Creates: ~/worktrees/myproject/feature-auth
+ # worktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"
#
- # # Nested bare repo (git clone --bare <url> project/.git)
- # # Creates: ~/code/project/feature-auth (sibling to .git)
- # worktree-path = "../{{ branch | sanitize }}"
+ # `~` expands to the home directory. Relative paths are relative to the repository root.
#
# ## LLM commit messages
#
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 a0a4aed04..a7613c1a1 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -11,11 +11,13 @@ info:
GIT_EDITOR: ""
LANG: C
LC_ALL: C
+ PSModulePath: ""
RUST_LOG: warn
SHELL: ""
TERM: alacritty
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
WT_TEST_DELAYED_STREAM_MS: "-1"
WT_TEST_EPOCH: "1735776000"
@@ -106,32 +108,31 @@ Location:
Worktree path template
-Controls where new worktrees are created. Paths are relative to the repository root.
+Controls where new worktrees are created.
Variables:
-- {{ repo }} — repository directory name
+- {{ repo_path }} — absolute path to the repository (e.g., /Users/me/code/myproject)
+- {{ repo }} — repository directory name (e.g., myproject)
- {{ branch }} — raw branch name (e.g., feature/auth)
- {{ branch | sanitize }} — filesystem-safe: / and \ become - (e.g., feature-auth)
- {{ branch | sanitize_db }} — database-safe: lowercase, underscores, hash suffix (e.g., feature_auth_x7k)
Examples for repo at ~/code/myproject, branch feature/auth:
- # Default — siblings in parent directory
+ # Default — sibling directory
# Creates: ~/code/myproject.feature-auth
- worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
+ # worktree-path = "{{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}"

# Inside the repository
# Creates: ~/code/myproject/.worktrees/feature-auth
- worktree-path = ".worktrees/{{ branch | sanitize }}"
- 
- # Namespaced (useful when multiple repos share a parent directory)
- # Creates: ~/code/worktrees/myproject/feature-auth
- worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"
+ worktree-path = "{{ repo_path }}/.worktrees/{{ branch | sanitize }}"

- # Nested bare repo (git clone --bare <url> project/.git)
- # Creates: ~/code/project/feature-auth (sibling to .git)
- worktree-path = "../{{ branch | sanitize }}"
+ # Centralized worktrees directory
+ # Creates: ~/worktrees/myproject/feature-auth
+ worktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"
+
+~ expands to the home directory. Relative paths are relative to the repository root.
LLM commit messages
diff --git a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_verbose_output.snap b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_verbose_output.snap
index 0c1302dad..fd72de92b 100644
--- a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_verbose_output.snap
+++ b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_verbose_output.snap
@@ -22,11 +22,14 @@ info:
LC_ALL: C
MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
PATH: "[PATH]"
+ PSModulePath: ""
RUST_LOG: warn
SHELL: ""
TERM: alacritty
USERPROFILE: "[TEST_HOME]"
WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
WT_TEST_DELAYED_STREAM_MS: "-1"
WT_TEST_EPOCH: "1735776000"
@@ -38,7 +41,7 @@ exit_code: 0
----- stderr -----
○ Expanding worktree-path
-  ../{{ repo }}.{{ branch | sanitize }} → ../repo.feature
+  {{ repo_path }}/../{{ repo }}.{{ branch | sanitize }} → _REPO_/../repo.feature
✓ Created branch feature from main and worktree @ _REPO_.feature
↳ To customize worktree locations, run wt config create
▲ Cannot change directory — shell integration not installed
diff --git a/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_multiline_template.snap b/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_multiline_template.snap
index 95ff31dac..900cc4add 100644
--- a/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_multiline_template.snap
+++ b/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_multiline_template.snap
@@ -24,11 +24,14 @@ info:
LC_ALL: C
MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
PATH: "[PATH]"
+ PSModulePath: ""
RUST_LOG: warn
SHELL: ""
TERM: alacritty
USERPROFILE: "[TEST_HOME]"
WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
WT_TEST_DELAYED_STREAM_MS: "-1"
WT_TEST_EPOCH: "1735776000"
@@ -42,7 +45,7 @@ repo=repo
----- stderr -----
○ Expanding worktree-path
-  ../{{ repo }}.{{ branch | sanitize }} → ../repo.multiline-test
+  {{ repo_path }}/../{{ repo }}.{{ branch | sanitize }} → _REPO_/../repo.multiline-test
✓ Created branch multiline-test from main and worktree @ _REPO_.multiline-test
↳ To customize worktree locations, run wt config create
▲ Cannot change directory — shell integration not installed
diff --git a/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_template.snap b/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_template.snap
index 8769140ee..a7feb8191 100644
--- a/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_template.snap
+++ b/tests/snapshots/integration__integration_tests__switch__switch_execute_verbose_template.snap
@@ -24,11 +24,14 @@ info:
LC_ALL: C
MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
PATH: "[PATH]"
+ PSModulePath: ""
RUST_LOG: warn
SHELL: ""
TERM: alacritty
USERPROFILE: "[TEST_HOME]"
WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
WT_TEST_DELAYED_STREAM_MS: "-1"
WT_TEST_EPOCH: "1735776000"
@@ -41,7 +44,7 @@ branch=verbose-test
----- stderr -----
○ Expanding worktree-path
-  ../{{ repo }}.{{ branch | sanitize }} → ../repo.verbose-test
+  {{ repo_path }}/../{{ repo }}.{{ branch | sanitize }} → _REPO_/../repo.verbose-test
✓ Created branch verbose-test from main and worktree @ _REPO_.verbose-test
↳ To customize worktree locations, run wt config create
▲ Cannot change directory — shell integration not installed