Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Docs: Revamp config documentation
Maximilian Roosb5527a190750
diff --git a/docs/content/configuration.md b/docs/content/configuration.mdindex 2be839d45..b012db184 100644--- a/docs/content/configuration.md+++ b/docs/content/configuration.md@@ -8,90 +8,123 @@ group = "Reference"Worktrunk uses two configuration files:-- **User config**: `~/.config/worktrunk/config.toml` — Personal settings, LLM commands, saved approvals-- **Project config**: `.config/wt.toml` — Project-specific hooks (checked into version control)+| File | Location | Purpose |+|------|----------|---------|+| **User config** | `~/.config/worktrunk/config.toml` | Personal settings, command defaults, approved project commands |+| **Project config** | `.config/wt.toml` | Lifecycle hooks, checked into version control |-## Project Hooks+## User Config-Create `.config/wt.toml` in your repository to automate setup and validation at worktree lifecycle events. See the dedicated [Hooks](/hooks/) page for complete documentation.+The user config stores personal preferences that apply across all repositories. Create it with:-Quick example:+```bash+wt config create+```-```toml-[post-create]-install = "npm ci"+This creates `~/.config/worktrunk/config.toml` with documented examples. View the current configuration with `wt config show`.-[pre-merge]-test = "npm test"-lint = "npm run lint"-```+### Worktree Path Template-### Hook execution+Controls where new worktrees are created. The template is relative to the repository root:-<!-- ⚠️ AUTO-GENERATED-HTML from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_hooks_post_create.snap — edit source to update -->+```toml+# Default — siblings in parent directory+worktree-path = "../{{ main_worktree }}.{{ branch }}"-{% terminal() %}-<span class="prompt">$</span> wt switch --create feature-x-🔄 <span style='color:var(--cyan,#0aa)'>Running post-create <b>install</b>:</span>-<span style='background:var(--bright-white,#fff)'> </span> <span style='opacity:0.67'><span style='color:var(--blue,#00a)'>uv</span></span><span style='opacity:0.67'> sync</span>+# Inside the repository+worktree-path = ".worktrees/{{ branch }}"- Resolved 24 packages in 145ms- Installed 24 packages in 1.2s-✅ <span style='color:var(--green,#0a0)'>Created new worktree for <b>feature-x</b> from <b>main</b> at <b>../repo.feature-x</b></span>-🔄 <span style='color:var(--cyan,#0aa)'>Running post-start <b>dev</b>:</span>-<span style='background:var(--bright-white,#fff)'> </span> <span style='opacity:0.67'><span style='color:var(--blue,#00a)'>uv</span></span><span style='opacity:0.67'> run dev</span>-{% end %}+# Namespaced (useful when multiple repos share a parent directory)+worktree-path = "../worktrees/{{ main_worktree }}/{{ branch }}"+```-<!-- END AUTO-GENERATED -->+**Available variables:**+- `{{ main_worktree }}` — main worktree directory name+- `{{ branch }}` — branch name (slashes replaced with dashes)-**Security**: Project commands require approval on first run. Approvals are saved to user config. Use `--force` to bypass prompts or `--no-verify` to skip hooks entirely.+### Command Defaults-### Template variables+Override default flag behavior for commands. Settings here apply unless explicitly overridden on the command line.-Hooks can use these variables:+**`wt list` defaults:**-- `{{ repo }}` — Repository name-- `{{ branch }}` — Branch name-- `{{ worktree }}` — Worktree path-- `{{ repo_root }}` — Repository root path-- `{{ target }}` — Target branch (for merge hooks)+```toml+[list]+full = true # --full (default: false)+branches = true # --branches (default: false)+remotes = true # --remotes (default: false)+```-## User Config Reference+**`wt step commit` and `wt merge` staging:**-Create the user config with defaults:+```toml+[commit]+stage = "all" # "all" (default), "tracked", or "none"+```-```bash-$ wt config create+**`wt merge` defaults:**++```toml+[merge]+# All options default to true+squash = false # --no-squash: preserve individual commits+commit = false # --no-commit: skip committing uncommitted changes+remove = false # --no-remove: keep worktree after merge+verify = false # --no-verify: skip project hooks```-This creates `~/.config/worktrunk/config.toml` with documented examples.+### LLM Commit Messages-### Key settings+Configure automatic commit message generation. Requires an external tool like [llm](https://llm.datasette.io/):```toml-# Worktree path template-# Default: "../{{ main_worktree }}.{{ branch }}"-path-template = "../{{ main_worktree }}.{{ branch }}"--# LLM commit message generation (see /llm-commits/)[commit-generation]command = "llm"args = ["-m", "claude-haiku-4.5"]+```++See [LLM Commit Messages](/llm-commits/) for setup details and template customization.-# Per-project command approvals (auto-populated)-[approved-commands."my-project"]-"post-create.install" = "npm install"+### Approved Commands++When project hooks run for the first time, Worktrunk prompts for approval. Approved commands are saved here automatically:++```toml+[projects."my-project"]+approved-commands = [+ "post-create.install = npm ci",+ "pre-merge.test = npm test",+]+```++Manage approvals with `wt config approvals list` and `wt config approvals clear <repo>`.++## Project Config++The project config defines lifecycle hooks — commands that run at specific points during worktree operations. This file is checked into version control and shared across the team.++Create `.config/wt.toml` in the repository root:++```toml+[post-create]+install = "npm ci"++[pre-merge]+test = "npm test"+lint = "npm run lint"```+See [Hooks](/hooks/) for complete documentation on hook types, execution order, and template variables.+## Shell Integration-Worktrunk needs shell integration to change directories. Install with:+Worktrunk needs shell integration to change directories when switching worktrees. Install with:```bash-$ wt config shell install+wt config shell install```-Or manually add to your shell config:+Or manually add to the shell config:```bash# bash/zsh@@ -101,14 +134,12 @@ eval "$(wt config shell init bash)"wt config shell init fish | source```-## Environment Variables+Without shell integration, `wt switch` prints the target directory but cannot `cd` into it.-Override default behavior with environment variables:+## Environment Variables-| Variable | Effect |-|----------|--------|-| `WORKTRUNK_CONFIG_PATH` | Override user config location (default: `~/.config/worktrunk/config.toml`) |-| `NO_COLOR` | Disable colored output |+| Variable | Purpose |+|----------|---------|+| `WORKTRUNK_CONFIG_PATH` | Override user config location |+| `NO_COLOR` | Disable colored output ([standard](https://no-color.org/)) || `CLICOLOR_FORCE` | Force colored output even when not a TTY |--These follow standard conventions — `NO_COLOR` is the [no-color.org](https://no-color.org/) standard.diff --git a/src/config/user.rs b/src/config/user.rsindex fc592073e..1b0d467c4 100644--- a/src/config/user.rs+++ b/src/config/user.rs@@ -276,7 +276,10 @@ impl WorktrunkConfig {// Add environment variables with WORKTRUNK prefix// Uses "__" separator (default) to support field names with underscores- // Example: WORKTRUNK_COMMIT_GENERATION__COMMAND maps to commit-generation.command+ // TODO: This doesn't work for nested fields due to serde rename mismatch.+ // The config crate maps WORKTRUNK_COMMIT_GENERATION__COMMAND to `commit_generation.command`+ // (snake_case), but serde expects `commit-generation.command` (kebab-case).+ // Only WORKTRUNK_CONFIG_PATH works reliably (handled separately in get_config_path).builder = builder.add_source(config::Environment::with_prefix("WORKTRUNK").separator("__"));let config: Self = builder.build()?.try_deserialize()?;