Skip to content

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

docs: clarify user project-specific settings section (#830)

Maximilian Roosee029d19f14d
diff --git a/.claude-plugin/skills/worktrunk/reference/config.md b/.claude-plugin/skills/worktrunk/reference/config.md
index 5750be59d..55edda6fe 100644
--- a/.claude-plugin/skills/worktrunk/reference/config.md
+++ b/.claude-plugin/skills/worktrunk/reference/config.md
@@ -153,25 +153,32 @@ Pager behavior for `wt select` diff previews.
# pager = "delta --paging=never"
```
-### Per-project settings (Experimental)
+### User project-specific settings
-Per-project settings are keyed by project identifier (e.g., `github.com/user/repo`).
-These contain approved hook commands plus optional overrides of global settings.
-Setting overrides (worktree-path, list, commit, merge) are new; approved-commands is stable.
+User config settings apply to all projects. [Project config](https://worktrunk.dev/config/#worktrunk-project-configuration) settings are shared with teammates. The `[projects]` table holds personal, project-specific settings like approved hook commands and worktree layout. Entries are keyed by project identifier (e.g., `github.com/user/repo`).
+
+#### Approved hook commands
+
+When a project hook runs for the first time, worktrunk asks for approval. Approved commands are saved here, preventing repeated prompts.
```toml
[projects."github.com/user/repo"]
-# Approved hook commands (auto-populated when approving on first run)
approved-commands = ["npm ci", "npm test"]
+```
+
+Auto-managed. To reset, delete the entry or run `wt hook approve --clear`.
+
+#### Setting overrides (Experimental)
-# Optional overrides (omit to use global settings)
+Override global settings for a specific project. Useful when one repo needs a different worktree layout or merge behavior.
+
+```toml
+[projects."github.com/user/repo"]
worktree-path = ".worktrees/{{ branch | sanitize }}"
list.full = true
merge.squash = false
```
-For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see [`wt hook` docs](https://worktrunk.dev/hook/).
-
### Custom prompt templates
Templates use [minijinja](https://docs.rs/minijinja/) syntax.
diff --git a/dev/config.example.toml b/dev/config.example.toml
index 9d8698e24..83d0c2bd2 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -81,23 +81,28 @@
# # Example:
# # pager = "delta --paging=never"
#
-# ### Per-project settings (Experimental)
+# ### User project-specific settings
#
-# Per-project settings are keyed by project identifier (e.g., `github.com/user/repo`).
-# These contain approved hook commands plus optional overrides of global settings.
-# Setting overrides (worktree-path, list, commit, merge) are new; approved-commands is stable.
+# User config settings apply to all projects. Project config (https://worktrunk.dev/config.md#worktrunk-project-configuration/) settings are shared with teammates. The `[projects]` table holds personal, project-specific settings like approved hook commands and worktree layout. Entries are keyed by project identifier (e.g., `github.com/user/repo`).
+#
+# #### Approved hook commands
+#
+# When a project hook runs for the first time, worktrunk asks for approval. Approved commands are saved here, preventing repeated prompts.
#
# [projects."github.com/user/repo"]
-# # Approved hook commands (auto-populated when approving on first run)
# approved-commands = ["npm ci", "npm test"]
#
-# # Optional overrides (omit to use global settings)
+# Auto-managed. To reset, delete the entry or run `wt hook approve --clear`.
+#
+# #### Setting overrides (Experimental)
+#
+# Override global settings for a specific project. Useful when one repo needs a different worktree layout or merge behavior.
+#
+# [projects."github.com/user/repo"]
# worktree-path = ".worktrees/{{ branch | sanitize }}"
# list.full = true
# merge.squash = false
#
-# For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see `wt hook` docs (https://worktrunk.dev/hook/).
-#
# ### Custom prompt templates
#
# Templates use minijinja (https://docs.rs/minijinja/) syntax.
diff --git a/docs/content/config.md b/docs/content/config.md
index 51abfba4e..2fd08b5e7 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -161,25 +161,32 @@ Pager behavior for `wt select` diff previews.
# pager = "delta --paging=never"
```
-### Per-project settings (Experimental)
+### User project-specific settings
-Per-project settings are keyed by project identifier (e.g., `github.com/user/repo`).
-These contain approved hook commands plus optional overrides of global settings.
-Setting overrides (worktree-path, list, commit, merge) are new; approved-commands is stable.
+User config settings apply to all projects. [Project config](@/config.md#worktrunk-project-configuration) settings are shared with teammates. The `[projects]` table holds personal, project-specific settings like approved hook commands and worktree layout. Entries are keyed by project identifier (e.g., `github.com/user/repo`).
+
+#### Approved hook commands
+
+When a project hook runs for the first time, worktrunk asks for approval. Approved commands are saved here, preventing repeated prompts.
```toml
[projects."github.com/user/repo"]
-# Approved hook commands (auto-populated when approving on first run)
approved-commands = ["npm ci", "npm test"]
+```
+
+Auto-managed. To reset, delete the entry or run `wt hook approve --clear`.
+
+#### Setting overrides (Experimental)
-# Optional overrides (omit to use global settings)
+Override global settings for a specific project. Useful when one repo needs a different worktree layout or merge behavior.
+
+```toml
+[projects."github.com/user/repo"]
worktree-path = ".worktrees/{{ branch | sanitize }}"
list.full = true
merge.squash = false
```
-For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see [`wt hook` docs](@/hook.md).
-
### Custom prompt templates
Templates use [minijinja](https://docs.rs/minijinja/) syntax.
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 68fc7b26a..8b531ff7c 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1617,25 +1617,32 @@ Pager behavior for `wt select` diff previews.
# pager = "delta --paging=never"
```
-### Per-project settings (Experimental)
+### User project-specific settings
-Per-project settings are keyed by project identifier (e.g., `github.com/user/repo`).
-These contain approved hook commands plus optional overrides of global settings.
-Setting overrides (worktree-path, list, commit, merge) are new; approved-commands is stable.
+User config settings apply to all projects. [Project config](@/config.md#worktrunk-project-configuration) settings are shared with teammates. The `[projects]` table holds personal, project-specific settings like approved hook commands and worktree layout. Entries are keyed by project identifier (e.g., `github.com/user/repo`).
+
+#### Approved hook commands
+
+When a project hook runs for the first time, worktrunk asks for approval. Approved commands are saved here, preventing repeated prompts.
```toml
[projects."github.com/user/repo"]
-# Approved hook commands (auto-populated when approving on first run)
approved-commands = ["npm ci", "npm test"]
+```
+
+Auto-managed. To reset, delete the entry or run `wt hook approve --clear`.
+
+#### Setting overrides (Experimental)
-# Optional overrides (omit to use global settings)
+Override global settings for a specific project. Useful when one repo needs a different worktree layout or merge behavior.
+
+```toml
+[projects."github.com/user/repo"]
worktree-path = ".worktrees/{{ branch | sanitize }}"
list.full = true
merge.squash = false
```
-For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see [`wt hook` docs](@/hook.md).
-
### Custom prompt templates
Templates use [minijinja](https://docs.rs/minijinja/) syntax.
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 c85c4521f..830095ab0 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -133,23 +133,28 @@ Creates ~/.config/worktrunk/config.toml with the following content:
# # Example:
# # pager = "delta --paging=never"
#
- # ### Per-project settings (Experimental)
+ # ### User project-specific settings
#
- # Per-project settings are keyed by project identifier (e.g., `github.com/user/repo`).
- # These contain approved hook commands plus optional overrides of global settings.
- # Setting overrides (worktree-path, list, commit, merge) are new; approved-commands is stable.
+ # User config settings apply to all projects. Project config (https://worktrunk.dev/config.md#worktrunk-project-configuration/) settings are shared with teammates. The `[projects]` table holds personal, project-specific settings like approved hook commands and worktree layout. Entries are keyed by project identifier (e.g., `github.com/user/repo`).
+ #
+ # #### Approved hook commands
+ #
+ # When a project hook runs for the first time, worktrunk asks for approval. Approved commands are saved here, preventing repeated prompts.
#
# [projects."github.com/user/repo"]
- # # Approved hook commands (auto-populated when approving on first run)
# approved-commands = ["npm ci", "npm test"]
#
- # # Optional overrides (omit to use global settings)
+ # Auto-managed. To reset, delete the entry or run `wt hook approve --clear`.
+ #
+ # #### Setting overrides (Experimental)
+ #
+ # Override global settings for a specific project. Useful when one repo needs a different worktree layout or merge behavior.
+ #
+ # [projects."github.com/user/repo"]
# worktree-path = ".worktrees/{{ branch | sanitize }}"
# list.full = true
# merge.squash = false
#
- # For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see `wt hook` docs (https://worktrunk.dev/hook/).
- #
# ### Custom prompt templates
#
# Templates use minijinja (https://docs.rs/minijinja/) syntax.
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 b21f830c1..208d85ce2 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -178,23 +178,28 @@ Pager behavior for wt select diff previews.
# Example:
# pager = "delta --paging=never"
-Per-project settings (Experimental)
+User project-specific settings
-Per-project settings are keyed by project identifier (e.g., github.com/user/repo).
-These contain approved hook commands plus optional overrides of global settings.
-Setting overrides (worktree-path, list, commit, merge) are new; approved-commands is stable.
+User config settings apply to all projects. Project config settings are shared with teammates. The [projects] table holds personal, project-specific settings like approved hook commands and worktree layout. Entries are keyed by project identifier (e.g., github.com/user/repo).
+
+Approved hook commands
+
+When a project hook runs for the first time, worktrunk asks for approval. Approved commands are saved here, preventing repeated prompts.
[projects."github.com/user/repo"]
- # Approved hook commands (auto-populated when approving on first run)
approved-commands = ["npm ci", "npm test"]
- 
- # Optional overrides (omit to use global settings)
+
+Auto-managed. To reset, delete the entry or run wt hook approve --clear.
+
+Setting overrides (Experimental)
+
+Override global settings for a specific project. Useful when one repo needs a different worktree layout or merge behavior.
+
+ [projects."github.com/user/repo"]
worktree-path = ".worktrees/{{ branch | sanitize }}"
list.full = true
merge.squash = false
-For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at <repo>/.config/wt.toml. Run wt config create --project to create one, or see wt hook docs.
-
Custom prompt templates
Templates use minijinja syntax.