빠른 흐름
# 새 worktree 추가 (브랜치가 없으면 -b로 생성)
git worktree add ../project-hotfix hotfix/login-bug
# worktree 목록 확인
git worktree list
# 작업 완료 후 worktree 제거
git worktree remove ../project-hotfix기본 흐름
어떤 병렬 작업 방식을 먼저 떠올리면 되나
| 상황 | 먼저 떠올릴 선택 |
|---|---|
| 브랜치 전환 없이 두 작업을 동시에 열기 | git worktree add |
| 기존 저장소 하나로 여러 작업 트리 관리 | worktree |
| 짧은 컨텍스트 전환 | stash보다 worktree 검토 |
| 작업 끝난 worktree 정리 | git worktree remove |
worktree가 해결하는 문제 — 브랜치 전환은 컨텍스트 전환 비용을 동반한다
보통 하나의 저장소 디렉터리에서는 한 브랜치만 checkout해 두고 작업한다. 다른 브랜치로 이동하려면 stash를 쌓거나 임시 커밋을 남기고 checkout해야 한다. 대규모 프로젝트에서는 브랜치 전환 자체가 빌드 캐시를 무효화하거나 IDE가 전체 파일을 재인덱싱하는 비용을 만들기도 한다. git worktree add는 같은 Git 객체 데이터베이스(.git/)를 공유하면서 별도 작업 디렉터리를 만들어, 브랜치마다 독립된 작업 공간을 갖게 한다. 저장소 파일을 복제하지 않으므로 디스크 비용도 낮다.
worktree의 내부 구조 — 하나의 .git이 여러 작업 트리를 관리한다
main worktree는 .git/ 디렉터리를 가진 원래 저장소다. git worktree add로 추가된 linked worktree는 .git 파일(디렉터리가 아니라 파일)을 갖고 이것이 main worktree의 .git/worktrees/<name>/ 폴더를 가리킨다. 모든 worktree가 같은 객체 데이터베이스와 ref를 공유하므로, 한 worktree에서 커밋한 내용이 다른 worktree에서도 즉시 보인다. 단, 같은 브랜치를 두 worktree에서 동시에 checkout할 수는 없다. 이를 시도하면 "already checked out" 오류가 발생한다.
worktree가 실무에서 유용한 시나리오 — stash 남발을 줄이는 대안이다
feature 브랜치에서 작업 중 hotfix 요청이 들어왔을 때, stash를 쌓고 브랜치를 바꾸는 대신 git worktree add ../hotfix hotfix/login-bug로 별도 폴더를 열면 기존 작업을 그대로 두고 hotfix를 처리할 수 있다. release 브랜치와 main 브랜치를 나란히 열어 두고 차이를 직접 비교하거나, PR 리뷰를 위해 리뷰 대상 브랜치를 별도 폴더에서 실행해 보는 상황도 worktree가 편리하다. 핵심은 "브랜치 전환"을 "작업 공간 분리"로 대체해 사고를 단순하게 만드는 것이다.
# 기존 작업 유지
/project -> feature/login
# 별도 폴더에서 hotfix
/project-hotfix -> hotfix/login-bugworktree 사용 시 주의할 점 — 폴더와 브랜치 대응 관계를 명확히 유지해야 한다
여러 작업 디렉터리가 생기면 "지금 이 폴더가 어떤 브랜치인가"를 혼동하기 쉽다. 경로 이름(../project-hotfix)과 브랜치 이름(hotfix/login-bug)을 일관되게 대응시키는 네이밍 규칙이 도움이 된다. 작업을 마친 worktree는 git worktree remove <path>로 정리해야 .git/worktrees/ 아래의 관련 메타데이터도 함께 제거된다. 그냥 디렉터리를 삭제하면 git worktree list에 "prunable" 상태로 남고, git worktree prune으로 정리할 수 있다.
선택 기준
| 상황 | 적합한 선택 |
|---|---|
| hotfix를 처리하면서 feature 작업을 보존하고 싶다 | git worktree add ../hotfix <branch> |
| 두 브랜치를 나란히 열어 비교하고 싶다 | 각각 다른 경로에 worktree 추가 |
| 현재 활성화된 worktree 목록 확인 | git worktree list |
| 작업 완료 후 worktree 정리 | git worktree remove <path> |
| 삭제된 폴더에 대한 메타데이터 정리 | git worktree prune |
주의할 점
같은 브랜치를 두 worktree에서 동시에 checkout할 수 없습니다. 이를 시도하면
"already checked out" 오류가 발생합니다. 또한 worktree를 디렉터리만 삭제하면
.git/worktrees/ 안의 메타데이터가 남아 있으므로, 반드시 git worktree remove
또는 git worktree prune으로 정리하세요.
git worktree add ../project-main main
git worktree add ../project-main-2 main
# fatal: 'main' is already checked out at '/Users/.../project-main'참고 링크
1 sources