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.tomlnew file mode 100644index 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.tomlindex 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 worktreesdiff --git a/src/config.rs b/src/config.rsindex 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///