Git worktree로 브랜치 스위칭 비용 줄이기

개발을 진행하다가 새로운 개발이 들어오거나 긴급하게 에러를 처리할 때, 작업하고 있던 것을 git stash에 저장한 뒤에 main에서 hofix 브랜치를 만들어서 hotfix 브랜치로 checkout 한 뒤, 작업이 완료되면 기존에 있던 작업 브랜치로 돌아가 git stash 에 저장되어 있던 작업을 pop으로 꺼내주면서 마저 진행했던 경험이 있다.

그러다가 stash가 많아지고 작업할 브랜치가 많아지면서 스위치할 때 신경써야하는 부분이 발생한다. 이러한 것들이 스위치 비용이라고 생각한다. 최근에는 claude code 와 작업을 함께하고 있는데, claude code 에게 작업을 맡겨놓고, 다른 작업을 할 수 있는 환경이 필요해졌다.

방법을 찾기 위해 Claude 공식문서를 찾아보았다. 일반적인 워크플로우 메뉴를 읽다가 Git worktree를 사용하여 병렬 Claude Code 세션 실행하기 섹션을 찾았다. 여기서 키워드를 발견하여 Git worktree를 검색해보았다.

Git worktree

Git 공식문서에서는 동일한 저장소에 연결된 여러 작업 트리를 관리한다고 되어있다.
아직 무슨 말인지 모르겠다. 명령어를 실행시켜보자.

worktree 추가

git worktree add ../feature-payment feature/payment

이 명령어를 실행하면 현재 프로젝트 디렉토리 옆에 feature-payment라는 새로운 디렉토리가 생긴다. 그리고 그 안에는 feature/payment 브랜치가 체크아웃되어 있다.

my-project/          # 원래 작업하던 곳 (develop 브랜치)
my-project-feature/  # 새로 생긴 worktree (feature/payment 브랜치)

신기한 건, 이 두 디렉토리가 같은 Git 저장소를 공유한다는 점이다. .git 디렉토리를 복사하는 게 아니라 공유하기 때문에 한쪽에서 커밋하면 다른 쪽에서도 바로 확인할 수 있다.

실제로 써보기

간단한 테스트 프로젝트로 직접 써봤다.

# 테스트 프로젝트 생성
mkdir ~/projects/worktree-test
cd ~/projects/worktree-test
git init
echo "# Test Project" > README.md
git add .
git commit -m "Initial commit"

# worktree 추가해보기
git worktree add ../worktree-test-feature -b feature/test

실행하면 worktree-test-feature라는 디렉토리가 생기고, 그 안에 feature/test 브랜치가 체크아웃되어 있다.

ls ~/projects/
# worktree-test/
# worktree-test-feature/

두 디렉토리를 오가면서 파일을 수정하고 커밋해봤는데, 정말 독립적으로 작동한다. 한쪽에서 파일을 수정해도 다른 쪽에는 영향이 없다.

기존 방식과의 차이

기존 방식 (git stash 사용)

# 1. 작업 중단하고 저장
git add .
git stash

# 2. hotfix 브랜치로 이동
git checkout -b hotfix/urgent-bug

# 3. 수정 후 다시 돌아가기
git checkout develop
git stash pop

# 4. node_modules나 .next 캐시 문제로 npm install 또는 npm run dev 다시...

worktree 방식

# 1. 작업은 그대로 두고
# 2. 새 디렉토리에서 hotfix
git worktree add ../project-hotfix -b hotfix/urgent-bug
cd ../project-hotfix
npm install

# 3. 수정 완료 후
cd ../project  # 원래 작업으로 돌아가기
# 작업이 그대로 남아있음!

# 4. hotfix worktree 정리
git worktree remove ../project-hotfix

차이가 느껴지는가? stash를 쓰면 작업을 저장하고 복원하는 과정이 필요하지만, worktree를 쓰면 그냥 디렉토리만 옮겨 다니면 된다.

worktree 목록 확인

git worktree list

~/projects/worktree-test          a1b2c3d [main]
~/projects/worktree-test-feature  d4e5f6g [feature/test]

현재 어떤 worktree들이 있는지, 어떤 브랜치를 체크아웃하고 있는지 한눈에 볼 수 있다.

worktree 제거

작업이 끝난 worktree는 제거해주면 된다.

git worktree remove ../worktree-test-feature

브랜치는 그대로 남아있고, 작업 디렉토리만 사라진다. 나중에 다시 필요하면 git worktree add로 다시 만들면 된다.

활용 계획

Claude Code와 병렬 작업

앞으로 가장 써보고 싶은 방법은 Claude Code와 병렬로 작업하는 것이다.

# 1. 메인 작업 디렉토리 (내가 직접 작업)
cd ~/projects/worktree-test
npm run dev  # localhost:3000

# 2. AI 작업 디렉토리 (Claude Code가 작업)
git worktree add ../worktree-test-ai -b feature/ai-generates
cd ../worktree-test-ai
npm install
code .

# 3. VSCode 새 창에서 Claude Code 실행
# "모달 컴포넌트 만들어줘" 같은 작업 요청

이렇게 하면 Claude Code가 작업하는 동안 나는 원래 디렉토리에서 내 작업을 계속할 수 있을 것 같다. 두 작업이 완전히 독립적으로 진행되기 때문에 서로 방해받지 않을 거다.

작업이 완료되면 AI가 만든 코드를 확인하고, 괜찮으면 메인 브랜치로 merge하면 될 것이다.

cd ~/projects/worktree-test
git merge feature/ai-generates

필요 없으면 그냥 worktree만 삭제하면 끝이다.

git worktree remove ../worktree-test-ai
git branch -D feature/ai-generates

Git Flow와 함께 사용하기

회사에서 Git Flow를 사용하고 있는데, worktree를 활용하면 더 효율적일 것 같다는 생각이 들었다.

~/projects/worktree-test/
├── develop/       # 평소 작업하는 곳
├── release/       # QA 진행 중인 release 브랜치
├── feature-ui/    # UI 개발 중
└── hotfix/        # 긴급 수정용 (필요할 때만)

각 디렉토리에서 독립적으로 개발 서버를 띄우고, 빌드하고, 테스트할 수 있을 것이다.

특히 release 브랜치에서 QA를 진행하면서 동시에 develop에서 다음 기능을 개발하는 상황에서 유용할 것 같다. QA에서 버그가 발견되면 develop에서 수정하고 release로 cherry-pick하면 되는데, 두 브랜치를 왔다 갔다 하지 않아도 되니까 훨씬 편할 것 같다. 이 부분은 실제 프로젝트에 적용해보면서 검증해봐야겠다.

주의할 점

1. node_modules 관리

각 worktree는 독립적인 디렉토리이기 때문에 node_modules도 각각 설치해야 한다. Next.js 프로젝트면 각각 수백 MB씩 차지할 수 있으니 디스크 공간을 고려해야 한다.

만약 package.json이 동일하다면 심볼릭 링크를 사용할 수도 있다.

cd ~/projects/worktree-test-hotfix
ln -s ../worktree-test/node_modules node_modules

하지만 dependency가 조금이라도 다르면 문제가 생길 수 있으니 조심해야 한다.

2. 같은 브랜치는 한 번만

하나의 브랜치는 하나의 worktree에서만 체크아웃할 수 있다.

git worktree add ../test-1 develop  # OK
git worktree add ../test-2 develop  # ❌ 에러 발생

이미 다른 곳에서 체크아웃된 브랜치는 다시 체크아웃할 수 없다. 이건 당연한 거긴 한데, 처음에 헷갈릴 수 있다.

3. 빌드 결과물 관리

.next/, out/, dist/ 같은 빌드 결과물은 각 worktree마다 독립적으로 생성된다. .gitignore에 잘 등록되어 있는지 확인해야 한다.

정리

Git worktree는 다음과 같은 상황에서 특히 유용할 것 같다.

1. 긴급 수정이 필요한데 현재 작업을 중단하고 싶지 않을 때
2. 여러 브랜치를 동시에 확인하며 작업해야 할 때 (PR 리뷰 등)
3. Claude Code 같은 AI 도구와 병렬로 작업할 때 (계획)
4. Git Flow처럼 여러 브랜치를 자주 오가야 할 때 (계획)
5. 여러 버전을 동시에 실행하며 테스트해야 할 때

git stash와 git checkout을 반복하면서 느꼈던 스위치 비용을 확실히 줄일 수 있을 것 같다. 특히 Next.js 같은 프레임워크에서 브랜치를 전환할 때마다 .next 캐시가 재생성되는 시간을 기다리지 않아도 되는 게 가장 큰 장점일 것 같다.

아직 실험적인 기능이라는 경고가 있긴 하지만, 일단 기본적인 테스트에서는 문제가 없었다. 앞으로 실제 프로젝트에 적용하면서 더 검증해 볼 예정이다.