git worktree는 한참 동안 “있긴 한데 잘 안 쓰는 명령” 취급을 받아왔다. 그러던 것이 2026년 들어 분위기가 크게 달라졌다. PhpStorm 2026.1이 Git Worktrees 1급 지원을 발표했고, Claude Code와 Cursor가 다중 에이전트 병렬 실행을 worktree 기반으로 권장하면서 갑자기 모두가 이 기능을 다시 들여다보고 있다. 이번 포스팅에서는 Git Worktrees를 실전에서 어떻게 쓰는지 정리하고자 한다. 8개 서브 명령의 정확한 시그니처, 긴급 핫픽스·코드 리뷰·AI 에이전트 병렬 실행 같은 구체적 시나리오, IDE 통합과 흔한 함정까지 한 번에 다룬다. git checkout으로 브랜치를 갈아타다가 작업 흐름이 끊긴 경험이 있다면 이 글이 도움이 된다.
왜 git worktree가 필수가 되었나
Git Worktrees가 주목받는 이유는 두 가지다. 첫째, AI 코딩 에이전트의 병렬 실행 패턴이 표준이 되었다. Claude Code --worktree(단축형 -w) 플래그, Cursor 3의 “Parallel Agents” 기능(최대 8개 병렬), parallel-code 같은 도구가 모두 worktree를 기반으로 동작한다. 둘째, IDE가 본격적으로 1급 시민으로 대접하기 시작했다. PhpStorm 2026.1은 Git Worktrees 통합 UI를 추가했고, VS Code도 2025년 7월(1.103)부터 worktree 지원을 더해 2025년 12월(1.108)에는 Source Control 뷰에 Worktrees 노드까지 추가했다.
# 컨텍스트 스위칭 비용을 보여주는 통상적 시나리오
$ git status # 현재 작업 중인 변경사항 확인
$ git stash push -m "WIP" # 임시 보관
$ git checkout main # 메인 브랜치로 전환
$ git pull # 최신 코드 받기
$ git checkout -b hotfix/x # 핫픽스 브랜치 생성
# ... 핫픽스 완료 후 ...
$ git checkout feature/y # 원래 브랜치로 복귀
$ git stash pop # 임시 보관한 변경 복원위 명령 시퀀스는 한 번 실행할 때마다 평균 10~15분의 컨텍스트 스위칭 비용을 발생시킨다. IDE의 인덱싱이 다시 돌아가고, 빌드 캐시가 무효화되며, 머릿속 작업 컨텍스트가 흐려진다. Git Worktrees는 이 시퀀스 전체를 cd ../hotfix-x 한 줄로 대체한다. 두 디렉터리가 같은 .git 데이터를 공유하지만 서로 다른 브랜치를 동시에 체크아웃한 채 독립적으로 작업할 수 있다.
git worktree는 정확히 무엇이고 어떻게 동작하나
Git Worktrees는 “하나의 저장소에서 여러 작업 디렉터리를 동시에 운영하는 메커니즘”이다. 각 worktree는 독립된 작업 트리(working tree)를 가지지만 .git 디렉터리(객체 데이터·refs)를 공유한다. 메인 worktree는 git init이나 git clone으로 만들어진 최초의 디렉터리이고, 링크된 worktree는 git worktree add로 추가된다.
$ git worktree list
/home/user/projects/myapp abcd123 [main]
/home/user/projects/myapp-hotfix 5678efg [hotfix/auth]
/home/user/projects/myapp-experiment 9012hij (detached HEAD)위 명령은 현재 저장소에 연결된 worktree 3개를 보여준다. 각 행은 경로, HEAD 해시, 체크아웃된 브랜치 정보다. 같은 저장소를 가리키지만 각 디렉터리는 서로 다른 브랜치를 가지고 있고, 한쪽 변경이 다른 쪽에 즉시 영향을 주지 않는다.
.git/
├── HEAD
├── objects/ # 모든 worktree가 공유
├── refs/heads/ # 모든 worktree가 공유
└── worktrees/ # per-worktree 메타데이터
├── myapp-hotfix/
│ ├── HEAD # per-worktree
│ ├── index # per-worktree
│ └── gitdir # 실제 worktree 경로 기록
└── myapp-experiment/
├── HEAD
├── index
└── gitdir위 디렉터리 트리는 Git Worktrees의 내부 구조다. objects/와 refs/heads/는 모든 worktree가 공유하므로 한 worktree에서 git fetch를 실행하면 다른 worktree에서도 즉시 새 커밋이 보인다. 반면 HEAD와 index는 worktree마다 분리되어 있어 각자 독립된 staging 영역을 가진다. 이 구조 덕분에 같은 저장소에서 6개의 브랜치를 동시에 체크아웃해도 디스크 사용량은 작업 트리 크기만큼만 늘어난다.
5분 안에 끝내는 Git Worktrees 핵심 명령
Git Worktrees는 8개 서브 명령을 가지지만 실무에서 90%는 add / list / remove 세 개로 끝난다. 가장 흔한 시나리오인 “긴급 핫픽스”를 예로 들면 아래 4단계가 전부다. 현재 작업 중인 feature 브랜치를 그대로 둔 채, 메인 브랜치에서 핫픽스를 만들고 다시 돌아온다.
# 1. 현재 디렉터리는 그대로 두고, 메인 브랜치 기반 hotfix worktree 추가
$ git worktree add -b hotfix/login-bug ../myapp-hotfix main
# 2. 새 디렉터리로 이동해 작업
$ cd ../myapp-hotfix
$ vim src/auth.js
$ git commit -am "Fix login redirect bug"
$ git push -u origin hotfix/login-bug
# 3. 원래 작업 디렉터리로 복귀 (feature 브랜치는 그대로)
$ cd -
# 4. 핫픽스 머지가 끝났다면 worktree 제거
$ git worktree remove ../myapp-hotfix
$ git branch -d hotfix/login-bug위 시퀀스의 핵심은 git worktree add -b <new-branch> <path> <base> 형태다. -b 옵션이 새 브랜치를 만들고, 두 번째 인수가 worktree 디렉터리 경로, 세 번째가 분기 기준이다. 작업이 끝나면 git worktree remove <path>로 worktree 디렉터리를 정리하고 git branch -d로 로컬 브랜치까지 지우는 것이 깔끔하다. 이 패턴 하나만 익혀도 stash·checkout·pop 사이클 자체가 사라진다.
8개 서브 명령 한눈에 정복
Git Worktrees의 전체 서브 명령은 add, list, lock, move, prune, remove, repair, unlock의 8개다. 공식 문서 기준으로 각 명령의 핵심 시그니처와 실용 옵션을 정리하면 다음과 같다.
| 명령 | 핵심 시그니처 | 주요 옵션 | 사용 시점 |
|---|---|---|---|
| add | git worktree add [-b NEW] PATH [COMMITISH] | -b, -d, --lock, -f | 새 worktree 생성 |
| list | git worktree list [-v|--porcelain] | -v, --porcelain, -z | 현황 조회 |
| lock | git worktree lock [--reason TEXT] PATH | --reason | 외장 디스크/공유 보호 |
| move | git worktree move PATH NEWPATH | -f | worktree 디렉터리 이동 |
| prune | git worktree prune [-n] [-v] | -n, --expire 2.weeks | 누락된 worktree 정리 |
| remove | git worktree remove [-f] PATH | -f, -f -f | worktree 삭제 |
| repair | git worktree repair [PATH...] | (인수만) | 경로 손상 복구 |
| unlock | git worktree unlock PATH | (인수만) | 잠금 해제 |
# add: 다양한 변형
$ git worktree add ../my-feature # 디렉터리 이름과 같은 브랜치 자동 생성
$ git worktree add ../my-bugfix bugfix/x # 기존 브랜치 체크아웃
$ git worktree add -d ../tmp HEAD~5 # 분리된 HEAD로 과거 커밋 검토
$ git worktree add --lock --reason "USB" /mnt/usb/backup main
# prune: 디렉터리만 수동 삭제했을 때 메타데이터 청소
$ git worktree prune -n -v # 무엇이 정리될지 미리 확인
$ git worktree prune --expire 2.weeks # 2주 이상 누락된 것만
# repair: 메인 worktree를 mv로 옮겼을 때 복구
$ cd /new/path/myapp
$ git worktree repair # 모든 링크 자동 복구위 예시 중 --lock --reason 조합은 USB 드라이브나 NAS 같은 분리 가능 저장소에 worktree를 만들 때 유용하다. 잠금이 걸려 있으면 prune이 실수로 메타데이터를 지우지 않는다. repair는 잘 알려지지 않았지만 한 번 잘못 옮긴 디렉터리를 살릴 때 유일한 방법이다. mv 대신 항상 git worktree move를 쓰는 습관을 들이면 repair를 호출할 일이 거의 없다.
AI 에이전트 시대의 Git Worktrees 병렬 실행 패턴
2026년의 Git Worktrees 활용 사례 가운데 가장 빠르게 확산되는 것이 AI 에이전트 병렬 실행이다. Claude Code 공식 문서는 자체 --worktree(-w) 플래그를 지원하며, 이 플래그가 <repo>/.claude/worktrees/<이름>/ 경로에 worktree를 자동 생성하고 그 안에서 세션을 시작한다. Cursor 3의 “Parallel Agents” 기능도 내부적으로 worktree를 만들어 에이전트마다 별도 작업 트리를 할당한다. parallel-code, ccmanager 같은 오픈소스 도구는 같은 코드베이스 위에서 여러 AI 에이전트 세션을 동시 실행하는 패턴을 표준화하고 있다.
# 패턴 1: Claude Code 자체 --worktree 플래그 (가장 간단)
$ claude --worktree feature-auth
$ claude --worktree dashboard-build
$ claude --worktree api-tests
# 위 명령은 .claude/worktrees/<이름>/ 디렉터리를 자동 생성하고
# worktree-<이름> 브랜치에서 세션을 시작한다.
# 변경 없이 종료하면 worktree와 브랜치가 자동 정리된다.위 패턴은 Claude Code 공식 권장 방식이다. git worktree add나 cd를 직접 칠 필요가 없고, 세션 종료 시 변경이 없으면 worktree까지 자동으로 청소된다. .claude/worktrees/를 .gitignore에 등록해 두는 것을 권장한다. 같은 코드베이스에서 동시에 인증 모듈 리팩터링, 대시보드 신기능 구현, API 테스트 보강을 따로 진행시킬 때 가장 빠르게 시작할 수 있다.
# 패턴 2: 수동 git worktree + 외부 도구 결합
$ git worktree add -b agent/auth-refactor ../myapp-auth main
$ git worktree add -b agent/dashboard-build ../myapp-dash main
# 각 worktree에서 별도 터미널로 도구 실행
$ (cd ../myapp-auth && claude) # Claude Code 세션 시작
$ (cd ../myapp-dash && cursor .) # Cursor 인스턴스 열기위 패턴은 IDE나 도구를 섞어 쓸 때 유용하다. Claude Code는 claude 명령으로 현재 디렉터리에서 시작하고, Cursor는 cursor .로 동일하게 시작한다. 한 worktree에는 Claude Code, 다른 worktree에는 Cursor를 띄워 두면 도구별 강점을 동시에 활용할 수 있다.
# 패턴 3: 자동화 스크립트로 worktree 병렬 부트스트랩
#!/usr/bin/env bash
TASKS=("auth-refactor" "dashboard-build" "api-tests")
for task in "${TASKS[@]}"; do
path="../myapp-${task}"
branch="agent/${task}"
# worktree 생성 (이미 있으면 건너뜀)
git worktree add -b "$branch" "$path" main 2>/dev/null || true
# headless 모드(-p)로 백그라운드 실행
(cd "$path" && claude -p "$task 작업을 수행하고 변경 사항을 커밋해 주세요" &)
done
wait
echo "모든 에이전트 작업이 완료되었습니다."위 스크립트는 TASKS 배열을 늘리면 그대로 N개 에이전트로 확장된다. claude -p는 headless 모드로 프롬프트를 한 번 실행하고 종료하므로 백그라운드 일괄 작업에 적합하다. 2>/dev/null || true 덕분에 같은 브랜치가 이미 worktree로 잡혀 있어도 스크립트가 멈추지 않는다. 마지막 wait이 모든 백그라운드 에이전트가 끝날 때까지 기다린다.
IDE에서 Git Worktrees 다루는 법
IDE 통합은 2026년 4월 기준으로 제품마다 격차가 크다. PhpStorm 2026.1과 VS Code는 비교적 매끄럽지만, IntelliJ IDEA·WebStorm 같은 다른 JetBrains 제품은 아직 외부 명령에 의존해야 한다. Claude Code의 /ide 명령처럼 worktree 인식이 안 되는 도구도 있어 통합 상태를 알고 시작하는 것이 중요하다.
# PhpStorm 2026.1: VCS 메뉴에서 직접 생성·전환 가능
# (외부 명령 사용 시)
$ phpstorm ../myapp-hotfix & # 새 worktree를 별도 IDE 창으로 열기
# IntelliJ IDEA / WebStorm: 외부 명령 + 멀티 프로젝트 창
$ idea ../myapp-hotfix &
# VS Code: 워크스페이스로 등록하면 사이드바에서 전환
$ code ../myapp-hotfix
$ code --add ../myapp-hotfix # 기존 창에 폴더 추가위 명령은 IDE에 worktree를 인식시키는 방법이다. PhpStorm 2026.1은 “VCS → Git → Worktrees” 메뉴에서 worktree를 직접 만들고 전환할 수 있어서 명령행을 거의 쓰지 않게 된다. IntelliJ나 WebStorm을 쓴다면 worktree마다 별도 IDE 창을 띄우는 멀티-인스턴스 패턴이 무난하다. VS Code는 --add 옵션으로 같은 창에 여러 worktree를 폴더로 묶어 사이드바에서 빠르게 전환할 수 있다. 다만 빌드 캐시가 분리된다는 점은 IDE를 분리하는 패턴의 단점이라 PR 단위 작업이 잦은 환경에서는 worktree 디렉터리에 빌드 캐시를 공유하는 심볼릭 링크를 두기도 한다.
흔히 마주치는 Git Worktrees 함정과 해결책
Git Worktrees를 처음 도입할 때 마주치는 함정은 정해져 있다. 다행히 모두 한 줄짜리 명령으로 해결된다. 같은 브랜치를 두 worktree에서 체크아웃하려고 하면 git이 거부하는데, 이는 의도된 안전장치다. 미정리 파일이 남아 있는 worktree를 remove하면 데이터 손실 가능성이 있어 git이 막는다. 디렉터리만 수동으로 지우면 메타데이터가 남아 list에 죽은 항목이 표시된다.
# 함정 1: 같은 브랜치 중복 체크아웃 시도
$ git worktree add ../another-main main
fatal: 'main' is already checked out at '/home/user/projects/myapp'
# 해결: 같은 브랜치를 정말 두 worktree에서 보고 싶다면 detach
$ git worktree add -d ../readonly-main main
# 함정 2: 디렉터리만 rm 한 뒤 list에 유령이 남는 경우
$ rm -rf ../myapp-hotfix
$ git worktree list
/home/user/projects/myapp abcd123 [main]
/home/user/projects/myapp-hotfix 5678efg [hotfix/x] (prunable)
# 해결: prune 실행
$ git worktree prune -v
Removing worktrees/myapp-hotfix: gitdir file points to non-existent location
# 함정 3: 미정리 파일 때문에 remove 실패
$ git worktree remove ../myapp-experiment
fatal: '../myapp-experiment' contains modified or untracked files
# 해결: 의도한 변경이 없으면 -f, 잠금까지 풀려면 -f -f
$ git worktree remove -f ../myapp-experiment위 사례에서 가장 흔한 것이 함정 2다. 디렉터리 정리를 rm -rf로 끝내면 git worktree list에 (prunable) 표시가 남는다. 이때 git worktree prune을 실행하지 않으면 같은 경로에 새 worktree를 만들 때 충돌이 발생한다. 함정 1은 의도된 안전장치이므로 우회하려면 -d(detached HEAD)를 쓰는 것이 정석이다. 함정 3은 -f 한 번이면 충분하지만 변경 내용을 한 번 더 확인하는 습관을 들이는 게 좋다.
FAQ
Git Worktrees는 git submodule과 어떻게 다른가?
submodule은 다른 저장소의 코드를 현재 저장소의 일부로 가져오는 메커니즘이고, Git Worktrees는 같은 저장소를 여러 작업 디렉터리에서 동시에 보는 메커니즘이다. submodule은 저장소가 다르고 worktree는 저장소가 같다. 두 개념은 직교하므로 한 저장소가 submodule을 포함하면서 동시에 worktree로 분기될 수 있다. 다만 submodule이 있는 worktree는 git worktree move로 이동할 수 없다는 제약이 있다.
같은 코드베이스에서 동시에 몇 개의 Git Worktrees를 운영해도 괜찮은가?
기술적 상한은 없다. 디스크 용량과 IDE의 인덱싱 부담이 실질적 한계다. 코드베이스가 1GB이고 빌드 산출물까지 포함해 worktree 1개가 3GB라면 10개 worktree는 30GB를 차지한다. AI 에이전트 병렬 실행 사례에서는 보통 4~8개 worktree가 가장 흔하고, parallel-code 같은 멀티 에이전트 도구는 10개 이상을 동시에 운영하는 사례를 보고했다.
Git Worktrees가 만든 브랜치는 push할 때 일반 브랜치와 똑같이 다뤄지는가?
같다. worktree는 로컬 작업 트리 운영 방식일 뿐이고 원격에 영향을 주지 않는다. git push -u origin hotfix/x 같은 명령은 worktree 안에서 실행해도 메인 디렉터리에서 실행해도 결과가 동일하다. 다른 worktree에서 git fetch를 실행하면 모든 worktree의 원격 추적 브랜치가 한꺼번에 갱신된다.
Git Worktrees와 git stash 중 어느 쪽을 써야 하나?
작업이 1시간 미만이고 한 가지 작은 변경만 임시 보관할 때는 stash가 가볍다. 그러나 핫픽스가 30분 이상 걸리거나 동시에 두 작업을 오가야 한다면 Git Worktrees가 압도적으로 낫다. stash는 IDE 인덱싱·빌드 캐시·실행 중 프로세스를 보존하지 못해 컨텍스트 복귀 비용이 크다. worktree는 디렉터리째 보존되므로 IDE를 그대로 두고 다른 디렉터리만 새 창에서 열면 된다.
Git Worktrees 도입 후 .gitignore나 빌드 캐시는 어떻게 관리해야 하나?
각 worktree는 독립된 작업 트리이므로 node_modules나 target/ 같은 빌드 산출물도 별도로 생성된다. 디스크가 빠듯하다면 빌드 캐시 디렉터리를 심볼릭 링크로 공유하는 패턴이 일반적이다. 다만 동시 빌드 시 충돌 가능성이 있으므로 한 번에 하나의 worktree에서만 빌드되는 것을 보장해야 한다. .gitignore는 모든 worktree가 같은 refs/heads/*를 공유하므로 자동으로 동일하게 적용된다.
마치며
지금까지 Git Worktrees를 실전 시점에서 정리해 보았다. 처음 worktree를 도입했을 때 가장 인상 깊었던 변화는 “메인 브랜치에서 PR 리뷰하면서 동시에 feature 브랜치에서 작업할 수 있다”는 단순한 사실이었다. 예전엔 PR 코드를 보려고 stash·checkout·pop 사이클을 돌릴 때마다 IDE 인덱싱이 다시 돌아 1~2분을 멍하니 기다렸는데, worktree로 바꾸고 나서는 디렉터리만 새 IDE 창에서 열면 그만이라 리뷰 빈도 자체가 늘었다. 최근 Claude Code로 백그라운드 작업을 돌릴 때도 worktree마다 다른 에이전트를 띄워 두면 머지 충돌이 거의 사라져서 이제는 worktree 없는 워크플로우로 돌아갈 수 없게 되었다. git checkout으로 브랜치를 갈아탈 때마다 작업 흐름이 끊기는 게 익숙해졌다면, 한 번쯤은 worktree를 도입해 보길 권한다.