git worktree 是 Git 内置的一个功能，允许你在同一个仓库下同时检出多个分支到不同目录，每个目录都是独立的工作区。本文从零开始讲清楚 git worktree 的使用场景、完整操作命令和注意事项，帮你真正用好这个被很多开发者忽略的实用功能。
觉得 Git 命令太繁琐？ 如果你更习惯用自然语言描述需求——直接说"帮我为 hotfix 分支新建一个独立工作目录"，EasyClaw 能理解意图并直接执行，省去记命令参数的负担。本地运行，安装即用。命令教程往下看，两种方式各取所需。
git worktree 解决什么问题？
先说一个典型的开发痛点：
你正在 feature/new-login 分支上开发新功能，代码改了一半。这时线上突然出现紧急 Bug，需要切换到 main 分支修复。
普通做法的问题：
- 用
git stash暂存当前改动，切换到main修复 Bug，再切回来恢复暂存 - 或者新建一个 commit 保存进度，之后还要 amend 或 rebase 清理
这些操作本身不复杂，但在需要频繁切换的场景下（同时维护多个版本、并行开发多个功能）会变得很繁琐，而且暂存/恢复的过程容易出错。
git worktree 的解法：
为 main 分支创建一个独立的工作目录，在那里修复 Bug，完全不影响你在 feature/new-login 分支上的进行中工作。两个目录同时存在，共享同一个 .git 仓库，磁盘空间占用远小于完整克隆两份仓库。
git worktree 的核心概念
理解三个核心概念：
主工作树（Main Worktree）
用 git clone 或 git init 得到的那个目录，包含完整的 .git 目录。这是你的"主基地"。
链接工作树（Linked Worktree）
用 git worktree add 创建的额外工作目录。它没有独立的 .git 目录，而是通过一个指针文件链接到主仓库的 .git。
共享对象存储
所有工作树共享同一份 Git 对象数据库（commits、blobs、trees），不重复存储文件历史，只有工作区文件是独立的。
git worktree 完整操作教程
创建新工作树
基础语法：
git worktree add <路径> <分支名>
示例一：为已有分支创建工作树
# 在上级目录创建 hotfix 分支的工作树
git worktree add ../hotfix-workspace main# 切换到新工作树目录
cd ../hotfix-workspace# 此时你在 main 分支，原目录的 feature 分支未受影响
示例二：同时创建新分支和工作树
# 从 main 创建新分支 hotfix/issue-123，并为其创建工作树
git worktree add -b hotfix/issue-123 ../hotfix-123 main
示例三：创建裸工作树（不检出文件，仅用于构建）
git worktree add --no-checkout ../build-temp main
查看所有工作树
git worktree list
输出示例：
/Users/dev/myproject abc1234 [feature/new-login]
/Users/dev/hotfix-workspace def5678 [main]
/Users/dev/hotfix-123 ghi9012 [hotfix/issue-123]
第一列是工作树路径，第二列是当前 HEAD 的 commit hash，第三列是分支名。
在工作树之间切换
git worktree 的各个工作树就是普通的文件目录，直接用 cd 命令切换即可：
# 切到紧急修复工作树
cd ../hotfix-workspace# 修复 Bug，提交
git add .
git commit -m "fix: 修复登录页面 500 错误"# 回到原来的功能开发工作树
cd ../myproject
注意： 每个工作树只能对应一个分支，同一个分支不能同时被两个工作树检出。试图这样做会报错：
fatal: 'main' is already checked out at '../hotfix-workspace'
删除工作树
完成工作后及时清理工作树，避免目录杂乱：
方法一：先删目录，再清理记录
# 删除工作树目录
rm -rf ../hotfix-workspace# 清理 Git 内部的工作树记录
git worktree prune
方法二：使用 remove 命令（推荐）
git worktree remove ../hotfix-workspace
如果工作树有未提交的改动，remove 会拒绝删除。强制删除（慎用，会丢失未提交内容）：
git worktree remove --force ../hotfix-workspace
修复损坏的工作树记录
当工作树目录被手动删除（没有用 git worktree remove），Git 内部记录和实际目录不同步。使用 prune 清理悬空记录：
git worktree prune
# 加 --dry-run 先预览会删除哪些记录
git worktree prune --dry-run
锁定工作树（防止误删）
对于长期保留的工作树，可以加锁防止 prune 误清理：
# 锁定
git worktree lock ../hotfix-workspace --reason "v2.0 发布前保留"# 解锁
git worktree unlock ../hotfix-workspace
实际工作场景中的 worktree 使用模式
模式一：紧急修复 + 功能开发并行
myproject/ ← feature/new-login（当前功能开发）
myproject-hotfix/ ← hotfix/issue-xxx（紧急线上修复）
在 myproject-hotfix 完成修复并 push 后，用 git worktree remove 清理，不影响主开发目录。
模式二：多版本同时维护
myproject/ ← develop（主开发分支）
myproject-v1/ ← release/v1.x（旧版本维护）
myproject-v2/ ← release/v2.x（当前版本维护）
需要向 v1.x 回移补丁时，直接在 myproject-v1 目录操作，cherry-pick 对应 commit 过来，互不干扰。
模式三：并行构建不同配置
myproject/ ← 开发分支，代码持续变动
myproject-build/ ← main（仅用于构建，不直接编辑）
CI/CD 脚本从 myproject-build 目录触发构建，不受开发中的未提交内容影响。
git worktree 与相关方案对比
| 方案 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| git worktree | 同仓库多分支并行 | 共享对象存储，磁盘节省 | 分支不能重复检出 |
| git stash | 临时保存进度 | 操作简单 | 频繁切换容易混乱 |
| git clone（完整副本） | 完全隔离的实验环境 | 完全独立 | 磁盘占用大，对象不共享 |
| 多个终端窗口 + 同一工作树 | 不涉及分支切换的并行任务 | 无需额外配置 | 同一工作树同时操作易冲突 |
使用 git worktree 的注意事项
注意一：IDE 项目配置可能需要单独设置
部分 IDE（如 IntelliJ IDEA、VS Code）的项目配置文件（.idea/、.vscode/）是针对单个工作树的，在新工作树中首次打开项目时可能需要重新配置。
注意二：子模块（submodule）的处理
包含 Git 子模块的仓库，在新工作树中需要重新运行 git submodule update --init 初始化子模块，不会自动继承。
注意三：.gitignore 中的 worktree 目录
如果工作树目录创建在主仓库目录内（不推荐，但有人这样做），需要将工作树目录名加入 .gitignore，避免被 Git 误追踪。推荐将工作树创建在主仓库目录外部，规避这个问题。
注意四：共享 Git Hooks
所有工作树共享主仓库的 .git/hooks，这意味着在任何工作树中的 commit、push 都会触发相同的 Hooks 脚本，需要确保 Hooks 逻辑对所有分支都适用。
常见问题
Q1：git worktree 和直接 clone 两份仓库有什么本质区别？
核心区别在于 Git 对象的共享。worktree 共享同一份 .git 对象数据库，不重复存储 commit 历史和文件内容，在大型仓库（几个 GB 的历史）中磁盘节省非常明显。clone 两份会完整复制所有历史，互相独立但占用翻倍。
Q2：在 worktree 中提交的 commit 会影响主工作树吗？
会，因为共享同一个 Git 仓库。在链接工作树中提交到某个分支的 commit，在主工作树中也能看到（git log <分支名>）。这是设计如此，两个工作树看到的是同一个分支历史。
Q3：能在 worktree 中使用 git rebase 和 git merge 吗？
完全可以，worktree 支持所有 Git 操作，和主工作树没有区别。
Q4：worktree 中能检出 tag 或特定 commit（detached HEAD）吗？
可以，使用 git worktree add <路径> <tag名> 或 git worktree add <路径> <commit-hash>，会创建 detached HEAD 状态的工作树。
Q5：Windows 系统上使用 git worktree 有什么需要注意的？
路径分隔符使用正斜杠（/）或双反斜杠（\\）均可，Git for Windows 会自动处理。路径中避免包含中文或空格，部分工具在处理含中文的路径时可能出现编码问题。
总结
git worktree 是一个被严重低估的 Git 内置功能。核心使用场景总结为三类：
- 紧急修复 + 功能开发并行：不用 stash，直接开新工作树
- 多版本同时维护：每个版本一个工作树，独立操作互不干扰
- 构建隔离：保持一个干净的构建目录，不受开发中未提交内容影响
掌握 add、list、remove、prune 这四个核心命令，已经能覆盖 90% 的 worktree 使用场景。
【AI辅助创作声明：本文由 AI 辅助整理与撰写，内容已经过人工审校与调整。】