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

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