Skip to content

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

Add --project flag to wt config create (#110)

Maximilian Roos69474c620dc8
diff --git a/dev/config.example.toml b/dev/config.example.toml
index 035549ca2..cc78ecc5f 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -70,7 +70,7 @@ 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: dev/wt.example.toml for project configuration examples
+# Run `wt config create --project` to create one, or see https://worktrunk.dev/hooks/
# ============================================================================
# Custom Prompt Templates (Advanced)
diff --git a/docs/content/config.md b/docs/content/config.md
index f6e80d106..94405e316 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -31,6 +31,12 @@ Create user config file with documented examples:
wt config create
```
+Create project config file (.config/wt.toml) for hooks:
+
+```bash
+wt config create --project
+```
+
Show current configuration and file locations:
```bash
@@ -219,7 +225,7 @@ Usage: wt config [OPTIONS] <COMMAND>
Commands:
shell Shell integration setup
- create Create user configuration file
+ create Create configuration file
show Show configuration files & locations
cache Manage caches (CI status, default branch)
var Get or set runtime variables (stored in git config)
diff --git a/src/cli.rs b/src/cli.rs
index 3de00902f..04baac8d0 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -269,15 +269,24 @@ pub enum ConfigCommand {
action: ConfigShellCommand,
},
- /// Create user configuration file
+ /// Create configuration file
#[command(
after_long_help = concat!(
+ "## User config\n\n",
"Creates `~/.config/worktrunk/config.toml` with the following content:\n\n```\n",
include_str!("../dev/config.example.toml"),
+ "```\n\n",
+ "## Project config\n\n",
+ "With `--project`, creates `.config/wt.toml` in the current repository:\n\n```\n",
+ include_str!("../dev/wt.example.toml"),
"```"
)
)]
- Create,
+ Create {
+ /// Create project config (.config/wt.toml) instead of user config
+ #[arg(long)]
+ project: bool,
+ },
/// Show configuration files & locations
#[command(
@@ -693,6 +702,12 @@ Create user config file with documented examples:
wt config create
```
+Create project config file (.config/wt.toml) for hooks:
+
+```console
+wt config create --project
+```
+
Show current configuration and file locations:
```console
diff --git a/src/commands/config.rs b/src/commands/config.rs
index 7e1598852..782d4d77e 100644
--- a/src/commands/config.rs
+++ b/src/commands/config.rs
@@ -18,8 +18,11 @@ use crate::help_pager::show_help_in_pager;
use crate::llm::test_commit_generation;
use crate::output;
-/// Example configuration file content (displayed in help with values uncommented)
-const CONFIG_EXAMPLE: &str = include_str!("../../dev/config.example.toml");
+/// Example user configuration file content (displayed in help with values uncommented)
+const USER_CONFIG_EXAMPLE: &str = include_str!("../../dev/config.example.toml");
+
+/// Example project configuration file content
+const PROJECT_CONFIG_EXAMPLE: &str = include_str!("../../dev/wt.example.toml");
/// Comment out all non-comment, non-empty lines for writing to disk
fn comment_out_config(content: &str) -> String {
@@ -45,14 +48,41 @@ fn comment_out_config(content: &str) -> String {
}
/// Handle the config create command
-pub fn handle_config_create() -> anyhow::Result<()> {
- let config_path = require_user_config_path()?;
+pub fn handle_config_create(project: bool) -> anyhow::Result<()> {
+ if project {
+ let repo = Repository::current();
+ let config_path = repo.worktree_root()?.join(".config/wt.toml");
+ create_config_file(
+ config_path,
+ PROJECT_CONFIG_EXAMPLE,
+ "Project config",
+ &[
+ "Edit this file to configure hooks for this repository",
+ "See https://worktrunk.dev/hooks/ for hook documentation",
+ ],
+ )
+ } else {
+ create_config_file(
+ require_user_config_path()?,
+ USER_CONFIG_EXAMPLE,
+ "User config",
+ &["Edit this file to customize worktree paths and LLM settings"],
+ )
+ }
+}
+/// Create a config file at the specified path with the given content
+fn create_config_file(
+ path: PathBuf,
+ content: &str,
+ config_type: &str,
+ success_hints: &[&str],
+) -> anyhow::Result<()> {
// Check if file already exists
- if config_path.exists() {
+ if path.exists() {
output::info(cformat!(
- "User config already exists: <bold>{}</>",
- format_path_for_display(&config_path)
+ "{config_type} already exists: <bold>{}</>",
+ format_path_for_display(&path)
))?;
output::blank()?;
output::hint(cformat!(
@@ -65,21 +95,24 @@ pub fn handle_config_create() -> anyhow::Result<()> {
}
// Create parent directory if it doesn't exist
- if let Some(parent) = config_path.parent() {
+ if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent).context("Failed to create config directory")?;
}
// Write the example config with all values commented out
- let commented_config = comment_out_config(CONFIG_EXAMPLE);
- std::fs::write(&config_path, commented_config).context("Failed to write config file")?;
+ let commented_config = comment_out_config(content);
+ std::fs::write(&path, commented_config).context("Failed to write config file")?;
// Success message
output::success(cformat!(
- "Created config file: <bold>{}</>",
- format_path_for_display(&config_path)
+ "Created {}: <bold>{}</>",
+ config_type.to_lowercase(),
+ format_path_for_display(&path)
))?;
output::blank()?;
- output::hint("Edit this file to customize worktree paths and LLM settings")?;
+ for hint in success_hints {
+ output::hint(*hint)?;
+ }
Ok(())
}
diff --git a/src/main.rs b/src/main.rs
index 97529ab48..1948ba2e6 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -732,7 +732,7 @@ fn main() {
}
}
}
- ConfigCommand::Create => handle_config_create(),
+ ConfigCommand::Create { project } => handle_config_create(project),
ConfigCommand::Show { doctor } => handle_config_show(doctor),
ConfigCommand::Cache { action } => match action {
CacheCommand::Show => handle_cache_show(),
diff --git a/tests/integration_tests/config_init.rs b/tests/integration_tests/config_init.rs
index 780072e04..82f8e360f 100644
--- a/tests/integration_tests/config_init.rs
+++ b/tests/integration_tests/config_init.rs
@@ -59,7 +59,7 @@ fn test_config_init_creates_file() {
----- stdout -----
----- stderr -----
- ✅ Created config file: ~/.config/worktrunk/config.toml
+ ✅ Created user config: ~/.config/worktrunk/config.toml
💡 Edit this file to customize worktree paths and LLM settings
");
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 681d4b830..4e86bd2c1 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -18,10 +18,13 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt config create - Create user configuration file
+wt config create - Create configuration file
Usage: wt config create [OPTIONS]
Options:
+ --project
+ Create project config (.config/wt.toml) instead of user config
+
-h, --help
Print help (see a summary with '-h')
@@ -35,6 +38,8 @@ Usage: wt config create [OPTIONS]
-v, --verbose
Show commands and debug info
+User config
+
Creates ~/.config/worktrunk/config.toml with the following content:
# Worktrunk Global Configuration
@@ -109,7 +114,7 @@ Creates ~/.config/worktrunk/config.toml with the following content:

# NOTE: For project-specific hooks (post-create, post-start, pre-merge, etc.),
# use a separate PROJECT config file at <repo>/.config/wt.toml
- # See: dev/wt.example.toml for project configuration examples
+ # Run `wt config create --project` to create one, or see https://worktrunk.dev/hooks/

# ============================================================================
# Custom Prompt Templates (Advanced)
@@ -227,3 +232,125 @@ Creates ~/.config/worktrunk/config.toml with the following content:
# Generate one cohesive commit message that captures the overall change.
# Use conventional commit format (feat/fix/docs/refactor).
# """
+
+Project config
+
+With --project, creates .config/wt.toml in the current repository:
+
+ # Worktrunk Project Configuration
+ # 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
+ # developers working on the project.
+ 
+ # Available template variables (all hooks):
+ # {{ 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 hooks also support:
+ # {{ target }} - Target branch for the merge (e.g., "main")
+ 
+ # Post-Create Hook
+ # Runs SEQUENTIALLY and BLOCKS until complete
+ # 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 = "npm install"
+ #
+ # 2. Named table (runs sequentially in declaration order):
+ # [post-create]
+ # install = "npm install --frozen-lockfile"
+ # build = "npm run build"
+ 
+ # Post-Start Hook
+ # Runs in BACKGROUND as detached processes (parallel)
+ # Use for: uv sync, npm install, bundle install, build, dev servers, file watchers,
+ # downloading assets too large for git (images, ML models, binaries), long-running tasks
+ # The worktree switch completes immediately, these run in parallel
+ # Output is logged to .git/wt-logs/{branch}-post-start-{name}.log
+ #
+ # Format options:
+ # 1. Single string:
+ # post-start = "npm run dev"
+ #
+ # 2. Named table (runs in parallel):
+ # [post-start]
+ # server = "npm run dev"
+ # watch = "npm run watch"
+ 
+ # Pre-Commit Hook
+ # Runs SEQUENTIALLY before committing changes during merge (blocking, fail-fast)
+ # All commands must exit with code 0 for commit to proceed
+ # Runs for both squash and no-squash merge modes
+ # Use for: formatters, linters, quick validation
+ #
+ # Single command:
+ # pre-commit = "cargo fmt -- --check"
+ #
+ # Multiple commands:
+ # [pre-commit]
+ # format = "cargo fmt -- --check"
+ # lint = "cargo clippy -- -D warnings"
+ 
+ # Pre-Merge Hook
+ # 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
+ #
+ # Single command:
+ # pre-merge = "cargo test"
+ #
+ # Multiple commands:
+ # [pre-merge]
+ # test = "cargo test"
+ # build = "cargo build --release"
+ 
+ # Post-Merge Hook
+ # Runs SEQUENTIALLY in the main worktree after successful merge (blocking)
+ # Runs after push succeeds but before cleanup
+ # Use for: updating production builds, notifications, cleanup
+ #
+ # Single command:
+ # post-merge = "cargo install --path ."
+ #
+ # Multiple commands:
+ # [post-merge]
+ # install = "cargo install --path ."
+ # notify = "echo 'Merged!'"
+ 
+ # Example: Node.js Project
+ # [post-create]
+ # install = "npm ci"
+ #
+ # [post-start]
+ # server = "npm run dev"
+ #
+ # [pre-merge]
+ # lint = "npm run lint"
+ # test = "npm test"
+ 
+ # Example: Rust Project
+ # [post-create]
+ # build = "cargo build"
+ #
+ # [pre-merge]
+ # format = "cargo fmt -- --check"
+ # clippy = "cargo clippy -- -D warnings"
+ # test = "cargo test"
+ #
+ # post-merge = "cargo install --path ."
+ 
+ # Example: Python Project
+ # [post-create]
+ # venv = "python -m venv .venv"
+ # install = ".venv/bin/pip install -r requirements.txt"
+ #
+ # [pre-merge]
+ # format = ".venv/bin/black --check ."
+ # lint = ".venv/bin/ruff check ."
+ # test = ".venv/bin/pytest"
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 6b8fdd715..45d9e4bdc 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -22,7 +22,7 @@ Usage: wt config [OPTIONS] <COMMAND>
Commands:
shell Shell integration setup
- create Create user configuration file
+ create Create configuration file
show Show configuration files & locations
cache Manage caches (CI status, default branch)
var Get or set runtime variables (stored in git config)
@@ -61,6 +61,10 @@ Create user config file with documented examples:
wt config create
+Create project config file (.config/wt.toml) for hooks:
+
+ wt config create --project
+
Show current configuration and file locations:
wt config show
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_short.snap b/tests/snapshots/integration__integration_tests__help__help_config_short.snap
index b0c876f31..e3d10cb9e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_short.snap
@@ -22,7 +22,7 @@ Usage: wt config [OPTIONS] <COMMAND>
Commands:
shell Shell integration setup
- create Create user configuration file
+ create Create configuration file
show Show configuration files & locations
cache Manage caches (CI status, default branch)
var Get or set runtime variables (stored in git config)