[Git] Worktree

이런 상황 겪어본 적 있어?

feature 브랜치에서 열심히 작업하고 있는데 갑자기 팀장이 말한다.

"야, main에 버그 났어. 빨리 고쳐."

 

지금 내 상태는 이렇다.

• feature/login 브랜치에서 파일 10개 수정 중
• 아직 commit하기엔 애매한 상태

보통은 이렇게 한다.

git stash        # 작업 임시 저장
git checkout main
# hotfix 작업...
git checkout feature/login
git stash pop    # 다시 꺼내기 → conflict 날 수도 있음

stash는 "서랍에 잠깐 넣어두는 것"이다. 꺼낼 때 뭔가 엉킬 수 있고, 여러 번 반복되면 스트레스가 쌓인다.

git worktree는 이 문제를 다르게 접근한다. 책상을 하나 더 펼치는 것이다.

 

git worktree란?

하나의 git 저장소에서 여러 작업 디렉토리를 동시에 체크아웃할 수 있는 기능이다.

my-repo/          ← main 브랜치 (메인 worktree)
my-repo-hotfix/   ← hotfix/bug-123 브랜치 (추가 worktree)
my-repo-feature/  ← feature/login 브랜치 (추가 worktree)

각 폴더는 독립된 작업 공간(각 worktree는 독립적인 체크아웃 상태를 유지)이지만, .git 객체는 공유한다.

그래서 브랜치를 통째로 clone하는 것보다 디스크를 훨씬 적게 쓴다.(커밋/브랜치/태그 정보를 공유)

 

기본 사용법

# 새 worktree 추가 (브랜치 자동 생성)
git worktree add ../my-repo-hotfix hotfix/bug-123

# 기존 브랜치로 worktree 추가
git worktree add ../my-repo-feature feature/login

# worktree 목록 확인
git worktree list

# worktree 제거
git worktree remove ../my-repo-hotfix

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

 

실제 시나리오

Before: stash 방식

# feature 작업 중단하고 stash
git stash

# main으로 전환 후 hotfix
git checkout main
git checkout -b hotfix/bug-123
# ... 수정 ...
git commit -m "fix: 버그 수정"
git checkout main
git merge hotfix/bug-123

# 다시 feature로 복귀
git checkout feature/login
git stash pop   # conflict 발생 가능

After: worktree 방식

# feature 폴더는 그대로 두고 hotfix용 폴더 생성
git worktree add -b hotfix/bug-123 ../my-repo-hotfix main
cd ../my-repo-hotfix

# ... 수정 ...
git commit -m "fix: 버그 수정"

# 내 feature 작업으로 복귀 — 아무것도 안 건드렸음
cd ../my-repo

 

장점

• stash 불필요 — 브랜치 전환 시 현재 작업을 stash/commit 안 해도 된다
• 빌드 캐시 유지 — 각 worktree가 독립된 빌드 결과물을 가져서 재빌드를 최소화한다 (C/C++ 프로젝트에서 특히 유용)
• 병렬 작업 — feature 개발 중 hotfix를 별도 폴더에서 동시에 진행할 수 있다
• 디스크 효율 — .git 객체를 공유하므로 clone보다 용량을 절약한다
• IDE 친화적 — 각 폴더를 별도 프로젝트로 열 수 있다

 

위험요소 및 주의사항

같은 브랜치 중복 체크아웃 불가

# 에러: already checked out
git worktree add ../copy main

폴더를 그냥 삭제하면 참조가 남는다

rm -rf ../my-repo-hotfix   # 이렇게 하면 안 됨

# 반드시 이렇게
git worktree remove ../my-repo-hotfix
# 또는 삭제 후 정리
git worktree prune

hook이 공유된다

.git/hooks가 모든 worktree에 공유되므로, worktree별로 다른 동작이 필요하면 별도 처리가 필요하다.

submodule 주의

submodule이 있는 경우 각 worktree에서 별도로 초기화해야 한다.

git submodule update --init

 

이런 사람한테 추천

상황	worktree 필요도
혼자 작업, 브랜치 전환 거의 없음	낮음 (stash로 충분)
hotfix가 자주 터지는 팀 환경	높음
빌드 시간이 긴 프로젝트 (C/C++ 등)	높음
여러 브랜치를 동시에 비교해야 할 때	높음

 

정리

git worktree는 stash의 대체제가 아니라 컨텍스트 스위칭 비용을 줄이는 도구다.

서랍(stash)에 넣고 꺼내는 게 불편해지기 시작했다면, 책상을 하나 더 펼쳐보자.