WORKTRUNK_WORKTREE_PATH does not override project-specific worktree-path

[jeremy0dell]

The configuration docs say:

All user config options can be overridden with environment variables using the WORKTRUNK_ prefix.

They specifically map worktree-path to WORKTRUNK_WORKTREE_PATH. However, a matching [projects."<id>"].worktree-path currently wins over the environment variable.

Reproduction:

tmp=$(mktemp -d) &&
git init -q -b main "$tmp/repo" &&
cd "$tmp/repo" &&
git config user.name Test &&
git config user.email test@example.com &&
touch README &&
git add README &&
git commit -qm initial &&
git remote add origin https://github.com/acme/demo.git &&
printf '[projects."github.com/acme/demo"]\nworktree-path = "%s/from-project"\n' "$tmp" > "$tmp/wt.toml" &&
WORKTRUNK_CONFIG_PATH="$tmp/wt.toml" \
WORKTRUNK_WORKTREE_PATH="$tmp/from-environment" \
wt switch --create feature --no-cd --no-hooks --yes --format=json

Actual output:

{"action":"created","branch":"feature","path":"/var/folders/2b/yvd22vqx2c95tq_lcsmf5k8w0000gn/T/tmp.y75Y7uvTHo/from-project","created_branch":true,"base_branch":"main"}

Expected: the worktree is created at $tmp/from-environment.

Actual: it is created at $tmp/from-project.

Should invocation-level overrides use this precedence?

--config-set > WORKTRUNK_WORKTREE_PATH > project config > global config

This could help my project by no longer needing this path arg resolver and this wt project config identifier. Would be happy to give this implementation a go

[worktrunk-bot]

Thanks — reproduced exactly as you described, and the diagnosis turns out to be a bit different from an env-layer bug: WORKTRUNK_WORKTREE_PATH does reach worktree-path fine. What loses is the global key, not the env layer.

Layer and specificity are separate steps. load_with_warnings merges system config → user config → env vars → --config-set into one document; worktree_path_for_project then resolves specificity on the merged result, and a [projects."…"] entry beats the global key whichever layer set it. So --config-set hits the same wall your env var does:

Invocation (your repro, [projects."github.com/acme/demo"].worktree-path set)	Created at
WORKTRUNK_WORKTREE_PATH=$tmp/from-environment	$tmp/from-project
--config-set 'worktree-path = "…/from-config-set"'	$tmp/from-project
--config-set 'projects."github.com/acme/demo".worktree-path = "…"'	the --config-set value ✅

That last row works today, which may cover your provider without the path arg resolver — --config-set takes a TOML fragment, so naming the project entry deep-merges into it. You'd still need the identifier (your second link), so it's a partial win rather than a full one.

I've opened #3789 to fix the docs, which currently promise env vars override "all user config options" without naming the specificity axis at all — that gap is why this reads as a bug, and it bites every user who sets both a project entry and an env var, not just this repro.

On your proposed precedence: I'd flag one tradeoff before it's implemented. WORKTRUNK_WORKTREE_PATH > project config means a export WORKTRUNK_WORKTREE_PATH=… in a shell profile silently clobbers every [projects."…"] layout — the env var stops being an override and becomes a global mute switch for per-project config. A narrower shape that keeps your use case: make it apply only when the var is set for that single invocation, or add an explicit opt-in. Either way it's a maintainer call on precedence semantics rather than something triage should land, so I'll leave the design decision to @max-sixty — your offer to implement it is very welcome.

Verification notes

Built main at 715af4cd7 and ran your repro verbatim plus the two --config-set variants; the table above is that output. test_switch_create_project_worktree_path_outranks_invocation_layers in #3789 pins all three rows end-to-end, with controls proving each invocation layer reaches the global key when no project entry is present.

The identifier for the [projects."…"] key comes from the raw remote.<name>.url (no .git suffix, url.insteadOf not applied); wt config show prints it in the PROJECT CONFIG section as Identifier: ….

[max-sixty]

env vars should indeed take precedence over the user project config, @worktrunk-bot we should fix this throughout

[max-sixty]

thanks @jeremy0dell ! The bug report is the really valuable bit. (no objection if you want to implement but the bug report is the useful part!)

[worktrunk-bot]

Done in #3790 — env vars and --config-set now outrank [projects."…"] entries, not just the global key. @jeremy0dell if you'd rather land this yourself, say the word and I'll close mine; it's a directive I picked up, not a claim on the issue.

The mechanism, since it turned out to be one change rather than a per-setting sweep: layer and specificity were resolved in separate steps, so the accessors saw a flat document and let a project entry answer for the global key whichever layer had set it. The two invocation layers now apply at both scopes — whatever they set is dropped from every project entry, so the global key they also set answers for it. That covers worktree-path and every other override-semantics key in one place.

Two things stay as they were. Naming the entry (--config-set 'projects."github.com/acme/demo".worktree-path = …') still wins, since it's the highest layer and the most specific key. And per-project hooks and aliases are untouched: those append to the global ones rather than replacing them, so an env-set hook was never being outranked, and dropping the project's copy would have silently stopped it running.

On the shell-profile concern I raised earlier — an exported WORKTRUNK_WORKTREE_PATH now does mute every [projects."…"] layout, which is the tradeoff @max-sixty called. Worth knowing if you export one persistently rather than per-invocation.

For your provider, this should retire both links: the path arg resolver since the plain env var now wins, and the project config identifier with it, since you no longer need the identifier to aim the override.

#3789 documented the old rule, so I've closed it; #3790 carries the corrected precedence section instead.