{"id":"d9b12889-2274-467a-bab3-b542d16ae5f6","shortId":"u4PeTM","kind":"skill","title":"using-git-worktrees","tagline":"当需要开始与当前工作区隔离的功能开发，或在执行实现计划之前使用——通过原生工具或 git worktree 回退机制确保隔离工作区存在","description":"# 使用 Git 工作树\n\n## 概述\n\n确保工作发生在隔离的工作区中。优先使用你的平台的原生 worktree 工具。仅在没有原生工具可用时，再回退到手动 git worktree。\n\n**核心原则：** 先检测现有隔离。然后用原生工具。再回退到 git。绝不与 harness 对抗。\n\n**开始时宣布：** \"我正在使用 using-git-worktrees 技能来建立一个隔离的工作区。\"\n\n## 步骤 0：检测现有隔离\n\n**创建任何东西之前，先检查你是否已经在一个隔离的工作区里。**\n\n```bash\nGIT_DIR=$(cd \"$(git rev-parse --git-dir)\" 2>/dev/null && pwd -P)\nGIT_COMMON=$(cd \"$(git rev-parse --git-common-dir)\" 2>/dev/null && pwd -P)\nBRANCH=$(git branch --show-current)\n```\n\n**Submodule 守卫：** 在 git submodule 内 `GIT_DIR != GIT_COMMON` 也为真。在判定\"已经在 worktree 内\"之前，先确认你不在 submodule 里：\n\n```bash\n# 如果这条命令返回路径，说明你在 submodule 里，不是 worktree —— 按普通仓库处理\ngit rev-parse --show-superproject-working-tree 2>/dev/null\n```\n\n**如果 `GIT_DIR != GIT_COMMON`（且不是 submodule）：** 你已经在一个 linked worktree 内。跳到步骤 3（项目设置）。**不要**再创建一个 worktree。\n\n按分支状态报告：\n\n- 在某个分支上：\"已经在隔离工作区 `<path>`，分支 `<name>`。\"\n- 分离 HEAD：\"已经在隔离工作区 `<path>`（分离 HEAD，由外部管理）。完成时需要创建分支。\"\n\n**如果 `GIT_DIR == GIT_COMMON`（或在 submodule 内）：** 你在一个普通的仓库检出里。\n\n用户是否已经在你的 instructions 里表明过 worktree 偏好？如果没有，创建 worktree 之前先征求同意：\n\n> \"你希望我搭一个隔离的 worktree 吗？它能保护你当前分支不被改动。\"\n\n如果用户已声明过偏好，直接遵循，不再询问。如果用户拒绝同意，原地工作并跳到步骤 3。\n\n## 步骤 1：创建隔离工作区\n\n**你有两种机制。按这个顺序尝试。**\n\n### 1a. 原生 Worktree 工具（首选）\n\n用户已经请求隔离工作区（步骤 0 已获同意）。你是否已经有创建 worktree 的方法？可能是名为 `EnterWorktree`、`WorktreeCreate` 的工具、`/worktree` 命令，或 `--worktree` 标志。如果有，用它，然后跳到步骤 3。\n\n原生工具自动处理目录放置、分支创建和清理。在你已经有原生工具的情况下使用 `git worktree add`，会创建你的 harness 看不到也无法管理的\"幻影状态\"。\n\n只有在没有原生 worktree 工具可用时，才进入步骤 1b。\n\n### 1b. Git Worktree 回退\n\n**只在步骤 1a 不适用时使用** —— 你没有可用的原生 worktree 工具。手动用 git 创建 worktree。\n\n#### 目录选择\n\n按以下优先级。明确的用户偏好始终优先于观察到的文件系统状态。\n\n1. **检查你的 instructions 里是否声明过 worktree 目录偏好。** 如果用户已指定，不再询问直接用。\n\n2. **检查是否存在项目本地的 worktree 目录：**\n\n   ```bash\n   ls -d .worktrees 2>/dev/null     # 首选（隐藏目录）\n   ls -d worktrees 2>/dev/null      # 备选\n   ```\n\n   找到就用。如果两者都存在，`.worktrees` 优先。\n\n3. **检查是否存在全局目录：**\n\n   ```bash\n   project=$(basename \"$(git rev-parse --show-toplevel)\")\n   ls -d ~/.config/superpowers/worktrees/$project 2>/dev/null\n   ```\n\n   找到就用（兼容老的全局路径）。\n\n4. **如果没有其他可参考的信息**，默认用项目根目录下的 `.worktrees/`。\n\n#### 安全验证（仅项目本地目录）\n\n**创建 worktree 前必须验证目录已被忽略：**\n\n```bash\ngit check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null\n```\n\n**如果未被忽略：** 添加到 .gitignore，提交该改动，然后继续。\n\n**为什么关键：** 防止 worktree 内容被意外提交到仓库。\n\n全局目录（`~/.config/superpowers/worktrees/`）无需验证。\n\n#### 创建工作树\n\n```bash\nproject=$(basename \"$(git rev-parse --show-toplevel)\")\n\n# 根据选定位置确定路径\n# 项目本地：path=\"$LOCATION/$BRANCH_NAME\"\n# 全局：path=\"~/.config/superpowers/worktrees/$project/$BRANCH_NAME\"\n\ngit worktree add \"$path\" -b \"$BRANCH_NAME\"\ncd \"$path\"\n```\n\n**沙盒回退：** 如果 `git worktree add` 因权限错误（沙盒拒绝）失败，告诉用户沙盒阻止了 worktree 创建，你将在当前目录原地工作。然后原地运行 setup 和基线测试。\n\n## 步骤 3：项目设置\n\n自动检测并运行相应的设置命令：\n\n```bash\n# Node.js\nif [ -f package.json ]; then npm install; fi\n\n# Rust\nif [ -f Cargo.toml ]; then cargo build; fi\n\n# Python\nif [ -f requirements.txt ]; then pip install -r requirements.txt; fi\nif [ -f pyproject.toml ]; then poetry install; fi\n\n# Go\nif [ -f go.mod ]; then go mod download; fi\n```\n\n## 步骤 4：验证基线干净\n\n运行测试确保工作区初始状态干净：\n\n```bash\n# 使用项目对应的命令\nnpm test / cargo test / pytest / go test ./...\n```\n\n**如果测试失败：** 报告失败，询问是继续还是排查。\n\n**如果测试通过：** 报告就绪。\n\n### 报告\n\n```\n工作树已就绪：<full-path>\n测试通过（<N> 个测试，0 个失败）\n准备实现 <feature-name>\n```\n\n## 快速参考\n\n| 情况 | 操作 |\n|------|------|\n| 已在 linked worktree 内 | 跳过创建（步骤 0） |\n| 在 submodule 内 | 按普通仓库处理（步骤 0 守卫） |\n| 有原生 worktree 工具 | 用它（步骤 1a） |\n| 没有原生工具 | git worktree 回退（步骤 1b） |\n| `.worktrees/` 存在 | 用它（验证已忽略） |\n| `worktrees/` 存在 | 用它（验证已忽略） |\n| 两者都存在 | 用 `.worktrees/` |\n| 都不存在 | 检查 instructions 文件，再默认 `.worktrees/` |\n| 全局路径存在 | 用它（向后兼容） |\n| 目录未被忽略 | 添加到 .gitignore + 提交 |\n| 创建时权限错误 | 沙盒回退，原地工作 |\n| 基线测试失败 | 报告失败 + 询问 |\n| 无 package.json/Cargo.toml | 跳过依赖安装 |\n\n## 常见错误\n\n### 与 harness 对抗\n\n- **问题：** 平台已经提供隔离的情况下还在用 `git worktree add`\n- **修复：** 步骤 0 检测现有隔离。步骤 1a 让位给原生工具。\n\n### 跳过检测\n\n- **问题：** 在已有的 worktree 内嵌套创建另一个 worktree\n- **修复：** 创建任何东西之前都先跑步骤 0\n\n### 跳过忽略验证\n\n- **问题：** worktree 内容被跟踪，污染 git status\n- **修复：** 创建项目本地 worktree 前始终使用 `git check-ignore`\n\n### 假设目录位置\n\n- **问题：** 造成不一致、违反项目约定\n- **修复：** 遵循优先级：现有目录 > 全局历史路径 > instructions 文件 > 默认\n\n### 带着失败的测试继续\n\n- **问题：** 无法区分新 bug 和已有问题\n- **修复：** 报告失败，获得明确许可后再继续\n\n## 红线\n\n**绝不：**\n\n- 步骤 0 已检测到现有隔离时还创建 worktree\n- 在已有原生 worktree 工具（如 `EnterWorktree`）的情况下还用 `git worktree add`。这是 #1 错误——有就用。\n- 跳过步骤 1a 直接跳到步骤 1b 的 git 命令\n- 不验证已忽略就创建项目本地 worktree\n- 跳过基线测试验证\n- 不询问就带着失败的测试继续\n\n**始终：**\n\n- 先跑步骤 0 检测\n- 优先原生工具，其次 git 回退\n- 遵循目录优先级：现有目录 > 全局历史路径 > instructions 文件 > 默认\n- 项目本地目录验证已忽略\n- 自动检测并运行项目设置\n- 验证测试基线干净\n\n## 集成\n\n**被以下技能调用：**\n\n- **brainstorming**（阶段 4）- 设计通过且需要实现时必需\n- **subagent-driven-development** - 执行任何任务前必需\n- **executing-plans** - 执行任何任务前必需\n- 任何需要隔离工作区的技能\n\n**配合使用：**\n\n- **finishing-a-development-branch** - 工作完成后清理时必需","tags":["using","git","worktrees","superpowers","jnmetacode","agent-skills","agentic-coding","ai-coding","chinese","claude-code","code-review","cursor"],"capabilities":["skill","source-jnmetacode","skill-using-git-worktrees","topic-agent-skills","topic-agentic-coding","topic-ai-coding","topic-chinese","topic-claude-code","topic-code-review","topic-cursor","topic-gemini-cli","topic-kiro","topic-mcp","topic-npm-package","topic-prompt-engineering"],"categories":["superpowers-zh"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/jnMetaCode/superpowers-zh/using-git-worktrees","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add jnMetaCode/superpowers-zh","source_repo":"https://github.com/jnMetaCode/superpowers-zh","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 3384 github stars · SKILL.md body (4,677 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:52:48.641Z","embedding":null,"createdAt":"2026-04-18T21:56:01.934Z","updatedAt":"2026-05-18T18:52:48.641Z","lastSeenAt":"2026-05-18T18:52:48.641Z","tsv":"'/.config/superpowers/worktrees':279,321,342 '/cargo.toml':504 '/dev/null':55,70,116,252,259,282,302,310 '/worktree':194 '0':39,185,439,451,457,517,530,568,597 '1':174,235,581 '1a':178,223,464,520,585 '1b':217,218,470,587 '2':54,69,115,243,251,258,281,301,309 '3':129,172,202,265,371 '4':285,418,616 'add':208,348,359,514,579 'b':350 'basenam':269,326 'bash':43,98,247,267,294,324,374,421 'brainstorm':614 'branch':73,75,338,344,351,633 'bug':560 'build':389 'cargo':388,425 'cargo.toml':386 'cd':46,60,353 'check':297,305,544 'check-ignor':296,304,543 'common':59,67,88,121,149 'current':78 'd':249,256,278 'develop':621,632 'dir':45,53,68,86,119,147 'download':415 'driven':620 'enterworktre':191,575 'execut':624 'executing-plan':623 'f':377,385,393,402,410 'fi':382,390,400,407,416 'finish':630 'finishing-a-development-branch':629 'git':3,8,12,21,27,35,44,47,52,58,61,66,74,82,85,87,106,118,120,146,148,206,219,229,270,295,303,327,346,357,466,512,536,542,577,589,601 'git-common-dir':65 'git-dir':51 'gitignor':313,493 'go':408,413,428 'go.mod':411 'har':29,210,508 'head':139,142 'ignor':298,306,545 'instal':381,397,406 'instruct':155,237,484,554,606 'link':125,446 'locat':337 'ls':248,255,277 'mod':414 'name':339,345,352 'node.js':375 'npm':380,423 'p':57,72 'package.json':378,503 'package.json/cargo.toml':502 'pars':50,64,109,273,330 'path':336,341,349,354 'pip':396 'plan':625 'poetri':405 'project':268,280,325,343 'pwd':56,71 'pyproject.toml':403 'pytest':427 'python':391 'q':299,307 'r':398 'requirements.txt':394,399 'rev':49,63,108,272,329 'rev-pars':48,62,107,271,328 'rust':383 'setup':368 'show':77,111,275,332 'show-curr':76 'show-superproject-working-tre':110 'show-toplevel':274,331 'skill' 'skill-using-git-worktrees' 'source-jnmetacode' 'status':537 'subag':619 'subagent-driven-develop':618 'submodul':79,83,96,101,123,151,453 'superproject':112 'test':424,426,429 'topic-agent-skills' 'topic-agentic-coding' 'topic-ai-coding' 'topic-chinese' 'topic-claude-code' 'topic-code-review' 'topic-cursor' 'topic-gemini-cli' 'topic-kiro' 'topic-mcp' 'topic-npm-package' 'topic-prompt-engineering' 'toplevel':276,333 'tree':114 'use':2,34 'using-git-worktre':1,33 'work':113 'worktre':4,9,17,22,36,92,104,126,133,157,161,164,180,188,197,207,214,220,226,231,239,245,250,257,263,288,292,300,308,318,347,358,364,447,460,467,471,475,481,487,513,525,527,533,540,570,572,578,592 'worktreecr':192 '不再询问':169 '不再询问直接用':242 '不是':103 '不要':131 '不询问就带着失败的测试继续':594 '不适用时使用':224 '不验证已忽略就创建项目本地':591 '与':507 '且不是':122 '两者都存在':479 '个失败':440 '个测试':438 '为什么关键':316 '之前':94 '之前先征求同意':162 '也为真':89 '仅在没有原生工具可用时':19 '仅项目本地目录':290 '任何需要隔离工作区的技能':627 '优先':264 '优先使用你的平台的原生':16 '优先原生工具':599 '会创建你的':209 '你在一个普通的仓库检出里':153 '你将在当前目录原地工作':366 '你已经在一个':124 '你希望我搭一个隔离的':163 '你是否已经有创建':187 '你有两种机制':176 '你没有可用的原生':225 '使用':11 '使用项目对应的命令':422 '修复':515,528,538,550,562 '假设目录位置':546 '偏好':158 '先检查你是否已经在一个隔离的工作区里':42 '先检测现有隔离':24 '先确认你不在':95 '先跑步骤':596 '全局':340 '全局历史路径':553,605 '全局目录':320 '全局路径存在':488 '其次':600 '兼容老的全局路径':284 '内':84,93,127,152,448,454 '内容被意外提交到仓库':319 '内容被跟踪':534 '内嵌套创建另一个':526 '再创建一个':132 '再回退到':26 '再回退到手动':20 '再默认':486 '准备实现':441 '分支':137 '分支创建和清理':204 '分离':138,141 '创建':160,230,291,365 '创建任何东西之前':41 '创建任何东西之前都先跑步骤':529 '创建工作树':323 '创建时权限错误':495 '创建隔离工作区':175 '创建项目本地':539 '前始终使用':541 '前必须验证目录已被忽略':293 '原地工作':497 '原地工作并跳到步骤':171 '原生':179 '原生工具自动处理目录放置':203 '只在步骤':222 '只有在没有原生':213 '可能是名为':190 '向后兼容':490 '吗':165 '告诉用户沙盒阻止了':363 '命令':195,590 '和基线测试':369 '和已有问题':561 '回退':221,468,602 '回退机制确保隔离工作区存在':10 '因权限错误':360 '在':81,452 '在你已经有原生工具的情况下使用':205 '在判定':90 '在已有原生':571 '在已有的':524 '在某个分支上':135 '基线测试失败':498 '备选':260 '失败':362 '如':574 '如果':117,145,356 '如果两者都存在':262 '如果有':199 '如果未被忽略':311 '如果没有':159 '如果没有其他可参考的信息':286 '如果测试失败':430 '如果测试通过':433 '如果用户已声明过偏好':167 '如果用户已指定':241 '如果用户拒绝同意':170 '如果这条命令返回路径':99 '始终':595 '存在':472,476 '它能保护你当前分支不被改动':166 '守卫':80,458 '安全验证':289 '完成时需要创建分支':144 '对抗':30,509 '工作完成后清理时必需':634 '工作树':13 '工作树已就绪':436 '工具':18,181,227,461,573 '工具可用时':215 '已在':445 '已检测到现有隔离时还创建':569 '已经在':91 '已经在隔离工作区':136,140 '已获同意':186 '带着失败的测试继续':557 '常见错误':506 '平台已经提供隔离的情况下还在用':511 '幻影状态':212 '开始时宣布':31 '当需要开始与当前工作区隔离的功能开发':5 '快速参考':442 '情况':443 '我正在使用':32 '或':196 '或在':150 '或在执行实现计划之前使用':6 '手动用':228 '才进入步骤':216 '执行任何任务前必需':622,626 '找到就用':261,283 '技能来建立一个隔离的工作区':37 '报告':435 '报告失败':431,499,563 '报告就绪':434 '按以下优先级':233 '按分支状态报告':134 '按普通仓库处理':105,455 '按这个顺序尝试':177 '提交':494 '提交该改动':314 '操作':444 '文件':485,555,607 '无':501 '无法区分新':559 '无需验证':322 '明确的用户偏好始终优先于观察到的文件系统状态':234 '有原生':459 '有就用':583 '标志':198 '核心原则':23 '根据选定位置确定路径':334 '检查':483 '检查你的':236 '检查是否存在全局目录':266 '检查是否存在项目本地的':244 '检测':598 '检测现有隔离':40,518 '概述':14 '步骤':38,173,184,370,417,450,456,463,469,516,519,567 '污染':535 '沙盒回退':355,496 '沙盒拒绝':361 '没有原生工具':465 '测试通过':437 '添加到':312,492 '然后原地运行':367 '然后用原生工具':25 '然后继续':315 '然后跳到步骤':201 '现有目录':552,604 '用':480 '用它':200,462,473,477,489 '用户已经请求隔离工作区':183 '用户是否已经在你的':154 '由外部管理':143 '的':588 '的工具':193 '的情况下还用':576 '的方法':189 '目录':246 '目录偏好':240 '目录未被忽略':491 '目录选择':232 '直接跳到步骤':586 '直接遵循':168 '看不到也无法管理的':211 '确保工作发生在隔离的工作区中':15 '红线':565 '绝不':566 '绝不与':28 '自动检测并运行相应的设置命令':373 '自动检测并运行项目设置':610 '获得明确许可后再继续':564 '被以下技能调用':613 '让位给原生工具':521 '设计通过且需要实现时必需':617 '询问':500 '询问是继续还是排查':432 '说明你在':100 '跳到步骤':128 '跳过依赖安装':505 '跳过创建':449 '跳过基线测试验证':593 '跳过忽略验证':531 '跳过检测':522 '跳过步骤':584 '运行测试确保工作区初始状态干净':420 '这是':580 '违反项目约定':549 '通过原生工具或':7 '造成不一致':548 '遵循优先级':551 '遵循目录优先级':603 '都不存在':482 '配合使用':628 '里':97,102 '里是否声明过':238 '里表明过':156 '错误':582 '问题':510,523,532,547,558 '防止':317 '阶段':615 '隐藏目录':254 '集成':612 '项目本地':335 '项目本地目录验证已忽略':609 '项目设置':130,372 '首选':182,253 '验证基线干净':419 '验证已忽略':474,478 '验证测试基线干净':611 '默认':556,608 '默认用项目根目录下的':287","prices":[{"id":"59eb9acd-9603-4502-8f9c-57dfa4fc54f0","listingId":"d9b12889-2274-467a-bab3-b542d16ae5f6","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"jnMetaCode","category":"superpowers-zh","install_from":"skills.sh"},"createdAt":"2026-04-18T21:56:01.934Z"}],"sources":[{"listingId":"d9b12889-2274-467a-bab3-b542d16ae5f6","source":"github","sourceId":"jnMetaCode/superpowers-zh/using-git-worktrees","sourceUrl":"https://github.com/jnMetaCode/superpowers-zh/tree/main/skills/using-git-worktrees","isPrimary":false,"firstSeenAt":"2026-04-18T21:56:01.934Z","lastSeenAt":"2026-05-18T18:52:48.641Z"}],"details":{"listingId":"d9b12889-2274-467a-bab3-b542d16ae5f6","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"jnMetaCode","slug":"using-git-worktrees","github":{"repo":"jnMetaCode/superpowers-zh","stars":3384,"topics":["agent-skills","agentic-coding","ai-coding","chinese","claude-code","code-review","cursor","gemini-cli","kiro","mcp","npm-package","prompt-engineering","skills","superpowers","tdd","trae"],"license":"mit","html_url":"https://github.com/jnMetaCode/superpowers-zh","pushed_at":"2026-05-18T16:40:33Z","description":"🦸 AI 编程超能力 · 中文增强版 — superpowers（116k+ ⭐）完整汉化 + 6 个中国原创 skills，让 Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI 等 16 款 AI 编程工具真正会干活","skill_md_sha":"0e6d413b6a7c2c5de3b5b2036300baf0f739f5ad","skill_md_path":"skills/using-git-worktrees/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/jnMetaCode/superpowers-zh/tree/main/skills/using-git-worktrees"},"layout":"multi","source":"github","category":"superpowers-zh","frontmatter":{"name":"using-git-worktrees","description":"当需要开始与当前工作区隔离的功能开发，或在执行实现计划之前使用——通过原生工具或 git worktree 回退机制确保隔离工作区存在"},"skills_sh_url":"https://skills.sh/jnMetaCode/superpowers-zh/using-git-worktrees"},"updatedAt":"2026-05-18T18:52:48.641Z"}}