Git worktree가 필요한 상황

한 저장소에서 기능 개발, 긴급 버그 수정, 코드 리뷰 대응을 번갈아 처리하면 브랜치를 계속 전환하게 됩니다. 이 과정에서 아직 커밋하지 않은 변경이 남아 있거나, 빌드 결과물과 의존성이 서로 달라 충돌하기 쉽습니다. Git worktree는 하나의 Git 저장소 객체를 공유하면서도 브랜치마다 별도의 작업 폴더를 만드는 기능입니다. 즉, 메인 작업은 그대로 둔 채 다른 폴더에서 hotfix 브랜치를 열거나, PR 검증 브랜치를 병렬로 확인할 수 있습니다.

worktree는 저장소를 복제하는 방식과 다릅니다. 커밋, 객체 데이터, 원격 저장소 설정은 기존 저장소를 공유하므로 전체 이력이 중복되지 않습니다. 다만 각 작업 폴더의 체크아웃 파일, 빌드 캐시, 환경 파일은 분리됩니다. 따라서 서로 다른 Node.js 의존성이나 Java 빌드 결과가 필요한 작업에도 적합합니다.

작업 폴더 만들기

먼저 기준 저장소에서 최신 원격 정보를 가져오고, 별도 폴더에 새 브랜치를 만들면서 worktree를 추가합니다. worktree 경로는 저장소 바깥의 형제 디렉터리로 두면 구조를 이해하기 쉽습니다. 예를 들어 현재 저장소가 service라면 ../service-hotfix-login처럼 만듭니다.

cd ~/projects/service
git fetch origin
git worktree add -b hotfix/login-timeout ../service-hotfix-login origin/main
cd ../service-hotfix-login
git status
git branch --show-current

위 명령은 origin/main을 기반으로 hotfix/login-timeout 브랜치를 생성하고 해당 브랜치를 새 폴더에 체크아웃합니다. 이미 존재하는 로컬 브랜치를 별도 폴더에서 열고 싶다면 -b 없이 git worktree add ../service-review feature/payment처럼 실행합니다. 같은 브랜치를 일반적으로 두 worktree에 동시에 체크아웃할 수는 없으므로, 작업 시작 전에 어느 폴더가 해당 브랜치를 사용 중인지 확인해야 합니다.

실무 운영 구조와 점검 명령

개발 중인 기능은 원래 폴더에 두고, 운영 장애 수정은 worktree에서 처리하는 방식이 안전합니다. 급한 수정이 끝난 뒤 원래 작업 폴더로 돌아갈 때는 stash나 브랜치 전환이 필요하지 않습니다. 코드 리뷰가 길어지는 PR도 전용 worktree에 체크아웃해 두면 재현, 테스트, 수정 제안을 독립적으로 수행할 수 있습니다.

# 현재 연결된 worktree와 브랜치 확인
git worktree list

# PR 검증용 브랜치를 새 폴더에 생성
git worktree add -b review/order-api ../service-review-order origin/feature/order-api

# 각 폴더에서 독립적으로 설치·테스트
cd ../service-review-order
npm ci
npm test

목록에는 worktree 경로, 연결된 커밋, 브랜치가 표시됩니다. 배포 전 확인용 worktree에서는 의존성 설치와 테스트 명령을 그 폴더 안에서 실행해야 합니다. node_modules, Gradle 캐시 산출물, Python 가상환경처럼 프로젝트 안에 생성되는 파일은 다른 worktree와 공유되지 않습니다. 반대로 사용자 전역 캐시나 Docker 데몬, 로컬 데이터베이스는 공유될 수 있으므로 포트와 테스트 데이터베이스 이름을 분리하는 것이 좋습니다.

환경 파일과 IDE 설정 주의점

.env 파일이 Git에서 제외되어 있다면 새 worktree에는 자동으로 생기지 않습니다. 민감한 값을 복사하는 대신 팀의 안전한 개발 환경 절차에 따라 비밀 관리 도구나 로컬 템플릿에서 주입해야 합니다. 최소한 .env.example을 유지하고, 필요한 환경 변수와 포트 값을 문서화하면 새 worktree 준비 시간을 줄일 수 있습니다. 동시에 실행하는 서버는 API 포트, 프론트엔드 개발 서버 포트, Compose 프로젝트 이름이 겹치지 않게 설정합니다.

# worktree별 포트 예시
APP_PORT=3002
VITE_PORT=5174
COMPOSE_PROJECT_NAME=service_review_order
DATABASE_URL=postgresql://app:password@localhost:5432/service_review_order

IDE도 폴더별로 별도 창을 열어야 언어 서버와 실행 구성이 섞이지 않습니다. JetBrains 계열의 실행 구성이나 VS Code의 디버그 포트가 충돌하면, 각 worktree의 설정 파일 또는 개인 설정에서 포트를 바꿉니다. 파일 감시 도구가 여러 폴더를 동시에 감시하면 CPU 사용량이 올라갈 수 있으므로, 당장 사용하지 않는 개발 서버는 종료합니다.

정리와 삭제를 안전하게 처리하기

병합 또는 배포가 끝난 worktree는 먼저 변경 사항이 없는지 확인한 뒤 제거합니다. 작업 폴더를 Finder나 쉘에서 먼저 삭제하지 말고 Git 명령으로 연결 정보를 정리하는 것이 원칙입니다. 폴더가 외부 이유로 사라졌다면 prune 명령으로 오래된 참조만 정리할 수 있습니다.

cd ~/projects/service
git -C ../service-hotfix-login status
git worktree remove ../service-hotfix-login
git branch -d hotfix/login-timeout

# 사라진 경로의 관리 정보 정리
git worktree prune
git worktree list

미커밋 변경이 있으면 remove가 중단됩니다. 이때 변경을 커밋하거나 검토한 뒤 처리하고, 정말 폐기할 변경일 때만 강제 제거 여부를 판단합니다. 브랜치를 삭제하기 전에는 원격 PR 병합 상태와 필요한 커밋이 다른 브랜치에 반영됐는지도 확인해야 합니다.

운영 체크리스트

  • 기능 개발, 긴급 수정, 리뷰 작업마다 목적이 분명한 브랜치와 worktree 경로를 사용한다.
  • 새 worktree에서 환경 파일, 포트, 테스트 데이터베이스를 독립적으로 준비한다.
  • git worktree list로 브랜치가 어느 폴더에 연결됐는지 수시로 확인한다.
  • 완료된 작업은 Git 명령으로 제거하고, 변경 사항과 병합 상태를 확인한 후 브랜치를 정리한다.
  • 동시 실행하는 서버와 IDE 디버거의 포트 충돌을 배포 전 테스트 항목에 포함한다.

Git worktree는 브랜치 전환 횟수를 줄이는 편의 기능을 넘어, 긴급 대응과 병렬 검증을 안전하게 분리하는 작업 방식입니다. 팀의 브랜치 규칙, 환경 변수 관리, 종료 절차와 함께 표준화하면 전환 비용과 실수 가능성을 함께 낮출 수 있습니다.