개발 중에 “긴급 버그 수정이 생겼어! 그런데 지금 하던 작업을 stash(임시 저장)하기는 귀찮은데…”라는 경험을 해보신 적이 없으신가요?
git worktree를 사용하면 하나의 리포지토리에서 여러 작업 디렉터리(working directory)를 생성하여, 서로 다른 브랜치에서 동시에 작업을 할 수 있습니다. 특히 AI 기반 개발(Claude Code, GitHub Copilot 등)을 통해 병렬적으로 코드를 실행할 때 필수적인 기술이 되고 있습니다.
본 기사에서는 git worktree의 기본 사용법부터 실질적인 활용 방법까지 상세히 설명합니다.
git 2.5(2015년)부터 도입된 표준 기능으로, 하나의 리포지토리에 대해 여러 개의 작업 디렉터리(worktree)를 가질 수 있는 구조입니다.
# 기존 워크플로우 (번거로운 패턴)
git checkout feature-a
# feature-a에서 작업 중...
...
# worktree를 사용한 워크플로우
# feature-a에서 작업하는 상태 그대로...
git worktree add ../hotfix-bug main # 다른 디렉터리에 main 기반의 worktree 생성
...
이 세 가지만 숙지해도 일상적인 사용에는 충분합니다.
| 명령어 | 설명 |
|---|
git worktree add <path> <branch> | 새로운 worktree를 생성합니다 |
git worktree list | 모든 worktree 목록을 표시합니다 |
git worktree remove <path> | worktree를 삭제합니다 |
# worktree 생성 (기존 브랜치)
git worktree add ../feature-dir feature-branch
# worktree 생성 (새로운 브랜치를 동시에 생성)
...
개발 작업을 중단하지 않고 hotfix 대응이 가능합니다.
# 현재 feature-A에서 작업 중
git worktree add ../hotfix-urgent main
cd ../hotfix-urgent
...
리뷰 대상 브랜치를 별도의 디렉터리에서 확인할 수 있습니다.
git worktree add ../review-pr-123 origin/feature/new-api
cd ../review-pr-123
# 빌드・테스트・작동 확인
...
Claude Code나 GitHub Copilot을 여러 개 동시에 실행할 때 그 진가를 발휘합니다.
# 여러 worktree를 생성
git worktree add ../project-feature-a -b feature/api-improvement main
git worktree add ../project-feature-b -b feature/ui-update main
...
프로덕션 환경의 문제 조사 시 유용합니다.
# 태그나 커밋으로부터 worktree 생성
git worktree add ../release-v2.0 v2.0.0
cd ../release-v2.0
...
| 장점 | 설명 |
|---|
| stash 불필요 | 작업을 중단하지 않고 다른 브랜치에서 작업 가능 |
| 디스크 절약 | clone보다 가볍습니다 ('.git' 디렉터리 공유) |
| 환경 분리 | node_modules 등의 의존 관계가 섞이지 않습니다 |
| 설정 공유 | git config 등은 모든 worktree에서 공유됩니다 |
| 빠름 | clone 없이 즉시 브랜치 배포가 가능합니다 |
| 주의사항 | 설명 |
|---|
| 동일 브랜치 중복 불가 | 하나의 브랜치는 하나의 worktree로만 사용 가능합니다 |
| 수동 삭제 금지 | rm -rf로 직접 삭제하면 무결성이 손상됩니다 |
| .gitignore 대상 파일 | .env 등은 수동으로 복사해야 합니다 |
| 관리의 복잡화 | worktree가 너무 많이 늘어나면 혼란스러울 수 있습니다 |
# 메타데이터가 남아있는 경우
git worktree list
# 삭제했다고 생각한 worktree가 표시됩니다
...
# 오류: fatal: 'feature-a' is already checked out at '/path/to/worktree'
# 대처법: 기존 worktree를 확인합니다
git worktree list
...
# 메인 worktree를 이동해버린 경우 등
git worktree repair
VSCode 2025년 7월 버전부터는 기본적으로 git worktree 관리 기능이 지원되었습니다.
설정 확인
{
"git.detectWorktrees": true
}
사용 방법
- 소스 관리 보기 열기
- “...” 메뉴 → “worktree” 선택
- “worktree 추가”, “worktree 삭제” 등을 선택
명령 팔레트
Git: Open Worktree in New Window
Git: Open Worktree in Current Window
Git: Delete Worktree
| 확장 기능 이름 | 특징 |
|---|
| Git Worktree Manager | GUI에서 직관적으로 worktree 관리 |
| Switch Git Worktree | 원클릭으로 worktree 전환 |
| Git Graph | 브랜치 구조 시각화 (보조적으로 유용) |
패턴 1: 형제 디렉터리 (권장)
~/repos/
├── my-project/ # 메인 리포지토리 (main)
├── my-project-feature-a/ # worktree
...
패턴 2: 전용 디렉터리에 모으기
~/repos/
├── my-project/ # 메인 리포지토리
└── my-project.worktrees/ # worktree 전용
...
주의: .git 내부에는 worktree를 생성하는 것이 좋지 않습니다 (NG). Git의 메타데이터와 혼동되어 파일이 삭제될 가능성이 있습니다.
명명 규칙 통일하기- 예:
<project>-<branch-type>-<name>
, myapp-hotfix-bug123
정기적으로 prune 하기 git worktree prune
잠금 기능 활용하기- 네트워크 드라이브나 클라우드 스토리지를 사용할 때
git worktree lock ../feature-dir --reason "외장 HDD에 저장 중"
불필요한 worktree는 즉시 삭제- 관리가 복잡해지지 않도록
여러 worktree를 일괄 생성/삭제하는 스크립트입니다.
#!/bin/bash
# setup-worktrees.sh
PROJECT_NAME="my-project"
...
사용 예시
./setup-worktrees.sh feature-api feature-ui feature-test
| 항목 | 내용 |
|---|
| 추천도 | ★★★★★ |
| 도입 난이도 | 초급~중급 |
| 필수 명령어 | add / list / remove |
| 특히 유효한 상황 | 긴급 대응, PR 리뷰, AI 병렬 실행 |
git worktree는 특히 AI 기반 개발이 일반화된 현재에 있어 필수적인 기술입니다.
- stash의 번거로움에서 해방될 수 있습니다.
- 여러 작업을 안전하게 병행할 수 있습니다.
- VSCode와의 연동도 충실합니다.
꼭 일상적인 개발에 도입하여 효율적인 개발 라이프를 보내시길 바랍니다!
