worktree

정의

git worktree는 “하나의 저장소로 여러 작업 디렉터리”를 동시에 다루는 기능

git worktree는 하나의 Git 저장소(.git 디렉터리)를 공유하면서도, 서로 다른 폴더(working tree)에서 각각 다른 브랜치를 동시에 체크아웃할 수 있게 해주는 기능입니다. 즉 “브랜치 전환(switch/checkout) 때문에 작업을 끊지 않고”, 병렬로 작업 흐름을 유지하는 데 최적화되어 있습니다.

핵심: “같은 .git(오브젝트/히스토리) + 다른 작업 디렉터리(파일/인덱스/HEAD)”

main worktree(기본 작업 폴더) + linked worktree(추가 작업 폴더)를 만들 수 있습니다.

핵심 메시지

“브랜치 전환 비용(빌드/테스트/의존성/IDE 인덱싱)을 줄이고, 컨텍스트 스위칭을 없애는 것”이 worktree의 진짜 가치입니다.

 

동작 원리

왜 “브랜치가 동시에 열리는데” 저장소는 하나로 유지되는가

1) .git(오브젝트 DB)은 공유, 작업 폴더는 분리

worktree는 “Git 히스토리/오브젝트(pack, objects)는 공유”하되, 각 작업 폴더는 자기만의 체크아웃 파일, 인덱스(index), HEAD를 가집니다. 그래서 동일 저장소로도 서로 다른 브랜치를 각각의 폴더에서 동시에 편집할 수 있습니다.

2) “같은 브랜치”는 원칙적으로 worktree 2개에 동시에 체크아웃 불가

Git은 보통 하나의 브랜치가 동시에 여러 worktree에서 체크아웃되는 것을 막습니다. (같은 브랜치에 대해 서로 다른 폴더에서 동시에 커밋/리셋 등이 발생하면 혼선이 생기기 때문) 대신 실험/검증 목적이면 detached HEAD worktree를 만들어 “브랜치 없는 임시 작업”이 가능합니다.

TIP

“임시 실험(work-in-progress)을 하고 싶지만 브랜치를 더럽히고 싶지 않다”면 detached worktree를 만들면 됩니다. (공식 문서에도 이 패턴이 등장합니다.)

 

언제 쓰나

worktree가 “진짜 효율”을 만드는 대표 시나리오

1) 기능 개발 중 긴급 핫픽스

feature 브랜치 작업을 멈추지 않고, 별도 폴더에서 hotfix 브랜치로 즉시 대응

2) 서로 다른 버전 동시 빌드/테스트

release/maint 브랜치와 main 브랜치를 동시에 열어 비교, 회귀 테스트, 디버깅

3) PR 리뷰/재현용 환경 분리

현재 작업 폴더는 그대로 두고, PR 브랜치를 별도 폴더에 체크아웃해 재현/검증

GOOD

브랜치 전환 대신 폴더를 전환
IDE/빌드 캐시가 유지되어 컨텍스트 스위칭 비용이 크게 줄어듭니다.

BAD

한 폴더에서 계속 checkout/switch
빌드/의존성/IDE 인덱스가 흔들리며 생산성이 떨어질 수 있습니다.

 

기본 사용법

add / list / remove / prune — 이것만 알아도 실전 가능

1) worktree 생성: 기존 브랜치 / 새 브랜치

# (권장) 저장소 폴더의 “형제 디렉터리”에 worktree를 두는 패턴
# 예: repo/  (main worktree)
#     repo-wt/feature-login  (linked worktree)

# 이미 존재하는 브랜치를 새 폴더에 체크아웃
git worktree add ../repo-wt/feature-login feature/login

# 새 브랜치를 만들면서 worktree 생성
git worktree add -b feature/hotfix-1 ../repo-wt/hotfix-1 main

2) detached(임시) worktree: 실험/검증용

# 브랜치 없이(Detached HEAD) 현재 HEAD 기준으로 임시 worktree 생성
git worktree add --detach ../repo-wt/tmp-try

# 특정 커밋/태그 기준으로 임시 worktree 생성
git worktree add --detach ../repo-wt/tmp-tag v1.2.0

3) 목록 확인

git worktree list

4) 삭제 / 정리

# worktree를 “정상 절차”로 제거
git worktree remove ../repo-wt/feature-login

# 폴더를 실수로 지워버린 경우(.git/worktrees 메타가 남음) 정리
git worktree prune

TIP

worktree를 파일 탐색기로 지워도 “겉보기엔” 사라지지만, Git 내부 메타데이터가 남을 수 있습니다. 그럴 땐 git worktree prune으로 정리합니다.

 

실전 워크플로우

“feature 진행 중 hotfix”를 worktree로 끊김 없이 처리하기

시나리오

main worktree에서는 feature/login을 개발 중인데, 운영 버그로 hotfix가 급하게 필요하다고 가정합니다. 일반적인 switch 전략은 “작업 중인 변경사항을 stash/커밋/정리”해야 하므로 흐름이 끊깁니다. worktree는 이 비용을 제거합니다.

# (1) hotfix용 worktree 생성
git worktree add -b hotfix/urgent-1 ../repo-wt/hotfix-urgent main

# (2) hotfix 폴더로 이동해서 수정/테스트/커밋
cd ../repo-wt/hotfix-urgent
# ... fix ...
git commit -am "fix: urgent issue"

# (3) PR 생성 / main에 머지 후, worktree 정리
cd -  # 원래 worktree로 복귀
git worktree remove ../repo-wt/hotfix-urgent

 

주의사항

worktree가 편해지는 만큼, 실수 포인트도 있다

1

브랜치 중복 체크아웃

같은 브랜치를 다른 worktree에 또 체크아웃하려 하면 실패할 수 있습니다. 임시 목적이면 detached로 분리하세요.

2

디스크 사용량

worktree마다 체크아웃 파일/빌드 산출물이 생깁니다. (예: node_modules) “캐시/스토어” 전략을 같이 쓰면 체감이 좋아집니다.

3

폴더를 강제 삭제했을 때 메타 잔존

rm -rf로 폴더만 지우면 목록에는 남을 수 있습니다. prune으로 정리하세요.

 

요약

체크리스트로 마무리

CHECK

✅ 목적: 한 저장소에서 여러 브랜치를 동시에 열린 상태로 작업

✅ 핵심 명령: add / list / remove / prune

✅ 실전 패턴: feature 유지 + hotfix worktree 분리

✅ 주의: 같은 브랜치 중복 체크아웃 제한, 강제 삭제 후 prune 필요