Overlay workflow

The problem

Working across worktrees usually needs the same local hacks in each: hardcoded localhost URLs, disabled prod-only code paths, feature-flag overrides. Committing them is dangerous; copying them by hand is tedious.

The solution

The overlay is your personal patch of local hacks, stored outside any git tree, re-applied to every new worktree automatically, and guarded by two safety hooks that refuse to let it reach the remote.

Storage layout (per repo):

~/.worktree-overlays/<repo>/
├── local.patch     # git diff HEAD from your main clone (tracked-file edits)
├── .env            # untracked env files, copied verbatim
├── .env.local
└── ...

One-time setup per repo

cd ~/repos/myapp                    # your main clone with local hacks in place
wt snapshot                         # captures ~/.worktree-overlays/myapp/
wt install-safety-hooks             # blocks accidental commit/push of overlay lines

Optionally tune the [overlay] section in .worktreerc.

Daily flow

wt add fix-payment-bug              # creates worktree, auto-applies overlay
cd "$(wt cd fix-payment-bug)"
# your local hacks are already in place — dev server just works

The overlay apply step runs in the setup pipeline between env setup and post_setup hooks. You'll see it in the output:

     Linking env files
     Applied overlay patch

When your local hacks change

Edit them in your main clone, then re-snapshot:

cd ~/repos/myapp
wt snapshot                         # refresh the patch
 
# For existing worktrees, re-apply:
cd ~/repos/myapp-feat-x
wt setup --force

Safety net

The pre-commit and pre-push hooks installed by wt install-safety-hooks refuse to let overlay lines reach the remote:

$ git commit -m "wip"
wt-safety: BLOCKED - staged diff contains local overlay lines:
  | API_URL = "http://localhost:8080"
  | FEATURE_FLAG_X = True

Fix: unstage those lines (git restore --staged <file>) or edit them out.
Bypass (dangerous): git commit --no-verify

The wrapper preserves any pre-existing hook (pre-commit framework, husky, lint-staged) by moving it to <hook>.wt-original and delegating after the safety check passes. Both keep working.

Turning it off

Set enabled = false in .worktreerc:

[overlay]
enabled = false

The overlay apply step becomes a no-op. Existing captures under ~/.worktree-overlays/ are untouched.

Related commands

• wt snapshot — capture local overrides
• wt install-safety-hooks — install the guards
• Configuration [overlay] — full config reference