worktree是什么鬼？Codex和Claude双修把我搞晕了！

最近同时使用 macOS 和 Windows 上的 Codex 和 Claude 桌面版写代码！

给我搞迷糊了😵‍💫！

今天用 Windows 版 Claude Desktop 写代码，Opus 4.7 一轮改完之后，居然一点效果都没有，把我给弄慌了。

刚开始以为是降智，后来发现了一个叫worktree的东西。

我平时管理代码，主要就是 Git 的 add、commit、push、pull 这几个，连 branch 和 PR 都很少用。

突然给我塞进了一个worktree，超纲了啊！

而且我发现 Codex 和 Claude 管理项目和任务的逻辑是不太一样的！

而且即便是 Claude 本身选择了不同的目录，也会有差异。

一大堆知识盲区叠加在一起，看来必须捋一捋了，否则要搞出事情了。

其实我真正的焦虑点在于，如果我不清楚这些概念，我就会大量浪费 tokens。在 Claude 上你但凡探索一下，询问一下，走错一次，可能一小半配额就没有了。所以我必须变得更强，才能驾驭它，才能精打细算充分利用它的配额！

下面我就以我真实情况为例，来捋一捋这些软件中的概念和操作，最后重点讲一下 worktree 这个东西。

就当一个笔记了，有兴趣的可以一起看一看。

1、Codex和Claude的差别

这两个工具都是目前编程和智能体的巅峰之作，配合上自家的模型，绝对是顶级的存在，会遥遥领先于其它产品。但是他们之间的组织逻辑是有点不一样的。

这个是 Codex 的界面：

它是主打项目（project）的概念！

基本就是一个文件夹对应一个项目，一个项目可以有多个对话。每个对话有独立的上下文。我的习惯是，一个大功能的开发或者升级，就创建一个对话，然后所有相关微调都在这个对话中完成。可以充分利用上下文节省 tokens。

这是 Claude 的界面：

Claude 桌面版目前包含了三大功能：对话 chat、办公 cowork、编程 code。

我们做编程工作的话直接切换到 code。

Claude Code 主打的是会话（session）！

它没有项目的概念，你选择一个目录，直接在这个目录上创建会话。它的不同会话可以指向不同目录，也可以指向同一个目录。

我之前一直用终端版本，操作非常简单，就是进入一个目录，然后启动 Claude Code 直接开干。

来到桌面版之后，我是比较适应 Codex 这种组织方式。因为我首先需要确定我在哪个文件夹里面工作，而 session 这种方式还是有点不太习惯。

当然这个问题也不大！我遇到的问题是突然出现了一个worktree的概念。

2、Claude本身的区别

Claude Code 终端版我是用了很久的，然后桌面版也在 macOS 上用过几次。

终端是没有 worktree 这个概念的，直接就是选中一个目录，然后开始写代码就可以了。我之前在 macOS 上面，创建新的文件夹，开始开发，也没有遇到这个东西。

而这一次在 Windows 上升级 CodingPlan 项目，就遇到问题了！

我突然发现多了一个 worktree，而且是默认勾选的。我开始升级功能的时候，都没有留意到这一点。

开始开发前我手动启动了 Web 服务，开发完成之后，我就刷新页面开始去验证功能，发现一点变化都没有。这个时候我就有点不知所措了，为什么改了半天一点效果都没有呢？

经过仔细的观察对比，发现主要是受到了 worktree 的影响。

因为我之前在 macOS 上一切正常，所以我怀疑是 Windows 版本的问题。

后来发现并不是系统差异。

macOS 也有这个 worktree：

Windows 也可以没有 worktree：

这么一搞我就迷惑了，到底怎么个意思呢？

经过不断的对比，我突然悟了。

只要有 Git 的信息，就会出现 worktree 的选项，这才是问题的关键。也就是这个 worktree 是和版本原理相关的。

那么为什么 Claude 有这个东西，而 Codex 却没有呢？

是用这个好，还是不用这个好呢？

如果用了应该怎么来管理这个东西呢？

3、worktree 是什么？

其实这个概念我是很早就听过的，但是从来没用过。我知道AI智能体的兴起，导致这个比较深度或者说低频的功能被重用了。因为这个东西存在会直接影响我的工作流，所以我必须要研究一下。

就这个问题，我专门询问了 Opus 和 GPT。

worktree 的一句话理解就是：同一个 Git 仓库，开多个“工作目录”同时干不同的活。

至于 Git 是什么？

我想关心 worktree 的应该都知道是什么了！如果不知道的话，我就简单补充一句。

Git 是代码存档和版本管理工具，写代码做开发必备。

有一个很形象的比喻就是游戏存档。

有了存档，万一 Game Over 了，就可以从存档点继续，不用重头开始打怪升级。

也有人把它比作：Git 像多人协作记录本。

如果几个人一起开发一个项目，Git 可以记录：

谁改了什么
什么时候改的
为什么改
改了哪些文件

这样团队协作不会乱。

大概就是这样吧，反正是个好东西。用 AI 写文档写代码，就让它帮你装个 Git 来管理一下。

而 worktree 是 Git 里面的一个子功能。

下面就进入 worktree 的介绍了。

简单理解

普通 Git 仓库一般是这样：

my-project/
  .git/
  src/
  package.json

你在这个目录里只能同时处在一个分支，比如：

main

如果你切到另一个分支：

git checkout feature-login

当前目录里的代码就会被切换成 feature-login 分支的状态。

worktree 是什么

git worktree 允许你把同一个仓库的不同分支，分别放到不同文件夹里。

比如：

my-project/              # main 分支
my-project-login/        # feature-login 分支
my-project-ui/           # feature-ui 分支

它们看起来像三个项目目录，但底层共用同一个 Git 仓库数据。

也就是说：

一个 Git 仓库
├─ main 工作目录
├─ login 功能工作目录
└─ ui 功能工作目录

它解决什么问题

1、不用频繁切分支

没有 worktree 时：

git checkout main
git checkout feature-a
git checkout bugfix-b

切来切去，容易影响当前未提交代码。

有 worktree 后：

cd my-project
cd ../my-project-login
cd ../my-project-ui

直接换文件夹就等于换分支。

2、可以同时跑多个版本

比如你有：

my-project/        # main 分支
my-project-test/   # 新功能分支

你可以在两个目录分别启动服务：

cd my-project
npm run dev

另一个终端：

cd my-project-test
npm run dev -- --port 3001

这样可以同时对比主分支和新功能分支。

3、配合 AI 编程工具

像 Claude Code Desktop 这类工具用 worktree，主要是为了：

不直接污染你的主项目目录

它可以在一个独立 worktree 里改代码、测试、提交。

如果改得好，你再合并回来。

如果改坏了，直接删掉那个 worktree，不影响主目录。

常用命令

查看已有 worktree：

git worktree list

创建一个新 worktree：

git worktree add ../my-project-login feature-login

创建新分支并放到新 worktree：

git worktree add -b feature-login ../my-project-login

删除 worktree：

git worktree remove ../my-project-login

如果文件夹已经手动删了，清理记录：

git worktree prune

一个关键限制

同一个分支不能同时被两个 worktree 使用。

比如 main 已经在 my-project 里用了，那么你不能再让另一个 worktree 也 checkout 到 main。

因为 Git 要避免两个目录同时修改同一个分支导致混乱。

4、实操一下

光说不练假把式，我们就在 Claude 上实操一下！

上面说到了各种命令，可以作为基础，但是在 Claude 里面，我们不需要记忆这些命令。

直接在某个目录下创建一个 worktree 的文件夹作为项目目录。

然后在 Claude 桌面版中选中这个目录：

从截图中可以看到，默认选中了本地（Local）下面的 worktree 文件夹。这个时候它的右侧是没有 worktree 相关的勾选选项的。因为这是一个全新的项目，还没有版本管理的信息。

然后我让它帮我创建一个网页，只要输入上面的一句话，一个不错的学习网站就有了。

然后我就让它帮我创建 Git 版本管理：

OK，然后帮我初始化版本管理，添加忽略文件，然后提交第一个版本

很快就帮我搞好了：

完成。具体操作：
​
git init 初始化仓库
创建 .gitignore，忽略了 .DS_Store、编辑器目录、以及 .claude/（Claude Code 的工作文件）
提交 index.html + .gitignore 为第一个版本，commit hash 1d3d949

这样就不用担心代码丢掉，或者被改坏了。

可以看到目录中已经有一个 .git 的隐藏文件夹了，并且添加了忽略文件 .gitignore，以及我们的网页 index.html。

这个时候，再去点下 New session 就可以看到 worktree 的选项了。

上面说过，只要这个目录下有 Git 信息，就会自动勾选 worktree。

正常来说，我完全可以在上面的对话里，直接让它创建 worktree 并进行管理。但是为了更好的演示，我就浪费一点上下文，直接新建一个会话。

这个会话的目标是给这个网页创建一个浅色的模式，并设为默认模式。这样对比清晰一些。

提示词如下：

你好，我正在学习 worktree，之前在主分支已经创建了一个页面。现在我需要给页面添加一个主题切换功能，创建一个浅色模式，并设置为默认的模式

一句话下去就全部搞定了：

可以看到右边已经显示了浅色的网页，左下方出现了一个分支信息。

这个时候，如果你手动打开我们主目录下的index.html，会发现并没有修改，还是黑色主题。

这就是 worktree 和单纯的分支切换最大的区别。

worktree 这种方式，并不会直接在主目录下修改文件。

经过实测，Claude 的 worktree 目录如下：

它会放在当前工作目录下的 .claude 文件夹里面！

另外值得注意的一点是，一个 worktree 是对应一个分支的。

通过命令可以看到，有两个 worktree，对应两个分支。也就是说创建 worktree 的时候其实同时创建了一个分支。

现在我们就可以在 worktree 这个分支里尽情地修改了，完全不影响主目录的内容。你修改的内容可以单独提交多个版本。

同时你还可以再开一个 worktree 的对话，同时开发其他功能。两个 worktree 互不影响。

接下来我让它帮我优化了内容、界面、交互：

它甚至还帮我做了知识测验！

这已经是一个非常棒的学习网页了。我觉得差不多了！

让它并入主目录了：

非常好，我觉得改得差不多了，请帮我并入主目录，删除这个 worktree

它的反馈信息如下：

先检查状态和 worktree 列表。
​
合并和清理已基本完成，但有一个 Windows 层面的限制需要说明：
​
**已完成 ✓**
- 改动已提交到 `claude/unruffled-ramanujan-0a45ab`（commit `872b8b7`）
- 已 `--no-ff` 合并到 `master`（commit `86d92dc`）
- 已删除分支 `claude/unruffled-ramanujan-0a45ab`
- Git 已注销 worktree 元数据（`git worktree list` 已不再显示）
​
**残留 ⚠️**
- 物理目录 `E:\Jarvis_github\worktree\.claude\worktrees\unruffled-ramanujan-0a45ab` 还在磁盘上
- 删不掉的原因：**当前这个 Claude Code 会话本身就运行在这个目录里**，Windows 锁住了 cwd 句柄。我从内部无法删除自己所在的目录
​
**怎么处理这个空目录**
​
请在 Claude Code 中切到主目录会话，或直接关闭当前会话后，在主目录手动执行：
​
```powershell
Remove-Item -Recurse -Force "E:\Jarvis_github\worktree\.claude\worktrees\unruffled-ramanujan-0a45ab"
```
​
或在 PowerShell / 资源管理器里直接删除该目录即可。Git 那边已经干净了，删除目录纯属物理清理。

它已经帮我执行了各种命令，唯一没有搞定的就是文件夹还在。

因为我们在 Claude 里面创建会话的时候，Claude 占用了这个目录，所以删不掉。这个没有任何问题。关闭这个对话，手动删除即可，或者不删也可以。

其实如果你不介意冗余，你完全可以不用清理。

重点是，我们现在的主分支主目录已经升级了！

为了给大家演示这个功能，消耗了 31% 的五小时配额！！！

这种轻量级的活，真的不适合让 Opus 4.7 来干！这完全就是大炮打蚊子！

当然，这也是值得的。只要学会了这个概念，以后就不浪费了！

我个人的感觉是，如果你的项目不是很复杂，就不要去搞 worktree 这个东西了，直接在主目录修改，反正有版本管理，也不用担心搞坏。

如果你项目比较复杂，同时需要让 AI 并行开发多个功能，那么这是一个非常不错的方式。

另外 Claude 是直接提供了这个功能，而 Codex 没有直接提供，但是你也可以让 Codex 来帮你管理 worktree！

我的文章里只是截取了最核心或者我最关心一些点，如果大家有兴趣进行完整的学习，也可以访问我刚刚制作的网页。

里面已经包含了核心概念、为什么用、常用命令、实战场景、方案对比、知识检验、速查表等板块。

网址：

https://doc.tonyhub.xyz/worktree