worktree

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

worktree — Isolated Session & Branching Engine

worktree — 隔离会话与分支引擎

Operating Invariants

运行约束

  • Path Isolation: Confine all branch edits, shell commands, and test executions strictly within
    .agents/worktree/<branch>
    ; forbid modifying root repository files from a worktree session.
  • Dirty Tree Breaker: Verify working tree cleanliness via
    git status --porcelain
    before deleting a worktree; forbid deleting worktrees containing uncommitted modifications.
  • Pre-Mutation Gate: Stage worktree creation or removal in Canonical Changeset format and halt turn immediately; forbid executing worktree mutations on disk without affirmative human authorization.
  • 路径隔离:将所有分支编辑、Shell 命令和测试执行严格限制在
    .agents/worktree/<branch>
    内;禁止从 worktree 会话修改根仓库文件。
  • 脏工作区中断机制:删除 worktree 前,通过
    git status --porcelain
    验证工作区是否干净;禁止删除包含未提交修改的 worktree。
  • 变更前门禁:以 Canonical Changeset 格式暂存 worktree 的创建或删除操作,并立即中止当前轮次;未经明确的人工授权,禁止在磁盘上执行 worktree 变更。

Domain Rubric

领域规范

1. Naming & Storage Conventions

1. 命名与存储约定

  • <branch>
    : Strictly format as
    <type>/<slug>
    (
    feat/
    ,
    fix/
    ,
    refactor/
    ,
    chore/
    ,
    test/
    ).
  • <path>
    : Dedicated path strictly under
    .agents/worktree/<branch>
    .
  • Privacy Anchor: Root
    .gitignore
    must contain
    .agents/worktree/
    .
  • <branch>
    :严格使用
    <type>/<slug>
    格式(
    feat/
    、
    fix/
    、
    refactor/
    、
    chore/
    、
    test/
    )。
  • <path>
    :必须是严格位于
    .agents/worktree/<branch>
    下的专用路径。
  • 隐私锚点:根目录的
    .gitignore
    必须包含
    .agents/worktree/
    。

2. Supported Worktree Operations

2. 支持的 Worktree 操作

  • [CREATE]
    : Add a new worktree branch checked out at target path.
  • [DELETE]
    : Remove worktree directory and prune git administrative metadata.
  • [LIST]
    : Inspect active worktrees and associated branches.
  • [CREATE]
    :在目标路径添加并检出一个新的 worktree 分支。
  • [DELETE]
    :删除 worktree 目录并清理 Git 管理元数据。
  • [LIST]
    :查看活动 worktree 及其关联分支。

Canonical Output Contract

Canonical Output Contract

text
undefined
text
undefined

Changeset: Git Worktree <Action>

Changeset: Git Worktree <Action>

-- .agents/worktree/<branch>/     
-- [<ACTION>] <Worktree operation summary>.
Summary: 1 worktree affected (<branch>).
undefined
-- .agents/worktree/<branch>/     
-- [<ACTION>] <Worktree operation summary>.
Summary: 1 worktree affected (<branch>).
undefined

Execution Protocol

执行协议

Phase 1: Pre-flight & Collision Audit

阶段 1:预检与冲突审计

  1. For create: Inspect
    git worktree list
    and verify no branch or directory collision exists.
  2. For delete: Inspect
    git status --porcelain
    inside target
    <path>
    . If dirty, halt immediately and report uncommitted files.
  3. For list: Run
    git worktree list
    and present active worktrees, halting turn immediately.
  1. 对于 create:检查
    git worktree list
    ,确认不存在分支或目录冲突。
  2. 对于 delete:在目标
    <path>
    内执行
    git status --porcelain
    。如果工作区存在未提交修改,立即中止并报告未提交文件。
  3. 对于 list:执行
    git worktree list
    并展示活动 worktree,随后立即中止当前轮次。

Phase 2: Staging & Authorization Gate

阶段 2:暂存与授权门禁

  1. Stage the planned worktree modification in Canonical Changeset format.
  2. Present the staging summary and halt turn immediately. Never execute git mutations without affirmative authorization.
  1. 使用 Canonical Changeset 格式暂存计划执行的 worktree 修改。
  2. 展示暂存摘要并立即中止当前轮次。未经明确授权,绝不执行 Git 变更。

Phase 3: Atomic Execution & Handoff

阶段 3:原子执行与交付

  1. On approval, execute the required operation:
    • Create:
      git worktree add <path> -b <branch> <base_ref>
    • Delete:
      git worktree remove <path> && git worktree prune
  2. Report operation completed with the absolute workspace path for IDE navigation.
  1. 获得批准后,执行所需操作:
    • Create:
      git worktree add <path> -b <branch> <base_ref>
    • Delete:
      git worktree remove <path> && git worktree prune
  2. 报告操作已完成,并提供可供 IDE 导航的绝对工作区路径。