Skip to content

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

docs: Standardize "user config" terminology

Maximilian Roose5c1a7f6deab
diff --git a/README.md b/README.md
index 0b8d5d89d..43a90438b 100644
--- a/README.md
+++ b/README.md
@@ -193,6 +193,23 @@ wt config shell install # Bash, Zsh, Fish
or for manual setup: `wt config shell --help`.
+### LLM commit messages
+
+Worktrunk can invoke external commands to generate commit messages.
+[llm](https://llm.datasette.io/) is recommended.
+
+Add to user config (`~/.config/worktrunk/config.toml`):
+
+```toml
+[commit-generation]
+command = "llm"
+args = ["-m", "claude-haiku-4-5-20251001"]
+```
+
+`wt merge` generates commit messages automatically or `wt step commit` runs just the commit step.
+
+For custom prompt templates: `wt config --help`.
+
### Local merging with `wt merge`
`wt merge` handles the full merge workflow: stage, commit, squash, rebase,
@@ -223,23 +240,6 @@ cargo install --path . </pre></td>
</tr>
</table>
-### LLM commit messages
-
-Worktrunk can invoke external commands to generate commit messages.
-[llm](https://llm.datasette.io/) is recommended.
-
-`~/.config/worktrunk/config.toml`:
-
-```toml
-[commit-generation]
-command = "llm"
-args = ["-m", "claude-haiku-4-5-20251001"]
-```
-
-`wt merge` generates commit messages automatically or `wt step commit` runs just the commit step.
-
-For custom prompt templates: `wt config --help`.
-
<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__merge__readme_example_complex.snap — edit source to update -->
```console
@@ -293,7 +293,7 @@ test result: ok. 18 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; fin
### Project hooks
-Configure hooks in `.config/wt.toml`:
+Configure hooks in project config (`.config/wt.toml`):
| Hook | When | Example |
| --------------- | ----------------------------------- | ---------------------------- |
@@ -1103,19 +1103,19 @@ Global Options:
eval "$(wt config shell init bash)"
```
-2. (Optional) Create config file
+2. (Optional) Create user config file
```console
wt config create
```
- This creates ~/.config/worktrunk/config.toml with examples.
+ This creates `~/.config/worktrunk/config.toml` with examples.
3. (Optional) Enable LLM commit messages
Install: `uv tool install -U llm`
Configure: `llm keys set anthropic`
- Add to config.toml:
+ Add to user config:
```toml
[commit-generation]
@@ -1143,12 +1143,12 @@ Docs: <https://llm.datasette.io/> | <https://github.com/sigoden/aichat>
## Configuration Files
-**Global config** (user settings):
+**User config**:
- Location: `~/.config/worktrunk/config.toml` (or `WORKTRUNK_CONFIG_PATH`)
- Run `wt config create --help` to view documented examples
-**Project config** (repository hooks):
+**Project config**:
- Location: `.config/wt.toml` in repository root
- Contains: post-create, post-start, pre-commit, pre-merge, post-merge hooks
@@ -1197,11 +1197,11 @@ Global Options:
Worktrunk executes commands in three contexts:
-1. **Project hooks** (`.config/wt.toml`) - Automation for worktree lifecycle
-2. **LLM commands** (`~/.config/worktrunk/config.toml`) - Commit message generation
+1. **Project hooks** (project config: `.config/wt.toml`) - Automation for worktree lifecycle
+2. **LLM commands** (user config: `~/.config/worktrunk/config.toml`) - Commit message generation
3. **--execute flag** - Commands provided explicitly
-Commands from project hooks and LLM configuration require approval on first run. Approved commands are saved to `~/.config/worktrunk/config.toml` under the project's configuration. If a command changes, Worktrunk requires new approval.
+Commands from project hooks and LLM configuration require approval on first run. Approved commands are saved to user config under the project's configuration. If a command changes, Worktrunk requires new approval.
**Example approval prompt:**
diff --git a/src/cli.rs b/src/cli.rs
index 59da5eecb..09579cce0 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -269,7 +269,7 @@ pub enum ConfigCommand {
action: ConfigShellCommand,
},
- /// Create global configuration file
+ /// Create user configuration file
#[command(
after_long_help = concat!(
"Creates `~/.config/worktrunk/config.toml` with the following content:\n\n```\n",
@@ -281,7 +281,7 @@ pub enum ConfigCommand {
/// Show configuration files & locations
#[command(
- after_long_help = r#"Shows location and contents of global config (`~/.config/worktrunk/config.toml`)
+ after_long_help = r#"Shows location and contents of user config (`~/.config/worktrunk/config.toml`)
and project config (`.config/wt.toml`).
If a config file doesn't exist, shows defaults that would be used."#
@@ -537,19 +537,19 @@ pub enum Commands {
eval "$(wt config shell init bash)"
```
-2. (Optional) Create config file
+2. (Optional) Create user config file
```console
wt config create
```
- This creates ~/.config/worktrunk/config.toml with examples.
+ This creates `~/.config/worktrunk/config.toml` with examples.
3. (Optional) Enable LLM commit messages
Install: `uv tool install -U llm`
Configure: `llm keys set anthropic`
- Add to config.toml:
+ Add to user config:
```toml
[commit-generation]
@@ -577,7 +577,7 @@ Docs: <https://llm.datasette.io/> | <https://github.com/sigoden/aichat>
## Configuration Files
-**Global config** (user settings):
+**User config**:
- Location: `~/.config/worktrunk/config.toml` (or `WORKTRUNK_CONFIG_PATH`)
- Run `wt config create --help` to view documented examples
diff --git a/src/commands/config.rs b/src/commands/config.rs
index 8992f1ff0..ac0fb39f5 100644
--- a/src/commands/config.rs
+++ b/src/commands/config.rs
@@ -42,7 +42,7 @@ fn comment_out_config(content: &str) -> String {
/// Handle the config create command
pub fn handle_config_create() -> anyhow::Result<()> {
- let config_path = get_global_config_path().ok_or_else(|| {
+ let config_path = get_user_config_path().ok_or_else(|| {
anyhow::anyhow!(
"Cannot determine config directory. Set $HOME or $XDG_CONFIG_HOME environment variable"
)
@@ -51,7 +51,7 @@ pub fn handle_config_create() -> anyhow::Result<()> {
// Check if file already exists
if config_path.exists() {
output::info(cformat!(
- "Global config already exists: <bold>{}</>",
+ "User config already exists: <bold>{}</>",
format_path_for_display(&config_path)
))?;
output::blank()?;
@@ -85,8 +85,8 @@ pub fn handle_config_show() -> anyhow::Result<()> {
// Build the complete output as a string
let mut output = String::new();
- // Render global config
- render_global_config(&mut output)?;
+ // Render user config
+ render_user_config(&mut output)?;
output.push('\n');
// Render project config if in a git repository
@@ -106,9 +106,9 @@ pub fn handle_config_show() -> anyhow::Result<()> {
Ok(())
}
-fn render_global_config(out: &mut String) -> anyhow::Result<()> {
+fn render_user_config(out: &mut String) -> anyhow::Result<()> {
// Get config path
- let config_path = get_global_config_path().ok_or_else(|| {
+ let config_path = get_user_config_path().ok_or_else(|| {
anyhow::anyhow!(
"Cannot determine config directory. Set $HOME or $XDG_CONFIG_HOME environment variable"
)
@@ -118,7 +118,7 @@ fn render_global_config(out: &mut String) -> anyhow::Result<()> {
out,
"{}",
cformat!(
- "{INFO_EMOJI} Global Config: <bold>{}</>",
+ "{INFO_EMOJI} User Config: <bold>{}</>",
format_path_for_display(&config_path)
)
)?;
@@ -370,7 +370,7 @@ fn check_zsh_compinit_missing() -> bool {
}
}
-fn get_global_config_path() -> Option<PathBuf> {
+fn get_user_config_path() -> Option<PathBuf> {
// Respect XDG_CONFIG_HOME environment variable for testing (Linux)
if let Ok(xdg_config) = std::env::var("XDG_CONFIG_HOME") {
let config_path = PathBuf::from(xdg_config);
diff --git a/src/config/user.rs b/src/config/user.rs
index c07a1dc00..fc592073e 100644
--- a/src/config/user.rs
+++ b/src/config/user.rs
@@ -10,10 +10,10 @@ use std::sync::OnceLock;
#[cfg(not(test))]
use etcetera::base_strategy::{BaseStrategy, choose_base_strategy};
-/// Global override for config path, set via --config CLI flag
+/// Override for user config path, set via --config CLI flag
static CONFIG_PATH: OnceLock<PathBuf> = OnceLock::new();
-/// Set the global config path override (called from CLI --config flag)
+/// Set the user config path override (called from CLI --config flag)
pub fn set_config_path(path: PathBuf) {
CONFIG_PATH.set(path).ok();
}
diff --git a/tests/integration_tests/config_init.rs b/tests/integration_tests/config_init.rs
index 43913f0f2..8d088e1e0 100644
--- a/tests/integration_tests/config_init.rs
+++ b/tests/integration_tests/config_init.rs
@@ -30,7 +30,7 @@ fn test_config_init_already_exists() {
----- stdout -----
----- stderr -----
- ⚪ Global config already exists: ~/.config/worktrunk/config.toml
+ ⚪ User config already exists: ~/.config/worktrunk/config.toml
💡 Use 'wt config show' to view existing configuration
💡 Use 'wt config create --help' for config format reference
diff --git a/tests/integration_tests/config_show.rs b/tests/integration_tests/config_show.rs
index 33d31d9ab..b8539f98f 100644
--- a/tests/integration_tests/config_show.rs
+++ b/tests/integration_tests/config_show.rs
@@ -51,7 +51,7 @@ server = "npm run dev"
----- stdout -----
----- stderr -----
- ⚪ Global Config: ~/.config/worktrunk/config.toml
+ ⚪ User Config: ~/.config/worktrunk/config.toml
  worktree-path = "../{{ main_worktree }}.{{ branch }}"
 
  [projects."test-project"]
@@ -99,7 +99,7 @@ fn test_config_show_no_project_config() {
----- stdout -----
----- stderr -----
- ⚪ Global Config: ~/.config/worktrunk/config.toml
+ ⚪ User Config: ~/.config/worktrunk/config.toml
  worktree-path = "../{{ main_worktree }}.{{ branch }}"
⚪ Project Config: [REPO]/.config/wt.toml
@@ -140,7 +140,7 @@ fn test_config_show_outside_git_repo() {
----- stdout -----
----- stderr -----
- ⚪ Global Config: ~/.config/worktrunk/config.toml
+ ⚪ User Config: ~/.config/worktrunk/config.toml
  worktree-path = "../{{ main_worktree }}.{{ branch }}"
⚪ Project Config: Not in a git repository
@@ -296,7 +296,7 @@ fn test_config_show_warns_unknown_project_keys() {
----- stdout -----
----- stderr -----
- ⚪ Global Config: ~/.config/worktrunk/config.toml
+ ⚪ User Config: ~/.config/worktrunk/config.toml
  worktree-path = "../{{ main_worktree }}.{{ branch }}"
⚪ Project Config: [REPO]/.config/wt.toml
@@ -339,7 +339,7 @@ fn test_config_show_warns_unknown_user_keys() {
----- stdout -----
----- stderr -----
- ⚪ Global Config: ~/.config/worktrunk/config.toml
+ ⚪ User Config: ~/.config/worktrunk/config.toml
🟡 Unknown key commit-gen will be ignored
  worktree-path = "../{{ main_worktree }}.{{ branch }}"
 
diff --git a/tests/snapshots/integration__integration_tests__config_show__config_show_partial_shell_config_shows_hint.snap b/tests/snapshots/integration__integration_tests__config_show__config_show_partial_shell_config_shows_hint.snap
index fbdebf595..395da8f33 100644
--- a/tests/snapshots/integration__integration_tests__config_show__config_show_partial_shell_config_shows_hint.snap
+++ b/tests/snapshots/integration__integration_tests__config_show__config_show_partial_shell_config_shows_hint.snap
@@ -27,7 +27,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-⚪ Global Config: ~/.config/worktrunk/config.toml
+⚪ User Config: ~/.config/worktrunk/config.toml
💡 Empty file (using defaults)
⚪ Project Config: [REPO]/.config/wt.toml
diff --git a/tests/snapshots/integration__integration_tests__config_show__config_show_zsh_compinit_correct_order.snap b/tests/snapshots/integration__integration_tests__config_show__config_show_zsh_compinit_correct_order.snap
index 90a7c2616..6ca1a92ae 100644
--- a/tests/snapshots/integration__integration_tests__config_show__config_show_zsh_compinit_correct_order.snap
+++ b/tests/snapshots/integration__integration_tests__config_show__config_show_zsh_compinit_correct_order.snap
@@ -27,7 +27,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-⚪ Global Config: ~/.config/worktrunk/config.toml
+⚪ User Config: ~/.config/worktrunk/config.toml
💡 Empty file (using defaults)
⚪ Project Config: [REPO]/.config/wt.toml
diff --git a/tests/snapshots/integration__integration_tests__config_show__config_show_zsh_compinit_warning.snap b/tests/snapshots/integration__integration_tests__config_show__config_show_zsh_compinit_warning.snap
index c8c6554fa..4e8d877d6 100644
--- a/tests/snapshots/integration__integration_tests__config_show__config_show_zsh_compinit_warning.snap
+++ b/tests/snapshots/integration__integration_tests__config_show__config_show_zsh_compinit_warning.snap
@@ -26,7 +26,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-⚪ Global Config: ~/.config/worktrunk/config.toml
+⚪ User Config: ~/.config/worktrunk/config.toml
💡 Empty file (using defaults)
⚪ Project Config: [REPO]/.config/wt.toml
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 eba04845c..b59cb267e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -19,7 +19,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt config create - Create global configuration file
+wt config create - Create user configuration file
Usage: wt config create [OPTIONS]
Options:
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 e2218549b..8b4aec2a6 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -23,7 +23,7 @@ Usage: wt config [OPTIONS] <COMMAND>
Commands:
shell Shell integration setup
- create Create global configuration file
+ create Create user configuration file
show Show configuration files & locations
cache Manage caches (CI status, default branch)
status Manage branch status markers
@@ -53,17 +53,17 @@ Usage: wt config [OPTIONS] <COMMAND>
 eval "$(wt config shell init bash)"
-2. (Optional) Create config file
+2. (Optional) Create user config file
 wt config create
- This creates ~/.config/worktrunk/config.toml with examples.
+ This creates ~/.config/worktrunk/config.toml with examples.
3. (Optional) Enable LLM commit messages
Install: uv tool install -U llm
Configure: llm keys set anthropic
- Add to config.toml:
+ Add to user config:
 [commit-generation]
 command = "llm"
@@ -85,7 +85,7 @@ Docs: <https://llm.datasette.io/> | <https://github.com/sigoden/aichat>
Configuration Files
-Global config (user settings):
+User config:
- Location: ~/.config/worktrunk/config.toml (or WORKTRUNK_CONFIG_PATH)
- Run wt config create --help to view documented examples
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 dfe8cfd47..e7296d773 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_short.snap
@@ -23,7 +23,7 @@ Usage: wt config [OPTIONS] <COMMAND>
Commands:
shell Shell integration setup
- create Create global configuration file
+ create Create user configuration file
show Show configuration files & locations
cache Manage caches (CI status, default branch)
status Manage branch status markers
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_show.snap b/tests/snapshots/integration__integration_tests__help__help_config_show.snap
index 0d99ff654..b873869d9 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_show.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_show.snap
@@ -36,7 +36,7 @@ Usage: wt config show [OPTIONS]
-v, --verbose
Show commands and debug info
-Shows location and contents of global config (~/.config/worktrunk/config.toml)
+Shows location and contents of user config (~/.config/worktrunk/config.toml)
and project config (.config/wt.toml).
If a config file doesn't exist, shows defaults that would be used.
diff --git a/tests/snapshots/integration__integration_tests__internal_flag__config_show_with_internal_flag.snap b/tests/snapshots/integration__integration_tests__internal_flag__config_show_with_internal_flag.snap
index 22263bec2..30ad26fcd 100644
--- a/tests/snapshots/integration__integration_tests__internal_flag__config_show_with_internal_flag.snap
+++ b/tests/snapshots/integration__integration_tests__internal_flag__config_show_with_internal_flag.snap
@@ -27,7 +27,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-⚪ Global Config: ~/.config/worktrunk/config.toml
+⚪ User Config: ~/.config/worktrunk/config.toml
  worktree-path = "../{{ main_worktree }}.{{ branch }}"
⚪ Project Config: [REPO]/.config/wt.toml