개발 중 긴급한 버그 수정 요청(Hotfix)이 들어오거나, 두 개의 브랜치를 비교하며 테스트해야 할 때가 있습니다. 대부분의 개발자는 진행 중이던 작업을 git stash로 임시 저장한 뒤 git checkout으로 브랜치를 전환합니다. 하지만 이 과정에서 node_modules나 빌드 산출물이 꼬여 다시 설치해야 하거나, 에디터 컨텍스트가 초기화되는 등 작업 흐름이 끊길 수 있습니다.
**Git Worktree(워크트리)**를 사용하면 하나의 저장소를 바탕으로 여러 브랜치를 독립된 개별 폴더처럼 열어둘 수 있습니다. 본문에서는 Git Worktree의 핵심 동작 원리부터 실전 명령어, 주의사항까지 정리합니다.
1. Git Worktree란 무엇이며 왜 써야 할까?
Git Worktree는 Git 2.5 버전부터 탑재된 내장 기능으로, 하나의 .git 저장소 디렉토리를 여러 개의 작업 디렉토리(Working Tree)가 공유할 수 있게 해주는 도구입니다.
💡 쉽게 이해하는 비유
기존의git checkout이 방 하나에 가구를 계속 교체하며 작업하는 방식이라면, Git Worktree는 하나의 지하실(Git 메타데이터) 위에 여러 개의 독립된 방(브랜치 폴더)을 지어놓고 자유롭게 방을 건너다니는 방식입니다.
기존 방식(git checkout) vs Git Worktree 비교
| 구분 | 일반적인 Git Checkout | Git Worktree 활용 |
|---|---|---|
| 브랜치 전환 방식 | 파일 시스템 전체 덮어쓰기 | 폴더 이동으로 작업 대상 변경 |
| 빌드 산출물 충돌 | node_modules 등 의존성 재설치 필요 | 폴더별 독립된 빌드 환경 유지 |
| 작업 중단(Context Switch) | stash 저장 및 복원 필수 | 하던 작업 그대로 두고 다른 폴더 열기 |
| 저장소 용량 활용 | 저장소를 여러 개 clone 하면 용량 N배 | .git은 하나만 공유하므로 용량 최소화 |
2. 실전 Git Worktree 명령어 완전 정복
Git Worktree를 시작하는 데 복잡한 설정은 전혀 필요 없습니다. Git이 설치된 터미널에서 다음 4가지 핵심 명령어만 기억하면 즉시 실무에 적용할 수 있습니다.
① 워크트리 추가하기 (git worktree add)
새로운 기능 개발이나 긴급 수정용 브랜치를 독립 폴더로 만들 때 사용합니다.
# 기본 문법: git worktree add <생성할_폴더_경로> <브랜치명>
# 예시 1: 기존에 존재하는 'feature/payment' 브랜치를 '../payment-work' 폴더에 마운트
git worktree add ../payment-work feature/payment
# 예시 2: 새로운 브랜치 'hotfix/login-bug'를 생성함과 동시에 워크트리 폴더로 만들기 (-b 옵션)
git worktree add -b hotfix/login-bug ../login-hotfix main⚠️ 폴더 경로 지정 팁
워크트리 폴더는 현재 Git 저장소 내부 폴더(src/등)에 생성하면 Git이 untracked 파일로 인식할 수 있습니다. 따라서 프로젝트 루트 디렉토리 외부(../) 또는.gitignore에 등록된.worktrees/같은 전용 폴더에 생성하는 것이 안전합니다.
② 활성화된 워크트리 목록 확인 (git worktree list)
현재 내 로컬 시스템에서 어떤 폴더가 어떤 브랜치와 마운트되어 있는지 한눈에 확인할 수 있습니다.
git worktree list[실행 결과 예시]
/home/user/project-main 2a4f6d8 [main]
/home/user/payment-work 8c1d2e5 [feature/payment]
/home/user/login-hotfix 9f3a1b2 [hotfix/login-bug]③ 워크트리 제거 및 정리 (git worktree remove / prune)
작업이 완료되어 PR이 병합되었다면, 사용하던 워크트리 폴더를 깔끔하게 해제합니다.
# 특정 워크트리 마운트 해제 및 삭제
git worktree remove ../payment-work
# 만약 탐색기에서 폴더를 강제로 삭제했을 경우, Git 메타데이터 연결 정리
git worktree prune3. 워크트리 활용 시나리오
시나리오 A: 긴급 핫픽스(Hotfix) 3분 만에 처리하기
- 기능 개발 폴더(
/project-main)에서 열심히 코드를 작성하던 중 프로덕션 버그 발생 stash할 필요 없이 터미널을 열고 명령어 입력:
git worktree add -b hotfix/payment-error ../hotfix-work main- VS Code나 IDE로
../hotfix-work폴더를 열고 즉시 버그 수정 후 커밋 & 푸시 - 기존 폴더로 돌아와 중단 없이 개발 계속 진행!
시나리오 B: 두 개의 브랜치 동시 구동 및 E2E 비교 테스트
- 프론트엔드 리팩토링 전(
main브랜치)과 후(refactor/ui브랜치)의 UI를 화면 양쪽에 나란히 띄워놓고 비교하고 싶을 때 매우 유용합니다. - 포트만 다르게 지정하여 두 폴더에서 동시에 서버를 구동할 수 있습니다.
(npm run dev -- --port 3000vsnpm run dev -- --port 3001)
4. Git Worktree 도입 시 체크리스트 & 주의사항
Git Worktree가 강력한 만큼, 초보자들이 실수하기 쉬운 포인트들이 있습니다.
1) 동일한 브랜치를 여러 폴더에 마운트 불가능
Git은 데이터 무결성을 위해 하나의 브랜치를 두 개 이상의 워크트리 폴더에 동시에 마운트하는 것을 차단합니다. 만약 동일한 코드를 다른 곳에서 실험하고 싶다면, 새로운 분기 브랜치(test-branch)를 만들어 마운트해야 합니다.
2) .env 등 환경 변수 파일의 공유
.git 메타데이터는 공유되지만, .gitignore에 의해 추적되지 않는 환경 변수 파일(.env.local, config.json 등)은 폴더마다 별도로 존재합니다. 새로운 워크트리를 생성했다면 필수 설정 파일이나 심볼릭 링크(Symlink)를 복사해 주어야 정상 구동됩니다.
3) IDE 및 에디터 확장 프로그램 호환성
VS Code나 JetBrains(IntelliJ, WebStorm 등) 계열 에디터는 Git Worktree를 대체로 잘 지원합니다. 다만 프로젝트 설정, 캐시, 실행 구성은 워크트리별로 다르게 동작할 수 있으므로 첫 도입 시 작은 프로젝트에서 먼저 확인하는 편이 좋습니다.
요약 및 결론
- Git Worktree는 하나의 Git 저장소를 바탕으로 여러 브랜치 폴더를 마주 보며 작업할 수 있는 강력한 기능입니다.
- 불필요한
stash,checkout, 의존성 재설치 시간을 줄여 작업 흐름을 유지하는 데 도움이 됩니다. - 여러 브랜치를 동시에 비교하거나 핫픽스를 병행해야 하는 팀이라면
git worktree add명령어를 실습해볼 만합니다.