using-git-worktrees

使用 Git 工作树

核心原则

隔离功能开发。保持 main 干净。

Git 工作树让你可以在不同目录中同时处理多个分支。

何时使用

• 开始开发新功能
• main 分支上的开发仍在继续，同时修复 bug
• 需要切换上下文，但不想暂存更改
• 希望将不同的工作流清晰分开

设置流程

步骤 1：检查是否已有工作树目录

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

如果找到：使用该目录。 如果两个目录都存在：优先使用 .worktrees。

步骤 2：检查 CLAUDE.md 中的偏好设置

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

如果指定了偏好设置：直接使用，无需询问。

步骤 3：如果不存在目录

询问用户：

No worktree directory found. Where should I create worktrees?
1. .worktrees/ (project-local, hidden)
2. worktrees/ (project-local, visible)
3. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

步骤 4：验证 .gitignore

# Check if directory pattern in .gitignore
grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore

如果不存在，请添加：

echo ".worktrees/" >> .gitignore
# or
echo "worktrees/" >> .gitignore

创建工作树

标准创建

# Determine branch name from feature
BRANCH_NAME="feature/descriptive-name"

# Create worktree with new branch
git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"

# Navigate to worktree
cd ".worktrees/$BRANCH_NAME"

从现有分支创建

git worktree add ".worktrees/$BRANCH_NAME" "$BRANCH_NAME"

创建后的设置

安装依赖项

# 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

运行初始测试

# Run test suite
npm test  # or appropriate command

# Report status

如果测试失败：报告失败情况，并询问是继续还是进行排查。 如果测试通过：报告已准备就绪。

工作树管理

列出工作树

git worktree list

移除工作树

# After merging feature branch
git worktree remove ".worktrees/feature/branch-name"

# Force remove (if needed)
git worktree remove --force ".worktrees/feature/branch-name"

清理过期工作树

git worktree prune

最佳实践

命名规范

• 功能使用 feature/descriptive-name
• bug 使用 bugfix/issue-number-description
• 紧急修复使用 hotfix/critical-issue

让工作树各司其职

• 每个工作树对应一个功能
• 完成后合并并移除
• 不要让工作树不断累积

定期同步

# In worktree, get latest from main
git fetch origin
git rebase origin/main

完成检查清单

功能完成时：

1. 所有测试均通过
2. 代码已审查
3. 已合并到 main
4. 工作树已移除
5. 分支已删除（如需要）

# Full cleanup
git checkout main
git pull
git worktree remove ".worktrees/feature/name"
git branch -d feature/name

通知模板

开始创建工作树时：

"I'm using the using-git-worktrees skill to set up an isolated workspace for [feature name]."

完成时：

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