--worktree · Claude Code 命令 · Claude Code 中文学习站

启动参数看官方文档

在隔离的git worktree中启动Claude

Syntax

--worktree [name]

示例

claude -w feature-auth

别名

-w

全网调研整理

典型场景

多终端同时开发独立功能时,每个 worktree 文件状态彼此完全隔离
紧急热修复需与进行中功能并行时,不打断也不污染现有分支
用 `claude --worktree "#1234"` 直接基于指定 PR 分支创建隔离调试环境
多 subagent 并行修改同一文件时,分配独立 worktree 防止写冲突
大规模重构拆成多批次任务时,防止单 agent 上下文窗口溢出

实用技巧

在项目根目录创建 `.worktreeinclude` 文件,可将 `.env`、`config/secrets.json` 等 gitignore 文件自动复制进每个新 worktree
在 settings.json 中设置 `worktree.baseRef: "head"` 可让 worktree 从本地 HEAD 而非 `origin/HEAD` 分叉,携带本地未推送改动
将 `.claude/worktrees/` 加入 `.gitignore`,防止临时 worktree 目录出现在主仓库 `git status` 中
自定义 subagent YAML 前置加 `isolation: worktree`,每次调用该 agent 自动在独立 worktree 内运行
省略名称直接运行 `claude -w` 可让 Claude 自动生成随机 worktree 名称(如 bright-running-fox)

常见坑

首次使用前须先在该目录运行一次 `claude` 接受 workspace trust 授权,否则 `--worktree` 直接报错退出
非交互模式(`-p`)退出后 worktree 不会自动清理,需手动 `git worktree remove` 释放
git stash 跨所有 worktree 共享存储,在 worktree 环境下混用 stash 易恢复到错误上下文

来源

创建于

v2.1.49

变化时间线(按版本倒序)

修复v2.1.157· 2026/05/30 · 2026/05/30

修复 `--worktree` 和 `--worktree --tmux` 返回规范仓库根目录而不是当前 linked worktree 的问题

改进v2.1.133· 2026/05/08 · 2026/05/08

行为改变,现由 `worktree.baseRef` 设置控制是从 `origin/<default>` 还是本地 HEAD 分支

修复v2.1.85· 2026/03/27 · 2026/03/27

修复在非 git 仓库中退出错误的问题

修复v2.1.83· 2026/03/25 · 2026/03/25

修复包含前向斜杠时静默挂起的问题

修复v2.1.78· 2026/03/18 · 2026/03/18

修复了未从worktree目录加载skills和hooks的问题

改进v2.1.76· 2026/03/14 · 2026/03/14

改进了startup性能，新增worktree.sparsePaths设置支持git sparse-checkout

改进v2.1.69· 2026/03/05 · 2026/03/05

改进了 `--worktree` 启动时间，消除了启动路径上的 git subprocess。

新增v2.1.49· 2026/02/20 · 2026/02/20

新增 `--worktree` flag（短选项 `-w`）用于在隔离的 git worktree 中启动 Claude