这份指南涵盖了从核心概念、创建、日常操作到清理的全流程，并特别针对 macOS + iOS 开发（SourceTree / Xcode / CocoaPods）的场景做了优化。
Git Worktree 完整使用指南（macOS 开发版）
一、核心概念：它到底是什么？
Worktree 不是复制代码，而是"共享历史，独立工作区"。
- 共享 ：所有 Worktree 共用同一个
.git文件夹（历史记录、分支、标签都在里面）。 - 独立：每个 Worktree 拥有独立的物理文件（源码），可以同时检出不同的分支。
类比 ：就像一本书（.git 仓库）只有一个，但你在不同页码（分支）夹了多个书签（Worktree 目录）。打开书签 A 看到第 10 页，打开书签 B 看到第 50 页，但书本身只有一本。
硬盘占用 ：相比于用 cp -r 复制整个项目（连历史一起复制），Worktree 极其节省空间。10 个 Worktree 大约只占用 10 份最新源码的大小，而非 10 份完整历史。
二、创建 Worktree（终端操作）
注意：SourceTree 没有"创建 Worktree"的按钮，必须在终端执行命令。
1. 基本命令
bash
git worktree add <新目录绝对路径> <已存在的分支名>2. 场景一：分支已存在（如紧急修复 hotfix）
bash
cd ~/Projects/MyApp
git worktree add ../MyApp-hotfix hotfix执行后，上级目录会出现 MyApp-hotfix 文件夹，里面是 hotfix 分支的最新代码。
3. 场景二：分支不存在（如新建功能分支 feature/login）
使用 -b 参数，基于指定分支（如 main）创建新分支并同时创建 Worktree：
bash
git worktree add -b feature/login ../MyApp-login main执行后，会基于 main 创建新分支 feature/login，并在 ../MyApp-login 目录下生成 Worktree。
4. 文件夹命名建议（最佳实践）
虽然名字可以随便起，但强烈建议采用 主工程名-分支功能 的格式：
~/Projects/MyApp（主工程，默认main分支）~/Projects/MyApp-hotfix（紧急修复）~/Projects/MyApp-feature-payment（支付功能开发）
好处：在 SourceTree 书签或 Finder 里扫一眼就知道对应哪个分支，防止切错项目。
三、在 SourceTree 中打开并操作
- 添加仓库 ：打开 SourceTree，点击"+ 新建" -> "添加工作副本"，浏览并选择刚刚创建的 Worktree 目录（如
MyApp-hotfix）。 - 日常操作 ：添加后，它像一个普通仓库一样出现在书签列表。提交、拉取、推送 等操作与普通仓库完全一致。
- 首次推送新分支时 ，记得在推送弹窗中勾选"推送到远程"并手动输入远程分支名（如
feature/login），以建立上游跟踪。
- 首次推送新分支时 ，记得在推送弹窗中勾选"推送到远程"并手动输入远程分支名（如
四、日常开发中的关键操作
1. 合并其他分支的代码（完全没问题）
你可以在当前 Worktree 中，将仓库里任意分支（无论该分支是否被其他 Worktree 占用）合并进来：
- 在 SourceTree 中点击"合并"，选择目标分支即可。
- 或在终端执行：
git merge feature/login。
唯一禁忌 ：不能 在当前 Worktree 中执行 git checkout 或 git switch 切换到已被其他 Worktree 占用的分支，否则 Git 会报错。
2. 如果必须切换到已被占用的分支怎么办？
不要强行切换，而是为该分支新建一个 Worktree：
bash
git worktree add ../MyApp-another-branch another-branch五、iOS 开发特别注意事项（Xcode + CocoaPods）
1. Xcode：必须重新打开
- 每个 Worktree 都是独立的项目副本，位于不同路径。
- 必须用 Xcode 分别打开 每个 Worktree 目录下的
.xcworkspace或.xcodeproj。 - 好处 ：Xcode 的
DerivedData默认基于路径隔离，因此不同 Worktree 的编译缓存互不干扰，避免"幽灵报错"。
2. CocoaPods：必须重新执行 pod install
-
Pods文件夹和Podfile.lock通常不提交到 Git（在.gitignore中），因此新 Worktree 目录下没有这些文件。 -
切换到新 Worktree 目录后，必须 在终端执行：
bashcd ~/Projects/MyApp-hotfix pod install -
如果不同分支的
Podfile差异较大，Podfile.lock可能变化，记得一起提交。
六、清理与删除（安全操作）
当你完成分支工作，不再需要某个 Worktree 时，请按以下步骤彻底清理：
-
关闭 Xcode：确保该 Worktree 对应的 Xcode 项目已关闭，防止文件被锁定。
-
确保代码已提交（可选但推荐）。
-
在终端执行官方删除命令（必须在主仓库或其他 Worktree 目录下执行 ）：
bashgit worktree remove ../MyApp-hotfix- 如果有未提交的修改导致删除失败，加强制参数：
git worktree remove -f ../MyApp-hotfix
- 如果有未提交的修改导致删除失败，加强制参数：
-
（可选）删除本地分支 ：删除 Worktree 不会自动删除对应的本地分支，若不再需要：
bashgit branch -d hotfix -
查看所有 Worktree 列表 ：
git worktree list
七、完整工作流速查表
| 操作场景 | 命令 / 方法 | 在哪执行 |
|---|---|---|
| 创建 Worktree（分支存在） | git worktree add ../新目录 分支名 |
终端 |
| 创建 Worktree（新分支） | git worktree add -b 新分支 ../新目录 基分支 |
终端 |
| 打开项目 | 双击 SourceTree 书签 / 双击 Xcode 项目 | SourceTree / Finder |
| 拉取/提交/推送 | 与普通仓库完全一样 | SourceTree / 终端 |
| 合并别的分支 | 点击"合并"或 git merge 分支名（无限制） |
SourceTree / 终端 |
| 安装 CocoaPods | pod install |
终端（在 Worktree 目录内） |
| 删除 Worktree | git worktree remove ../目录名 |
终端（任意仓库目录） |
| 查看所有 Worktree | git worktree list |
终端 |
八、总结一句话
Worktree = 共享 .git 历史 + 独立物理文件 + 各自 Xcode + 各自 Pods。
它让你能在同一时刻 并行开发多个互不干扰的功能分支，且省硬盘、切换快。只要记住 "终端创建，SourceTree 打开，各目录独立装 Pods，用 remove 命令删除"，就能完美驾驭。🚀