claude-code - 💡(How to fix) Fix [DOCS] Worktree docs do not clarify `worktree.baseRef: "head"` inside linked worktrees

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

Choose the base branch and the worktree.baseRef behavior for linked worktrees, subagent worktrees, and EnterWorktree.

Current Documentation

The worktrees guide currently says:

Worktrees branch from your repository's default branch, origin/HEAD, so they start from a clean tree matching the remote. If no remote is configured or the fetch fails, the worktree falls back to your current local HEAD. To always branch from local HEAD instead, set worktree.baseRef to "head" in settings.

It also says:

Subagent worktrees use the same base branch as --worktree, so they branch from your repository's default branch unless worktree.baseRef is set to "head".

The settings reference says:

"head" branches from your current local HEAD, so unpushed commits and feature-branch state are present in the worktree. Applies to --worktree, the EnterWorktree tool, and subagent isolation

What's Wrong or Missing?

The current docs explain that worktree.baseRef: "head" uses the current local HEAD, but they do not define which HEAD is used when Claude Code is already running inside a linked git worktree.

That distinction matters because v2.1.154 fixed worktree.baseRef: "head" resolving to the main checkout's HEAD instead of the current worktree's HEAD when spawning subagents or calling EnterWorktree from inside a linked worktree.

Without that clarification, users working from a feature branch in a linked worktree cannot tell whether new subagent or EnterWorktree worktrees should inherit the active linked worktree commit or the main checkout commit. The existing phrase "current local HEAD" is especially ambiguous because the worktrees guide also describes worktrees as sharing repository history with the main checkout.

Suggested Improvement

Add a note under Choose the base branch, for example:

When Claude Code is already running inside a linked git worktree and worktree.baseRef is "head", new worktrees created by --worktree, EnterWorktree, or subagent isolation branch from the current linked worktree's HEAD, not from the main checkout's HEAD.

Also update the worktree.baseRef row in the settings reference to make the same behavior explicit.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Version context: Claude Code v2.1.154 fixed worktree.baseRef: "head" resolving to the main checkout's HEAD instead of the current worktree's HEAD when spawning subagents or calling EnterWorktree from inside a linked worktree.