#[non_exhaustive]pub struct Worktree {
pub sparse_paths: Option<Vec<String>>,
pub base_ref: Option<WorktreeBaseRef>,
pub bg_isolation: Option<BgIsolation>,
pub symlink_directories: Option<Vec<String>>,
pub location: Option<String>,
pub extra: Extra,
}Expand description
worktree.
Configure how Claude Code creates and manages git
worktrees for --worktree, the EnterWorktree
tool, and isolated subagents and background sessions.
Docs: worktree.
Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.sparse_paths: Option<Vec<String>>Check out only the listed directories in each worktree through git sparse-checkout. Claude Code writes only those directories plus root-level files to disk, which is faster in large monorepos; see Check out only the directories you need.
- Values: array of strings, directory paths relative to the repository root
- Default: unset, so each worktree checks out the whole tree
- Scope: any settings file.
Docs: sparsePaths.
base_ref: Option<WorktreeBaseRef>Choose which ref new worktrees branch from. "fresh" 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.
- Values: string, one of:
"fresh": new worktrees branch fromorigin/<default-branch>"head": new worktrees branch from your current localHEAD, including unpushed commits
- Default:
"fresh" - Scope: any settings file.
Docs: baseRef.
bg_isolation: Option<BgIsolation>Choose how background
sessions
isolate their file edits. If you moved a session to the background with ← or
/background, that session edits files in place whatever this key says. With
"worktree", Claude Code blocks Edit and Write in the main checkout until the
session calls EnterWorktree; with "none", background jobs edit the working copy
directly.
- Values: string, one of:
"worktree": Claude Code blocksEditandWritein the main checkout until the session callsEnterWorktree"none": background jobs edit the working copy directly
- Default:
"worktree" - Scope: any settings file.
Docs: bgIsolation.
symlink_directories: Option<Vec<String>>Symlink directories from the main repository into each worktree so you don’t duplicate large directories on disk.
- Values: array of strings, directory paths relative to the repository root
- Default: unset, so Claude Code symlinks no directories
- Scope: any settings file.
Docs: symlinkDirectories.
location: Option<String>Choose the folder on a remote machine where Desktop SSH
sessions
create their worktrees, instead of <project-root>/.claude/worktrees/. Only the desktop
app reads this key: --worktree, the EnterWorktree tool, isolated subagents, and
background sessions ignore it. Requires Claude Desktop v1.44121.0 or later.
- Values: string, an absolute path or one that starts with
~/ - Default: unset, so worktrees go inside the project
- Scope: user, in
~/.claude/settings.jsonon the remote machine.
Docs: location.
extra: ExtraKeys Claude Code accepts here that this crate doesn’t model (newer or undocumented ones), kept as written so the document round-trips.