DOCS / CONFIGURATION

.worktreeinclude

A fresh worktree contains everything git tracks — and nothing it ignores. That’s correct git behavior, and it’s also why a brand-new workspace has no .env, no local certificates, and none of your per-machine config. Birch fixes this with carryover: on every worktree it creates, gitignored files matching your patterns are copied in from your source checkout. The default is .env*; a .worktreeinclude file at the repo root replaces that default with your own list.

The default: `.env*`

With no configuration at all, Birch carries every gitignored file matching .env* (.env, .env.local, .env.development, …) from your source checkout into each new worktree. For many projects that’s exactly the set of files an agent needs to run the dev server or the tests, so no setup is required.

The `.worktreeinclude` file

To carry a different set, create a file named .worktreeinclude at the root of your source checkout (the repository’s primary worktree). It uses gitignore syntax, and Birch hands it to git verbatim — comments, blank lines, ! negation, and directory patterns all work exactly as they do in .gitignore. It is the same de-facto standard file that Claude Code and Conductor read, so one file serves all three tools.

# Local environment files — but never the production one
.env*
!.env.production

# Per-machine config and local certificates
config/local/
certs/

Replacement semantics

A present .worktreeinclude replaces the built-in default wholesale — it does not add to it:

State of the file	What is carried
No `.worktreeinclude`	The default: `.env*`
File with patterns	Exactly the files your patterns match — `.env*` is no longer implied
Empty file	Nothing
Present but unreadable (e.g. a dangling symlink)	Nothing — deliberately never the default, since the file may exist precisely to restrict what travels

So if you write a .worktreeinclude and still want env files carried, list .env* in it explicitly.

What actually gets copied

A file is copied only when it is both gitignored and matched by a carryover pattern:

Tracked files are never carried — git checks them out in the new worktree anyway.
Untracked-but-not-ignored files are never carried — they would immediately dirty the fresh worktree’s status.
Matching is done by git itself, not a re-implementation, so pattern behavior is exactly gitignore behavior.
A file that is ignored only by an uncommitted or branch-local .gitignore edit in your source checkout is skipped with a warning: in the new worktree (checked out at the base branch) it would not be ignored, and a later git add -A would commit it.
Existing files are never overwritten — a same-named file already present in the new worktree (for example, tracked on the target branch) always wins.

Carryover is best-effort by design: a file that can’t be copied is logged as a warning, and carryover never fails or blocks worktree creation.

When carryover runs

Carryover runs on every worktree Birch creates:

Creating a workspace from the GUI
birch worktree new from the CLI
Checking out a PR into a worktree

It deliberately does not run when:

Birch adopts an existing worktree it didn’t create — re-copying could clobber files an agent already edited.
The primary worktree is being set up — that checkout is the carryover source, not a target.