.worktreeinclude

Git worktrees do not copy gitignored local files by default. .worktreeinclude is the project file format that tells Conductor which gitignored files to copy into new local workspaces.

Add .worktreeinclude to the repository root when every new local workspace should receive the same local files.

You can also configure the same behavior in .conductor/settings.toml. Use the Files to copy reference for settings examples, eligibility rules, precedence, defaults, and pattern syntax. Use Use Files to copy for a guided setup flow.

What .worktreeinclude does

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

Conductor reads .worktreeinclude through Files to copy. Claude Code also documents the same file for copying gitignored files into worktrees, so it is useful when a project uses both tools.

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

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 local workspace.

When to commit it

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

That gives every teammate and every new local 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.

You can configure personal or repository-specific Files to copy patterns with file_include_globs in Conductor settings:

"$schema" = "https://conductor.build/schemas/settings.repo.schema.json"

file_include_globs = """
.env.local
config/local.json
"""

If .worktreeinclude exists, it wins over file_include_globs. See Files to copy for the full precedence rules.

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 full syntax reference and examples.