cmux worktree布局怎么选:nested、outer-nested与sibling三种模式完整对比
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 的工作流说明可以进一步上手。