cmux-and-worktrees

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CMX and Worktrees

CMX 和 Worktrees

Run concurrent coding sessions safely by isolating each task in a git worktree.

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

Non-Negotiable Command Rule

不可协商的命令规则

Use
```
cmx
```
for every command in this skill.
Do not substitute
```
cmux
```
in normal operation.
If
```
cmx
```
fails, check alias availability with
```
type cmx
```
before taking any fallback action.

本技能中的所有命令都使用
```
cmx
```
。
常规操作中不要替换为
```
cmux
```
。
如果
```
cmx
```
执行失败，在采取任何备用操作前，先使用
```
type cmx
```
检查别名是否可用。

Preflight

预检查

Verify current directory is inside a git repo:

bash

git rev-parse --is-inside-work-tree

Verify
```
cmx
```
is available:

bash

type cmx

Ensure worktrees are ignored in git:

bash

rg -n '^\.worktrees/$' .gitignore || echo '.worktrees/' >> .gitignore

Inspect active worktrees:

bash

cmx ls

bash

git rev-parse --is-inside-work-tree

验证
```
cmx
```
是否可用：

bash

type cmx

确保worktrees在git中被忽略：

bash

rg -n '^\.worktrees/$' .gitignore || echo '.worktrees/' >> .gitignore

查看活跃的worktrees：

bash

cmx ls

Core Commands

核心命令

Create new isolated task:
```
cmx new <branch>
```
Resume existing task:
```
cmx start <branch>
```
Jump to worktree:
```
cmx cd [branch]
```
List worktrees:
```
cmx ls
```
Merge into primary checkout:
```
cmx merge [branch] [--squash]
```
Remove worktree + branch:
```
cmx rm [branch | --all] [--force]
```
Generate setup hook:
```
cmx init [--replace]
```

Show/set layout config:

cmx config

cmx config set layout <nested|outer-nested|sibling> [--global]

Update tool:
```
cmx update
```
Show version:
```
cmx version
```

创建新的隔离任务：
```
cmx new <branch>
```
恢复现有任务：
```
cmx start <branch>
```
切换到worktree：
```
cmx cd [branch]
```
列出worktrees：
```
cmx ls
```
合并到主工作区：
```
cmx merge [branch] [--squash]
```
删除worktree和分支：
```
cmx rm [branch | --all] [--force]
```
生成设置钩子：
```
cmx init [--replace]
```

查看/设置布局配置：

cmx config

cmx config set layout <nested|outer-nested|sibling> [--global]

更新工具：
```
cmx update
```
查看版本：
```
cmx version
```

Standard Workflow

标准工作流程

Start feature work:

bash

cmx new feature-auth

Start urgent fix in parallel:

bash

cmx new fix-payments

Merge and clean up bugfix:

bash

cmx merge fix-payments --squash
git commit -m "fix(payments): resolve checkout bug"
cmx rm fix-payments

Resume feature:

bash

cmx start feature-auth

开始功能开发：

bash

cmx new feature-auth

并行开始紧急修复：

bash

cmx new fix-payments

合并并清理bug修复：

bash

cmx merge fix-payments --squash
git commit -m "fix(payments): resolve checkout bug"
cmx rm fix-payments

恢复功能开发：

bash

cmx start feature-auth

Setup Hook Workflow

设置钩子工作流程

Generate a project-specific setup hook:

bash

cmx init

If needed, regenerate:

bash

cmx init --replace

Commit
```
.cmux/setup
```
so future worktrees inherit setup automatically.

生成项目专属的设置钩子：

bash

cmx init

如有需要，重新生成：

bash

cmx init --replace

提交
```
.cmux/setup
```
，以便后续worktree自动继承设置。

Branch and Path Behavior

分支和路径行为

Treat
```
new
```
as "new branch + new worktree".
Treat
```
start
```
as "reuse existing worktree/session".
Expect worktree paths under
```
.worktrees/<branch>/
```
in nested layout.
Expect branch sanitization (e.g.,
```
feature/foo
```
becomes
```
feature-foo
```
path name).

```
new
```
操作表示“新建分支 + 新建worktree”。
```
start
```
操作表示“复用现有worktree/会话”。
在嵌套布局中，worktree路径位于
```
.worktrees/<branch>/
```
下。
分支名称会被标准化（例如，
```
feature/foo
```
会变为
```
feature-foo
```
路径名）。

Safety Rules

安全规则

Ask for confirmation before
```
cmx rm --all
```
.
Ask for confirmation before
```
cmx rm --force
```
.
Prefer
```
cmx merge <branch> --squash
```
for compact history unless user requests full merge commits.
Ensure worktree changes are committed before merging.
Remove finished worktrees after successful merge to reduce branch/worktree drift.

执行
```
cmx rm --all
```
前需确认。
执行
```
cmx rm --force
```
前需确认。
除非用户要求完整合并提交，否则优先使用
```
cmx merge <branch> --squash
```
以保持提交历史简洁。
合并前确保worktree中的更改已提交。
成功合并后删除已完成的worktree，以减少分支/worktree混乱。

Troubleshooting

故障排除

```
Not in a git repo
```
: move to repo root, then rerun.
```
Worktree not found
```
: run
```
cmx ls
```
, then choose correct branch or create with
```
cmx new <branch>
```
.
Merge blocked by uncommitted changes: commit or stash inside the worktree, then retry.
Remove blocked by dirty tree: clean state first, or use
```
cmx rm --force
```
only with explicit confirmation.

```
Not in a git repo
```
：切换到仓库根目录后重新运行。
```
Worktree not found
```
：运行
```
cmx ls
```
，然后选择正确的分支或使用
```
cmx new <branch>
```
创建。
合并因未提交更改被阻止：在worktree中提交或暂存更改后重试。
删除因工作区未清理被阻止：先清理状态，或仅在明确确认后使用
```
cmx rm --force
```
。