[DOCS] Missing instructions for environment file setup in Git Worktree workflow

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees

Section/Topic

Run parallel Claude Code sessions with Git worktrees

Current Documentation

Step 2: Create a new worktree ``bash # Create a new worktree with a new branch git worktree add ../project-feature-a -b feature-a ... ` **Step 3: Run Claude Code in each worktree** `bash # Navigate to your worktree cd ../project-feature-a # Run Claude Code in this isolated environment claude ``

What's Wrong or Missing?

The current guide instructs users to create a worktree and immediately run claude. It fails to mention that git worktree add creates a fresh checkout and does not copy untracked files (such as .env or .claude/settings.local.json).

Since Claude Code relies heavily on these files for API keys, database URLs, and local configuration, following this guide strictly will result in a broken session for most users (e.g., authentication failures or missing environment variables).

While the Desktop documentation explicitly addresses this issue and offers .worktreeinclude as a solution, the CLI workflow documentation ignores it entirely.

Suggested Improvement

Insert a step between creating the worktree and running Claude to address environment variables.

Suggested text insertion:

Step 2.5: Copy environment configuration Git worktrees do not copy untracked files like .env or local settings by default. You must copy these manually to ensure Claude connects to your environment correctly. ``bash cp .env ../project-feature-a/ cp .claude/settings.local.json ../project-feature-a/.claude/ 2>/dev/null || true ``

Impact

High - Prevents users from using a feature

Additional Context

• Related documentation showing the correct awareness of this issue in the Desktop app: Claude Code on desktop > Copying files ignored with .gitignore