[DOCS] [Worktree settings] `worktree.baseRef` setting not documented

[coygeek]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Worktree settings" section (lines 256–265)

Current Documentation

The "Worktree settings" section documents only two keys:

Key	Description	Example
worktree.symlinkDirectories	Directories to symlink from the main repository into each worktree to avoid duplicating large directories on disk. No directories are symlinked by default	["node_modules", ".cache"]
worktree.sparsePaths	Directories to check out in each worktree via git sparse-checkout (cone mode). Only the listed paths are written to disk, which is faster in large monorepos	["packages/my-app", "shared/utils"]

No setting for controlling the base branch is documented.

What's Wrong or Missing?

As of v2.1.133, Claude Code introduces a worktree.baseRef setting with two valid values:

• worktree.baseRef: "fresh" (default) — --worktree, EnterWorktree, and agent-isolation worktrees branch from origin/<default> (the remote default branch)
• worktree.baseRef: "head" — worktrees branch from local HEAD instead

The v2.1.133 changelog notes that EnterWorktree's default base was changed back to origin/<default> (it had been local HEAD since v2.1.128), and that users who want to preserve unpushed commits in new worktrees should set worktree.baseRef: "head". This behavior change is not documented in the Worktree settings section or in the worktrees page.

Suggested Improvement

Add worktree.baseRef to the Worktree settings table:

| `worktree.baseRef`             | Which ref to branch from when creating a new worktree via `--worktree`, `EnterWorktree`, or agent `isolation: "worktree"`. `"fresh"` branches from `origin/<default>` (the remote default branch); `"head"` branches from local `HEAD`. Defaults to `"fresh"`. | `"fresh"` |

Also update the "Choose the base branch" section in the worktrees page to note that worktree.baseRef controls this behavior and defaults to origin/<default>.

Impact

Medium - Makes feature difficult to understand

Additional Context

Changelog entry (v2.1.133):

Added worktree.baseRef setting (fresh | head) to choose whether --worktree, EnterWorktree, and agent-isolation worktrees branch from origin/<default> or local HEAD. Note: the default fresh changes EnterWorktree's base back to origin/<default> (it has been local HEAD since 2.1.128) — set worktree.baseRef: "head" to keep unpushed commits in new worktrees

Affected Pages:

Page	Context
https://code.claude.com/docs/en/settings	"Worktree settings" section — worktree.baseRef missing from settings table
https://code.claude.com/docs/en/worktrees	"Choose the base branch" section — no mention of worktree.baseRef or its effect on --worktree and EnterWorktree base

Total scope: 2 pages affected

[coygeek]

Issue #57148 Verification

Title: [DOCS] [Worktree settings] worktree.baseRef setting not documented
Issue Date: 2026-05-08
Verification Date: 2026-05-12
Status: RESOLVED

---

Issue Summary

This issue reports that the worktree.baseRef setting (introduced in v2.1.133) is missing from the "Worktree settings" section of the settings page and from the "Choose the base branch" section of the worktrees page.

---

Verification Results

Claim 1: worktree.baseRef missing from Worktree settings table

Status: RESOLVED

At https://code.claude.com/docs/en/settings, lines 272–274, the Worktree settings table now includes all three worktree keys:

| worktree.baseRef | Which ref new worktrees branch from. "fresh" (default) branches from origin/<default-branch> for a clean tree matching the remote. "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 | "head" |
| worktree.symlinkDirectories | Directories to symlink from the main repository into each worktree to avoid duplicating large directories on disk. No directories are symlinked by default | ["node_modules", ".cache"] |
| worktree.sparsePaths | Directories to check out in each worktree via git sparse-checkout (cone mode). Only the listed paths are written to disk, which is faster in large monorepos | ["packages/my-app", "shared/utils"] |

worktree.baseRef is fully documented with description, behavior explanation, and example value.

Verdict: The setting is present and documented. No further action needed on this page.

---

Claim 2: worktree.baseRef missing from worktrees page "Choose the base branch" section

Status: RESOLVED

At https://code.claude.com/docs/en/worktrees, line 45, the "Choose the base branch" section reads:

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. Setting baseRef to "head" makes new worktrees carry your unpushed commits and feature-branch state, which is useful when isolating subagents that need to operate on in-progress work. The setting accepts only "fresh" or "head", not arbitrary git refs

The section explicitly documents that worktree.baseRef controls the base branch behavior and defaults to origin/HEAD.

Verdict: The setting and its effect on --worktree and EnterWorktree base are fully documented. No further action needed on this page.

---

Current State

Claim	Status
worktree.baseRef missing from Worktree settings table	RESOLVED
worktree.baseRef missing from worktrees page "Choose the base branch" section	RESOLVED

---

Suggested Fix

N/A - issue has been resolved.

---

References

• URL: https://code.claude.com/docs/en/settings (lines 272–274)
• URL: https://code.claude.com/docs/en/worktrees (line 45)
• URL: https://code.claude.com/docs/en/changelog (line 146) — changelog confirming worktree.baseRef was added in v2.1.133

---

Conclusion & Recommendation

Primary Concern: worktree.baseRef setting introduced in v2.1.133 was not documented in the Worktree settings table or the worktrees page.

Resolution Status: RESOLVED

Recommendation: CLOSE

Both affected pages now document worktree.baseRef completely. The settings page includes the full three-key Worktree settings table, and the worktrees page's "Choose the base branch" section explicitly explains the worktree.baseRef setting and its effect on --worktree, EnterWorktree, and agent isolation worktrees.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.