Chapter 8: Git Worktrees & Branch 관리

현대적인 기능 개발에는 격리가 필요합니다. 현재 작업 상태를 불안정하게 만들지 않고 새 기능에 작업하고, 반쯤 완성된 작업을 stash하지 않고 context를 전환하며, 지속적인 branch 전환 없이 병렬 워크스트림을 실행해야 합니다. Git worktree는 이 모든 것을 해결합니다.

Git Worktree란 무엇입니까?

Git worktree는 동일한 repository의 여러 branch를 동시에 체크아웃할 수 있게 해줍니다 — 각각 디스크의 자체 디렉토리에서.

Worktree 없이는 단일 repository에 하나의 working directory가 있습니다. Branch를 전환하면 해당 하나의 디렉토리의 모든 파일이 변경됩니다. Context를 전환할 때마다 변경 사항을 stash하거나, 진행 중인 작업을 commit하거나, 상태를 잃을 위험을 감수해야 합니다.

Worktree를 사용하면 다음을 가질 수 있습니다:

~/projects/myapp/ — main branch
~/projects/myapp-feature-auth/ — feature/auth branch
~/projects/myapp-hotfix-123/ — hotfix/issue-123 branch

세 가지 모두 동일한 repository입니다. Commit, tag, 히스토리는 공유됩니다. 하지만 각 디렉토리는 자체 working tree와 staging area를 가지며, 다른 것들과 완전히 격리되어 있습니다.

이것이 v4.2.0에서 도입된 Superpowers 필수 worktree 격리 정책의 기반입니다: 모든 feature branch는 자체 worktree를 갖으며, main branch는 직접 수정되지 않습니다.

새 개발 Branch 만들기

새 작업을 시작할 때 이 다섯 단계를 따르세요.

Step 1: 디렉토리 선택

Worktree 디렉토리 이름을 branch 이름과 일치하도록 지정하세요. 메인 working directory 옆에 유지하세요:

# 메인 repo가 위치:
/Users/you/projects/myapp

# 새 worktree가 위치할 곳:
/Users/you/projects/myapp--feature-user-auth

이중 대시 규칙(--)은 프로젝트 이름과 branch 이름을 시각적으로 구분하며, ls로 worktree를 쉽게 식별할 수 있게 해줍니다.

Step 2: Branch와 Worktree 만들기

# 메인 repo 디렉토리 내부에서:
git worktree add ../myapp--feature-user-auth -b feature/user-auth

# 이것은 다음을 생성합니다:
# 1. feature/user-auth라는 새 branch
# 2. ../myapp--feature-user-auth에 새 디렉토리
# 3. 새 branch로 체크아웃된 해당 디렉토리

기존 branch에서 worktree를 만들려면:

git worktree add ../myapp--feature-user-auth feature/user-auth

Step 3: 안전 확인

작업을 시작하기 전에, worktree가 올바르게 설정되었는지 확인하세요:

cd ../myapp--feature-user-auth

# 올바른 branch에 있는지 확인
git branch --show-current
# 예상: feature/user-auth

# worktree가 clean한지 확인
git status
# 예상: nothing to commit, working tree clean

# 올바른 곳에서 branch를 만들었는지 확인
git log --oneline -5
# 최근 main branch 히스토리가 base로 표시되어야 합니다

이 단계를 건너뛰지 마세요. 잘못된 branch나 dirty tree에서 작업을 시작하는 것은 혼란스러운 버그의 일반적인 원인입니다.

Step 4: 프로젝트 설정

일부 프로젝트는 새로운 체크아웃 후 추가 설정이 필요합니다. 새 worktree에서:

# 의존성 설치 (node_modules가 공유되지 않는 경우)
npm install

# 필요한 경우 환경 파일 복사
cp ../myapp/.env.local .env.local

# 필요한 파일 생성
npm run generate

정식 설정 단계는 프로젝트의 CLAUDE.md 또는 README.md를 확인하세요.

Step 5: Baseline Tests

기능 코드 한 줄을 작성하기 전에, 전체 test suite를 실행하세요:

npm test

시작하기 전에 모든 test가 통과해야 합니다. 깨끗한 체크아웃에서 test가 실패한다면, 기능 작업을 시작하기 전에 해결해야 할 기존 문제가 있는 것입니다. 이 baseline은 작업 중 도입된 test 실패가 base branch에서 상속된 것이 아닌 변경 사항으로 인한 것임을 보장합니다.

개발 Branch 마무리하기

기능이 완료되고 모든 test가 통과하면, 작업을 처리하는 네 가지 옵션이 있습니다.

네 가지 옵션

옵션	사용 시기	일어나는 일
로컬 Merge	작은 변경, 쓰기 권한 있음, 리뷰 불필요	Branch가 main에 merge됨, worktree 제거됨
PR 만들기	팀 프로젝트, 리뷰 필요, 또는 CI 게이트가 통과해야 함	원격에서 PR이 열림, PR이 merge될 때까지 worktree 유지
현상 유지	진행 중인 작업, merge 준비 안됨, 나중에 돌아올 수 있음	Worktree와 branch가 보존됨, 조치 없음
삭제	실패한 실험, 더 이상 필요 없는 작업	Branch와 worktree가 영구적으로 삭제됨

옵션 A: 로컬 Merge

# Test 통과 확인
npm test

# main으로 전환하고 merge
cd ../myapp
git checkout main
git pull origin main
git merge --no-ff feature/user-auth -m "feat: add user authentication"

# worktree 제거
git worktree remove ../myapp--feature-user-auth

# branch 삭제
git branch -d feature/user-auth

옵션 B: Pull Request 만들기

# branch를 원격에 push
cd ../myapp--feature-user-auth
git push -u origin feature/user-auth

# PR 만들기 (GitHub CLI 사용)
gh pr create --title "feat: add user authentication" --body "..."

# PR이 리뷰되고 merge될 때까지 worktree가 살아있습니다

옵션 C: 현상 유지

조치 불필요. Worktree와 branch가 지속됩니다. 잊혀지지 않도록 댓글이나 issue에 진행 중인 작업 상태를 문서화하세요.

옵션 D: 삭제

경고: 이것은 영구적이며 되돌릴 수 없습니다.

삭제 옵션은 명시적 확인이 필요합니다. 프롬프트에서 "discard" 단어를 입력해야 합니다. 이는 실수로 작업을 삭제하는 것을 방지합니다.

# worktree 디렉토리 제거
git worktree remove --force ../myapp--feature-user-auth

# 로컬 branch 삭제
git branch -D feature/user-auth

# 원격에 push했다면, 원격 branch도 삭제
git push origin --delete feature/user-auth

작업에 가치가 없다고 확신할 때만 삭제하세요. 조금이라도 의심이 있다면, "현상 유지"를 사용하고 나중에 다시 살펴보세요.

여러 Worktree 관리하기

Repository의 모든 활성 worktree를 보려면:

git worktree list

출력 예시:

/Users/you/projects/myapp              abc1234 [main]
/Users/you/projects/myapp--feature-auth  def5678 [feature/user-auth]
/Users/you/projects/myapp--hotfix-99   ghi9012 [hotfix/issue-99]

디렉토리를 수동으로 삭제한 후 오래된 worktree 참조를 정리하려면:

git worktree prune

Main Branch 보호

Superpowers 프로토콜은 main branch에 대한 하나의 절대적 규칙을 강제합니다:

Main에 직접 commit하지 마세요. 모든 변경은 branch와 worktree를 통해 이루어집니다.

이것은 v4.2.0 필수 worktree 격리 정책에 의해 강제됩니다. 작고 "빠른" fix도 worktree를 사용해야 합니다. 항상 격리된 상태에서 작업하는 규율은 전체 종류의 문제를 방지합니다: main에 실수로 commit, 단일 branch에서 혼재된 변경, 깔끔하게 되돌릴 수 있는 능력의 상실.

Main에 직접 commit하려 한다면, 멈추세요. Worktree를 만드세요. 30초가 걸리며 해결하는 데 몇 시간이 걸릴 수 있는 실수를 방지합니다.