首頁全景圖學習路線

name	`using-git-worktrees`
description (EN)	Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
說明 (繁中)	當開始需要與目前工作區隔離的功能工作，或在執行實作計畫之前使用 —— 透過原生工具或 git worktree 備援方式確保有隔離的工作區

using-git-worktrees

開工先開一個隔離的 git worktree，主分支不被打擾。

Using Git Worktrees

使用 Git Worktrees

Overview

總覽

Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.

確保工作在隔離的工作區中進行。優先使用你平台的原生 worktree 工具。只有在沒有原生工具可用時，才改用手動 git worktree。

Core principle: Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.

核心原則： 先偵測現有的隔離狀態。再用原生工具。最後才回到 git。永遠不要對抗 harness。

Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."

開始時宣告： 「我正使用 using-git-worktrees 技能來設定隔離的工作區。」

Step 0: Detect Existing Isolation

第 0 步：偵測現有的隔離狀態

Before creating anything, check if you are already in an isolated workspace.

在建立任何東西之前，檢查你是否已在隔離的工作區中。

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)

Submodule guard: GIT_DIR != GIT_COMMON is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:

子模組防護： GIT_DIR != GIT_COMMON 在 git 子模組內部也成立。在得出「已在 worktree 中」的結論之前，先確認你不位於子模組中：

# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
git rev-parse --show-superproject-working-tree 2>/dev/null

# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
git rev-parse --show-superproject-working-tree 2>/dev/null

If GIT_DIR != GIT_COMMON (and not a submodule): You are already in a linked worktree. Skip to Step 2 (Project Setup). Do NOT create another worktree.

如果 GIT_DIR != GIT_COMMON（且不是子模組）： 你已在一個連結的 worktree 中。跳到第 2 步（專案設定）。不要再建立 worktree。

Report with branch state: - On a branch: "Already in isolated workspace at <path> on branch <name>." - Detached HEAD: "Already in isolated workspace at <path> (detached HEAD, externally managed). Branch creation needed at finish time."

回報分支狀態： - 在分支上：「已位於隔離工作區 <path>，分支 <name>。」 - Detached HEAD：「已位於隔離工作區 <path>（detached HEAD，外部管理）。完成時需建立分支。」

If GIT_DIR == GIT_COMMON (or in a submodule): You are in a normal repo checkout.

如果 GIT_DIR == GIT_COMMON（或在子模組中）： 你位於一般的 repo checkout 中。

Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:

使用者是否已在你的指令中表明其 worktree 偏好？如果沒有，在建立 worktree 前先徵求同意：

"Would you like me to set up an isolated worktree? It protects your current branch from changes."

「你要我設定一個隔離的 worktree 嗎？它會保護你目前的分支不受變更影響。」

Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 2.

尊重任何已宣告的偏好，不再詢問。如果使用者婉拒同意，就原地工作並跳到第 2 步。

Step 1: Create Isolated Workspace

第 1 步：建立隔離工作區

You have two mechanisms. Try them in this order.

你有兩種機制。依這個順序嘗試。

1a. Native Worktree Tools (preferred)

1a. 原生 Worktree 工具（首選）

The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like EnterWorktree, WorktreeCreate, a /worktree command, or a --worktree flag. If you do, use it and skip to Step 2.

使用者已要求隔離工作區（第 0 步的同意）。你已有建立 worktree 的方式嗎？可能是名為 EnterWorktree、WorktreeCreate 的工具、/worktree 指令，或 --worktree 旗標。如果有，就使用它並跳到第 2 步。

Native tools handle directory placement, branch creation, and cleanup automatically. Using git worktree add when you have a native tool creates phantom state your harness can't see or manage.

原生工具會自動處理目錄位置、分支建立與清理。當你有原生工具卻用 git worktree add，會建立你的 harness 看不見也無法管理的幽靈狀態。

Only proceed to Step 1b if you have no native worktree tool available.

只有在沒有原生 worktree 工具可用時，才繼續到第 1b 步。

1b. Git Worktree Fallback

1b. Git Worktree 備援

Only use this if Step 1a does not apply — you have no native worktree tool available. Create a worktree manually using git.

只有當第 1a 步不適用時才使用 —— 你沒有可用的原生 worktree 工具。手動用 git 建立 worktree。

Directory Selection

目錄選擇

Follow this priority order. Explicit user preference always beats observed filesystem state.

依這個優先序。使用者的明確偏好永遠勝過觀察到的檔案系統狀態。

Check your instructions for a declared worktree directory preference. If the user has already specified one, use it without asking.

檢查你的指令中是否有宣告的 worktree 目錄偏好。 如果使用者已指定，直接使用，不再詢問。

Check for an existing project-local worktree directory: bash ls -d .worktrees 2>/dev/null # Preferred (hidden) ls -d worktrees 2>/dev/null # Alternative If found, use it. If both exist, .worktrees wins.

檢查既有的專案內 worktree 目錄： bash ls -d .worktrees 2>/dev/null # Preferred (hidden) ls -d worktrees 2>/dev/null # Alternative 如果有就使用。如果兩者都存在，.worktrees 優先。

If there is no other guidance available, default to .worktrees/ at the project root.

如果沒有其他指引可用，預設使用專案根目錄的 .worktrees/。

Safety Verification (project-local directories only)

安全性驗證（僅限專案內目錄）

MUST verify directory is ignored before creating worktree:

建立 worktree 前必須驗證目錄已被忽略：

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

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

If NOT ignored: Add to .gitignore, commit the change, then proceed.

如果未被忽略： 加入 .gitignore、commit 這個變更，然後繼續。

Why critical: Prevents accidentally committing worktree contents to repository.

為什麼關鍵： 防止不小心把 worktree 內容 commit 進 repo。

Create the Worktree

建立 Worktree

# Determine path based on chosen location
path="$LOCATION/$BRANCH_NAME"

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

# Determine path based on chosen location
path="$LOCATION/$BRANCH_NAME"

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

Sandbox fallback: If git worktree add fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.

Sandbox 備援： 如果 git worktree add 因權限錯誤（sandbox 拒絕）而失敗，告訴使用者 sandbox 封鎖了 worktree 建立，你改在目前目錄工作。然後原地執行設定與基線測試。

Step 2: Project Setup

第 2 步：專案設定

Auto-detect and run appropriate setup:

自動偵測並執行適當的設定：

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

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

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

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

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

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

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

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

Step 3: Verify Clean Baseline

第 3 步：驗證乾淨的基線

Run tests to ensure workspace starts clean:

執行測試以確保工作區以乾淨狀態開始：

# Use project-appropriate command
npm test / cargo test / pytest / go test ./...

# Use project-appropriate command
npm test / cargo test / pytest / go test ./...

If tests fail: Report failures, ask whether to proceed or investigate.

如果測試失敗： 回報失敗，詢問要繼續還是調查。

If tests pass: Report ready.

如果測試通過： 回報就緒。

Report

回報

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

快速參考

Situation	Action
Already in linked worktree	Skip creation (Step 0)
In a submodule	Treat as normal repo (Step 0 guard)
Native worktree tool available	Use it (Step 1a)
No native tool	Git worktree fallback (Step 1b)
`.worktrees/` exists	Use it (verify ignored)
`worktrees/` exists	Use it (verify ignored)
Both exist	Use `.worktrees/`
Neither exists	Check instruction file, then default `.worktrees/`
Directory not ignored	Add to .gitignore + commit
Permission error on create	Sandbox fallback, work in place
Tests fail during baseline	Report failures + ask
No package.json/Cargo.toml	Skip dependency install

情境	動作
已在連結的 worktree 中	跳過建立（第 0 步）
在子模組中	視為一般 repo（第 0 步防護）
有原生 worktree 工具	使用它（第 1a 步）
沒有原生工具	Git worktree 備援（第 1b 步）
`.worktrees/` 存在	使用它（驗證已忽略）
`worktrees/` 存在	使用它（驗證已忽略）
兩者都存在	使用 `.worktrees/`
都不存在	檢查指令檔，然後預設 `.worktrees/`
目錄未被忽略	加入 .gitignore + commit
建立時權限錯誤	Sandbox 備援，原地工作
基線測試失敗	回報失敗 + 詢問
沒有 package.json/Cargo.toml	跳過依賴安裝

Common Rationalizations

常見合理化藉口

Excuse	Reality
"I'm obviously not in a worktree — no need to check"	Run Step 0. Harness-created isolation and submodules both fool eyeballing; the detection commands settle it.
"`git worktree add` is quicker than hunting for a native tool"	A native tool (e.g. `EnterWorktree`) owns placement, branching, and cleanup. Bypassing it is the #1 mistake — it creates phantom state your harness can't see or manage.
"The worktree directory is surely ignored already"	Run `git check-ignore`. An unignored worktree directory commits the whole tree into the repo.
"Any directory name works"	Explicit instructions beat an existing project-local directory, which beats the `.worktrees/` default.
"The workspace is fresh — baseline tests can wait"	A dirty baseline makes every later failure ambiguous. Run the tests now; proceeding past failures is your human partner's call.

藉口	事實
「我顯然不在 worktree 裡——不必檢查」	執行第 0 步。harness 建立的隔離狀態與子模組都會騙過肉眼；偵測指令才能定案。
「`git worktree add` 比找原生工具快」	原生工具（例如 `EnterWorktree`）負責放置、分支與清理。繞過它是最常見的錯誤 #1 —— 它會建立你的 harness 看不見也無法管理的幽靈狀態。
「worktree 目錄肯定已經被忽略了」	執行 `git check-ignore`。未被忽略的 worktree 目錄會把整棵樹 commit 進 repo。
「任何目錄名都行」	明確的指令勝過既有的專案內目錄，既有的專案內目錄勝過 `.worktrees/` 預設。
「工作區是全新的——基線測試可以晚點跑」	骯髒的基線會讓之後每個失敗都變得不明確。現在就跑測試；要不要在失敗中繼續前進是你的人工夥伴的決定。