CodeBuddy Git Worktree 支持

一、概述

·并行开发：在不影响主工作区的情况下进行实验性开发。

·安全隔离：AI 的所有更改都在独立目录中进行。

·零存储开销：worktree 共享 Git 对象，不会复制整个仓库。

·子代理隔离：支持多个 AI 子代理在独立 worktree 中并行工作。

·tmux 集成：可选在独立的 tmux 会话中运行。

·非 Git 支持：通过 WorktreeCreate/WorktreeRemove hooks，SVN、Perforce 等项目也能使用 worktree 隔离。

二、快速开始

# 自动生成名称创建 worktreecodebuddy –worktree# 指定名称创建 worktreecodebuddy –worktree feature-auth# 指定基础分支创建 worktreecodebuddy –worktree –worktree-branch origin/develop # 基于远程 develop 分支codebuddy –worktree –worktree-branch feature/foo # 基于本地 feature/foo 分支# 在 tmux 会话中运行(推荐用于长时间任务)codebuddy –worktree –tmux# 基于 PR/MR 创建 worktree(用于代码审查)codebuddy –worktree "#123" # GitHub PR 编号codebuddy –worktree "https://github.com/owner/repo/pull/123" # GitHub PR 链接codebuddy –worktree "https://gitlab.com/owner/repo/-/merge_requests/456" # GitLab MR 链接codebuddy –worktree "https://cnb.woa.com/owner/repo/-/pulls/789" # CNB PR 链接

三、在会话中创建

已启动 CodeBuddy Code 会话后，可以通过自然语言请求创建 worktree:

> start a worktree> work in a worktree> 启动 worktree

AI 会自动调用 EnterWorktree 工具创建隔离工作目录并切换过去。

注意：只有明确提到 “worktree” 时才会触发，说 “帮我开一个分支” 或“修复这个 bug” 不会自动创建 worktree。

四、CLI 参数

六、创建 Worktree

当使用 –worktree 参数启动时:

1. CodeBuddy 在 .codebuddy/worktrees/ 目录下创建新的 worktree

2. 确定基础分支:

·如果指定了 –worktree-branch origin/xxx，基于远程分支 origin/xxx

·如果指定了 –worktree-branch xxx，基于本地分支 xxx

·如果未指定，默认基于远程默认分支（通常是 origin/main 或 origin/master）

3. 自动创建对应的分支(如 worktree-feature-auth)

4. 将工作目录切换到 worktree；如果你是从仓库子目录启动，会优先进入新 worktree 中对应的相对子目录

5. 执行初始化(复制设置、创建符号链接、复制 .worktreeinclude 文件等)

分支不存在时的行为：

·如果指定的分支（远程或本地）不存在，会打印警告并自动降级到远程默认分支继续创建

·不会中断启动流程

七、退出时的选择

当你退出 worktree 会话时，CodeBuddy 会检测变更并提供选项：

·保留 Worktree：保留所有更改和分支，可以稍后继续

·删除 Worktree：清理 worktree 和关联分支

·保留但退出 tmux：（tmux 模式）保留 worktree 但关闭 tmux 会话

八、变更检测

退出前，CodeBuddy 会检测：

·未提交的文件变更

·未推送的提交

如果没有任何变更，worktree 会自动清理。

九、配置

在 settings.json 中配置 worktree 行为:

{ "worktree": { "symlinkDirectories": ["node_modules", ".next", ".cache", "dist"] }}

十、配置项

符号链接目录可以避免在每个 worktree 中重复安装依赖，节省时间和磁盘空间。

十一、同步本地忽略文件(.worktreeinclude)

.env.local、.env.development 等本地配置文件通常被 .gitignore 排除，但新 worktree 中同样需要它们才能正常运行。

解决方式:在仓库根目录创建 .worktreeinclude 文件，列出需要复制的文件(语法与 .gitignore 相同):

# .worktreeinclude# 列出需要复制到新 worktree 的本地文件# 环境变量.env.local.env.development.local.env.test.local# 本地 IDE 配置.vscode/settings.json# 本地证书或密钥(如有)certs/localhost.pem

每次创建新 worktree 时，这些文件会自动从主仓库根目录复制过去。复用已有 worktree 时不会重新复制。

注意：说明：

注意：.worktreeinclude 应该提交到 Git，这样团队成员都能受益。

十二、Hook-based Worktree

默认情况下，worktree 功能依赖 Git 内置的 git worktree 命令。对于使用 SVN、Perforce 或没有版本控制的项目，可以通过配置 WorktreeCreate / WorktreeRemove hooks 来使用 worktree 隔离功能。

十三、决策优先级

1. 配置了 WorktreeCreate hook？ → 使用 hook 创建（即使在 Git 仓库中也优先使用 hook）2. 在 Git 仓库中？ → 使用 git worktree3. 都不满足？ → 报错并提示配置 hook

核心规则：

·Hook 优先于 Git：配置了 WorktreeCreate hook 后，即使在 Git 仓库中也走 hook，不走 git worktree

·创建失败不降级：WorktreeCreate hook 失败时不会回退到 git worktree，直接报错

·删除失败不阻塞：WorktreeRemove hook 失败只记录警告，不阻止退出流程

十四、配置方式

在 .codebuddy/settings.json（项目级）或 ~/.codebuddy/settings.json（全局）中配置：

{ "hooks": { "WorktreeCreate": [ { "hooks": [ { "type": "command", "command": "bash ~/.codebuddy/hooks/worktree-create.sh" } ] } ], "WorktreeRemove": [ { "hooks": [ { "type": "command", "command": "bash ~/.codebuddy/hooks/worktree-remove.sh" } ] } ] }}

两个 hook 独立配置，可以只配 WorktreeCreate 不配 WorktreeRemove（此时退出时不会自动清理，会提示手动删除目录）。

十五、输入数据（stdin）

Hook 脚本通过 stdin 接收 JSON 格式的上下文数据。

WorktreeCreate 输入：

{ "hook_event_name": "WorktreeCreate", "session_id": "abc123def456", "cwd": "/Users/user/project", "transcript_path": "/Users/user/.codebuddy/sessions/abc123/transcript.md", "name": "feature-auth"}

WorktreeRemove 输入：

{ "hook_event_name": "WorktreeRemove", "session_id": "abc123def456", "cwd": "/Users/user/project", "transcript_path": "/Users/user/.codebuddy/sessions/abc123/transcript.md", "worktree_path": "/tmp/codebuddy-worktrees/feature-auth"}

十六、输出与 Exit Code

WorktreeCreate：

·stdout：必须输出创建好的 worktree 绝对路径（取最后一行非空行）

·stderr：可输出日志，不影响路径解析

·exit code 0：成功，解析 stdout 中的路径

·exit code 非 0：创建失败，报错并退出（不降级到 git worktree）

# 正确示例：日志输出到 stderr，路径输出到 stdoutecho "Initializing SVN checkout…" >&2echo "/home/user/.codebuddy/worktrees/feature-auth"

WorktreeRemove：

·没有决定控制：任何 exit code 都不会阻止退出流程

·失败仅记录警告日志

十七、退出行为差异

与 Git worktree 不同，hook-based worktree 退出时始终显示 keep/remove 菜单，不做变更检测（因为非 Git 项目没有 git status）。

十八、Hook 脚本模板

WorktreeCreate (~/.codebuddy/hooks/worktree-create.sh):

#!/bin/bashset -eINPUT=$(cat)NAME=$(echo "$INPUT" | jq -r '.name')CWD=$(echo "$INPUT" | jq -r '.cwd')WORKTREE_PATH="$HOME/.codebuddy/worktrees/$NAME"mkdir -p "$WORKTREE_PATH"# 在这里添加 VCS 初始化逻辑（SVN checkout、P4 sync、目录复制等）cp -r "$CWD"/* "$WORKTREE_PATH/" 2>/dev/null || true# 最后一行输出绝对路径到 stdout（必需）echo "$WORKTREE_PATH"

WorktreeRemove (~/.codebuddy/hooks/worktree-remove.sh):

#!/bin/bashINPUT=$(cat)WORKTREE_PATH=$(echo "$INPUT" | jq -r '.worktree_path')# 安全检查：确保路径在预期范围内if [[ "$WORKTREE_PATH" != "$HOME/.codebuddy/worktrees/"* ]]; then echo "Refusing to remove path outside worktrees directory: $WORKTREE_PATH" >&2 exit 1firm -rf "$WORKTREE_PATH"

注意：说明：

注意：脚本依赖 jq 解析 JSON。macOS：brew install jq，Linux：apt install jq。

十九、实战示例

SVN 项目：

{ "hooks": { "WorktreeCreate": [ { "hooks": [ { "type": "command", "command": "bash -c 'INPUT=$(cat); NAME=$(echo $INPUT | jq -r .name); DIR=\\"$HOME/.codebuddy/worktrees/$NAME\\"; svn checkout https://svn.example.com/repo/trunk \\"$DIR\\" >&2 && echo \\"$DIR\\"'" } ] } ], "WorktreeRemove": [ { "hooks": [ { "type": "command", "command": "bash -c 'cat | jq -r .worktree_path | xargs rm -rf'" } ] } ] }}

无 VCS 的项目（目录复制）：

{ "hooks": { "WorktreeCreate": [ { "hooks": [ { "type": "command", "command": "bash -c 'INPUT=$(cat); NAME=$(echo $INPUT | jq -r .name); CWD=$(echo $INPUT | jq -r .cwd); DIR=\\"$HOME/.codebuddy/worktrees/$NAME\\"; cp -r \\"$CWD\\" \\"$DIR\\" && echo \\"$DIR\\"'" } ] } ], "WorktreeRemove": [ { "hooks": [ { "type": "command", "command": "bash -c 'cat | jq -r .worktree_path | xargs rm -rf'" } ] } ] }}

20、tmux 集成

使用 –tmux 参数可以在独立的 tmux 会话中运行 CodeBuddy：

# 基本用法codebuddy –worktree –tmux# 使用传统模式（不使用 popup）codebuddy –worktree –tmux –tmux-classic

21、tmux 要求

·tmux 版本 3.2 或更高（支持 popup 功能）

·如果版本较低，会自动回退到传统模式

22、退出 tmux 会话

·按 Ctrl+D 或输入 /exit 退出 CodeBuddy

·tmux 会话会根据你的选择保留或关闭

23、目录结构

your-repo/├── .codebuddy/│ └── worktrees/│ ├── feature-auth/ # worktree 目录│ │ ├── node_modules -> ../../node_modules # 符号链接│ │ └── …│ └── fix-bug-123/├── .worktreeinclude # 定义需要复制的本地文件(建议提交)└── …

24、手动管理 Worktree

CodeBuddy Code 在会话退出时会自动处理 worktree 的清理。但有时需要在会话外手动管理——比如清理残留的 worktree，或者需要更灵活地控制分支和目录位置。

25、在会话外清理 Worktree

直接使用 Git 命令清理:

# 查看当前所有 worktreegit worktree list# 删除指定 worktree(worktree 内没有未提交改动时)git worktree remove .codebuddy/worktrees/feature-auth# 强制删除(有未提交改动时)git worktree remove –force .codebuddy/worktrees/feature-auth# 同时删除对应的分支git branch -D worktree-feature-auth# 清理失效的 worktree 引用(目录已删但 Git 还记着)git worktree prune

26、用 Git 直接创建 Worktree

有时需要检出已有分支，或者把 worktree 放到仓库目录之外，可以绕开 CodeBuddy Code 直接用 Git 创建，然后再在里面启动会话:

# 新建分支并创建 worktree(放在仓库外)git worktree add ../project-feature-a -b feature-a# 检出已有分支git worktree add ../project-bugfix bugfix-123# 进入 worktree,启动 CodeBuddy Codecd ../project-feature-a && codebuddy# 用完后清理git worktree remove ../project-feature-a

这种方式适合需要把 worktree 放在特定位置、或者复用现有分支的场景。

27、子代理隔离

当让 CodeBuddy Code 启动多个子代理并行工作时，可以让每个子代理运行在独立的 worktree 中，避免文件冲突。

28、isolation: worktree 是什么

在自定义 Agent 的 frontmatter 中加上 isolation: worktree，每次用 Task 工具启动这个 Agent 时，系统会自动为它创建一个独立的 worktree，而不是在主仓库目录里直接运行。

这意味着:

·多个子代理可以同时修改同名文件，互不影响

·主仓库目录保持干净，子代理的临时改动不会污染它

·子代理完成后，worktree 按需保留或删除

29、创建隔离型自定义 Agent

在 .codebuddy/agents/ 目录下创建 Markdown 文件:

—name: isolated-workerdescription: 在独立 worktree 中工作,不影响主仓库isolation: worktree—你在一个独立的 git worktree 中运行。请专注完成分配给你的任务,完成后汇报结果。

30、使用效果

主 Agent 用 Task 工具启动该 Agent 时，会自动为它创建独立的 worktree。多个子代理可以同时工作，即使修改了相同的文件也不会冲突。

子代理完成后:

·没有变更:worktree 自动删除

·有变更:worktree 保留，主 Agent 会收到 worktree 位置信息

31、验证隔离效果

> 使用 isolated-worker agent，在当前目录创建 test.txt，写入 "hello"

检查结果:

# 主仓库里没有这个文件ls test.txt# → No such file or directory ✓# 文件在子代理的 worktree 里ls .codebuddy/worktrees/agent-xxx/test.txt# → 存在 ✓

33、场景一：基于特定分支开发

问题：需要在 develop 分支上开发新功能，而不是基于 main 分支。

解决方案:

# 基于远程 develop 分支创建 worktreecodebuddy –worktree feature-xxx –worktree-branch origin/develop# 基于本地分支创建（保留本地未推送的提交）codebuddy –worktree feature-yyy –worktree-branch my-local-branch

34、场景二：并行处理紧急 Bug

问题：正在开发新功能，代码改了一半，突然需要修紧急 bug。

解决方案：

# 终端 1:继续开发新功能codebuddy –worktree feature-payment# 终端 2:专门修 bug，互不干扰codebuddy –worktree hotfix-login-crash

两个 worktree 同时打开，互不影响。bug 修完提交 PR，再回到功能开发。

35、场景三：高风险重构

问题：想尝试大规模重构，但不确定能否成功，不想污染主仓库。

解决方案：

codebuddy –worktree refactor-esm

在会话中：

> 帮我把 src/core 目录从 CommonJS 迁移到 ESM

结果：

·成功：提交，推 PR，合并。

·失败：退出时选择 “Remove worktree”，所有改动一键丢弃。

36、场景四：审查 PR

问题：想在本地跑一下同事的 PR 代码，但不想污染工作目录。

解决方案：

codebuddy –worktree "#456"

在会话中：

> 帮我看看这次 PR 改了什么，有没有潜在问题> 运行一下测试

审查完直接退出，worktree 自动清理。

37、场景五：并行任务

问题：有多个独立任务(写文档、加测试、开发新接口)，想分别推进。

解决方案：

codebuddy –worktree task-docs –tmuxcodebuddy –worktree task-tests –tmuxcodebuddy –worktree task-new-api –tmux

每个 worktree 让 AI 专注做一件事，配合 tmux 实现真正并行工作。

38、场景六：子代理协作

问题：大型任务需要多个 AI 并行处理不同模块。

解决方案：

首先创建隔离型 Agent（见上文子代理隔离章节），然后：

> 使用三个并行的 api-worker 子代理: 第一个处理 src/api/user/ 目录 第二个处理 src/api/order/ 目录 第三个处理 src/api/product/ 目录

三个子代理各自在独立 worktree 中工作，即使修改了共享文件也不会冲突。

40、Q1：–worktree-branch 应该传远程分支还是本地分支？

严格区分：

·–worktree-branch origin/xxx → 使用远程分支（会先 fetch 最新代码）

·–worktree-branch xxx → 使用本地分支（保留本地未推送的提交）

如果指定的分支不存在，会打印警告并降级到远程默认分支，不会中断启动。

41、Q2：worktree 会占用很多磁盘空间吗?

不会。所有 worktree 共享 Git 对象数据库，只需要存储工作文件本身。如果配置了 symlinkDirectories，大型目录也会共享，几乎不占额外空间。

42、Q3：复用已有 worktree 时，.env.local 等文件还会重新复制吗?

不会。复用时直接进入已有目录，跳过初始化。如需同步新配置，需删除 worktree 后重建:

git worktree remove –force .codebuddy/worktrees/my-featuregit branch -D worktree-my-featurecodebuddy –worktree my-feature

43、Q4：worktree 里的提交会影响主仓库吗?

不会。worktree 有独立分支，提交只在该分支上。要合并到主分支，需走正常 PR 流程或手动 git merge。

44、Q5：创建 worktree 中途断开了，留下残缺目录怎么办?

git worktree remove –force .codebuddy/worktrees/<名称>git branch -D worktree-<名称>

然后重新创建即可。

45、Q6：symlinkDirectories 配置了但没生效?

复用已有 worktree 时不会重新初始化。删除旧 worktree 重建一次即可。

46、Q7：子代理隔离是安全沙箱吗?

不是。子代理在文件层面隔离，但权限与主 Agent 相同，理论上可操作 worktree 之外的文件。这个功能的目的是防止多个 Agent 之间的文件冲突，而非安全限制。

47、Q8：配置了 WorktreeCreate hook 后还能用 Git Worktree 吗？

不能同时使用。Hook 优先级高于 Git——一旦配置了 WorktreeCreate hook，所有 worktree 操作都走 hook，即使在 Git 仓库中也是如此。要恢复使用 git worktree，删除 settings.json 中的 WorktreeCreate 配置即可。

48、Q9：只配了 WorktreeCreate 没配 WorktreeRemove 会怎样？

创建正常工作，但退出时不会自动清理。系统会提示 worktree 目录保留在哪里，需要手动删除。

49、Q10：Hook 脚本执行失败了怎么办？

WorktreeCreate 失败会直接报错，不会降级到 git worktree，检查脚本的 stderr 输出排查问题。WorktreeRemove 失败只记录警告，不影响退出流程。

50、Q11：在非 Git 项目中使用 hook-based worktree，退出时为什么没有自动清理？

hook-based worktree 退出时始终显示 keep/remove 菜单，不进行变更检测（因为非 Git 项目没有 git status）。需要手动选择是否删除。

51、注意事项

·Git 仓库或 Hook：–worktree 需要 Git 仓库或配置 WorktreeCreate hook（非 Git 项目如 SVN、Perforce 可通过 hook 支持）

·分支命名：自动创建的分支以 worktree- 为前缀

·清理：长时间未使用的 worktree 不会自动清理，需要手动删除或使用 /rewind 命令

·符号链接：某些工具可能不支持符号链接的目录，请根据项目需求配置

52、相关文档

·CLI 参考 – 完整的命令行参数说明

·Hooks 参考 – Hook 系统详细文档

·设置配置 – 配置文件说明