Per-worktree Git config
TL;DR: The 30-Second Summary
Use Git's `extensions.worktreeConfig` feature to configure different `user.email`, `core.hooksPath`, or GPG signing keys for specific worktrees within the same repository.
The Real-Life Scenario
“A developer contributes to an open-source repo for both personal and work projects. In the `oss-feature` worktree, commits must use `personal@gmail.com`, while `client-feature` requires `dev@company.com`.”
By default, `git config` modifies `.git/config`, which applies globally to all worktrees in that repository. With `extensions.worktreeConfig`, Git enables per-worktree configuration files.
The Single Configuration Limitation
Running `git config user.email` in any worktree normally changes the email across the entire repository. You cannot have different Git settings per worktree without the extension.
What you see in the terminal:
$ git config user.email "work@corp.com"
# Overwrote email for all worktrees!Under the Hood: Git Plumbing & Architecture
Enabling `extensions.worktreeConfig` tells Git to read `.git/worktrees/<name>/config.worktree` in addition to the main `.git/config`.
Quick Command Recipes
Copy and adapt these commands directly in your terminal:
Enable per-worktree configuration extension
Enables per-worktree config files in `.git/worktrees/<name>/config.worktree`.
git config extensions.worktreeConfig trueSet configuration for current worktree only
Writes the setting strictly to this worktree's config file.
git config --worktree user.email 'dev@personal.com'Step-by-Step Practical Walkthrough
Follow these verified steps to safely resolve the issue and guarantee that your filesystem and Git references are in sync.
Enable the extension
Activate worktree configuration support.
git config extensions.worktreeConfig trueSet worktree-specific config
Apply setting only to this worktree.
git config --worktree user.name 'Dev Agent'Verify the configuration scope
Confirms the setting originates from `config.worktree`.
git config --show-origin user.namefile:.git/worktrees/agent/config.worktree Dev Agent
Edge Cases & Advanced Scenarios
Per-worktree hooks path
You can set `git config --worktree core.hooksPath .githooks/agent` to run custom hooks in specific worktrees.
Common Mistakes to Avoid
❌ Mistake: Running `git config --local` thinking it is per-worktree
Why it causes trouble: `--local` writes to `.git/config`, affecting ALL worktrees.
What to do instead: Use `git config --worktree`.
Verification Checklist
- ✓`git config --worktree` writes to `.git/worktrees/<id>/config.worktree`
- ✓Other worktrees retain their original configuration values
Senior Engineering Tips
- ★WorktreeWise lets you set custom Git author, email, and shell settings per worktree directly in the UI.
Key Takeaways
- 01.Enable `git config extensions.worktreeConfig true`.
- 02.Use `git config --worktree <key> <val>` for worktree-scoped settings.
How WorktreeWise Solves This Visually
WorktreeWise eliminates the manual friction and mental overhead of CLI flags. It displays real-time branch states, uncommitted modifications, active terminals, and lock statuses across all worktrees on a single visual dashboard.
WorktreeWise Engineering Publication
Written and curated by the core WorktreeWise team. We build developer tools that turn Git worktrees, workflows, and parallel AI coding agents into second nature.