claude-code - 💡(How to fix) Fix [DOCS] Worktrees guide still says EnterWorktree branches from the default branch [1 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/worktrees

Section/Topic

"Start Claude in a worktree" and "Choose the base branch"

Current Documentation

The docs currently say:

You can also ask Claude to "work in a worktree" during a session, and it will create one with the EnterWorktree tool.

Worktrees branch from your default branch: origin/HEAD if the repository has a remote, otherwise the current local HEAD. The origin/HEAD reference is stored in your local .git directory and was set when you cloned.

What's Wrong or Missing?

This is outdated for EnterWorktree after v2.1.128. The release changed EnterWorktree to create the new branch from the current local HEAD instead of the repository default branch, so local unpushed commits are preserved.

The current worktrees page introduces EnterWorktree and then immediately states that worktrees branch from origin/HEAD / the default branch. That gives readers the wrong mental model for what happens when they ask Claude to move the current session into a worktree.

Suggested Improvement

Update the base-branch guidance to call out EnterWorktree explicitly.

Suggested fix:

• State that EnterWorktree creates the new worktree branch from the current local HEAD as of v2.1.128.
• Mention that this preserves local, unpushed commits in the starting state.
• If claude --worktree still follows different base-branch rules, document that separately instead of using one shared paragraph for both flows.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 1 page affected

Version context: Behavior changed in v2.1.128.