Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] [Worktree settings] `worktree.baseRef` setting not documented

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

Code Example

| `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"` |
RAW_BUFFERClick to expand / collapse

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:

KeyDescriptionExample
worktree.symlinkDirectoriesDirectories 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.sparsePathsDirectories 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:

PageContext
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

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#agent setup#task chaining#parallel task#integration issue#index setup

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING