cmux worktree布局怎么选:nested、outer-nested与sibling三种模式完整对比

原创2026-11-16 19:22:19437 阅读

cmux worktree布局怎么选:nested、outer-nested与sibling三种模式完整对比

如果你正在用 cmux 管理多个并行 Claude Code 会话,却不确定 worktree 布局(layout)该选 nested、outer-nested 还是 sibling,这篇指南会用目录结构图和一张对比表,帮你一次性看懂三种模式的差异与适用场景,并在最后给出一键切换的配置命令。

cmux 是什么?为什么需要布局选择?

cmux 是一个纯 Bash 工具,它为每个 Claude agent 创建一个独立的 git worktree,让多个 AI 会话在同一仓库上并行工作而互不干扰。

worktree 本身很简单,真正影响日常体验的是这些 worktree 目录放在哪里:

  • 放在仓库里面(.worktrees/)还是仓库外面?
  • 每个分支一个独立目录,还是统一收进一个文件夹?
  • 目录名会不会和真实分支冲突?

cmux 把这件事做成了三个开箱即用的预设,也就是本文的主角:nested、outer-nested、sibling。

三种 worktree 布局模式:目录结构一览

假设你的仓库名为 myapp、要拉出的分支是 feature/auth(cmux 会把斜杠规范化为 feature-auth,见 cmux.sh),三种模式生成的目录结构分别如下。

1. nested —— 默认模式,worktree 藏在仓库内部

myapp/
└── .worktrees/
    └── feature-auth/      ← worktree 目录
  • 所有 worktree 集中在仓库根目录的 .worktrees/ 下
  • 这是 cmux 的默认布局,无需任何配置(cmux.sh)
  • 官方建议在 .gitignore 中加入 .worktrees/,避免误提交

2. outer-nested —— 仓库外部的集中文件夹

~/projects/
├── myapp/                    ← 主仓库
└── myapp.worktrees/          ← 所有 worktree 收在这里
    └── feature-auth/
  • worktree 放在仓库的父目录中,统一收纳到 <仓库名>.worktrees/ 文件夹(cmux.sh)
  • 仓库内部保持干净,磁盘占用也不落在仓库里

3. sibling —— 平级兄弟目录,每个分支一个文件夹

~/projects/
├── myapp/                    ← 主仓库
├── myapp-feature-auth/       ← 一个分支一个平级目录
└── myapp-fix-payments/
  • 每个 worktree 直接是主仓库旁边的同级目录,命名为 <仓库名>-<分支名>(cmux.sh)
  • 目录之间完全平级,编辑器多开窗口时最直观

nested vs outer-nested vs sibling 对比表

维度 nested(默认) outer-nested sibling
worktree 位置 仓库内 .worktrees/ 父目录 <repo>.worktrees/ 父目录平级
目录命名 .worktrees/<分支名> <repo>.worktrees/<分支名> <repo>-<分支名>
仓库是否变干净 需要 .gitignore ✅ 天然干净 ✅ 天然干净
切换项目上下文 在仓库内 cd 即可 需进外部文件夹 每个目录独立,最直观
磁盘隔离 ❌ 占用仓库磁盘 ✅ 可放其他盘 ✅ 可放其他盘
适用场景 日常默认 统一管理多个仓库 每个功能独立窗口/IDE

怎么选?三种布局适用场景建议

🧭 按你的工作习惯对号入座:

  • 拿不准就选 nested:零配置、开箱即用,cmux 默认就是它。把 .worktrees/ 加进 .gitignore 即可安心使用。
  • 仓库体积敏感、想隔离磁盘选 outer-nested:worktree 会完整检出代码,放进仓库外可以避免 IDE 索引、构建缓存把主仓库拖慢;多个仓库还可以共用一个上层目录统一管理。
  • 重度并行、习惯每个任务开独立窗口选 sibling:每个分支就是一个平级目录,myapp-feature-auth、myapp-fix-payments 一目了然,多开终端或 IDE 项目时不用记内部路径。

⚠️ 一个常见疑问:切换布局不会移动已有 worktree。cmux 在切换时会提示现有 worktree 的数量,需要先 cmux rm --all 清理后新布局才完全生效(cmux.sh)。

cmux 布局配置命令教程

布局功能自 0.1.4 版本引入,详见 NOTES.md 的发布说明。

查看当前生效的布局

cmux config
# 输出示例:layout=nested (source: default)

配置读取优先级为:项目级 .cmux/config.json > 全局 ~/.cmux/config.json > 默认 nested(cmux.sh)。

为单个项目设置布局

在仓库内执行:

cmux config set layout outer-nested     # 写入 <repo>/.cmux/config.json

设置全局默认布局

cmux config set layout sibling --global # 写入 ~/.cmux/config.json

三个合法预设值为 nested、outer-nested、sibling,填错会得到 Invalid layout 提示(cmux.sh)。

常见问题 FAQ

Q:改布局后原来的 worktree 会丢吗? A:不会移动,cmux 只做位置新约定。建议先 cmux rm --all 清理旧 worktree(分支仍保留在主仓库,代码不丢)。

Q:布局会影响 cmux 的其他命令吗? A:不会。new、start、ls、merge、rm 都会自动按当前布局解析目录,例如 cmux ls 的过滤路径会随布局切换(cmux.sh)。

Q:为什么 cmux 要把分支名的斜杠替换成横线? A:feature/auth 这类分支名直接做目录名会多出一层子目录,破坏布局约定,所以统一规范化为 feature-auth(cmux.sh)。

总结:一张表带走选择结论

你的情况 推荐布局
新手 / 不折腾 nested(默认,加 .gitignore 即可)
仓库大、想隔离磁盘与索引 outer-nested
每个功能开独立窗口 sibling

一句话建议:默认 nested 就够;目录开始"乱"了再切 outer-nested 或 sibling。所有细节源码都在单文件 cmux.sh 中,配合 README.md 的工作流说明可以进一步上手。

登录后查看全文
cmux