Git Worktree 완전 가이드

작성일: 2026-03-27

개요

Git Worktree는 하나의 Git 저장소(.git 폴더 공유)에서 여러 개의 독립적인 작업 디렉토리(워크트리)를 동시에 운영하는 기능입니다. Git 2.5(2015년)에 도입되었으며, 최근 Claude Code, Cursor 같은 AI 코딩 에이전트들이 적극 활용하면서 다시 주목받고 있습니다.

핵심 장점

🚀 브랜치 전환 0초 - 디렉토리 이동만 하면 됨 (stash/unstash 불필요)
🔒 완전한 격리 - 각 워크트리마다 다른 브랜치, 다른 상태, 다른 설정
💾 디스크 절약 - .git 폴더를 공유해서 여러 clone보다 훨씬 적은 공간
⚡ 병렬 작업 - 여러 IDE/터미널에서 동시에 diferentes 브랜치 작업 가능

기본 사용법

워크트리 생성

# 기존 브랜치로 워크트리 생성
git worktree add <경로> <브랜치명>
git worktree add ../hotfix hotfix/login-error

# 새 브랜치 생성하며 워크트리 만들기
git worktree add -b feature/new-api ../api-feature

# 경로명으로 자동 브랜치 생성 (경로: ../payment → 브랜치: payment)
git worktree add ../payment

워크트리 목록 확인

git worktree list          # 기본 목록
git worktree list -v       # 상세 정보 포함

예시 출력:

/Users/me/project a1b2c3d [main]
/Users/me/hotfix e4f5g6h [hotfix/urgent]
/Users/me/feature i7j8k9l [feature/auth]

워크트리 삭제

git worktree remove ../hotfix           # 정상 삭제
git worktree remove --force ../hotfix   # 변경사항 있어도 강제 삭제

사용하지 않는 워크트리 정리

git worktree prune      # 존재하지 않는 워크트리 참조 제거

실전 활용 시나리오

🆘 긴급 핫픽스 대응

# 현재: feature/user-profile에서 작업 중 (변경사항 많음)

# 핫픽스 워크트리 생성 (main 기반)
git worktree add -b hotfix/security ../hotfix main
cd ../hotfix
# 긴급 수정, 커밋, 머지 완료

# 원래 작업으로 복귀 - stash 없이 바로 이어서 작업 가능!
cd ../project
# 변경사항 그대로 남아있음

🔍 코드 리뷰하면서 개발 계속

# 리뷰할 PR 브랜치로 워크트리
git fetch origin
git worktree add ../review-pr-123 origin/feature/payment
cd ../review-pr-123
# 실제로 실행해보며 리뷰

# 동시에 원래 작업도 진행 (다른 터미널)
cd ../project && code .  # 개발용
cd ../review-pr-123 && code .  # 리뷰용

🧪 다양한 환경 테스트

# 여러 브랜치를 동시에 실행
git worktree add ../test-main main
git worktree add ../test-develop develop

cd ../test-main && npm start -- --port 3000 &
cd ../test-develop && npm start -- --port 3001 &
# localhost:3000 (main) vs localhost:3001 (develop) 병렬 테스트

🚀 병렬 개발 (Claude Code/Cursor와 함께)

# 각 기능별 워크트리 생성
git worktree add ../auth-feature feature/auth
git worktree add ../payment-feature feature/payment
git worktree add ../admin-feature feature/adminpanel

# 각 워크트리에서 독립적인 Claude Code 세션 실행
cd ../auth-feature && claude    # 인증 기능 개발
cd ../payment-feature && claude # 결제 기능 개발
# 서로 간섭 없이 병렬 작업!

주의사항 & 베스트 프랙티스

❌ 피해야 할 것

같은 브랜치를 여러 워크트리에서 동시에 체크아웃 불가
```
fatal: 'main' is already checked out at '/path/to/worktree'
```
워크트리를 저장소 내부에 만들지 말 것
- .gitignore 스트레스 유발
- 권장: 상위 디렉토리에 생성 (../feature-name)

공유 파일 수정 주의

# ❌ 모든 워크트리가 .env를 동시에 수정하면 충돌
# ✅ 환경별 설정 파일 분리
cp .env.example .env.auth     # auth 워크트리
cp .env.example .env.payment # payment 워크트리

✅ 권장사항

네이밍 컨벤션

git worktree add ../feature-user-auth feature/user-auth
git worktree add ../hotfix-login-bug hotfix/login-bug
git worktree add ../release-v2-1 release/v2.1

정기적 정리

# 커밋되지 않은 변경사항이 있으면 우선 커밋 또는 stash
git worktree list | grep -v "main\|develop" | while read path; do
 cd $path && git status
done

# 정리
git worktree prune

Git 설정 최적화 (대용량 저장소)

git config core.preloadindex true
git config core.fscache true
git config gc.auto 256

AI 코딩 에이전트와의 시너지

왜 Git Worktree가 AI 코딩에 perfect한가? - 🤖 AI가 파일을 직접 읽고 수정하기 때문에 동시 작업 시 충돌 가능성 있음 - 🔒 워크트리로 완전히 격리 → 각 AI 세션이 독립된 디렉토리에서 작업 - 💸 실험 비용 최소화 → 문제 생기면 그 워크트리만 삭제

Claude Code 사용법:

# 워크트리에서 Claude 시작
claude --worktree feature-auth

# 자동 브랜치명: worktree-feature-auth
# 워크트리 위치: <repo>/.claude/worktrees/feature-auth/

# 여러 세션 병렬 실행
# 터미널 1: claude --worktree auth-refactor
# 터미널 2: claude --worktree payment-new
# 터미널 3: claude --worktree hotfix-urgent

세션 종료 시: - 변경사항 없음 → 워크트리 + 브랜치 자동 삭제 - 변경사항 있음 → 유지할지 물어봄 (나중에 claude --resume으로 재개 가능)

참고 자료

이 가이드는 다음 웹 아티클들을 종합하여 작성되었습니다:

#	제목	비고
1	Practical Guide to Git Worktree	실용적인 사용법, CLI 도구(wt) 소개
2	Git - git-worktree Documentation	공식 문서, 모든 옵션 상세 설명
3	Git Worktree 완벽 가이드 - 효율적인 멀티 브랜치 워크플로우 구축하기	Git 2.50 최신 기능, 실무 시나리오 가득, 스크립트 예제
4	git worktree 사용법 - Engineering Blog by Dale Seo	AI 코딩 에이전트(Claude Code) 연동 설명 최고

추가 참고

초기 학습 비용은 있지만, 장기적으로 팀의 생산성과 코드 품질에 미치는 긍정적 영향은 투자 비용을 충분히 상회합니다. 지금 바로 시작해서 더 스마트한 Git 워크플로우를 경험해보세요!