Can't find .env in Codex Worktree? Copy it with .worktreeinclude

The .env cannot be found in the Codex Worktree usually because the file is ignored by Git, and the new worktree will only automatically obtain files tracked by the repository. For locally hosted Worktrees created by Codex Apps, you can add .worktreeinclude in the repository root directory and only copy the ignored files that are actually needed.

Minimum configuration is written like this

Create a .worktreeinclude in the root directory of the main repository:

.env
.env.local
config/local-secrets.json

The syntax is similar to .gitignore's path pattern. After creating a new Worktree, Codex will copy the matching ignore file from the local checkup directory; Other untracked documents not listed will not be included together. Files already present at the target location will not be overwritten.

Why is the old Worktree still not available?

.worktreeinclude Acts during the process of creating a locally hosted Worktree and does not automatically rewrite already created worktrees. Old Worktrees can manually copy the required files after confirming the destination path, or create a new Worktree validation rule. Do not change .env to Git trace files to fix the issue, as this increases the risk of miscommitting keys.

First, determine if the scenario is suitable

This mechanism is designed for the native Worktree managed by ChatGPT desktop applications. Remote Worktree and directories created by executing git worktree add from the command line will not automatically copy configurations because of this file; These environments should be prepared through their respective initialization scripts, key injections, or deployment configurations.

What should I do if the file arrives and still shows an error?

First, confirm the current directory in the Worktree integration terminal, then check whether the application reads .env, .env.local, or another name. Then check the file permissions and the working directory of the startup command. You can see the file but the variable is empty. The issue has shifted from "Worktree not copied" to "Application did not load this file." You should check the framework's environment variable rules instead of continuing to modify .worktreeinclude.

Only list the local configurations necessary to run, avoiding copying the entire key or home directory into each working tree. This allows the test to run without turning the Worktree into a borderless copy of sensitive files.