Skip to content

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.toml
index 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.md
index 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 Integration
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index 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 Integration
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 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 Integration
Worktrunk 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.rs
index 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(&current);
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's
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 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 ~/.config/worktrunk/config.toml with the following content:
With --project, creates .config/wt.toml in the current repository:
-  # 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/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 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:
  </diff>
 
  """
-
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.
-See wt hook for hook types, execution order, template variables, and examples.
+Location: .config/wt.toml (checked into version control and shared with the team).
-Non-hook settings
+Hooks
-  # .config/wt.toml
+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"
 
+  # 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 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)
- 
+
+Copy-ignored excludes
+
  # Add more gitignored excludes for wt step copy-ignored
  [step.copy-ignored]
  exclude = [".cache/", ".turbo/"]
- 
-  # Command aliases (run with wt step <name>)
+
+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 for usage and flags.
+
  [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 [aliases] section instead.
SHELL INTEGRATION