feat(config): local-context-first config via git local config

[bezhermoso]

Summary

Adds support for reading wt configuration directly from a repo's .git/config, enabling local-context-first semantics: a repo can carry its own wt configuration without requiring ~/.wt/repos/<name>.conf or wt context add setup.

This means a user can configure a repo once:

git config --local wt.enabled true
git config --local wt.worktreesBase ~/src/monorepo-worktrees
git config --local wt.ideaFilesBase ~/src/monorepo-idea
git config --local wt.baseBranch main

...and all wt commands Just Work from inside that repo or any of its worktrees, with no global context setup needed.

How it works

A new wt_read_git_config() function in lib/wt-common is called at source-time, before the existing wt_read_config(). It checks for the wt.enabled=true gate, reads wt.* keys from the repo's local git config via git config --local --get-regexp '^wt\.', validates them, and sets the corresponding WT_* shell variables.

Config precedence (highest to lowest)

Priority	Source	When it wins
1	Git local config (wt.* in .git/config)	CWD is inside a repo/worktree with wt.enabled=true and all required keys
2	Environment variable	Exported before wt-common sourced
3	Context .conf file	~/.wt/repos/<name>.conf has the value
4	Hardcoded default	Nothing else provided it

Git config keys

Git config key	Shell variable	Required?
wt.enabled	(gate — must be true)	Yes
wt.worktreesBase	WT_WORKTREES_BASE	Yes
wt.ideaFilesBase	WT_IDEA_FILES_BASE	Yes
wt.baseBranch	WT_BASE_BRANCH	Yes
wt.activeWorktree	WT_ACTIVE_WORKTREE	No (optional)
wt.metadataPatterns	WT_METADATA_PATTERNS	No (optional)

WT_MAIN_REPO_ROOT is always auto-derived from git rev-parse --git-common-dir and is not a configurable key. This eliminates a potential source of conflict between what git says the repo root is and what the user configured.

All-or-nothing validation

All three required keys must be present and non-empty. If any is missing, no git config values are applied and a diagnostic warning is printed to stderr naming the missing keys.

Key design choices

• Explicit opt-in: wt.enabled=true must be set — repos don't accidentally pick up local config
• Worktree-transparent: git config --local in a worktree reads from the main repo's .git/config automatically, so config set once in the main repo is visible from all worktrees
• mainRepoRoot is not configurable: always derived from git-common-dir to avoid stale/conflicting values
• Read-only: wt never writes to git config; users manage it with standard git config commands
• Bash 3.2 compatible: uses tr for case-insensitive key matching (macOS ships bash 3.2)
• No interference with existing workflows: repos without wt.enabled=true are silently skipped; the context system and env vars continue to work exactly as before
• Scoped reload: only wt help calls wt_read_git_config after a force-reload — context switching and completions intentionally reload from .conf only

What's NOT changing

• No wt config subcommand (users use git config directly)
• No changes to wt context add / install.sh setup flows
• No git global config support (local only)
• No changes to the .conf file format or context system

Test plan

• 40 unit tests covering: gate behavior, core config loading, validation, optional keys, case insensitivity, worktree support, auto-derivation, and precedence
• All existing integration/e2e tests still pass (1 pre-existing failure in wt-remove --merged is unrelated)
• Manual: git config --local wt.enabled true + set 3 required keys, wt help shows values
• Manual: cd into a worktree of that repo — same result
• Manual: set wt.enabled false, run wt help — falls back to .conf/defaults
• Manual: set only wt.baseBranch (incomplete), run wt help — warning on stderr
• Manual: outside any git repo, wt help shows .conf/default values, no warning

🤖 Generated with Claude Code

---

Changelog

refactor: unified config API with wt_read_config orchestrator

Refactored the config-reading API to provide a single entry point with explicit mode control:

• Renamed wt_read_config → wt_read_context_config (public, reads context .conf files)
• New wt_read_config orchestrator with --mode=(ordered|git|context) and --force flags:
  • --mode=ordered (default): git config first, context fills gaps; returns non-zero only if both fail
  • --mode=git: git-local config only
  • --mode=context: context .conf only
  • --force: clears all WT_* vars before loading
• wt_read_git_config now returns non-zero on failure (not in repo, not enabled, incomplete config)
• Deleted deprecated wt_load_context_config() shim from lib/wt-context
• Updated all call sites: source-time load, wt-help, bash/zsh completions
• Tests: updated unit tests for new return semantics, added 7 orchestrator tests, simplified 3 precedence tests to use wt_read_config --force

[guodong-sq]

do the values set in wt_read_git_config need to go through _wt_expand_path()?

[guodong-sq]

should this be called by wt_load_context_config?

[bezhermoso]

It seem to me that wt_load_context_config's purpose is to load config from a context's *.conf files. I think it's wrong to override that with git local configs. I see these two as the two possible sources to pick from.

Perhaps what we need is a wt_load_config --from=(git|context|ordered)?

• --from git load from local git config only
• --from context load from current context only
• --from ordered try loading from git first, then context fallback (the default behavior to achieve local-context-first)

[guodong-sq]

makes sense, also this will prevent issues in completion, as the implementation calls wt_load_config which will wipe all the variables set in here.

[bezhermoso]

OK, 4c6c244 implement this.

[guodong-sq]

This is no longer true with the added wt_read_git_config

[bezhermoso]

4c6c244 addresses this: this function is renamed to wt_read_context_config (it only reads from context configs), and the new wt_read_config orchestrator documents the full precedence behavior.