Skip to content

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

docs: Update config example paths and options

Maximilian Roosb5ff056368f6
diff --git a/.claude-plugin/skills/worktrunk/reference/project-config.md b/.claude-plugin/skills/worktrunk/reference/project-config.md
index f16693df2..6e586053d 100644
--- a/.claude-plugin/skills/worktrunk/reference/project-config.md
+++ b/.claude-plugin/skills/worktrunk/reference/project-config.md
@@ -459,4 +459,4 @@ wt switch --create test-hooks # Test hooks work
## Example Config
-See `.config/wt.example.toml` in the worktrunk repository for a complete annotated example.
+See `dev/wt.example.toml` in the worktrunk repository for a complete annotated example.
diff --git a/.claude-plugin/skills/worktrunk/reference/user-config.md b/.claude-plugin/skills/worktrunk/reference/user-config.md
index 0fd89f891..070cbfb97 100644
--- a/.claude-plugin/skills/worktrunk/reference/user-config.md
+++ b/.claude-plugin/skills/worktrunk/reference/user-config.md
@@ -117,12 +117,6 @@ worktree-path = ".worktrees/{{ branch }}"
```
Result: `~/code/myproject/.worktrees/feature-auth`
-Shared directory:
-```toml
-worktree-path = "../worktrees/{{ main_worktree }}/{{ branch }}"
-```
-Result: `~/code/worktrees/myproject/feature-auth`
-
</example>
### Workflow
@@ -226,9 +220,8 @@ squash-template = "..."
squash-template-file = "~/.config/worktrunk/squash-template.txt"
# Approved Commands (auto-populated by wt switch --execute --force)
-[[approved-commands]]
-project = "github.com/user/repo"
-command = "npm install"
+[projects."github.com/user/repo"]
+approved-commands = ["npm install"]
```
## Troubleshooting
@@ -270,4 +263,4 @@ wt config --help # Show LLM setup guide
## Example Config
-See `config.example.toml` in the worktrunk repository for a complete annotated example.
+See `dev/config.example.toml` in the worktrunk repository for a complete annotated example.
diff --git a/dev/config.example.toml b/dev/config.example.toml
index c6f1d15d7..3d72cedb2 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -1,9 +1,9 @@
# Worktrunk Global Configuration
-# Location (XDG Base Directory spec):
-# macOS/Linux: ~/.config/worktrunk/config.toml (or $XDG_CONFIG_HOME/worktrunk/config.toml)
-# Windows: %APPDATA%\worktrunk\config.toml
+# Copy to: ~/.config/worktrunk/config.toml (or use `wt config create`)
#
-# Generate with: wt config create
+# Alternative locations (XDG Base Directory spec):
+# macOS/Linux: $XDG_CONFIG_HOME/worktrunk/config.toml
+# Windows: %APPDATA%\worktrunk\config.toml
# Commit Message Generation (Optional)
# For generating commit messages during merge operations (wt merge)
@@ -18,18 +18,31 @@ args = ["-m", "claude-haiku-4.5"]
# command = "aichat"
# args = ["-m", "claude:claude-haiku-4.5"]
+# Optional: Load template from file (mutually exclusive with 'template')
+# Supports ~ expansion: ~/.config/worktrunk/commit-template.txt
+# template-file = "~/.config/worktrunk/commit-template.txt"
+
+# Optional: Load squash template from file (mutually exclusive with 'squash-template')
+# Supports ~ expansion: ~/.config/worktrunk/squash-template.txt
+# squash-template-file = "~/.config/worktrunk/squash-template.txt"
+
+# See "Custom Prompt Templates" section at end of file for inline template options.
+
# Worktree Path Template
-# Variables: {{ main_worktree }} = main worktree directory name, {{ branch }} = branch name
-# Branch slashes are replaced with dashes (feature/auth → feature-auth)
-# Paths are relative to the main worktree root (original repository directory)
+# Variables:
+# {{ main_worktree }} - Main worktree directory name (e.g., "myproject")
+# {{ branch }} - Branch name with slashes replaced by dashes (feature/auth → feature-auth)
+#
+# Paths are relative to the main worktree root (original repository directory).
+#
+# Example paths created (main worktree at /Users/dev/myproject, branch feature/auth):
+# "../{{ main_worktree }}.{{ branch }}" → /Users/dev/myproject.feature-auth
+# ".worktrees/{{ branch }}" → /Users/dev/myproject/.worktrees/feature-auth
worktree-path = "../{{ main_worktree }}.{{ branch }}"
# Alternative: Inside repo (useful for bare repos)
# worktree-path = ".worktrees/{{ branch }}"
-# Alternative: Shared directory for multiple repos
-# worktree-path = "../worktrees/{{ main_worktree }}/{{ branch }}"
-
# List Command Defaults
# Configure default behavior for `wt list`
[list]
@@ -45,30 +58,24 @@ stage = "all" # What to stage: "all", "tracked", or "none"
# Note: `stage` defaults from [commit] section above
[merge]
squash = true # Squash commits when merging
-commit = true # Create commit after merge
+commit = true # Commit, squash, and rebase during merge
remove = true # Remove worktree after merge
verify = true # Run project hooks
# Approved Commands
# Commands approved for automatic execution after switching worktrees
# Auto-populated when you use: wt switch --execute "command" --force
-[[approved-commands]]
-project = "github.com/user/repo"
-command = "npm install"
+[projects."github.com/user/repo"]
+approved-commands = ["npm install"]
# NOTE: For project-specific hooks (post-create, post-start, pre-merge, etc.),
# use a separate PROJECT config file at <repo>/.config/wt.toml
-# See: .config/wt.example.toml for project configuration examples
-
-# Optional: Load template from file (mutually exclusive with 'template')
-# Supports ~ expansion: ~/.config/worktrunk/commit-template.txt
-# template-file = "~/.config/worktrunk/commit-template.txt"
-
-# Optional: Load squash template from file (mutually exclusive with 'squash-template')
-# Supports ~ expansion: ~/.config/worktrunk/squash-template.txt
-# squash-template-file = "~/.config/worktrunk/squash-template.txt"
+# See: dev/wt.example.toml for project configuration examples
+# ============================================================================
# Custom Prompt Templates (Advanced)
+# ============================================================================
+# These options belong under [commit-generation] section above.
# NOTE: Templates are synced from src/llm.rs by `cargo test readme_sync`
# Optional: Custom prompt template (inline) - Uses minijinja syntax
diff --git a/.config/wt.example.toml b/dev/wt.example.toml
similarity index 98%
rename from .config/wt.example.toml
rename to dev/wt.example.toml
index 1c5b09ccb..92d06d184 100644
--- a/.config/wt.example.toml
+++ b/dev/wt.example.toml
@@ -1,5 +1,5 @@
# Worktrunk Project Configuration
-# Location: <repo>/.config/wt.toml
+# Copy to: <repo>/.config/wt.toml
#
# This file defines project-specific hooks that run automatically during
# worktree operations. It should be checked into git and shared across all
diff --git a/src/config/user.rs b/src/config/user.rs
index 497b1380e..e38876af9 100644
--- a/src/config/user.rs
+++ b/src/config/user.rs
@@ -225,7 +225,7 @@ pub struct MergeConfig {
#[serde(skip_serializing_if = "Option::is_none")]
pub squash: Option<bool>,
- /// Create commit after merge (default: true)
+ /// Commit, squash, and rebase during merge (default: true)
#[serde(skip_serializing_if = "Option::is_none")]
pub commit: Option<bool>,
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 0f2af4916..eba04845c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -39,11 +39,11 @@ Usage: wt config create [OPTIONS]
Creates ~/.config/worktrunk/config.toml with the following content:
# Worktrunk Global Configuration
- # Location (XDG Base Directory spec):
- # macOS/Linux: ~/.config/worktrunk/config.toml (or $XDG_CONFIG_HOME/worktrunk/config.toml)
- # Windows: %APPDATA%\worktrunk\config.toml
+ # Copy to: ~/.config/worktrunk/config.toml (or use `wt config create`)
#
- # Generate with: wt config create
+ # Alternative locations (XDG Base Directory spec):
+ # macOS/Linux: $XDG_CONFIG_HOME/worktrunk/config.toml
+ # Windows: %APPDATA%\worktrunk\config.toml

# Commit Message Generation (Optional)
# For generating commit messages during merge operations (wt merge)
@@ -58,18 +58,31 @@ Creates ~/.config/worktrunk/config.toml with the following content:
# command = "aichat"
# args = ["-m", "claude:claude-haiku-4.5"]

+ # Optional: Load template from file (mutually exclusive with 'template')
+ # Supports ~ expansion: ~/.config/worktrunk/commit-template.txt
+ # template-file = "~/.config/worktrunk/commit-template.txt"
+ 
+ # Optional: Load squash template from file (mutually exclusive with 'squash-template')
+ # Supports ~ expansion: ~/.config/worktrunk/squash-template.txt
+ # squash-template-file = "~/.config/worktrunk/squash-template.txt"
+ 
+ # See "Custom Prompt Templates" section at end of file for inline template options.
+ 
# Worktree Path Template
- # Variables: {{ main_worktree }} = main worktree directory name, {{ branch }} = branch name
- # Branch slashes are replaced with dashes (feature/auth → feature-auth)
- # Paths are relative to the main worktree root (original repository directory)
+ # Variables:
+ # {{ main_worktree }} - Main worktree directory name (e.g., "myproject")
+ # {{ branch }} - Branch name with slashes replaced by dashes (feature/auth → feature-auth)
+ #
+ # Paths are relative to the main worktree root (original repository directory).
+ #
+ # Example paths created (main worktree at /Users/dev/myproject, branch feature/auth):
+ # "../{{ main_worktree }}.{{ branch }}" → /Users/dev/myproject.feature-auth
+ # ".worktrees/{{ branch }}" → /Users/dev/myproject/.worktrees/feature-auth
worktree-path = "../{{ main_worktree }}.{{ branch }}"

# Alternative: Inside repo (useful for bare repos)
# worktree-path = ".worktrees/{{ branch }}"

- # Alternative: Shared directory for multiple repos
- # worktree-path = "../worktrees/{{ main_worktree }}/{{ branch }}"
- 
# List Command Defaults
# Configure default behavior for `wt list`
[list]
@@ -85,30 +98,24 @@ Creates ~/.config/worktrunk/config.toml with the following content:
# Note: `stage` defaults from [commit] section above
[merge]
squash = true # Squash commits when merging
- commit = true # Create commit after merge
+ commit = true # Commit, squash, and rebase during merge
remove = true # Remove worktree after merge
verify = true # Run project hooks

# Approved Commands
# Commands approved for automatic execution after switching worktrees
# Auto-populated when you use: wt switch --execute "command" --force
- [[approved-commands]]
- project = "github.com/user/repo"
- command = "npm install"
+ [projects."github.com/user/repo"]
+ approved-commands = ["npm install"]

# NOTE: For project-specific hooks (post-create, post-start, pre-merge, etc.),
# use a separate PROJECT config file at <repo>/.config/wt.toml
- # See: .config/wt.example.toml for project configuration examples
- 
- # Optional: Load template from file (mutually exclusive with 'template')
- # Supports ~ expansion: ~/.config/worktrunk/commit-template.txt
- # template-file = "~/.config/worktrunk/commit-template.txt"
- 
- # Optional: Load squash template from file (mutually exclusive with 'squash-template')
- # Supports ~ expansion: ~/.config/worktrunk/squash-template.txt
- # squash-template-file = "~/.config/worktrunk/squash-template.txt"
+ # See: dev/wt.example.toml for project configuration examples

+ # ============================================================================
# Custom Prompt Templates (Advanced)
+ # ============================================================================
+ # These options belong under [commit-generation] section above.
# NOTE: Templates are synced from src/llm.rs by `cargo test readme_sync`

# Optional: Custom prompt template (inline) - Uses minijinja syntax