Skip to content

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

feat(config): Add project example and clarify configs

Maximilian Roos48e5ee3f9303
diff --git a/.config/wt.example.toml b/.config/wt.example.toml
new file mode 100644
index 000000000..3b7cabc04
--- /dev/null
+++ b/.config/wt.example.toml
@@ -0,0 +1,125 @@
+# Worktrunk Project Configuration
+# Location: <repo>/.config/wt.toml
+#
+# This file defines project-specific commands that run automatically during
+# worktree operations. It should be checked into git and shared across all
+# developers working on the project.
+
+# Available template variables (all commands):
+# {repo} - Repository name (e.g., "my-project")
+# {branch} - Branch name (slashes replaced with dashes)
+# {worktree} - Absolute path to the worktree
+# {repo_root} - Absolute path to the repository root
+#
+# Merge-related commands also support:
+# {target} - Target branch for the merge (e.g., "main")
+
+# Post-Create Commands
+# Runs SEQUENTIALLY and BLOCKS until complete
+# Use for: npm install, bundle install, build, essential setup
+# The worktree switch won't complete until these finish
+# Commands run one after another in the worktree directory
+#
+# Format options:
+# 1. Single string:
+# post-create-command = "npm install"
+#
+# 2. Array (runs sequentially):
+# post-create-command = ["npm install", "npm run build"]
+#
+# 3. Named table (runs sequentially in declaration order):
+# [post-create-command]
+# install = "npm install --frozen-lockfile"
+# build = "npm run build"
+
+# Post-Start Commands
+# Runs in BACKGROUND as detached processes (parallel)
+# Use for: dev servers, file watchers, long-running tasks
+# The worktree switch completes immediately, these run in parallel
+# Output is logged to ~/.cache/worktrunk/logs/{repo}/{branch}/{command}.log
+#
+# Format options:
+# 1. Single string:
+# post-start-command = "npm run dev"
+#
+# 2. Array (runs in parallel):
+# post-start-command = ["npm run dev", "npm run watch"]
+#
+# 3. Named table (runs in parallel):
+# [post-start-command]
+# server = "npm run dev"
+# watch = "npm run watch"
+
+# Pre-Commit Commands
+# Runs SEQUENTIALLY before committing changes (blocking, fail-fast)
+# All commands must exit with code 0 for commit to proceed
+# Use for: formatters, linters, quick validation
+#
+# Format options same as post-create-command
+# pre-commit-command = "cargo fmt -- --check"
+#
+# Or multiple:
+# [pre-commit-command]
+# format = "cargo fmt -- --check"
+# lint = "cargo clippy -- -D warnings"
+
+# Pre-Squash Commands
+# Runs SEQUENTIALLY before squashing commits (blocking, fail-fast)
+# All commands must exit with code 0 for squash to proceed
+# Use for: validation before combining commits
+#
+# Format options same as post-create-command
+# pre-squash-command = "cargo test"
+
+# Pre-Merge Commands
+# Runs SEQUENTIALLY before merging to target branch (blocking, fail-fast)
+# All commands must exit with code 0 for merge to proceed
+# Use for: tests, linters, build verification before merging
+#
+# Format options same as post-create-command
+# pre-merge-command = ["cargo test", "cargo build"]
+#
+# Or named:
+# [pre-merge-command]
+# test = "cargo test"
+# build = "cargo build --release"
+
+# Post-Merge Commands
+# Runs SEQUENTIALLY in the main worktree after successful merge (blocking)
+# Runs after push succeeds but before cleanup
+# Use for: updating production builds, notifications, cleanup
+#
+# Format options same as post-create-command
+# post-merge-command = "cargo install --path ."
+
+# Example: Node.js Project
+# [post-create-command]
+# install = "npm ci"
+#
+# [post-start-command]
+# server = "npm run dev"
+#
+# [pre-merge-command]
+# lint = "npm run lint"
+# test = "npm test"
+
+# Example: Rust Project
+# [post-create-command]
+# build = "cargo build"
+#
+# [pre-merge-command]
+# format = "cargo fmt -- --check"
+# clippy = "cargo clippy -- -D warnings"
+# test = "cargo test"
+#
+# post-merge-command = "cargo install --path ."
+
+# Example: Python Project
+# [post-create-command]
+# venv = "python -m venv .venv"
+# install = ".venv/bin/pip install -r requirements.txt"
+#
+# [pre-merge-command]
+# format = ".venv/bin/black --check ."
+# lint = ".venv/bin/ruff check ."
+# test = ".venv/bin/pytest"
diff --git a/config.example.toml b/config.example.toml
index b19df9953..1352d9d25 100644
--- a/config.example.toml
+++ b/config.example.toml
@@ -92,29 +92,9 @@ worktree-path = "../{main-worktree}.{branch}"
# Supports ~ expansion: ~/.config/worktrunk/squash-template.txt
# squash-template-file = "~/.config/worktrunk/squash-template.txt"
-# Project Commands (Optional)
-# Define commands that run automatically when creating/switching worktrees
-# Place in `.config/wt.toml` in your repository root
-#
-# post-create-command: Runs SEQUENTIALLY and BLOCKS until complete
-# - Use for: npm install, bundle install, build, essential setup
-# - The worktree switch won't complete until these finish
-# - Commands run one after another in the worktree directory
-# - Example:
-# [project.post-create-command]
-# "install" = "npm install --frozen-lockfile"
-# "build" = "npm run build"
-#
-# post-start-command: Runs in BACKGROUND as detached processes
-# - Use for: dev servers, file watchers, long-running tasks
-# - The worktree switch completes immediately, these run in parallel
-# - Output is logged to ~/.cache/worktrunk/logs/{repo}/{branch}/{command}.log
-# - Example:
-# [project.post-start-command]
-# "server" = "npm run dev"
-# "watch" = "npm run watch"
-#
-# See README.md for complete documentation on all hook types
+# NOTE: For project-specific commands (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
# Approved Commands
# Commands approved for automatic execution after switching worktrees
diff --git a/src/config.rs b/src/config.rs
index c1143acb9..4a694e62c 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -1,3 +1,42 @@
+//! Configuration system for worktrunk
+//!
+//! Worktrunk has two independent configuration files:
+//!
+//! # User Config (~/.config/worktrunk/config.toml)
+//!
+//! **Purpose**: Personal preferences, not checked into git
+//!
+//! **Settings**:
+//! - `worktree-path` - Template for worktree paths (relative to repo root)
+//! - `commit-generation` - LLM command and templates for commit messages
+//! - `approved-commands` - Commands approved for automatic execution
+//!
+//! **Managed by**: Each developer maintains their own user config
+//!
+//! # Project Config (<repo>/.config/wt.toml)
+//!
+//! **Purpose**: Project-specific hooks and commands, checked into git
+//!
+//! **Settings**:
+//! - `post-create-command` - Sequential blocking commands when creating worktree
+//! - `post-start-command` - Parallel background commands after worktree created
+//! - `pre-commit-command` - Validation before committing
+//! - `pre-squash-command` - Validation before squashing commits
+//! - `pre-merge-command` - Validation before merging
+//! - `post-merge-command` - Cleanup after successful merge
+//!
+//! **Managed by**: Checked into the repository, shared across all developers
+//!
+//! # Configuration Model
+//!
+//! The two configs are **completely independent**:
+//! - No overlap in settings (they configure different things)
+//! - No merging or precedence rules needed
+//! - Loaded separately and used in different contexts
+//!
+//! User config controls "how worktrunk behaves for me", project config controls
+//! "what commands run for this project".
+
use config::{Config, ConfigError, File};
use serde::{Deserialize, Serialize};
use std::path::PathBuf;
@@ -6,7 +45,10 @@ use toml;
#[cfg(not(test))]
use etcetera::base_strategy::{BaseStrategy, choose_base_strategy};
-/// Configuration for worktree path formatting and LLM integration.
+/// User-level configuration for worktree path formatting and LLM integration.
+///
+/// This config is stored at `~/.config/worktrunk/config.toml` (or platform equivalent)
+/// and is NOT checked into git. Each developer maintains their own user config.
///
/// The `worktree-path` template is relative to the repository root.
/// Supported variables:
@@ -82,7 +124,11 @@ pub struct CommitGenerationConfig {
pub squash_template_file: Option<String>,
}
-/// Project-specific configuration (stored in .config/wt.toml within the project)
+/// Project-specific configuration with hooks and commands.
+///
+/// This config is stored at `<repo>/.config/wt.toml` within the repository and
+/// IS checked into git. It defines project-specific commands that run automatically
+/// during worktree operations. All developers working on the project share this config.
///
/// # Template Variables
///