mcpField
C
cmux-and-worktrees

cmux-and-worktrees

github.com/rami-maalouf开发244 次安装1 周前更新
代码仓库

关于 cmux-and-worktrees

面向编码 Agent 的技能，通过 `cmux` 在隔离的 Git worktree 中协调并行编码任务，涵盖创建、恢复、设置、合并和清理，并为高风险操作规定了确认步骤。

主要功能

  1. 01创建或恢复隔离的 worktree
  2. 02导航和列出 worktree
  3. 03合并分支，包括压缩合并
  4. 04生成并运行设置钩子
  5. 05为删除和合并设置安全规则

适用场景

  1. 01在仓库中并行开展编码任务
  2. 02恢复现有分支 worktree 上的工作
  3. 03设置并合并任务 worktree
  4. 04合并后清理 worktree

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/rami-maalouf/skills --skill cmux-and-worktrees

安装后在 Claude Code 中输入/cmux-and-worktrees确认已加载。

详细介绍

cmux 与 Worktree

通过将每项任务隔离在一个 git worktree 中，安全地并行运行多个编码会话。

不可妥协的命令规则

  • 在此技能中，每条命令都必须使用 cmux。
  • 正常操作时不得用 git worktree 替代。
  • 如果 cmux 命令失败，请先用 type cmux 确认其是否可用。

预检

  1. 确认当前目录位于 git 仓库内：
git rev-parse --is-inside-work-tree
  1. 确认 cmux 可用：
type cmux
  1. 确保 git 忽略 worktree：
rg -n '^\.worktrees/$' .gitignore || echo '.worktrees/' >> .gitignore
  1. 检查活动 worktree：
cmux ls

核心命令

  • 创建新的隔离任务：cmux new <branch>
  • 恢复现有任务：cmux start <branch>
  • 跳转到 worktree：cmux cd [branch]
  • 列出 worktree：cmux ls
  • 合并到主检出目录：cmux merge [branch] [--squash]
  • 移除 worktree 和分支：cmux rm [branch | --all] [--force]
  • 生成设置钩子：cmux init [--replace]
  • 显示／设置布局配置：cmux config、cmux config set layout <nested|outer-nested|sibling> [--global]
  • 更新工具：cmux update
  • 显示版本：cmux version

精确工作流

现有分支 -> Worktree
cd /path/to/repo
cmux ls
cmux start <existing-branch>
cmux cd <existing-branch>
bash .cmux/setup

示例：

cmux start eng-1296-onboarding-v2-question-view-context-dedupe
cmux cd eng-1296-onboarding-v2-question-view-context-dedupe
bash .cmux/setup
新分支 + 新 Worktree
cd /path/to/repo
cmux new <new-branch>
cmux cd <new-branch>
bash .cmux/setup

示例：

cmux new codex/pr1-onboarding-demographics-profile-report
cmux cd codex/pr1-onboarding-demographics-profile-report
bash .cmux/setup

设置钩子工作流

  1. 生成项目专用的设置钩子：
cmux init
  1. 如有需要，重新生成：
cmux init --replace
  1. 提交 .cmux/setup，以便后续 worktree 自动继承设置。
  2. 每次运行 cmux new 和 cmux start 后都运行设置：
bash .cmux/setup

分支和路径行为

  • 将 new 视为“新分支 + 新 worktree”。
  • 将 start 视为“复用现有 worktree／会话”。
  • 在嵌套布局中，worktree 路径位于 .worktrees/<branch>/ 下。
  • 预期分支名称会经过清理（例如，feature/foo 会变成路径名 feature-foo）。
  • 一个分支一次只能在一个 worktree 中检出。

安全规则

  • 执行 cmux rm --all 前请征求确认。
  • 执行 cmux rm --force 前请征求确认。
  • 除非用户要求完整合并提交，否则优先使用 cmux merge <branch> --squash，以保持历史记录简洁。
  • 合并前确保 worktree 中的更改已提交。
  • 合并成功后移除已完成的 worktree，以减少分支／worktree 漂移。

故障排除

  • Not in a git repo：切换到仓库根目录，然后重试。
  • Worktree not found：运行 cmux ls，然后选择正确的分支，或使用 cmux new <branch> 创建分支。
  • Branch already checked out：运行 cmux ls 并使用现有 worktree 路径。
  • 合并因存在未提交更改而受阻：在 worktree 中提交或暂存更改，然后重试。
  • 移除因工作树存在未提交更改而受阻：先清理工作树，或仅在获得明确确认后使用 cmux rm --force。
  • Expo Router 意外显示“Welcome to Expo”：终止过时的 expo/metro 进程，从目标 worktree 使用 --clear 重启，并重新打开开发客户端。
  • 在 worktree 中进行移动端开发：
cd apps/mobile
npm run dev -- --clear --host lan

评论

支持 Markdown