Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Auto-generate wt.example.toml from mod.rs source (#1835)
Maximilian Roos75dd8942844b
diff --git a/dev/wt.example.toml b/dev/wt.example.tomlindex dc27c616f..5e431b19c 100644--- a/dev/wt.example.toml+++ b/dev/wt.example.toml@@ -1,110 +1,54 @@-# Worktrunk Project Configuration-# Copy to: <repo>/.config/wt.toml-#-# Project-specific hooks that run automatically during worktree operations.-# Check this file into git to share hooks across all developers.--# ============================================================================-# Hook Formats-# ============================================================================-# All hooks support two formats:-#-# Single command:-# pre-start = "npm install"-#-# Named table (multiple commands):-# [pre-start]-# deps = "npm install"-# build = "npm run build"-#-# Named commands appear in output, making it easier to identify failures.--# ============================================================================-# Template Variables — see https://worktrunk.dev/hook/#template-variables-# ============================================================================-# Common variables:-# {{ repo }} - Repository directory name (e.g., "myproject")-# {{ branch }} - Branch name (e.g., "feature/auth")-# {{ worktree_path }} - Absolute path to 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)-#-# Filters:-# {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")-# {{ branch | sanitize_db }} - Database-safe identifier with hash suffix (e.g., "feature_auth_x7k")-# {{ branch | hash_port }} - Deterministic port 10000-19999--# ============================================================================-# Hooks-# ============================================================================--# Pre-Start: Runs after worktree creation, BLOCKS until complete-# Use for: installing dependencies, setting up databases, copying configs-#-# [pre-start]-# deps = "npm ci"-# env = "cp .env.example .env"--# Post-Start: Runs in BACKGROUND after worktree creation (parallel)-# Use for: dev servers, file watchers, background builds-# Output logged to .git/wt/logs/{branch}-project-post-start-{name}.log-#-# [post-start]-# server = "npm run dev -- --port {{ branch | hash_port }}"-# watch = "npm run watch"--# Post-Switch: Runs in BACKGROUND after every switch (parallel)-# Use for: terminal tab naming, tmux window titles, IDE notifications-#-# post-switch = "echo -ne '\\033]0;{{ branch }}\\007'"--# Pre-Commit: Runs before committing during merge, BLOCKS (fail-fast)-# Use for: formatters, linters, quick checks-#-# [pre-commit]-# format = "npm run format:check"-# lint = "npm run lint"--# Pre-Merge: Runs before merging to target, BLOCKS (fail-fast)-# Use for: tests, build verification+# # Project Configuration#+# Create with `wt config create --project`.+#+# Location: `.config/wt.toml` (checked into version control and shared with the team).+#+# ## Hooks+#+# See `wt hook --help` for hook types, execution order, template variables, and examples. Both project and user configs support hooks in the same format:+#+# # Single command+# pre-start = "npm ci"+#+# # Multiple named commands (concurrent for post-*, sequential for pre-*)# [pre-merge]# test = "npm test"# build = "npm run build"--# Post-Merge: Runs after successful merge, BLOCKS-# Use for: deployment, notifications-#-# post-merge = "echo 'Merged {{ branch }} to {{ target }}'"--# Pre-Remove: Runs before worktree removal, BLOCKS (fail-fast)-# Use for: cleanup, stopping services-#-# pre-remove = "docker compose down"--# ============================================================================-# Aliases (experimental) — run with `wt step <name>`-# ============================================================================-# Command templates that support the same variables as hooks.-# Project-config aliases require command approval on first run.#-# [aliases]-# deploy = "make deploy BRANCH={{ branch }}"-# url = "echo http://localhost:{{ branch | hash_port }}"--# ============================================================================-# Dev Server URL (shown in `wt list`)-# ============================================================================+# # Pipeline — list of maps, run in order (each map concurrent)+# post-start = [+# { install = "npm ci" },+# { build = "npm run build", server = "npm run dev" }+# ]+#+# ## Dev server URL+#+# # URL column in wt list (dimmed when port not listening)# [list]# url = "http://localhost:{{ branch | hash_port }}"--# ============================================================================-# Forge (GitHub/GitLab) Settings-# ============================================================================-# Override platform detection for SSH host aliases or custom domains.-# Set hostname for GitHub Enterprise or self-hosted GitLab API calls.#+# ## Forge platform override+#+# # Override platform detection for SSH aliases or self-hosted instances# [forge]-# platform = "github" # or "gitlab"-# hostname = "github.example.com" # API host (GHE / self-hosted GitLab)+# platform = "github" # or "gitlab"+# # hostname = "github.example.com" # API host (GHE / self-hosted GitLab)+#+# ## Copy-ignored excludes+#+# # Add more gitignored excludes for wt step copy-ignored+# [step.copy-ignored]+# exclude = [".cache/", ".turbo/"]+#+# Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.pi/`, `.worktrees/`). User config and project config exclusions are combined.+#+# ## Aliases+#+# Command templates that run with `wt step <name>`. See `wt step` aliases (https://worktrunk.dev/step/#aliases) for usage and flags.+#+# [aliases]+# deploy = "make deploy BRANCH={{ branch }}"+# url = "echo http://localhost:{{ branch | hash_port }}"+#+# Aliases defined here are shared with teammates. For personal aliases, use the user config (https://worktrunk.dev/config/#aliases) `[aliases]` section instead.diff --git a/docs/content/config.md b/docs/content/config.mdindex 4b5a9deac..4d6de6c10 100644--- a/docs/content/config.md+++ b/docs/content/config.md@@ -343,37 +343,73 @@ squash-template = """```<!-- DEFAULT_SQUASH_TEMPLATE_END --><!-- USER_CONFIG_END -->-+<!-- PROJECT_CONFIG_START --># Project Configuration-Project config (`.config/wt.toml`) defines lifecycle hooks and project-specific settings. This file is checked into version control and shared with the team. Create with `wt config create --project`.+Create with `wt config create --project`.++Location: `.config/wt.toml` (checked into version control and shared with the team).-See [`wt hook`](@/hook.md) for hook types, execution order, template variables, and examples.+## Hooks-### Non-hook settings+See `wt hook --help` for hook types, execution order, template variables, and examples. Both project and user configs support hooks in the same format:```toml-# .config/wt.toml+# Single command+pre-start = "npm ci"+# Multiple named commands (concurrent for post-*, sequential for pre-*)+[pre-merge]+test = "npm test"+build = "npm run build"++# Pipeline — list of maps, run in order (each map concurrent)+post-start = [+ { install = "npm ci" },+ { build = "npm run build", server = "npm run dev" }+]+```++## Dev server URL++```toml# URL column in wt list (dimmed when port not listening)[list]url = "http://localhost:{{ branch | hash_port }}"+```++## Forge platform override+```toml# Override platform detection for SSH aliases or self-hosted instances[forge]platform = "github" # or "gitlab"# hostname = "github.example.com" # API host (GHE / self-hosted GitLab)+```++## Copy-ignored excludes+```toml# Add more gitignored excludes for wt step copy-ignored[step.copy-ignored]exclude = [".cache/", ".turbo/"]+```++Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.pi/`, `.worktrees/`). User config and project config exclusions are combined.-# Command aliases (run with wt step <name>)+## Aliases++Command templates that run with `wt step <name>`. See [`wt step` aliases](@/step.md#aliases) for usage and flags.++```toml[aliases]deploy = "make deploy BRANCH={{ branch }}"-test = "cargo test"+url = "echo http://localhost:{{ branch | hash_port }}"```+Aliases defined here are shared with teammates. For personal aliases, use the [user config](@/config.md#aliases) `[aliases]` section instead.+<!-- PROJECT_CONFIG_END -->+# Shell IntegrationWorktrunk needs shell integration to change directories when switching worktrees. Install with:diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.mdindex 1be0c5f9b..f038835b9 100644--- a/skills/worktrunk/reference/config.md+++ b/skills/worktrunk/reference/config.md@@ -340,37 +340,73 @@ squash-template = """```<!-- DEFAULT_SQUASH_TEMPLATE_END --><!-- USER_CONFIG_END -->-+<!-- PROJECT_CONFIG_START --># Project Configuration-Project config (`.config/wt.toml`) defines lifecycle hooks and project-specific settings. This file is checked into version control and shared with the team. Create with `wt config create --project`.+Create with `wt config create --project`.++Location: `.config/wt.toml` (checked into version control and shared with the team).-See [`wt hook`](https://worktrunk.dev/hook/) for hook types, execution order, template variables, and examples.+## Hooks-### Non-hook settings+See `wt hook --help` for hook types, execution order, template variables, and examples. Both project and user configs support hooks in the same format:```toml-# .config/wt.toml+# Single command+pre-start = "npm ci"+# Multiple named commands (concurrent for post-*, sequential for pre-*)+[pre-merge]+test = "npm test"+build = "npm run build"++# Pipeline — list of maps, run in order (each map concurrent)+post-start = [+ { install = "npm ci" },+ { build = "npm run build", server = "npm run dev" }+]+```++## Dev server URL++```toml# URL column in wt list (dimmed when port not listening)[list]url = "http://localhost:{{ branch | hash_port }}"+```++## Forge platform override+```toml# Override platform detection for SSH aliases or self-hosted instances[forge]platform = "github" # or "gitlab"# hostname = "github.example.com" # API host (GHE / self-hosted GitLab)+```++## Copy-ignored excludes+```toml# Add more gitignored excludes for wt step copy-ignored[step.copy-ignored]exclude = [".cache/", ".turbo/"]+```++Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.pi/`, `.worktrees/`). User config and project config exclusions are combined.-# Command aliases (run with wt step <name>)+## Aliases++Command templates that run with `wt step <name>`. See [`wt step` aliases](https://worktrunk.dev/step/#aliases) for usage and flags.++```toml[aliases]deploy = "make deploy BRANCH={{ branch }}"-test = "cargo test"+url = "echo http://localhost:{{ branch | hash_port }}"```+Aliases defined here are shared with teammates. For personal aliases, use the [user config](https://worktrunk.dev/config/#aliases) `[aliases]` section instead.+<!-- PROJECT_CONFIG_END -->+# Shell IntegrationWorktrunk needs shell integration to change directories when switching worktrees. Install with:diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 443697bed..de5b977da 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -1911,37 +1911,73 @@ squash-template = """```<!-- DEFAULT_SQUASH_TEMPLATE_END --><!-- USER_CONFIG_END -->-+<!-- PROJECT_CONFIG_START --># Project Configuration-Project config (`.config/wt.toml`) defines lifecycle hooks and project-specific settings. This file is checked into version control and shared with the team. Create with `wt config create --project`.+Create with `wt config create --project`.++Location: `.config/wt.toml` (checked into version control and shared with the team).-See [`wt hook`](@/hook.md) for hook types, execution order, template variables, and examples.+## Hooks-### Non-hook settings+See `wt hook --help` for hook types, execution order, template variables, and examples. Both project and user configs support hooks in the same format:```toml-# .config/wt.toml+# Single command+pre-start = "npm ci"++# Multiple named commands (concurrent for post-*, sequential for pre-*)+[pre-merge]+test = "npm test"+build = "npm run build"+# Pipeline — list of maps, run in order (each map concurrent)+post-start = [+ { install = "npm ci" },+ { build = "npm run build", server = "npm run dev" }+]+```++## Dev server URL++```toml# URL column in wt list (dimmed when port not listening)[list]url = "http://localhost:{{ branch | hash_port }}"+```+## Forge platform override++```toml# Override platform detection for SSH aliases or self-hosted instances[forge]platform = "github" # or "gitlab"# hostname = "github.example.com" # API host (GHE / self-hosted GitLab)+```++## Copy-ignored excludes+```toml# Add more gitignored excludes for wt step copy-ignored[step.copy-ignored]exclude = [".cache/", ".turbo/"]+```++Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.pi/`, `.worktrees/`). User config and project config exclusions are combined.-# Command aliases (run with wt step <name>)+## Aliases++Command templates that run with `wt step <name>`. See [`wt step` aliases](@/step.md#aliases) for usage and flags.++```toml[aliases]deploy = "make deploy BRANCH={{ branch }}"-test = "cargo test"+url = "echo http://localhost:{{ branch | hash_port }}"```+Aliases defined here are shared with teammates. For personal aliases, use the [user config](@/config.md#aliases) `[aliases]` section instead.+<!-- PROJECT_CONFIG_END -->+# Shell IntegrationWorktrunk needs shell integration to change directories when switching worktrees. Install with:diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex 6e11ccb5d..2d1f75da3 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -1,7 +1,8 @@//! README and config synchronization tests//!//! Verifies that README.md examples stay in sync with their source snapshots and help output.-//! Also syncs default templates from src/llm.rs to dev/config.example.toml.+//! Also syncs default templates from src/llm.rs to dev/config.example.toml+//! and generates dev/wt.example.toml from the project config section.//! Automatically updates sections when out of sync.//!//! Run with: `cargo test --test integration readme_sync`@@ -76,6 +77,12 @@ static USER_CONFIG_PATTERN: LazyLock<Regex> = LazyLock::new(|| {Regex::new(r"(?s)<!-- USER_CONFIG_START -->\n(.*?)\n<!-- USER_CONFIG_END -->").unwrap()});+/// Regex to extract project config section from src/cli/mod.rs+/// Matches content between PROJECT_CONFIG_START and PROJECT_CONFIG_END markers+static PROJECT_CONFIG_PATTERN: LazyLock<Regex> = LazyLock::new(|| {+ Regex::new(r"(?s)<!-- PROJECT_CONFIG_START -->\n(.*?)\n<!-- PROJECT_CONFIG_END -->").unwrap()+});+/// Regex to find DEFAULT_TEMPLATE marker in user config section (markdown format)static DEFAULT_TEMPLATE_PATTERN: LazyLock<Regex> = LazyLock::new(|| {Regex::new(r"(?s)(<!-- DEFAULT_TEMPLATE_START -->\n).*?(<!-- DEFAULT_TEMPLATE_END -->)")@@ -1055,45 +1062,73 @@ fn convert_markdown_links_for_config(line: &str) -> String {.to_string()}-/// Extract user config documentation from src/cli/mod.rs-///-/// The user config section is embedded in mod.rs between USER_CONFIG_START-/// and USER_CONFIG_END markers. This function extracts that content for-/// transforming into config.example.toml.-fn extract_user_config_from_cli(cli_mod_content: &str) -> String {- USER_CONFIG_PATTERN+/// Extract a config section from src/cli/mod.rs by marker pattern.+fn extract_config_section(cli_mod_content: &str, pattern: &Regex, label: &str) -> String {+ pattern.captures(cli_mod_content).and_then(|cap| cap.get(1)).map(|m| m.as_str().to_string())- .expect("USER_CONFIG_START/END markers not found in src/cli/mod.rs")+ .unwrap_or_else(|| panic!("{label} markers not found in src/cli/mod.rs"))}-#[test]-fn test_config_source_generates_example_toml() {- let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));- let cli_mod_path = project_root.join("src/cli/mod.rs");- let config_path = project_root.join("dev/config.example.toml");-- let cli_mod_content = fs::read_to_string(&cli_mod_path)- .unwrap_or_else(|e| panic!("Failed to read {}: {}", cli_mod_path.display(), e));-- let user_config_content = extract_user_config_from_cli(&cli_mod_content);- let expected = transform_config_source_to_toml(&user_config_content);- let expected = trim_lines(&expected);-- let current = fs::read_to_string(&config_path)- .unwrap_or_else(|e| panic!("Failed to read {}: {}", config_path.display(), e));+/// Verify a config example file is in sync with its source section in mod.rs.+///+/// If out of sync, overwrites the file and panics so CI fails.+fn assert_config_example_in_sync(+ cli_mod_content: &str,+ pattern: &Regex,+ marker_label: &str,+ example_path: &Path,+) {+ let source = extract_config_section(cli_mod_content, pattern, marker_label);+ let expected = trim_lines(&transform_config_source_to_toml(&source));++ let current = fs::read_to_string(example_path)+ .unwrap_or_else(|e| panic!("Failed to read {}: {}", example_path.display(), e));let current = trim_lines(¤t);if current != expected {- fs::write(&config_path, format!("{}\n", expected)).unwrap();+ fs::write(example_path, format!("{}\n", expected)).unwrap();panic!(- "config.example.toml out of sync with user config section in src/cli/mod.rs. \- Run tests locally and commit the changes."+ "{} out of sync with {} section in src/cli/mod.rs. \+ Run tests locally and commit the changes.",+ example_path.file_name().unwrap().to_string_lossy(),+ marker_label,);}}+#[test]+fn test_config_source_generates_example_toml() {+ let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));+ let cli_mod_content = fs::read_to_string(project_root.join("src/cli/mod.rs"))+ .unwrap_or_else(|e| panic!("Failed to read src/cli/mod.rs: {e}"));++ assert_config_example_in_sync(+ &cli_mod_content,+ &USER_CONFIG_PATTERN,+ "USER_CONFIG_START/END",+ &project_root.join("dev/config.example.toml"),+ );+}++// TODO: Evaluate whether pointing to `wt hook --help` is sufficient for the project+// config example, or whether it should include a slim hooks quick-start (formats ++// common examples) so the created file is more self-contained.+#[test]+fn test_project_config_source_generates_example_toml() {+ let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));+ let cli_mod_content = fs::read_to_string(project_root.join("src/cli/mod.rs"))+ .unwrap_or_else(|e| panic!("Failed to read src/cli/mod.rs: {e}"));++ assert_config_example_in_sync(+ &cli_mod_content,+ &PROJECT_CONFIG_PATTERN,+ "PROJECT_CONFIG_START/END",+ &project_root.join("dev/wt.example.toml"),+ );+}+/// Verify that all config section keys appear in the user config documentation.////// When a new config section is added (e.g., `[switch.picker]`), this test ensures@@ -1104,7 +1139,8 @@ fn test_config_docs_include_all_sections() {let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));let cli_mod_path = project_root.join("src/cli/mod.rs");let cli_mod_content = fs::read_to_string(&cli_mod_path).unwrap();- let user_config_content = extract_user_config_from_cli(&cli_mod_content);+ let user_config_content =+ extract_config_section(&cli_mod_content, &USER_CONFIG_PATTERN, "USER_CONFIG");// Config sections that MUST be documented (non-deprecated, non-hook table sections).// When adding a new config section, add it here — the test will fail if it'sdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snapindex 714cd6bb4..c50273a6e 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap@@ -306,113 +306,57 @@ Creates [2m~/.config/worktrunk/config.toml[0m with the following content:With [2m--project[0m, creates [2m.config/wt.toml[0m in the current repository:-[107m [0m [2m# Worktrunk Project Configuration[0m-[107m [0m [2m# Copy to: <repo>/.config/wt.toml[0m-[107m [0m [2m#[0m-[107m [0m [2m# Project-specific hooks that run automatically during worktree operations.[0m-[107m [0m [2m# Check this file into git to share hooks across all developers.[0m-[107m [0m [2m[0m-[107m [0m [2m# ============================================================================[0m-[107m [0m [2m# Hook Formats[0m-[107m [0m [2m# ============================================================================[0m-[107m [0m [2m# All hooks support two formats:[0m-[107m [0m [2m#[0m-[107m [0m [2m# Single command:[0m-[107m [0m [2m# pre-start = "npm install"[0m-[107m [0m [2m#[0m-[107m [0m [2m# Named table (multiple commands):[0m-[107m [0m [2m# [pre-start][0m-[107m [0m [2m# deps = "npm install"[0m-[107m [0m [2m# build = "npm run build"[0m-[107m [0m [2m#[0m-[107m [0m [2m# Named commands appear in output, making it easier to identify failures.[0m-[107m [0m [2m[0m-[107m [0m [2m# ============================================================================[0m-[107m [0m [2m# Template Variables — see https://worktrunk.dev/hook/#template-variables[0m-[107m [0m [2m# ============================================================================[0m-[107m [0m [2m# Common variables:[0m-[107m [0m [2m# {{ repo }} - Repository directory name (e.g., "myproject")[0m-[107m [0m [2m# {{ branch }} - Branch name (e.g., "feature/auth")[0m-[107m [0m [2m# {{ worktree_path }} - Absolute path to worktree[0m-[107m [0m [2m# {{ primary_worktree_path }} - Main worktree (or default branch worktree for bare repos)[0m-[107m [0m [2m# {{ default_branch }} - Default branch name (e.g., "main")[0m-[107m [0m [2m# {{ target }} - Target branch (merge hooks only)[0m-[107m [0m [2m#[0m-[107m [0m [2m# Filters:[0m-[107m [0m [2m# {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")[0m-[107m [0m [2m# {{ branch | sanitize_db }} - Database-safe identifier with hash suffix (e.g., "feature_auth_x7k")[0m-[107m [0m [2m# {{ branch | hash_port }} - Deterministic port 10000-19999[0m-[107m [0m [2m[0m-[107m [0m [2m# ============================================================================[0m-[107m [0m [2m# Hooks[0m-[107m [0m [2m# ============================================================================[0m-[107m [0m [2m[0m-[107m [0m [2m# Pre-Start: Runs after worktree creation, BLOCKS until complete[0m-[107m [0m [2m# Use for: installing dependencies, setting up databases, copying configs[0m-[107m [0m [2m#[0m-[107m [0m [2m# [pre-start][0m-[107m [0m [2m# deps = "npm ci"[0m-[107m [0m [2m# env = "cp .env.example .env"[0m-[107m [0m [2m[0m-[107m [0m [2m# Post-Start: Runs in BACKGROUND after worktree creation (parallel)[0m-[107m [0m [2m# Use for: dev servers, file watchers, background builds[0m-[107m [0m [2m# Output logged to .git/wt/logs/{branch}-project-post-start-{name}.log[0m-[107m [0m [2m#[0m-[107m [0m [2m# [post-start][0m-[107m [0m [2m# server = "npm run dev -- --port {{ branch | hash_port }}"[0m-[107m [0m [2m# watch = "npm run watch"[0m-[107m [0m [2m[0m-[107m [0m [2m# Post-Switch: Runs in BACKGROUND after every switch (parallel)[0m-[107m [0m [2m# Use for: terminal tab naming, tmux window titles, IDE notifications[0m-[107m [0m [2m#[0m-[107m [0m [2m# post-switch = "echo -ne '\\033]0;{{ branch }}\\007'"[0m-[107m [0m [2m[0m-[107m [0m [2m# Pre-Commit: Runs before committing during merge, BLOCKS (fail-fast)[0m-[107m [0m [2m# Use for: formatters, linters, quick checks[0m-[107m [0m [2m#[0m-[107m [0m [2m# [pre-commit][0m-[107m [0m [2m# format = "npm run format:check"[0m-[107m [0m [2m# lint = "npm run lint"[0m-[107m [0m [2m[0m-[107m [0m [2m# Pre-Merge: Runs before merging to target, BLOCKS (fail-fast)[0m-[107m [0m [2m# Use for: tests, build verification[0m+[107m [0m [2m# # Project Configuration[0m[107m [0m [2m#[0m+[107m [0m [2m# Create with `wt config create --project`.[0m+[107m [0m [2m#[0m+[107m [0m [2m# Location: `.config/wt.toml` (checked into version control and shared with the team).[0m+[107m [0m [2m#[0m+[107m [0m [2m# ## Hooks[0m+[107m [0m [2m#[0m+[107m [0m [2m# See `wt hook --help` for hook types, execution order, template variables, and examples. Both project and user configs support hooks in the same format:[0m+[107m [0m [2m#[0m+[107m [0m [2m# # Single command[0m+[107m [0m [2m# pre-start = "npm ci"[0m+[107m [0m [2m#[0m+[107m [0m [2m# # Multiple named commands (concurrent for post-*, sequential for pre-*)[0m[107m [0m [2m# [pre-merge][0m[107m [0m [2m# test = "npm test"[0m[107m [0m [2m# build = "npm run build"[0m-[107m [0m [2m[0m-[107m [0m [2m# Post-Merge: Runs after successful merge, BLOCKS[0m-[107m [0m [2m# Use for: deployment, notifications[0m-[107m [0m [2m#[0m-[107m [0m [2m# post-merge = "echo 'Merged {{ branch }} to {{ target }}'"[0m-[107m [0m [2m[0m-[107m [0m [2m# Pre-Remove: Runs before worktree removal, BLOCKS (fail-fast)[0m-[107m [0m [2m# Use for: cleanup, stopping services[0m-[107m [0m [2m#[0m-[107m [0m [2m# pre-remove = "docker compose down"[0m-[107m [0m [2m[0m-[107m [0m [2m# ============================================================================[0m-[107m [0m [2m# Aliases (experimental) — run with `wt step <name>`[0m-[107m [0m [2m# ============================================================================[0m-[107m [0m [2m# Command templates that support the same variables as hooks.[0m-[107m [0m [2m# Project-config aliases require command approval on first run.[0m[107m [0m [2m#[0m-[107m [0m [2m# [aliases][0m-[107m [0m [2m# deploy = "make deploy BRANCH={{ branch }}"[0m-[107m [0m [2m# url = "echo http://localhost:{{ branch | hash_port }}"[0m-[107m [0m [2m[0m-[107m [0m [2m# ============================================================================[0m-[107m [0m [2m# Dev Server URL (shown in `wt list`)[0m-[107m [0m [2m# ============================================================================[0m+[107m [0m [2m# # Pipeline — list of maps, run in order (each map concurrent)[0m+[107m [0m [2m# post-start = [[0m+[107m [0m [2m# { install = "npm ci" },[0m+[107m [0m [2m# { build = "npm run build", server = "npm run dev" }[0m+[107m [0m [2m# ][0m+[107m [0m [2m#[0m+[107m [0m [2m# ## Dev server URL[0m+[107m [0m [2m#[0m+[107m [0m [2m# # URL column in wt list (dimmed when port not listening)[0m[107m [0m [2m# [list][0m[107m [0m [2m# url = "http://localhost:{{ branch | hash_port }}"[0m-[107m [0m [2m[0m-[107m [0m [2m# ============================================================================[0m-[107m [0m [2m# Forge (GitHub/GitLab) Settings[0m-[107m [0m [2m# ============================================================================[0m-[107m [0m [2m# Override platform detection for SSH host aliases or custom domains.[0m-[107m [0m [2m# Set hostname for GitHub Enterprise or self-hosted GitLab API calls.[0m[107m [0m [2m#[0m+[107m [0m [2m# ## Forge platform override[0m+[107m [0m [2m#[0m+[107m [0m [2m# # Override platform detection for SSH aliases or self-hosted instances[0m[107m [0m [2m# [forge][0m-[107m [0m [2m# platform = "github" # or "gitlab"[0m-[107m [0m [2m# hostname = "github.example.com" # API host (GHE / self-hosted GitLab)[0m+[107m [0m [2m# platform = "github" # or "gitlab"[0m+[107m [0m [2m# # hostname = "github.example.com" # API host (GHE / self-hosted GitLab)[0m+[107m [0m [2m#[0m+[107m [0m [2m# ## Copy-ignored excludes[0m+[107m [0m [2m#[0m+[107m [0m [2m# # Add more gitignored excludes for wt step copy-ignored[0m+[107m [0m [2m# [step.copy-ignored][0m+[107m [0m [2m# exclude = [".cache/", ".turbo/"][0m+[107m [0m [2m#[0m+[107m [0m [2m# Built-in excludes always apply: VCS metadata directories (`.bzr/`, `.hg/`, `.jj/`, `.pijul/`, `.sl/`, `.svn/`) and tool-state directories (`.conductor/`, `.entire/`, `.pi/`, `.worktrees/`). User config and project config exclusions are combined.[0m+[107m [0m [2m#[0m+[107m [0m [2m# ## Aliases[0m+[107m [0m [2m#[0m+[107m [0m [2m# Command templates that run with `wt step <name>`. See `wt step` aliases (https://worktrunk.dev/step/#aliases) for usage and flags.[0m+[107m [0m [2m#[0m+[107m [0m [2m# [aliases][0m+[107m [0m [2m# deploy = "make deploy BRANCH={{ branch }}"[0m+[107m [0m [2m# url = "echo http://localhost:{{ branch | hash_port }}"[0m+[107m [0m [2m#[0m+[107m [0m [2m# Aliases defined here are shared with teammates. For personal aliases, use the user config (https://worktrunk.dev/config/#aliases) `[aliases]` section instead.[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snapindex b40f8e6f4..331b36404 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap@@ -343,34 +343,60 @@ Default template:[107m [0m [2m[32m</diff>[0m[107m [0m[107m [0m [2m[32m"[0m[2m[32m""[0m-[32mPROJECT CONFIGURATION[0m-Project config ([2m.config/wt.toml[0m) defines lifecycle hooks and project-specific settings. This file is checked into version control and shared with the team. Create with [2mwt config create --project[0m.+Create with [2mwt config create --project[0m.-See [2mwt hook[0m for hook types, execution order, template variables, and examples.+Location: [2m.config/wt.toml[0m (checked into version control and shared with the team).-[32mNon-hook settings[0m+[1m[32mHooks[0m-[107m [0m [2m# .config/wt.toml[0m+See [2mwt hook --help[0m for hook types, execution order, template variables, and examples. Both project and user configs support hooks in the same format:++[107m [0m [2m# Single command[0m+[107m [0m [2mpre-start = [0m[2m[32m"npm ci"[0m+[107m [0m+[107m [0m [2m# Multiple named commands (concurrent for post-*, sequential for pre-*)[0m+[107m [0m [2m[36m[pre-merge][0m+[107m [0m [2mtest = [0m[2m[32m"npm test"[0m+[107m [0m [2mbuild = [0m[2m[32m"npm run build"[0m[107m [0m+[107m [0m [2m# Pipeline — list of maps, run in order (each map concurrent)[0m+[107m [0m [2mpost-start = [[0m+[107m [0m [2m { install = [0m[2m[32m"npm ci"[0m[2m },[0m+[107m [0m [2m { build = [0m[2m[32m"npm run build"[0m[2m, server = [0m[2m[32m"npm run dev"[0m[2m }[0m+[107m [0m [2m][0m++[1m[32mDev server URL[0m+[107m [0m [2m# URL column in wt list (dimmed when port not listening)[0m[107m [0m [2m[36m[list][0m[107m [0m [2murl = [0m[2m[32m"http://localhost:{{ branch | hash_port }}"[0m-[107m [0m++[1m[32mForge platform override[0m+[107m [0m [2m# Override platform detection for SSH aliases or self-hosted instances[0m[107m [0m [2m[36m[forge][0m[107m [0m [2mplatform = [0m[2m[32m"github"[0m[2m [0m[2m# or "gitlab"[0m[107m [0m [2m# hostname = "github.example.com" # API host (GHE / self-hosted GitLab)[0m-[107m [0m++[1m[32mCopy-ignored excludes[0m+[107m [0m [2m# Add more gitignored excludes for wt step copy-ignored[0m[107m [0m [2m[36m[step.copy-ignored][0m[107m [0m [2mexclude = [[0m[2m[32m".cache/"[0m[2m, [0m[2m[32m".turbo/"[0m[2m][0m-[107m [0m-[107m [0m [2m# Command aliases (run with wt step <name>)[0m++Built-in excludes always apply: VCS metadata directories ([2m.bzr/[0m, [2m.hg/[0m, [2m.jj/[0m, [2m.pijul/[0m, [2m.sl/[0m, [2m.svn/[0m) and tool-state directories ([2m.conductor/[0m, [2m.entire/[0m, [2m.pi/[0m, [2m.worktrees/[0m). User config and project config exclusions are combined.++[1m[32mAliases[0m++Command templates that run with [2mwt step <name>[0m. See [2mwt step[0m aliases for usage and flags.+[107m [0m [2m[36m[aliases][0m[107m [0m [2mdeploy = [0m[2m[32m"make deploy BRANCH={{ branch }}"[0m-[107m [0m [2mtest = [0m[2m[32m"cargo test"[0m+[107m [0m [2murl = [0m[2m[32m"echo http://localhost:{{ branch | hash_port }}"[0m++Aliases defined here are shared with teammates. For personal aliases, use the user config [2m[aliases][0m section instead.[32mSHELL INTEGRATION[0m