Manage secrets with .worktreeinclude

Git worktrees are useful because each agent gets a separate working tree. The problem is that a fresh worktree contains tracked files only. Untracked files, including gitignored files, stay behind in the main checkout unless a tool copies them.

.worktreeinclude is the small project file that fixes that setup gap. It tells tools that support worktrees which gitignored files are safe and useful to copy into each new worktree.

The problem with secrets in worktrees

Most projects correctly keep secrets out of Git:

• .env.local
• .env.development.local
• config/secrets.json
• local certificates
• service account files

That protects the repository, but it also means every new git worktree starts without the files your app may need to boot. It also leaves out untracked local files that are not gitignored. If you create many worktrees for parallel agent work, manually copying those files becomes slow and error-prone.

Git worktrees do not bring over:

• untracked files
• gitignored files
• local-only config
• local credentials
• generated files
• dependency folders and caches

In Conductor, Files to copy can copy matching gitignored files. It does not copy untracked files that Git does not ignore.

What .worktreeinclude does

A .worktreeinclude file lists gitignored files that should be copied into new worktrees.

Conductor exposes the same idea as Files to copy. Claude Code also documents .worktreeinclude for copying gitignored files into worktrees.

The important safety rule is that .worktreeinclude does not make a file tracked. It only selects files that are already ignored by Git.

For example:

.env.local
config/secrets.json
certs/local/**

This says: when a matching file exists in the main checkout and Git ignores it, copy it into the new worktree.

Why this belongs in the repo

Commit .worktreeinclude when the whole team needs the same local files in worktrees. The file contains patterns, not secret values, so it can usually live safely in Git.

That gives every teammate and every new workspace the same rule:

• keep secret values out of Git
• keep the list of required local files in Git
• create worktrees without repeating manual copy steps

If the pattern is personal to one machine, use Conductor's per-repo Files to copy setting instead of committing .worktreeinclude.

What not to solve with .worktreeinclude

Use .worktreeinclude for static gitignored files that already exist in the main checkout.

Use a setup script when the workspace needs to run commands, install dependencies, generate files, create symlinks, or fetch secrets from a password manager or cloud secret store.

Use your hosting provider or deployment environment for production secrets. .worktreeinclude is a local development convenience, not a production secret-management system.

Pattern syntax

.worktreeinclude uses .gitignore pattern syntax, including comments, root-anchored paths, nested globs, directory patterns, and negation with !.

See Files to copy for the syntax reference and examples.