using-git-worktrees

name	using-git-worktrees
description	Create isolated git worktrees with smart directory selection and safety verification. Use this when starting feature work that needs isolation, parallel development, or safe experimentation.
allowed-tools	Read, Glob, Grep, Bash
license	MIT
metadata	{"author":"obra/superpowers","version":"1.0"}

Using Git Worktrees

Git worktree를 사용한 격리된 개발 환경 생성 가이드입니다.

When to Use

• 기능 개발을 위한 격리된 환경 필요 시
• 여러 브랜치에서 동시 작업 시
• 안전한 실험이 필요할 때
• 구현 계획 실행 전 환경 준비 시

Quick Start

# 1. worktree 디렉토리 확인/생성
ls -la ../worktrees/ 2>/dev/null || mkdir -p ../worktrees

# 2. 새 worktree 생성
git worktree add ../worktrees/feature-name -b feature/feature-name

# 3. worktree로 이동
cd ../worktrees/feature-name

# 4. 작업 완료 후 정리
git worktree remove ../worktrees/feature-name

Directory Selection Strategy

권장 구조

project-root/
├── .git/                    # 메인 저장소
├── src/                     # 메인 작업 디렉토리
└── ...

../worktrees/                # worktree 전용 디렉토리
├── feature-auth/           # 인증 기능 작업
├── feature-api/            # API 개발
└── hotfix-critical/        # 긴급 수정

네이밍 규칙

../worktrees/{type}-{name}

types:
- feature-*    기능 개발
- hotfix-*     긴급 수정
- experiment-* 실험적 변경
- review-*     코드 리뷰용

Safety Verification

생성 전 체크리스트

# 1. 현재 상태 확인
git status                    # 미커밋 변경사항 확인
git stash list               # stash 상태 확인

# 2. 브랜치 존재 여부 확인
git branch -a | grep feature-name

# 3. worktree 목록 확인
git worktree list

생성 후 검증

# 1. worktree 상태 확인
git worktree list

# 2. 현재 브랜치 확인
git branch

# 3. 원격 연결 확인
git remote -v

Common Workflows

기능 개발 시작

# 1. 최신 main 기준으로 worktree 생성
git fetch origin
git worktree add ../worktrees/feature-x -b feature/x origin/main

# 2. 의존성 설치 (프로젝트에 따라)
cd ../worktrees/feature-x
npm install  # 또는 pip install -r requirements.txt

# 3. 개발 시작
code .  # 또는 원하는 에디터

코드 리뷰용 환경

# PR 브랜치를 별도 worktree로
git worktree add ../worktrees/review-pr-123 origin/feature/pr-123
cd ../worktrees/review-pr-123
# 테스트 실행, 코드 검토

긴급 수정

# 현재 작업 중단 없이 hotfix
git worktree add ../worktrees/hotfix-critical -b hotfix/critical origin/main
cd ../worktrees/hotfix-critical
# 수정 → 커밋 → PR

Cleanup

개별 worktree 제거

# 1. worktree 제거
git worktree remove ../worktrees/feature-x

# 2. 브랜치도 삭제하려면
git branch -d feature/x

전체 정리

# 1. 모든 worktree 목록
git worktree list

# 2. 정리 (삭제된 worktree 참조 제거)
git worktree prune

# 3. 미사용 worktree 디렉토리 삭제
rm -rf ../worktrees/old-feature
git worktree prune

Best Practices

1. 일관된 위치: worktree는 항상 ../worktrees/에
2. 명확한 네이밍: 목적이 드러나는 이름 사용
3. 정기적 정리: 완료된 worktree는 즉시 제거
4. 독립적 의존성: 각 worktree에서 별도로 의존성 설치
5. 메인 저장소 보존: worktree에서만 실험적 변경

Troubleshooting

문제	해결책
"already checked out"	다른 worktree에서 사용 중, 다른 브랜치명 사용
"not a valid ref"	git fetch 먼저 실행
의존성 오류	worktree에서 새로 설치 필요
변경사항 충돌	메인에서 stash 또는 commit 후 진행