Git Worktree sourcetree完整使用指南

这份指南涵盖了从核心概念、创建、日常操作到清理的全流程，并特别针对 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. 基本命令

git worktree add <新目录绝对路径> <已存在的分支名>

2. 场景一：分支已存在（如紧急修复 hotfix）

cd ~/Projects/MyApp
git worktree add ../MyApp-hotfix hotfix

执行后，上级目录会出现 MyApp-hotfix 文件夹，里面是 hotfix 分支的最新代码。

3. 场景二：分支不存在（如新建功能分支 feature/login）

使用 -b 参数，基于指定分支（如 main）创建新分支并同时创建 Worktree：

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 中打开并操作

1. 添加仓库 ：打开 SourceTree，点击"+ 新建" -> "添加工作副本"，浏览并选择刚刚创建的 Worktree 目录（如 MyApp-hotfix）。
2. 日常操作 ：添加后，它像一个普通仓库一样出现在书签列表。提交、拉取、推送 等操作与普通仓库完全一致。
   • 首次推送新分支时 ，记得在推送弹窗中勾选"推送到远程"并手动输入远程分支名（如 feature/login），以建立上游跟踪。

---

四、日常开发中的关键操作

1. 合并其他分支的代码（完全没问题）

你可以在当前 Worktree 中，将仓库里任意分支（无论该分支是否被其他 Worktree 占用）合并进来：

• 在 SourceTree 中点击"合并"，选择目标分支即可。
• 或在终端执行：git merge feature/login。

唯一禁忌 ：不能 在当前 Worktree 中执行 git checkout 或 git switch 切换到已被其他 Worktree 占用的分支，否则 Git 会报错。

2. 如果必须切换到已被占用的分支怎么办？

不要强行切换，而是为该分支新建一个 Worktree：

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 目录后，必须 在终端执行：

  cd ~/Projects/MyApp-hotfix
  pod install

• 如果不同分支的 Podfile 差异较大，Podfile.lock 可能变化，记得一起提交。

---

六、清理与删除（安全操作）

当你完成分支工作，不再需要某个 Worktree 时，请按以下步骤彻底清理：

1. 关闭 Xcode：确保该 Worktree 对应的 Xcode 项目已关闭，防止文件被锁定。

2. 确保代码已提交（可选但推荐）。

3. 在终端执行官方删除命令（必须在主仓库或其他 Worktree 目录下执行 ）：

   git worktree remove ../MyApp-hotfix

   • 如果有未提交的修改导致删除失败，加强制参数：git worktree remove -f ../MyApp-hotfix

4. （可选）删除本地分支 ：删除 Worktree 不会自动删除对应的本地分支，若不再需要：

   git branch -d hotfix

5. 查看所有 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 命令删除"，就能完美驾驭。🚀