Back to Details

using-git-worktrees

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

使用 Git 工作樹

Using Git Worktrees

概述

Overview

Git 工作樹建立共用相同儲存庫的獨立工作區，允許同時在多個分支上工作而無需切換。
**核心原則：**系統的目錄選擇+安全驗證=可靠隔離。
開始時聲明：“我正在使用 using-git-worktrees 技能來設置隔離的工作區。”
Git worktrees establish independent workspaces that share the same repository, allowing you to work on multiple branches simultaneously without switching.
Core Principle: System directory selection + security verification = reliable isolation.
Declaration to start: "I'm using the using-git-worktrees skill to set up an isolated workspace."

目錄選擇過程

Directory Selection Process

請遵循以下優先順序：
Please follow the following priority order:

1.檢查現有目錄

1. Check Existing Directories

bash
undefined
bash
undefined

Check in priority order

Check in priority order

ls -d .worktrees 2>/dev/null # Preferred (hidden) ls -d worktrees 2>/dev/null # Alternative

**如果找到：** 使用該目錄。如果兩者都存在，`.worktrees`獲勝。
ls -d .worktrees 2>/dev/null # Preferred (hidden) ls -d worktrees 2>/dev/null # Alternative

**If found:** Use that directory. If both exist, `.worktrees` takes precedence.

2.檢查CLAUDE.md

2. Check CLAUDE.md

bash
grep -i "worktree.*director" CLAUDE.md 2>/dev/null
若指定偏好： 無需詢問即可使用。
bash
grep -i "worktree.*director" CLAUDE.md 2>/dev/null
If preference is specified: Use it without asking.

3.詢問用戶

3. Ask the User

如果不存在目錄且沒有CLAUDE.md 首選項：
No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?
If no directory exists and there's no preference in CLAUDE.md:
No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

安全驗證

Security Verification

對於項目本地目錄（.worktrees 或 worktrees）

For project-local directories (.worktrees or worktrees)

在建立工作樹之前必須驗證目錄是否被忽略：
bash
undefined
Must verify the directory is ignored before creating the worktree:
bash
undefined

Check if directory is ignored (respects local, global, and system gitignore)

Check if directory is ignored (respects local, global, and system gitignore)

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

**如果不忽略：**

根據傑西的規則“立即修復損壞的東西”：
1. 將適當的行加入 .gitignore
2. 提交更改
3. 繼續創建工作樹

**為什麼重要：** 防止意外地將工作樹內容提交到儲存庫。
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

**If not ignored:**

Follow Jesse's rule "Fix broken things immediately":
1. Add the appropriate line to .gitignore
2. Commit the changes
3. Proceed to create the worktree

**Why it matters:** Prevent accidentally committing worktree content to the repository.

對於全域目錄（~/.config/superpowers/worktrees）

For global directories (~/.config/superpowers/worktrees)

耗盡.gitignore 驗證 - 完全在專案之外。
No need for .gitignore verification - completely outside the project.

創作步驟

Creation Steps

1. 檢測項目名稱

1. Detect Project Name

bash
project=$(basename "$(git rev-parse --show-toplevel)")
bash
project=$(basename "$(git rev-parse --show-toplevel)")

2. 創建工作樹

2. Create Worktree

bash
undefined
bash
undefined

Determine full path

Determine full path

case $LOCATION in .worktrees|worktrees) path="$LOCATION/$BRANCH_NAME" ;; /.config/superpowers/worktrees/*) path="/.config/superpowers/worktrees/$project/$BRANCH_NAME" ;; esac
case $LOCATION in .worktrees|worktrees) path="$LOCATION/$BRANCH_NAME" ;; /.config/superpowers/worktrees/*) path="/.config/superpowers/worktrees/$project/$BRANCH_NAME" ;; esac

Create worktree with new branch

Create worktree with new branch

git worktree add "$path" -b "$BRANCH_NAME" cd "$path"
undefined
git worktree add "$path" -b "$BRANCH_NAME" cd "$path"
undefined

3. 運行專案設定

3. Run Project Setup

自動偵測並運行適當的設定：
bash
undefined
Automatically detect and run appropriate setup:
bash
undefined

Node.js

Node.js

if [ -f package.json ]; then npm install; fi
if [ -f package.json ]; then npm install; fi

Rust

Rust

if [ -f Cargo.toml ]; then cargo build; fi
if [ -f Cargo.toml ]; then cargo build; fi

Python

Python

if [ -f requirements.txt ]; then pip install -r requirements.txt; fi if [ -f pyproject.toml ]; then poetry install; fi
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi if [ -f pyproject.toml ]; then poetry install; fi

Go

Go

if [ -f go.mod ]; then go mod download; fi
undefined
if [ -f go.mod ]; then go mod download; fi
undefined

4. 驗證乾淨的基線

4. Verify Clean Baseline

執行測試以確保工作樹乾淨啟動：
bash
undefined
Run tests to ensure the worktree starts clean:
bash
undefined

Examples - use project-appropriate command

Examples - use project-appropriate command

npm test cargo test pytest go test ./...

**如果測試失敗：** 報告失敗，詢問是否繼續或調查。

**如果測試通過：** 報告準備就緒。
npm test cargo test pytest go test ./...

**If tests fail:** Report the failure and ask whether to continue or investigate.

**If tests pass:** Report readiness.

5. 檢舉地點

5. Announce Location

Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

快速參考

Quick Reference

情況行動
.worktrees/
存在		使用它（驗證忽略）
worktrees/
存在		使用它（驗證忽略）
兩者都存在使用
.worktrees/
兩者都不存在檢查CLAUDE.md→詢問使用者
目錄不被忽略新增到 .gitignore + 提交
測試在基準期間失敗報告失敗+詢問
軟件包沒有.json/Cargo.toml跳過依賴安裝
ScenarioAction
.worktrees/
exists		Use it (verify ignored)
worktrees/
exists		Use it (verify ignored)
Both existUse 
.worktrees/
Neither existsCheck CLAUDE.md → Ask user
Directory not ignoredAdd to .gitignore + commit
Tests fail during baselineReport failure + ask
No package.json/Cargo.tomlSkip dependency installation

常見錯誤

Common Mistakes

跳過忽略驗證

Skipping Ignore Verification

  • 問題： 工作樹內容被跟蹤，污染 git 狀態
  • **修復：**始終使用
    git check-ignore
    在建立專案本機工作樹之前
  • Problem: Worktree content is tracked, polluting git status
  • Fix: Always use 
    git check-ignore
    before creating project-local worktrees

假設目錄位置

Assuming Directory Location

  • 問題： 造成不一致，違反專案約定
  • **修復：**遵循優先：現有>CLAUDE.md>詢問
  • Problem: Causes inconsistencies, violates project conventions
  • Fix: Follow priority: Existing > CLAUDE.md > Ask

繼續失敗的測試

Continuing with Failed Tests

  • 問題： 無法區分新錯誤和先前存在的問題
  • 修復： 報告失敗，獲得明確的許可才能繼續
  • Problem: Cannot distinguish new errors from pre-existing issues
  • Fix: Report failure, get explicit permission to continue

硬編碼設置命令

Hardcoding Setup Commands

  • 問題： 使用不同工具的專案中斷
  • **修復：**從項目文件中自動檢測（package.json等）
  • Problem: Breaks in projects using different tools
  • Fix: Auto-detect from project files (package.json, etc.)

示例工作流程

Example Workflow

You: I'm using the using-git-worktrees skill to set up an isolated workspace.

[Check .worktrees/ - exists]
[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]

Worktree ready at /Users/jesse/myproject/.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature
You: I'm using the using-git-worktrees skill to set up an isolated workspace.

[Check .worktrees/ - exists]
[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]

Worktree ready at /Users/jesse/myproject/.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature

危險信號

Red Flags

絕不：
  • 建立工作樹而不驗證它是否被忽略（專案本地）
  • 跳過基線測試驗證
  • 不詢問就繼續失敗的測試
  • 當目錄位置不明確時假定目錄位置
  • 跳過CLAUDE.md檢查
總是：
  • 遵循目錄優先： 現有 > CLAUDE.md > 詢問
  • 驗證專案本地的目錄被忽略
  • 自動偵測並運行專案設置
  • 驗證乾淨的測試基線
Never:
  • Create a worktree without verifying it's ignored (project-local)
  • Skip baseline test verification
  • Continue with failed tests without asking
  • Assume directory location when it's unclear
  • Skip CLAUDE.md check
Always:
  • Follow directory priority: Existing > CLAUDE.md > Ask
  • Verify project-local directories are ignored
  • Auto-detect and run project setup
  • Verify clean test baseline

一體化

Integration

調用者：
  • 腦力激盪（第 4 階段）- 當設計獲得批准並隨後實施時需要
  • 子代理驅動開發 - 執行任何任務之前需要
  • 執行計劃 - 執行任何任務之前需要
  • 任何需要獨立工作空間的技能
搭配：
  • 完成開發分支 - 工作完成後需要清理
Callers:
  • Brainstorm (Phase 4) - Required when design is approved and implementation follows
  • Sub-agent Driven Development - Required before executing any tasks
  • Execute Plan - Required before executing any tasks
  • Any skill that requires independent workspaces
Pair With:
  • Complete Development Branch - Required for cleanup after work is done