git worktree add 完整命令参考

基础：你实际会用的三种写法

看了多年开发者学 git worktree，95% 的使用归结为三种形式：

# 形式 1：检出已有分支
git worktree add <路径> <分支>

# 形式 2：创建新分支及其 worktree
git worktree add -b <新分支> <路径> <起点>

# 形式 3：在指定 commit/tag 上创建分离 worktree
git worktree add --detach <路径> <commit-ish>

其他所有（--lock、--reason、--guess-remote 等）都是这三种的特化。我们逐一走一遍。

形式 1：已有分支，新文件夹

git worktree add ../myapp-hotfix hotfix/urgent

发生了什么：

Git 创建 ../myapp-hotfix/ 新目录
在其中检出 hotfix/urgent 分支
在主仓库的 .git/worktrees/myapp-hotfix/ 注册元数据

前置条件：

hotfix/urgent 分支必须存在（本地或远程）
该分支不能已经在其他 worktree 检出
目标路径不能存在或必须为空

分支已被其他 worktree 检出时的错误：

fatal: 'hotfix/urgent' is already checked out at '/some/other/path'

修复：要么在已有 worktree 里干活，要么先 git worktree remove 掉那个。

形式 2：在 Worktree 里创建新分支

git worktree add -b feat/search ../myapp-search origin/main

发生了什么：

从 origin/main 创建新分支 feat/search
在 ../myapp-search/ 检出它
新分支从此存在于你的本地仓库

**为什么这是最有用的形式：**新任务几乎总是要新分支 —— 这条命令一把搞定。

变体：

# 从当前 HEAD 分出
git worktree add -b feat/search ../myapp-search

# 从指定 commit 分出
git worktree add -b hotfix/patch ../myapp-patch abc1234

# 从 tag 分出
git worktree add -b backport/1.2 ../myapp-1.2 v1.2.0

# 跟踪 origin/main 的分支（大写 -B 会覆盖已有分支）
git worktree add -B feat/search ../myapp-search origin/main

-b（小写）在分支已存在时失败。-B（大写）强制重置。没理由别用 -B。

形式 3：分离 Worktree

不附加到任何分支的 worktree —— 用于检视历史：

git worktree add --detach ../myapp-at-abc1234 abc1234

用例：

"这个 commit 时代码长什么样？"
不打扰分支的情况下做 bisect
构建特定发布 tag 做测试
跑老 commit 的测试套件

分离 worktree 里仍可 commit，但它们不属于任何分支，直到你跑 git switch -c new-branch。

常用标志

`--track`

设置新分支跟踪远程分支：

git worktree add -b feat/auth --track origin/feat/auth ../myapp-auth

进入 worktree 后 git push 和 git pull 直接就能用 —— 不需要 -u 标志。

速记：如果省略 -b 并给了一个仅远程存在的分支名，Git 会自动这么做（见 --guess-remote）。

`--guess-remote`

当你执行：

git worktree add ../myapp-auth feat/auth

而 feat/auth 本地不存在、但 origin/feat/auth 存在 —— Git 正常会失败。有了 --guess-remote（或通过 git config worktree.guessRemote true 配置），Git 会帮你创建跟踪 origin/feat/auth 的本地 feat/auth。

git config --global worktree.guessRemote true   # 永久开启

强烈推荐 —— 消除一整类"这为啥不工作"错误。

`--checkout` / `--no-checkout`

默认 add 检出文件。--no-checkout 只建元数据、不拉文件 —— 超大仓库需要 sparse-checkout 时很有用：

git worktree add --no-checkout ../myapp-big feat/big-feature
cd ../myapp-big
git sparse-checkout set src/feature-a   # 只拉 src/feature-a
git checkout

`--lock` 和 `--reason`

创建时立刻锁定 worktree，防止误清理：

git worktree add --lock --reason "CI build" /tmp/myapp-ci feat/big

适用于共享 CI 服务器、移动盘或挂载的网络文件系统上的 worktree。

`--force`

允许在已有路径（覆盖）或已被其他 worktree 检出的分支上（违反默认规则）创建 worktree。**很少安全。**真的知道自己在做什么再用。

git worktree add --force ../myapp-hotfix hotfix/urgent

`--orphan`

在孤儿分支（无历史）上创建 worktree。适合 gh-pages 之类的并行历史：

git worktree add --orphan gh-pages ../myapp-docs

需要 Git 2.42+。

完整语法参考

git worktree add [-f | --force]
                 [--detach]
                 [--checkout | --no-checkout]
                 [--lock [--reason <string>]]
                 [--orphan]
                 [-b <new-branch> | -B <new-branch>]
                 [--track]
                 [--guess-remote]
                 <path>
                 [<commit-ish>]

<path>：要创建的目录（相对或绝对）
<commit-ish>：任何可解析的 —— 分支名、tag、commit SHA、HEAD~5

常用配方

配方：处理队友的分支

git fetch origin
git worktree add ../myapp-review alice/experimental

（需要 worktree.guessRemote = true 或预先存在的本地分支。）

配方：本地评审 Pull Request

# GitHub 上的 PR #42
git fetch origin pull/42/head:pr-42
git worktree add ../myapp-pr-42 pr-42

配方：热修复不打扰功能分支

# 当前在 ~/projects/myapp 的 feat/big-refactor 分支上，有未提交改动
git worktree add ../myapp-hotfix -b hotfix/oncall origin/main
cd ../myapp-hotfix
# 修复、commit、push
git push -u origin hotfix/oncall
cd ../myapp
# 你的功能分支完全没被碰

配方：测试发布 tag

git worktree add ../myapp-v2.0 v2.0.0
cd ../myapp-v2.0
pnpm install && pnpm test
cd .. && git worktree remove ../myapp-v2.0

配方：三个并行 AI 编程会话

git worktree add -b feat/auth    ../myapp-auth    origin/main
git worktree add -b feat/search  ../myapp-search  origin/main
git worktree add -b fix/login    ../myapp-login   origin/main

# 各自启动 Claude Code：
cd ../myapp-auth    && claude &
cd ../myapp-search  && claude &
cd ../myapp-login   && claude &

完整指南：Claude Code + Git Worktree →

常见错误与修复

`fatal: 'feat/x' is already checked out at '/path'`

一个分支同一时刻只能在一个 worktree 里。 修复： 用已有 worktree，或先 git worktree remove 它。

`fatal: 'path' already exists`

目标目录已存在且非空。 修复： 换路径，或 --force（危险）。

`fatal: invalid reference: feat/x`

分支/ref 不存在，且 --guess-remote 未开启。 修复： git fetch origin，然后启用 worktree.guessRemote，或显式 -b feat/x origin/feat/x。

`fatal: HEAD is invalid`

仓库的主 HEAD 坏了（少见，通常是操作中断后）。 修复： 主仓库里 git checkout main，然后重试。

性能说明

创建 worktree 是 O(工作树大小) —— 文件得检出。GB 级仓库要几秒钟。
.git/objects/ 数据库是共享的，所以建 N 个 worktree 不会让磁盘占用翻 N 倍。
Worktree 共享主仓库的 reflog 和 stash 元数据，但各有自己的 HEAD 和工作状态。

巨型 monorepo 考虑 --no-checkout + sparse-checkout 只物化你需要的子集。

`-b` vs 先检出分支

让 worktree 有新分支有两种办法。都能用，一种更干净。

干净：

git worktree add -b feat/x ../myapp-x origin/main

一条命令。新分支、正确起点、worktree 就绪。

脏：

git branch feat/x origin/main   # 先建分支
git worktree add ../myapp-x feat/x   # 再建 worktree

两条命令。同样结果。第一种更好：原子、出错时单一回滚点、分支不会存在但没有对应 worktree。

延伸阅读

把 git worktree add 变成一次点击。

ParallelCode 把 worktree 创建直连 AI 代理（Claude Code、Cursor Agent）。选分支、选代理、走 —— 无命令、无仪式。

免费下载 ParallelCode →