Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! User-level configuration
//!
//! Personal preferences and per-project approved commands, not checked into git.
//!
//! # Precedence
//!
//! Sources rank by how close they are to the invocation: system config, user
//! config, `WORKTRUNK_*` env vars, `--config-set`. Within a layer, a
//! `[projects."…"]` entry outranks the global key of the same name; across
//! layers, a higher layer's global key beats a lower layer's entry.
//!
//! [`UserConfig::load_with_warnings`] flattens the layers into one document
//! and the accessors resolve specificity on the result — which alone would let
//! any entry beat any global key, whichever layer set it. So each layer merges
//! through [`merge_layer`], which first drops what the layer sets globally
//! from the entries beneath it.
mod accessors;
mod merge;
pub(crate) mod mutation;
mod path;
mod persistence;
pub(crate) mod project_match;
mod resolved;
mod schema;
mod sections;
#[cfg(test)]
mod tests;
use std::collections::HashSet;
use std::path::{Path, PathBuf};
use std::sync::{LazyLock, Mutex, OnceLock};
use super::{ConfigError, ConfigFileKind};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
/// Inline config overrides from the CLI `--config-set <toml>` flag, in
/// invocation order.
///
/// Set once from `main` after arg parsing (mirroring [`set_config_path`]) and
/// applied by [`UserConfig::load_with_warnings`] as the highest-priority layer,
/// above config files and `WORKTRUNK_*` env vars. Each entry is an independent
/// TOML fragment (e.g. `list.full = true`); later entries replace earlier ones
/// for the same key.
static CONFIG_OVERRIDES: OnceLock<Vec<String>> = OnceLock::new();
/// Explicit config paths already reported missing in this process.
static WARNED_MISSING_CONFIG_PATHS: LazyLock<Mutex<HashSet<PathBuf>>> =
LazyLock::new(|| Mutex::new(HashSet::new()));
/// Record the CLI `--config-set` overrides (called once from the
/// `--config-set` flag in `main`).
pub fn set_config_overrides(overrides: Vec<String>) {
CONFIG_OVERRIDES.set(overrides).ok();
}
/// The CLI `--config-set` overrides, empty when the flag was not used.
fn cli_config_overrides() -> &'static [String] {
CONFIG_OVERRIDES.get().map_or(&[], Vec::as_slice)
}
// Re-export public types
pub use merge::Merge;
pub use path::{
config_path, config_path_for_display, default_config_path, require_config_path,
set_config_path, system_config_path,
};
pub use resolved::ResolvedConfig;
pub use schema::valid_user_config_keys;
pub use sections::{
CommitConfig, CommitGenerationConfig, CopyIgnoredConfig, ListColumnConfig, ListConfig,
MergeConfig, RemoveConfig, StageMode, StepConfig, SwitchConfig, SwitchPickerConfig,
UserProjectOverrides,
};
/// Describes a problem encountered during config loading. Each variant
/// identifies which layer failed so callers can emit targeted diagnostics
/// (file errors with line/col vs env-var attribution).
///
/// Strict loading treats the first issue other than a rejected env-var
/// override as fatal; best-effort [`UserConfig::load_with_warnings()`]
/// returns all issues alongside the usable config.
#[derive(Debug)]
pub enum LoadError {
/// A file parser failed, retaining its source and raw diagnosis.
File(super::ConfigParseError),
/// An env-var override setting was rejected; other settings' overrides
/// may still apply. `vars` lists the `WORKTRUNK_*` env vars forming the
/// rejected setting as `(name, value)` pairs.
Env {
err: String,
vars: Vec<(String, String)>,
},
/// Lower layers loaded cleanly; applying CLI `--config-set` overrides
/// failed — either a fragment was not valid TOML or the merged result no
/// longer deserializes. `overrides` lists the raw values for attribution.
CliOverride { err: String, overrides: Vec<String> },
/// Validation errors (e.g. empty worktree-path).
Validation(String),
}
impl std::fmt::Display for LoadError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
LoadError::File(error) => error.fmt(f),
LoadError::Env { err, .. } => write!(f, "{err}"),
LoadError::CliOverride { err, .. } => write!(f, "{err}"),
LoadError::Validation(err) => write!(f, "{err}"),
}
}
}
impl std::error::Error for LoadError {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Self::File(error) => Some(error),
_ => None,
}
}
}
// ---- Env-var overlay ----
/// A single parsed WORKTRUNK_* env var with both typed and string representations.
#[derive(Clone)]
struct EnvVar {
/// Original env var name (e.g., `WORKTRUNK__LIST__TIMEOUT_MS`)
name: String,
/// TOML path segments (e.g., `["list", "timeout-ms"]`)
segments: Vec<String>,
/// Typed TOML value (bool/int/float/string coercion via [`try_parse_value`])
typed_value: toml::Value,
/// Raw string value, kept for fallback when the typed form doesn't match
/// the target field's type (e.g., `WORKTRUNK_WORKTREE_PATH=42` needs
/// `String`, not `Integer`).
raw_value: String,
}
/// Environment overrides that form one independently validatable setting.
///
/// Most settings are one leaf. Entries under an atomic section (currently a
/// custom list column) stay together so a required field and its companion
/// fields are validated as the setting the user actually configured.
#[derive(Default)]
struct EnvOverrideUnit {
vars: Vec<EnvVar>,
overlay: toml::Table,
}
/// Read `WORKTRUNK_*` env vars and parse each into an [`EnvVar`].
///
/// Env-var convention (matches the config crate's prior behavior):
/// - `WORKTRUNK_WORKTREE_PATH=foo` → `worktree-path = "foo"`
/// - `WORKTRUNK__LIST__TIMEOUT_MS=30` → `[list]\ntimeout-ms = 30`
/// - `WORKTRUNK_COMMIT__GENERATION__COMMAND=cmd` → `[commit.generation]\ncommand = "cmd"`
///
/// Infrastructure vars (`_CONFIG_PATH`, `_SYSTEM_CONFIG_PATH`,
/// `_APPROVALS_PATH`) and test vars (`_TEST_*`) are excluded.
fn parse_worktrunk_env_vars() -> Vec<EnvVar> {
const INFRA_VARS: &[&str] = &[
"WORKTRUNK_CONFIG_PATH",
"WORKTRUNK_SYSTEM_CONFIG_PATH",
"WORKTRUNK_APPROVALS_PATH",
];
// `std::env::vars()` panics on any non-UTF-8 entry, including unrelated
// ones; skip those entries instead.
let mut env_vars: Vec<_> = std::env::vars_os()
.filter_map(|(k, v)| Some((k.into_string().ok()?, v.into_string().ok()?)))
.filter(|(k, _)| k.starts_with("WORKTRUNK_"))
.filter(|(k, _)| !INFRA_VARS.contains(&k.as_str()))
.filter(|(k, _)| !k.starts_with("WORKTRUNK_TEST_"))
.collect();
env_vars.sort_by(|a, b| a.0.cmp(&b.0));
env_vars
.into_iter()
.filter_map(|(key, value)| {
// Strip WORKTRUNK_ prefix, split by __ for nesting, convert to kebab-case
let stripped = &key["WORKTRUNK_".len()..];
let segments: Vec<String> = stripped
.split("__")
.map(|s| {
s.to_lowercase()
.replace('_', "-")
.trim_start_matches('-')
.to_string()
})
.filter(|s| !s.is_empty())
.collect();
if segments.is_empty() {
return None;
}
Some(EnvVar {
name: key,
segments,
typed_value: try_parse_value(&value),
raw_value: value,
})
})
.collect()
}
/// Canonicalize a built env-var overlay through the same deprecation migration
/// as config files and `--config-set`, so a deprecated env var such as
/// `WORKTRUNK__MERGE__NO_FF` (which resolves to the deprecated key
/// `merge.no-ff`) takes effect as `merge.ff` instead of falling through as an
/// unknown field. Migrating before the deep-merge keeps env winning over a
/// lower layer's canonical key — the same fragment-before-merge ordering
/// [`UserConfig::apply_cli_overrides`] uses.
///
/// The rewrite is silent, matching the other ephemeral layer: an env overlay
/// has no file for `wt config update` to materialize.
///
/// Round-trips through [`super::deprecation::migrate_content`]'s string form.
/// The overlay's leaves are the scalars [`try_parse_value`] produces (bool,
/// int, float, string) plus nested tables, so it always serializes, and
/// `migrate_content` always returns valid TOML — mirroring the same
/// post-migration reparse `expect` in [`load_config_file`].
///
/// Canonicalization happens before choosing typed or string representations,
/// so deprecated names are checked against the same field types as canonical
/// names.
fn migrate_env_overlay(overlay: toml::Table) -> toml::Table {
let serialized = toml::to_string(&overlay).expect("env overlay serializes to TOML");
super::deprecation::migrate_content(&serialized)
.parse::<toml::Table>()
.expect("migrate_content returns valid TOML")
}
/// Return the path of a single-variable overlay after deprecation migration.
/// Migration moves, renames, or removes a scalar; it never expands it into
/// several settings. Removing an obsolete setting can leave an empty overlay.
fn env_overlay_path(mut table: &toml::Table) -> Option<Vec<String>> {
let mut path = Vec::new();
loop {
let (key, value) = table.iter().next()?;
path.push(key.clone());
match value {
toml::Value::Table(nested) if !nested.is_empty() => table = nested,
_ => return Some(path),
}
}
}
/// Group the fields that make up one setting, keeping atomic section entries
/// together. This reuses the same atomic-section contract as project precedence.
fn env_override_key(path: &[String]) -> Vec<String> {
for section_len in 0..path.len() {
let section: Vec<_> = path[..section_len].iter().map(String::as_str).collect();
let project_section =
section.len() == 4 && section[0] == "projects" && is_atomic_section(§ion[2..]);
if is_atomic_section(§ion) || project_section {
return path[..section_len + 1].to_vec();
}
}
path.to_vec()
}
/// Build and migrate an overlay from a chosen representation for every var.
fn env_overlay_from_values(vars: &[EnvVar], values: &[toml::Value]) -> toml::Table {
let mut overlay = toml::Table::new();
for (var, value) in vars.iter().zip(values) {
set_nested_value(&mut overlay, &var.segments, value.clone());
}
migrate_env_overlay(overlay)
}
/// Choose typed or string values for one setting as a group. Probing the
/// whole setting keeps required compound fields together: a custom column's
/// width can be typed as an integer when its required template arrives in the
/// same environment layer.
fn resolve_env_override_unit(file_table: &toml::Table, vars: &[EnvVar]) -> toml::Table {
let mut values: Vec<_> = vars.iter().map(|var| var.typed_value.clone()).collect();
loop {
let mut changed = false;
for (index, var) in vars.iter().enumerate() {
let overlay = env_overlay_from_values(vars, &values);
let mut candidate = file_table.clone();
merge_layer(&mut candidate, overlay);
if toml::Value::Table(candidate)
.try_into::<UserConfig>()
.is_ok()
{
continue;
}
let typed_value = std::mem::replace(
&mut values[index],
toml::Value::String(var.raw_value.clone()),
);
let overlay = env_overlay_from_values(vars, &values);
let mut candidate = file_table.clone();
merge_layer(&mut candidate, overlay);
if toml::Value::Table(candidate)
.try_into::<UserConfig>()
.is_ok()
{
changed = true;
} else {
values[index] = typed_value;
}
}
if !changed {
return env_overlay_from_values(vars, &values);
}
}
}
/// Resolve, migrate, and group each environment variable against the same
/// lower-layer config. Sorting makes aliases that migrate to one setting
/// deterministic, independent of the caller's input order.
fn env_override_units(file_table: &toml::Table, vars: &[EnvVar]) -> Vec<EnvOverrideUnit> {
let mut ordered_vars: Vec<_> = vars.iter().collect();
ordered_vars.sort_by(|left, right| left.name.cmp(&right.name));
let mut grouped_vars = std::collections::BTreeMap::<Vec<String>, Vec<EnvVar>>::new();
for var in ordered_vars {
let overlay = env_overlay_from_values(
std::slice::from_ref(var),
std::slice::from_ref(&var.typed_value),
);
let Some(path) = env_overlay_path(&overlay) else {
continue;
};
let key = env_override_key(&path);
grouped_vars.entry(key).or_default().push(var.clone());
}
grouped_vars
.into_values()
.map(|vars| EnvOverrideUnit {
overlay: resolve_env_override_unit(file_table, &vars),
vars,
})
.collect()
}
/// Try to coerce a string into a typed TOML value (bool → i64 → f64 → string).
fn try_parse_value(s: &str) -> toml::Value {
if s.eq_ignore_ascii_case("true") {
return toml::Value::Boolean(true);
}
if s.eq_ignore_ascii_case("false") {
return toml::Value::Boolean(false);
}
if let Ok(n) = s.parse::<i64>() {
return toml::Value::Integer(n);
}
if let Ok(n) = s.parse::<f64>() {
return toml::Value::Float(n);
}
toml::Value::String(s.to_string())
}
/// Set a value at a nested path in a TOML table, creating intermediate tables.
fn set_nested_value(table: &mut toml::Table, path: &[String], value: toml::Value) {
if path.len() == 1 {
table.insert(path[0].clone(), value);
return;
}
let entry = table
.entry(&path[0])
.or_insert_with(|| toml::Value::Table(toml::Table::new()));
if let toml::Value::Table(inner) = entry {
set_nested_value(inner, &path[1..], value);
}
}
/// Recursively merge `overlay` into `base`. Overlay values win for scalars;
/// nested tables merge recursively.
fn deep_merge_table(base: &mut toml::Table, overlay: toml::Table) {
for (key, value) in overlay {
match (base.get_mut(&key), &value) {
(Some(toml::Value::Table(base_t)), toml::Value::Table(overlay_t)) => {
deep_merge_table(base_t, overlay_t.clone());
}
_ => {
base.insert(key, value);
}
}
}
}
/// Merge one layer over `merged_table`, ranking its global keys above the
/// `[projects."…"]` entries the lower layers left there.
///
/// Every leaf `layer` sets globally is dropped from the accumulated entries
/// first, so the global key it also set is what answers for them; the layer
/// then merges on top, its own entries included. Dropping before the merge is
/// what keeps specificity local to a layer — a key the layer restates under
/// `projects."<name>"` lands after the drop and wins, with nothing here having
/// to recognize the case.
///
/// Composing keys are held back, their project-scoped values appending to the
/// global ones rather than replacing them ([`is_compose_only`]). Both already
/// apply, so there is no ranking to settle, and dropping the project's copy
/// would silently stop it running.
///
/// Only removals precede the merge, but a removal can still leave a document
/// that no longer deserializes: [`is_atomic_section`] names the sections that
/// have to go as a unit, and the removals degrade as a unit behind them — they
/// land on a candidate, and a candidate that stops
/// deserializing or validating is dropped for the plain merge rather than
/// handed to [`UserConfig::finalize`], which would answer a stranded required
/// field by wiping the config to defaults. The layer itself applies either way.
fn merge_layer(merged_table: &mut toml::Table, layer: toml::Table) {
// Nothing to rank: no entries beneath, or nothing above them. The common
// case is a config with no `[projects]` table at all, and it pays only the
// lookup.
if !merged_table.contains_key("projects") || layer.keys().all(|key| key == "projects") {
deep_merge_table(merged_table, layer);
return;
}
let mut global = layer.clone();
global.remove("projects");
let mut candidate = merged_table.clone();
if let Some(projects) = candidate
.get_mut("projects")
.and_then(toml::Value::as_table_mut)
{
for entry in projects
.iter_mut()
.filter_map(|(_, entry)| entry.as_table_mut())
{
drop_overridden_keys(entry, &global, &mut Vec::new());
}
}
deep_merge_table(&mut candidate, layer.clone());
match deserialize_and_validate(&candidate) {
Ok(()) => *merged_table = candidate,
// Reachable when a partial removal the enumerations above miss would
// invalidate the candidate, or when the layer itself is invalid (for
// example, an empty global `worktree-path` from the environment or
// `--config-set`). Keep the layer without the removals so its caller
// can validate and attribute the complete candidate.
Err(err) => {
log::debug!("keeping project precedence: {err}");
deep_merge_table(merged_table, layer);
}
}
}
/// Deserialize `table` into [`UserConfig`] and validate it, reporting the
/// first failure. The probe every layer runs before it commits.
fn deserialize_and_validate(table: &toml::Table) -> Result<(), String> {
match toml::Value::Table(table.clone()).try_into::<UserConfig>() {
Ok(config) => config.validate().map_err(|e| e.to_string()),
Err(err) => Err(err.to_string()),
}
}
fn deserialize_validation_issues(
table: &toml::Table,
) -> Result<Vec<persistence::UserConfigValidationIssue>, String> {
let config = toml::Value::Table(table.clone())
.try_into::<UserConfig>()
.map_err(|err| err.to_string())?;
Ok(config.validation_issues())
}
/// Remove from `entry` every leaf `overlay` sets. `section` tracks the path
/// walked so far for the predicates beside it.
fn drop_overridden_keys<'a>(
entry: &mut toml::Table,
overlay: &'a toml::Table,
section: &mut Vec<&'a str>,
) {
for (key, value) in overlay {
if is_compose_only(section, key) {
continue;
}
match (entry.get_mut(key.as_str()), value) {
// Both sides are sections: recurse, so an override of one leaf
// leaves the project's sibling leaves alone. An atomic section's
// children are not sections in that sense — they go whole, through
// the arms below.
(Some(toml::Value::Table(entry_table)), toml::Value::Table(overlay_table))
if !is_atomic_section(section) =>
{
section.push(key);
drop_overridden_keys(entry_table, overlay_table, section);
section.pop();
if entry_table.is_empty() {
entry.remove(key.as_str());
}
}
(Some(_), _) => {
entry.remove(key.as_str());
}
(None, _) => {}
}
}
}
/// A table whose entries the merge replaces whole, so removing one of an
/// entry's leaves neither removes the precedence nor leaves the entry usable.
///
/// `[list.custom-columns]` is the case: `ListConfig::merge_with` extends
/// `custom_columns` per *column*, so a project's `Ticket` replaces the global
/// `Ticket` outright — dropping only the overridden leaf would leave the
/// project's column winning anyway, the ranking this pass exists to remove.
/// And `ListColumnConfig::template` is required, so a partial removal can
/// strand a column that no longer deserializes.
///
/// `section` is the path of the containing table, so this asks "are this
/// table's children atomic".
fn is_atomic_section(section: &[&str]) -> bool {
section == ["list", "custom-columns"]
}
/// Whether the project-scoped `key` under `section` composes with the global
/// one instead of replacing it, so no layer displaces it.
///
/// Hook names come from the schema, cached the way
/// `config::is_user_project_override_key` caches its own lookup, so a new hook
/// can't be forgotten. The others are the composing keys elsewhere in the tree
/// — `[aliases]` (`UserConfig::aliases`) and `step.copy-ignored.exclude`
/// (`CopyIgnoredConfig::merged_with` unions the two pattern lists).
fn is_compose_only(section: &[&str], key: &str) -> bool {
static HOOKS: OnceLock<Vec<String>> = OnceLock::new();
match section {
[] => {
key == "aliases"
|| HOOKS
.get_or_init(crate::config::schema_top_level_keys::<crate::config::HooksConfig>)
.iter()
.any(|hook| hook == key)
}
["step", "copy-ignored"] => key == "exclude",
_ => false,
}
}
/// Load and validate a single config file. Returns the parsed table for
/// merging and validates via `toml::from_str::<UserConfig>` for rich errors.
fn load_config_file(
path: &Path,
migrated: &str,
kind: ConfigFileKind,
) -> Result<toml::Table, LoadError> {
// Validate by deserializing — gives rich line/col errors.
if let Err(err) = toml::from_str::<UserConfig>(migrated) {
return Err(LoadError::File(super::ConfigParseError::new(
kind, path, err,
)));
}
// Parse as table for merging. Infallible after from_str::<UserConfig>
// succeeds — valid UserConfig TOML is always valid TOML.
Ok(migrated
.parse::<toml::Table>()
.expect("valid TOML after UserConfig parse"))
}
/// User-level configuration for worktree path formatting and LLM integration.
///
/// This config is stored at `~/.config/worktrunk/config.toml` (or platform equivalent)
/// and is NOT checked into git. Each developer maintains their own user config.
///
/// The `worktree-path` template is relative to the repository root.
/// Supported variables:
/// - `{{ repo }}` - Repository directory name (e.g., `myproject`)
/// - `{{ branch }}` - Raw branch name (e.g., `feature/auth`)
/// - `{{ branch | sanitize }}` - Branch name with `/` and `\` replaced by `-`
///
/// # Examples
///
/// ```toml
/// # Default - parent directory siblings
/// worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
///
/// # Inside repo (clean, no redundant directory)
/// worktree-path = ".worktrees/{{ branch | sanitize }}"
///
/// # Repository-namespaced (useful for shared directories with multiple repos)
/// worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"
///
/// # Commit generation configuration
/// [commit.generation]
/// command = "llm -m claude-haiku-4.5" # Shell command for generating commit messages
///
/// # Per-project configuration
/// [projects."github.com/user/repo"]
/// worktree-path = ".worktrees/{{ branch | sanitize }}"
/// ```
///
/// Config file location:
/// - Linux: `$XDG_CONFIG_HOME/worktrunk/config.toml` or `~/.config/worktrunk/config.toml`
/// - macOS: `$XDG_CONFIG_HOME/worktrunk/config.toml` or `~/.config/worktrunk/config.toml`
/// - Windows: `%APPDATA%\worktrunk\config.toml`
///
/// Environment variables can override config file settings using `WORKTRUNK_` prefix with
/// `__` separator for nested fields (e.g., `WORKTRUNK_COMMIT__GENERATION__COMMAND`).
#[derive(Debug, Default, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct UserConfig {
/// Per-project configuration (approved commands, etc.)
/// Uses BTreeMap for deterministic serialization order and better diff readability
#[serde(default)]
pub projects: std::collections::BTreeMap<String, UserProjectOverrides>,
/// Hooks configuration (top-level keys like pre-merge, post-switch, etc.)
#[serde(flatten, default)]
pub hooks: crate::config::HooksConfig,
/// Worktree path template
#[serde(
rename = "worktree-path",
default,
skip_serializing_if = "Option::is_none"
)]
pub worktree_path: Option<String>,
/// Configuration for the `wt list` command
#[serde(default, skip_serializing_if = "super::is_default")]
pub list: sections::ListConfig,
/// Configuration for the `wt step commit` command (also used by merge)
#[serde(default, skip_serializing_if = "super::is_default")]
pub commit: sections::CommitConfig,
/// Configuration for the `wt merge` command
#[serde(default, skip_serializing_if = "super::is_default")]
pub merge: sections::MergeConfig,
/// Configuration for the `wt remove` command
#[serde(default, skip_serializing_if = "super::is_default")]
pub remove: sections::RemoveConfig,
/// Configuration for the `wt switch` command
#[serde(default, skip_serializing_if = "super::is_default")]
pub switch: sections::SwitchConfig,
/// Configuration for `wt step` subcommands
#[serde(default, skip_serializing_if = "super::is_default")]
pub step: sections::StepConfig,
/// Command aliases for `wt <name>`
#[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
pub aliases: std::collections::BTreeMap<String, crate::config::commands::CommandConfig>,
/// Skip the first-run shell integration prompt
#[serde(
default,
rename = "skip-shell-integration-prompt",
skip_serializing_if = "std::ops::Not::not"
)]
pub skip_shell_integration_prompt: bool,
/// Skip the first-run commit generation prompt
#[serde(
default,
rename = "skip-commit-generation-prompt",
skip_serializing_if = "std::ops::Not::not"
)]
pub skip_commit_generation_prompt: bool,
}
impl UserConfig {
/// Load configuration from system config, user config, and environment variables.
///
/// Configuration is loaded in the following order (later sources override earlier ones):
/// 1. Default values
/// 2. System config (organization-wide defaults)
/// 3. User config file (personal preferences)
/// 4. Environment variables (WORKTRUNK_*)
pub fn load() -> Result<Self, ConfigError> {
Self::load_with_cause().map_err(ConfigError::Load)
}
/// Like [`load()`](Self::load), but returns a [`LoadError`] that
/// distinguishes file-level parse failures (with line/col) from
/// `--config-set` and validation failures.
///
/// A rejected env-var override is not an error: like the tolerant load,
/// the setting falls back to the file layers and the other overrides
/// still apply. Its warning is emitted at startup by the user-config
/// prewarm, so every command reports it the same way.
pub(crate) fn load_with_cause() -> Result<Self, LoadError> {
let (config, warnings) = Self::load_with_warnings();
if let Some(err) = warnings
.into_iter()
.find(|warning| !matches!(warning, LoadError::Env { .. }))
{
return Err(err);
}
Ok(config)
}
/// Load the best config achievable, collecting issues as warnings.
///
/// Each config layer (system file, user file, env-var overlay) degrades
/// independently — a failure in one preserves data from earlier layers
/// instead of falling back to defaults. This means:
/// - Bad system config → skipped, user config + env vars still apply
/// - Bad user config → skipped, system config + env vars still apply
/// - Bad env vars → ignored, file-based config preserved
/// - Validation failure → warning emitted, defaults used (invalid config
/// causes bad behavior if applied, e.g. empty worktree-path template)
pub fn load_with_warnings() -> (Self, Vec<LoadError>) {
let mut warnings = Vec::new();
let mut merged_table = toml::Table::new();
// File layers merge in priority order: user settings override system settings.
for (config_path, kind) in [
(path::system_config_path(), ConfigFileKind::System),
(config_path(), ConfigFileKind::User),
] {
let Some(config_path) = config_path else {
continue;
};
let content = match std::fs::read_to_string(&config_path) {
Ok(content) => content,
Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
if kind == ConfigFileKind::User
&& path::is_config_path_explicit()
&& WARNED_MISSING_CONFIG_PATHS
.lock()
.unwrap()
.insert(config_path.clone())
{
crate::styling::eprintln!(
"{}",
crate::styling::warning_message(color_print::cformat!(
"Config file not found: <bold>{}</>",
crate::path::format_path_for_display(&config_path)
))
);
}
continue;
}
Err(err) => {
warnings.push(LoadError::Validation(format!(
"Failed to read {} @ {}: {err}",
kind.label().to_lowercase(),
crate::path::format_path_for_display(&config_path)
)));
continue;
}
};
match super::deprecation::check_and_migrate(
&config_path,
&content,
true,
kind,
None,
true,
) {
Ok(result) => {
super::deprecation::warn_unknown_fields::<UserConfig>(
&content,
&config_path,
kind,
);
match load_config_file(&config_path, &result.migrated_content, kind) {
Ok(table) => merge_layer(&mut merged_table, table),
Err(err) => warnings.push(err),
}
}
Err(err) => {
warnings.push(LoadError::Validation(err.to_string()));
}
}
}
// 3. Env-var overrides (override config files)
let env_vars = parse_worktrunk_env_vars();
if let Err(err) = Self::apply_env_vars(&env_vars, &mut merged_table, &mut warnings) {
warnings.push(LoadError::Validation(err));
return (Self::default(), warnings);
}
// 4. CLI `--config-set` overrides (override env vars and config files)
Self::apply_cli_overrides(cli_config_overrides(), &mut merged_table, &mut warnings);
Self::finalize(merged_table, warnings)
}
/// Apply the environment override layer above the file layers.
fn apply_env_vars(
env_vars: &[EnvVar],
merged_table: &mut toml::Table,
warnings: &mut Vec<LoadError>,
) -> Result<(), String> {
if env_vars.is_empty() {
return Ok(());
}
let file_table = merged_table.clone();
// File layers deserialize before merging. A malformed merged table
// is a loader error, rather than an error attributed to an env var.
let lower_validation_issues = deserialize_validation_issues(&file_table)?;
// Validate each setting against the same lower layer. Sequentially
// accepting values here would make compound settings such as custom
// columns depend on which field happened to be visited first.
let mut accepted_overlay = toml::Table::new();
for unit in env_override_units(&file_table, env_vars) {
let mut candidate = file_table.clone();
merge_layer(&mut candidate, unit.overlay.clone());
match deserialize_validation_issues(&candidate) {
Ok(issues) => {
// An unrelated unit may leave an existing file error for
// another override to repair. A unit setting that invalid
// value itself must be rejected, even if its issue matches
// the lower layer: retaining it could undo a valid repair.
if let Some(issue) = issues.iter().find(|issue| {
!lower_validation_issues.contains(issue) || issue.is_set_in(&unit.overlay)
}) {
warnings.push(LoadError::Env {
err: issue.to_string(),
vars: unit
.vars
.into_iter()
.map(|var| (var.name, var.raw_value))
.collect(),
});
} else {
deep_merge_table(&mut accepted_overlay, unit.overlay);
}
}
Err(err) => warnings.push(LoadError::Env {
err,
vars: unit
.vars
.into_iter()
.map(|var| (var.name, var.raw_value))
.collect(),
}),
}
}
if accepted_overlay.is_empty() {
return Ok(());
}
let mut candidate = file_table.clone();
merge_layer(&mut candidate, accepted_overlay);
*merged_table = candidate;
Ok(())
}
/// Apply CLI `--config-set <toml>` overrides as the highest-priority layer.
///
/// Each override is an independent TOML fragment merged in order, so a
/// later override replaces an earlier one for the same key. Scalars and
/// arrays replace the lower-layer value, while nested tables deep-merge
/// (via [`deep_merge_table`]) so sibling keys survive —
/// `--config-set list.full=true` leaves `list.branches` untouched.
///
/// Each fragment first runs through the same deprecation migration as a
/// config file ([`super::deprecation::migrate_content`] — structural and
/// silent rewrites, no `UpdateOnly`), so a deprecated key such as
/// `merge.no-ff` is canonicalized to `merge.ff` *before* the fragment is
/// parsed and merged, instead of falling through as an unknown field.
/// Migrating the fragment
/// (not the merged document) keeps layer precedence intact: the
/// canonicalized override wins over a lower layer's canonical key, rather
/// than colliding with it. The rewrite is silent — there is no file to
/// materialize, so the file-scoped "run `wt config update`" warning would
/// have nothing to act on.
///
/// The whole layer degrades as a unit: if any fragment fails to parse, or
/// the merged result fails to deserialize or validate, every override is
/// dropped and a [`LoadError::CliOverride`] is recorded, so a bad override
/// never silently corrupts (or wipes) the lower layers.
fn apply_cli_overrides(
overrides: &[String],
merged_table: &mut toml::Table,
warnings: &mut Vec<LoadError>,
) {
if overrides.is_empty() {
return;
}
let mut overlay = toml::Table::new();
for raw in overrides {
// `migrate_content` returns the fragment unchanged when it is not
// valid TOML, so the parse below still catches a malformed fragment
// and drops the whole layer with an attributed warning.
let migrated = super::deprecation::migrate_content(raw);
match migrated.parse::<toml::Table>() {
Ok(fragment) => deep_merge_table(&mut overlay, fragment),
Err(err) => {
warnings.push(LoadError::CliOverride {
err: err.to_string(),
overrides: overrides.to_vec(),
});
return;
}
}
}
let mut candidate = merged_table.clone();
merge_layer(&mut candidate, overlay);
// Probe deserialize *and* validate, so a semantically-invalid override
// (e.g. an empty worktree-path) drops just this layer rather than
// falling through to finalize(), which would wipe the lower layers to
// defaults.
if let Err(err) = deserialize_and_validate(&candidate) {
warnings.push(LoadError::CliOverride {
err,
overrides: overrides.to_vec(),
});
return;
}
*merged_table = candidate;
}
/// Deserialize a merged table into `UserConfig`, validate, and collect
/// any issues as warnings. Shared by the no-env and env-fallback paths.
fn finalize(table: toml::Table, mut warnings: Vec<LoadError>) -> (Self, Vec<LoadError>) {
match toml::Value::Table(table).try_into::<Self>() {
Ok(config) => match config.validate() {
Ok(()) => (config, warnings),
Err(e) => {
// Validation means the config is semantically wrong (e.g.,
// worktree-path=""). Using it causes bad behavior, so fall
// back to defaults rather than applying the broken config.
warnings.push(LoadError::Validation(e.to_string()));
(Self::default(), warnings)
}
},
Err(err) => {
warnings.push(LoadError::Validation(err.to_string()));
(Self::default(), warnings)
}
}
}
/// Load configuration from a TOML string for testing.
#[cfg(test)]
pub(crate) fn load_from_str(content: &str) -> Result<Self, ConfigError> {
let migrated = crate::config::deprecation::migrate_content(content);
let config: Self =
toml::from_str(&migrated).map_err(|e| ConfigError::Message(e.to_string()))?;
config.validate()?;
Ok(config)
}
}