`ce-worktree`

在 .worktrees/<branch> 下创建一个 git 工作树，并使用 git worktree add 单独无法处理的特定于分支的设置 — .env 复制、具有分支感知安全性的开发工具信任、gitignore 管理。

ce-worktree 是隔离结账技能。普通 git worktree add 创建工作树，但跳过大多数项目需要的每次签出设置：不遵循 .env 文件，mise/direnv 配置不受信任（因此钩子会阻止提示），并且 .worktrees/ 不会被 gitignored。此技能可以为您处理这些问题，并使用安全规则来防止不受信任的 PR 审查分支自动信任用户未见过的 .envrc 内容。

TL;DR

问题	回答
它有什么作用？	创建 `.worktrees/<branch>`，从主存储库复制 `.env*`，使用安全规则信任 `mise`/`direnv` 配置，将 `.worktrees` 添加到 `.gitignore`
何时使用它	审查 PR，同时保持主要结帐自由；并行运行多个功能；保持默认分支干净
它生产什么	位于 `.worktrees/<branch-name>` 的工作树准备好 `cd` 进入
跳过时间	适合主结账分支的单任务工作

＃＃问题

简单的 git worktree add 给你留下一棵工作树，它已经“技术上”检查过，但实际上已损坏：

.env* 文件不遵循 — 新工作树没有 .env，因此开发服务器会失败或回退到脆弱的默认值
mise/direnv 配置不受信任 — 每个 cd 进入工作树都会在信任提示下阻塞，从而减慢代理流程
审查分支上的危险 .envrc 自动信任 - 在 PR 审查工作树上天真地运行 direnv allow 会信任贡献者放入 .envrc 中的任何内容，这可能是 direnv 无法验证的源文件
.worktrees/ 不在 .gitignore 中 - 主检出中的每个 git status 显示工作树目录为未跟踪
主结帐受到干扰 — git worktree add origin/<branch> 可能最终会以用户意想不到的方式改变主结帐的状态
神秘的自动生成的分支名称，例如某些工具中的 worktree-jolly-beaming-raven ，模糊了工作树的实际用途

解决方案

ce-worktree 将工作树创建作为结构化通道运行：

在 .worktrees/<branch> 创建工作树（位置一致，绝不随机）
复制 .env、.env.local、.env.test 等（跳过 .env.example）
信任具有分支感知安全规则的 mise/direnv 配置 - 永远不会自动信任修改后的配置，永远不会在 PR 审查分支上使用 direnv allow
将 .worktrees 添加到 .gitignore（如果尚未存在）
获取 from-branch 而不是检查它 - 主存储库保持不受干扰
为上游调用者提供清晰的命名指导（feat/crowd-sniff、fix/email-validation，从不随机）

是什么让它如此新颖

1. 分支感知开发工具信任

对 mise/direnv 的信任按基本分支划分：

基地支部	行为
可信基础 (`main`、`develop`、`dev`、`trunk`、`staging`、`release/*`)	与该分支进行比较的配置；未更改的配置自动信任； `direnv allow` 允许
其他分支（专题、公关审查）	与默认分支进行比较的配置； `direnv allow` 无论如何都会跳过，因为 `.envrc` 可以源文件 direnv 无法验证

这种分裂的存在是因为审查分支通常包含来自外部贡献者的代码。自动信任他们的 .envrc 与自动运行他们的安装脚本是同样的错误 - 你不会，所以技能不会。

修改后的配置永远不会被自动信任。 当配置与基础配置不同时，技能会打印手动信任命令并等待用户首先查看差异。

2. `.env*` 传播并跳过 `.env.example`

大多数项目需要工作树中的 .env、.env.local、.env.test 等来运行任何内容。该技能从主存储库复制所有 .env* 文件，除了 .env.example （这是已提交的模板，而不是用户的本地机密）。创建后，工作树可以运行依赖于环境状态的开发服务器、测试或脚本，而无需手动设置。

3.不打扰主要结账

具有远程引用的 git worktree add 的行为有所不同，具体取决于本地分支是否存在。普通使用可能会意外地检查主存储库中的某些内容，或者因令人困惑的错误而失败。此技能获取 from-branch 而不是检查它 - 新的工作树是从远程引用创建的，但主要检查保持在原来的位置。

4.一致位置：`.worktrees/<branch>`

工作树转到 .worktrees/<branch> — 无一例外。可预测 cd 快捷方式、可预测清理、可预测扫描工作树的工具。带斜杠的分支名称 (feat/login) 成为所有主要文件系统都支持的目录路径 (.worktrees/feat/login)。

5. `.worktrees` 的自动-`.gitignore`

如果 .worktrees 尚未存在于 .gitignore 中，则该技能会将其添加。如果没有这个，主结帐中的每个 git status 都会将工作树目录显示为嘈杂的未跟踪条目。有了它，该目录对于主结帐中的 git 操作是不可见的。

6. 上游调用者的命名指南

当 /ce-work 或 /ce-code-review 调用此技能时，它们会传递从工作描述派生的有意义的分支名称（feat/crowd-sniff、fix/email-validation）。该技能明确不鼓励自动生成的神秘名称 - 它们掩盖了工作树的用途，并使以后的清理变得更加困难。

7. 没有用于读取/列出/删除的包装器 - 只需使用 `git`

其他工作树操作（列表、删除、切换）不会获得包装器。该技能明确告诉您直接使用 git worktree list、git worktree remove .worktrees/<branch>、cd .worktrees/<branch>、cd "$(git rev-parse --show-toplevel)"。包装裸 git 命令不会增加任何价值，还会增加维护负担——技能集中在设置很重要的部分。

简单示例

您正在开始开发通知静音功能，并希望将其与您的主要结账功能（该功能正在进行中）隔离。您调用 /ce-worktree feat/notification-mute。

该技能运行 bash scripts/worktree-manager.sh create feat/notification-mute。默认值：from-branch 是 origin/main。从获取的 origin/main 创建 .worktrees/feat/notification-mute。复制您的 .env、.env.local、.env.test。检测到您有 .mise.toml 与 main 匹配；自动信任，因为基础分支是 main 并且配置未更改。 .worktrees 已在您的 .gitignore 中，因此无需编辑。

输出：

创建工作树：.worktrees/feat/notification-mute
复制的 .env 文件：.env、.env.local、.env.test
可信 .mise.toml（匹配 main，允许自动信任）

切换方式： cd .worktrees/feat/notification-mute

您cd .worktrees/feat/notification-mute，运行bin/dev，然后开始工作 - 没有环境设置，没有信任提示，不会干扰主结账中的其他功能。

何时去实现它

在以下情况下使用 ce-worktree：

您正在审查 PR，并希望保持主要结帐免费以用于正在进行的工作
您正在并行运行多个功能，并且不想通过 git checkout 进行上下文切换
您希望保持默认分支不受正在进行状态的影响
技能（ce-work、ce-code-review）提供工作树作为选项

在以下情况下跳过 ce-worktree：

该工作是单任务，适合主结帐中的一个分支 - 工作树开销超过产量
你已经在工作树中 - 嵌套工作树不是该技能设计的目的
存储库没有 .env 文件或开发工具配置 - 简单的 git worktree add 就足够了

用作工作流程的一部分

ce-worktree 从链技能中调用作为其并行隔离选项：

/ce-work 阶段 1.2 — 开始工作时，用户可以在主结账中选择工作树（推荐用于并行功能）而不是分支
/ce-code-review — 用于在单独结账时与浏览器测试同时审查 PR
/ce-debug — 在调查除当前分支之外的分支上的 bug 且不影响正在进行的工作时

上游调用者传递有意义的分支名称；该技能需要 feat/...、fix/...、refactor/... 形状 - 而不是自动生成的随机名称。

使用独立版

直接调用：

/ce-worktree feat/notification-mute — 从默认分支创建
/ce-worktree fix/email-validation develop — 从不同的基础创建

其他工作树操作（列表、删除、切换）直接使用 git ：

git worktree list                          # list worktrees
git worktree remove .worktrees/<branch>    # remove a worktree
cd .worktrees/<branch>                     # switch to a worktree
cd "$(git rev-parse --show-toplevel)"      # return to main checkout

要将 .env* 复制到没有它们创建的现有工作树中，请从主存储库运行（而不是从工作树内部运行，因为带有斜杠的分支名称会混淆相对路径）：

cp .env* .worktrees/<branch>/

＃＃参考

论证	效果
`<branch-name>`	`<branch-name>`从默认分支创建工作树
`<branch-name> <from-branch>`	从指定的基创建工作树

默认值：

from-branch 默认为 origin 的默认分支（或者 main 如果无法解析）
新分支在 origin/<from-branch> 创建（如果远程不可用，则在本地引用创建）

＃＃常问问题

为什么需要单独的工作树技能而不只是 git worktree add？ 因为每次结帐设置很重要 - .env 复制、mise/direnv 信任、.gitignore 管理。普通的 git worktree add 会给你留下一棵无法运行的树。

为什么在审核分支上跳过 direnv allow？ 因为 .envrc 可以获取 direnv 未验证的其他文件。自动信任外部贡献者的 .envrc 与自动运行其安装脚本是同样的错误。该技能会在检查分支上跳过 direnv allow 并打印手动命令 - 您检查差异，然后在适当的情况下信任。

如果创建工作树时没有 .env* 文件怎么办？ 从主存储库运行 cp .env* .worktrees/<branch>/ （不是从工作树内部运行，因为分支名称通常包含斜杠，会混淆内部的相对路径）。

如何清理工作树？ cd "$(git rev-parse --show-toplevel)" 离开工作树，然后 git worktree remove .worktrees/<branch>。如果分支在上游被删除， /ce-clean-gone-branches 会一起处理工作树和分支清理。

为什么是 .worktrees/<branch> 而不是其他地方？ 可预测性。扫描工作树、制表符补全、分支到路径查找的工具都受益于一个规范位置。该目录是 gitignored，因此不会污染 git 状态。

它适用于远程尚不存在的分支吗？ 是的 - 新分支是在解析的基础引用本地创建的。该技能会获取当前的 origin/<from-branch> ，但不需要新的分支名称已存在于远程设备上。

另请参阅

/ce-work — 当用户为并行功能选择工作树模式时，在阶段 1.2 调用此技能
/ce-code-review — 建议与浏览器测试同时进行审查的工作树
/ce-clean-gone-branches — 当远程跟踪分支消失时一起清理工作树和分支

ce-worktree