Migrating from `git gtr`: config footguns

[indexzero]

Howdy @max-sixty 👋 — Really enjoying using wt. Your effort is much appreciated 🙏 I was on git gtr for about a year before I switched. Now I couldn't imagine going back because wt list makes juggling a dozen worktrees obvious

The pain point has been not having git gtr's config management — git gtr config:

# writes to .git/config — local to this checkout, private, always-trusted
git gtr config add gtr.hook.postCreate "pnpm install && ./hack/oneoff.sh"

# --global writes to ~/.gitconfig — every repo
git gtr config add gtr.hook.postCreate "pnpm install" --global

# committed .gtrconfig — shared with the team, gated behind `git gtr trust`
git gtr config set gtr.copy.include "**/.env.example"

Prior art: reading the tea leaves

When it comes to configs in general, I am with you on being "very keen to keep them simple". That said this issue continues to come up, which suggests other folks are stubbing their toes like I am trying to do what git gtr makes obvious and clean

git gtr is a fairly popular runner (~1.7k stars, brew installs ~5% userbase). I cite it specifically because I noticed that it hasn't been in the conversation. The config model it uses at once robust/flexible and simple

• Better config/hook ergonomics when creating new branch with uncommitted wt.toml #650 ("Better config/hook ergonomics…") — Also resolved because .git/config is shared across worktrees
• Support local config #1077 ("Support local config"): Closed. With the approach below the need for repo-specific
  file proposed goes away while still being shared across all worktrees
• Untracked wt.toml config files no longer work #2818 ("Untracked wt.toml config files no longer work"): Closed. With the approach below the need for the uncommitted file goes away while still being shared across all worktrees
• [pre-start] hook in project config (.config/wt.toml) does not fire on worktree creation #2856: Fixed via fix(hooks): resolve all hook config from the invoking worktree #2873, which is a fair amount of plumbing to keep track of. Using the approach git gtr leverages makes per-worktree config files obsolete which reduces complexity a fair amount 🎉

Why not existing solutions

There are two existing solutions here:

• ~/.config/worktrunk/config.toml: per-project config overrides
  • Issue: Add worktree-path support to project config #596
  • PR: feat: add per-project config overrides #749
• .config/wt.toml: per-repo or per-worktree config overrides
  • Recent fix: fix(hooks): resolve all hook config from the invoking worktree #2873

I thought about using both but adding [projects."github.com/owner/repo"] in my user config every time I use worktrunk with a new git repo is not pragmatic for my workflow

I am currently using .config/wt.toml and I nerd sniped myself here when trying to change that default path to wt.config.toml (not possible: .config/wt.toml is hard coded today).

RFC: worktrunk.config. prefixed values in git config

# local to this checkout — .git/config, uncommitted, private
wt config state worktrunk.config.hook.post-start "./hack/vendor.sh && pnpm install"

# global — ~/.gitconfig
wt config state worktrunk.config.hook.post-start "pnpm install" --global

Why I think this still honors our shared value on being "very keen to keep them configs simple":

• No new config source. It's git's existing surface, not a new file format. Precedence is git's own, which everyone already understands: .git/config (local) over ~/.gitconfig (global).
• Trust stays coherent. Local config is authored by me in my own checkout — always trusted, same as today's user config. Committed hooks keep the approval prompt.
• worktrunk.config.* prefix separates "state" from "config" we prefer the existing wt config state command with a conventionally prefixed key worktrunk.config.* to avoid introducing ambiguity for existing wt config state managed values
• includeIf for free. The [projectsMatching "hasconfig:…"] ask in Better config/hook ergonomics when creating new branch with uncommitted wt.toml #650 is literally git's conditional includes — you inherit it at zero cost.
• Fixes a footgun. WORKTRUNK_PROJECT_CONFIG_PATH resolves relative to CWD
  • NOT the worktree root — project_config_path() in src/git/repository/config.rs returns PathBuf::from(path) verbatim, while the default branch does root.join(".config").join("wt.toml"). A relative override silently no-ops from a subdirectory. Reading via git config is worktree-aware by construction.

imho this makes the .config/wt.toml and [projects.*] plumbing redundant (which strictly speaking simplifies the codebase around config management a fair amount), but that also requires releasing breaking changes, which are can often take on lives of their own.

Will 100% submit a PR for this if you think it's worth exploring. Thoughts?

[worktrunk-bot]

Thanks for the thorough write-up — the git gtr comparison and the linked history (#650, #1077, #2818, #2856) make the recurring shape clear. A few things I can confirm from the code so the discussion starts grounded:

No existing worktrunk.config.* read path. wt config state writes only under worktrunk.state.* (markers, per-branch vars) and worktrunk.default-branch — the worktrunk.config.* subsection you're proposing is unused today, so the prefix wouldn't collide with existing state. There's no mechanism that reads configuration (hooks, etc.) out of git config; config comes from ~/.config/worktrunk/config.toml (user), [projects."…"] overrides within it, and .config/wt.toml (project). So this is genuinely new surface, not something already half-present.

The WORKTRUNK_PROJECT_CONFIG_PATH footgun is real. Verified: project_config_path() returns PathBuf::from(path) verbatim for the env override, while the default path joins to the worktree root. A relative override does resolve against CWD, so it no-ops from a subdirectory. That's fixable on its own, independent of the larger RFC — though the env var is also load-bearing for test isolation (src/testing/mod.rs), so any change to its resolution semantics needs to keep that path working.

One tradeoff worth surfacing early: git config is a flat section.subsection.key = <string> model, while worktrunk config is nested TOML — scalar hooks like worktrunk.config.hook.post-start = "…" map cleanly, but tables/arrays ([list.custom-columns], [aliases], [projects."…"]) don't have an obvious flat-key encoding. The RFC's examples are all the easy scalar case; it'd be worth deciding whether the git-config surface is hooks-only or aims to cover the whole schema.

This repo keeps design discussions in a design/ proposal PR (opened to discuss, closed without merging — see the note in CLAUDE.md), which seems like the natural home for the "does this obsolete .config/wt.toml + [projects.*]" question you're raising, given it's really an architecture call rather than a single behavior change. Since you offered a PR, that's likely the lower-friction first step.

I'll leave the actual "worth exploring?" call to @max-sixty — you asked him directly and it's his config-simplicity philosophy in the balance. Just wanted to confirm the footgun and the namespace facts so the thread isn't starting from guesses.

[max-sixty]

I agree the configs are not perfect and you're totally right it's been a source of persistent requests

When originally planning worktrunk, I was indeed going to use the git config. That said, I'm a bit skeptical about adding git as a config source.

Beyond the standardization, what does this gives us over the existing approach — i.e. why do you think you're drawn to the git config over the per-project worktrunk one, re:

I thought about using both but adding [projects."github.com/owner/repo"] in my user config every time I use worktrunk with a new git repo is not pragmatic for my workflow

Is it the complication of [projects."github.com/owner/repo"]? (Would a cli flag to write a value into there for the current repo solve it? Or not really?)

[indexzero]

@max-sixty nice to (virtually) meet you 👋

i.e. why do you think you're drawn to the git config over the per-project worktrunk one

The reluctance to place all of this in a single top-level file is rooted in my security posture. I manage dotfiles like this from a public Github project, and symlink them into my home directory

Since I use worktrunk for many private repos, I want to avoid any private details potentially leaking into that public config. There are a variety of opinions on how severe these kinds of information disclosure vulnerabilities / CVEs can be, but "why risk it?" is my default stance

When originally planning worktrunk, I was indeed going to use the git config. That said, I'm a bit skeptical about adding git as a config source.

What makes you skeptical? I ask because I never hit an issue in git gtr during heavy claude use over the course of a year. I'm curious to learn where there might be pitfalls I don't see

That said, I do not have strong feelings that mechanism itself for repo-local config has to be git config based. There are other ways used to achive what I'm looking

Alternative: make relative path for repo-local config files configurable

The "itch" (in the CatB sense) that brought me here was that a few model's read of the codebase (concurrent reads from Fable 5, Opus 4.8 and GPT 5.5) stated that the relative path from git rev-parse --show-toplevel for the repo-local config file worktrunk reads was hard-coded to .config/wt.toml

If that relative path could be configured globally for all repos (to avoid the same potential private org/repo path from leaking into global public configs) I would considered this issue resolved 🫶

p.s. my heart's desire is wt.config.toml to align with every other config file which are all top-level; a repo-local directory with a single file just felt yucky

Thoughts?

[worktrunk-bot]

@indexzero — one concrete thing worth surfacing, since it may already meet the bar you set:

If that relative path could be configured globally for all repos (to avoid the same potential private org/repo path from leaking into global public configs) I would consider this issue resolved

That knob exists today: WORKTRUNK_PROJECT_CONFIG_PATH. It overrides the project-config location (default .config/wt.toml), it's a documented, supported env var (not a test-only escape hatch — see config → environment variables), and a relative value resolves against the worktree root. So it's exactly the global relative override you're describing:

# in your (public) dotfiles / shell profile
export WORKTRUNK_PROJECT_CONFIG_PATH=wt.config.toml

That applies across every repo, it's a bare filename (nothing like github.com/owner/repo leaks into the public config), each repo reads <worktree-root>/wt.config.toml, and it gives you the top-level wt.config.toml name from your p.s. — no .config/ directory.

Two accuracy notes so the thread stays grounded:

• The models' read that the path is hard-coded to .config/wt.toml is off: .config/wt.toml is the default, and this env var overrides it (project_config_path()).
• The CWD-relative footgun I flagged earlier in this thread was fixed in fix: anchor relative WORKTRUNK_PROJECT_CONFIG_PATH to the worktree root #3460 — relative values now anchor to the worktree root. That's on main but not yet in a release: the latest tag v0.67.0 (2026-07-10) predates the fix: anchor relative WORKTRUNK_PROJECT_CONFIG_PATH to the worktree root #3460 merge (2026-07-14), so on a released build a relative value still resolves against CWD (works from the worktree root, silently no-ops from a subdirectory) until the next release. An absolute path works on any version but points every repo at the same file, which isn't what you want here.

The larger RFC — git config as a config source, and whether this obsoletes .config/wt.toml + [projects.*] — is still @max-sixty's call, and I'm not weighing in on that. I just wanted to flag that the narrower "make the repo-local path a global relative override" ask looks already-shipped, modulo the release cut for robust subdirectory behavior.

[max-sixty]

There are a variety of opinions on how severe these kinds of information disclosure vulnerabilities / CVEs can be, but "why risk it?" is my default stance

totally understand!

and to confirm: the advantage of the git config is that it can be repo local and not committed into the repo? (as well as the other benefits, like avoiding another, differently typed, config source, etc)

[indexzero]

and to confirm: the advantage of the git config is that it can be repo local and not committed into the repo? (as well as the other benefits, like avoiding another, differently typed, config source, etc)

I'm not an expert on git internals, but I've been learning more about it lately. .git/config isn't in the tree, which means by definition it can't exist in a commit.

In turn, there's no path for those bytes to leave the machine — not through a commit, not a fork, not a teammate's clone. From a "why risk it?" perspective: it's zero risk by construction.

The order for merging configs has one footgun: extensions.worktreeConfig:

┌──────────┬────────────────────────────────────────┬──────────────────────────────────────────┐
│  Scope   │                     File               │    Shared across worktrees?              │
├──────────┼────────────────────────────────────────┼──────────────────────────────────────────┤
│ system   │ /etc/gitconfig                         │ [Y] system defaults                      │
├──────────┼────────────────────────────────────────┼──────────────────────────────────────────┤
│ user     │ ~/.gitconfig                           │ [Y] all repos                            │
├──────────┼────────────────────────────────────────┼──────────────────────────────────────────┤
│ local    │ $GIT_COMMON_DIR/config = .git/config   │ [Y] all worktrees                        │
├──────────┼────────────────────────────────────────┼──────────────────────────────────────────┤
│ worktree │ .git/worktrees/<name>/config.worktree  │ [N] needs extensions.worktreeConfig=true │
└──────────┴────────────────────────────────────────┴──────────────────────────────────────────

I've never personally used extensions.worktreeConfig but with prefixing it's strictly speaking not
necessary so it feels like a bit of a red herring a bit YAGNI for the majority of users (could be wrong here)

If you'd like I can open PR for a POC because I think code will prove itself out in the end. Objections?

[max-sixty]

I think your concerns are totally legitimate. I do worry this is quite a narrow use-case for a quite large feature addition!

My sense is that:

• if this is a very simple slot-in, we could maybe add it as experimental and say "we also look at worktrunk.config in git for config keys"
• if it's more than that — if we're going to have to be managing the lack of types in git config, managing hierarchies, etc; then it's not worthwhile

(I will add that it does feel a bit like config sprawl! but I also see your logic, and i had always wanted to do more with git config; indeed it's because it's difficult to commit the project config with git that it didn't work so well for worktrunk overall...)

---

Something that has worked well with worktrunk to avoid config sprawl is customizations with hooks & aliases & wt-foo — none of those quite fit here but one left-field option is that we try to pursue that broad direction; for example we search for a wt-custom-config binary that wt on every config get, and then anyone could have any config source if they build their own adapter

---

If you'd like I can open PR for a POC because I think code will prove itself out in the end. Objections?

I think this would be great to see! To set expectations, I think there's a decent possibility that if it works really well, we merge; but I don't want to guarantee anything. I hope that's reasonable?

[indexzero]

The hierarchy is managed by git itself, so no worries there

if this is a very simple slot-in, we could maybe add it as experimental and say "we also look at worktrunk.config in git for config keys"

That works for me 💯 it avoids conflating what "wt state in .git/config" vs "stuff I decided to write into .git/config myself for wt to see"

Both conceptually would co-exist side-by-side in .git/config but wt makes no guarantees about anything users choose to write in there

All or nothing for worktrunk.config avoids any nesting / merging which is where the real pains would be. All or nothing. On or off.

Happy to contribute it if that's helpful 💪