git worktree란? AI 에이전트 시대에 다시 주목받는 이유

핵심 요약: git worktree는 저장소 하나의 여러 브랜치를 각각 다른 폴더에 동시에 체크아웃하는 git 내장 기능입니다(2015년부터 있던 기능). 핵심 명령 셋: git worktree add ../폴더 브랜치 / list / remove. clone과 달리 .git 데이터를 공유해서 가볍고, stash 없이 브랜치를 "이동"이 아니라 "병행"할 수 있습니다. 10년째 조용하던 이 기능이 요즘 다시 주목받는 이유는 하나 — AI 에이전트 여럿을 같은 저장소에서 병렬로 돌릴 때 서로 파일을 덮어쓰지 않게 하는 표준 격리 수단이 됐기 때문입니다. Orca·Cursor 등 병렬 에이전트 도구들이 전부 이 위에 서 있습니다.

이 글에서 다루는 내용: worktree의 동작 원리, 기본 명령, clone·stash와의 비교, 에이전트 시대에 갖는 의미, 주의점.

동작 원리: 하나의 .git, 여러 개의 작업 폴더

일반적으로 저장소 하나 = 폴더 하나 = 체크아웃 하나입니다. worktree는 이 등식을 풀어서, 같은 .git(커밋·객체 저장소)을 공유하는 추가 작업 폴더를 만듭니다. 폴더마다 다른 브랜치를 체크아웃할 수 있고, 어느 폴더에서 커밋하든 같은 저장소 히스토리에 쌓입니다. 복제(clone)와 결정적으로 다른 점 — 데이터를 공유하므로 디스크를 거의 안 먹고, fetch도 한 번이면 모든 worktree에 반영됩니다.

기본 명령 3개

# 새 worktree 만들기 (새 브랜치와 함께)
git worktree add ../myrepo-feature -b feature/login

# 현재 worktree 목록
git worktree list

# 다 쓴 worktree 정리
git worktree remove ../myrepo-feature

알아둘 규칙 하나: 같은 브랜치를 두 worktree에 동시에 체크아웃할 수는 없습니다. "한 브랜치 = 한 작업 폴더"가 강제되는데, 이 제약이 오히려 병렬 작업의 안전장치가 됩니다.

언제 쓰나: 전통적 용도

에이전트 이전에도 쓸모는 있었습니다 — 기능 개발 중 급한 핫픽스가 들어왔을 때 stash·커밋 없이 옆 폴더에서 처리하기, 리뷰할 PR을 내 작업과 별도 폴더에 받아 실행해보기, 브랜치 간 동작 비교(두 폴더에서 각각 서버 띄우기). "브랜치 전환 비용" — stash 지옥, 빌드 캐시 초기화, IDE 인덱스 재생성 — 을 없애는 기능이라고 정리하면 됩니다.

에이전트 시대의 재발견

병렬 에이전트의 최대 난제는 격리입니다 — 에이전트 둘이 같은 폴더에서 일하면 서로의 변경을 덮어쓰고, 한쪽 빌드가 다른 쪽 테스트를 깨뜨립니다. worktree는 이 문제의 기성 해답이었습니다: 에이전트마다 worktree 하나씩 주면, 같은 저장소에서 일하되 물리적으로 안 겹칩니다. 그래서 Orca(소개)는 아예 worktree를 제품의 뼈대로 삼았고, Cursor의 병렬 에이전트(Agents Window)도 실행 위치 옵션으로 worktree를 제공합니다. 도구 없이 수동으로도 같은 구성이 됩니다 — 터미널 두 개에 worktree 두 개, 각각 Claude Code를 띄우면 그게 수제 병렬 관제입니다(조합 워크플로의 확장판).

주의점

의존성 폴더는 공유 안 됩니다 — node_modules, venv는 worktree마다 새로 설치해야 합니다(디스크·시간 비용은 여기서 발생). 환경 파일도 각자 — .env 같은 비추적 파일은 worktree에 없으므로 복사 스크립트를 마련해두면 편합니다. 정리 습관 — 다 쓴 worktree를 방치하면 브랜치·폴더가 쌓입니다. git worktree list를 주기적으로. 그리고 에이전트에게 worktree를 맡길 때는 어느 폴더가 "진짜" 작업인지 사람이 추적해야 합니다 — 도구(Orca 등)를 쓰는 이유가 결국 이 추적의 자동화입니다.

자주 묻는 질문 (FAQ)

Q. clone을 여러 개 하는 것과 뭐가 다른가요?

A. worktree는 .git 데이터를 공유해 디스크를 거의 안 쓰고, fetch·브랜치·스태시가 한 저장소로 통합 관리됩니다. clone 여러 개는 각각 독립 저장소라 동기화를 사람이 챙겨야 합니다.

Q. 오래된 git에서도 되나요?

A. git 2.5(2015년)부터 있는 기능이라 사실상 모든 현역 환경에서 됩니다. 다만 초기 버전보다 최신 git이 세부 동작이 다듬어져 있으니 업데이트를 권합니다.

Q. 에이전트 병렬용으로 worktree를 직접 관리할까요, 도구를 쓸까요?

A. 동시 2개 수준이면 수동(터미널 2개)으로 충분하고, 그 이상이 일상이 되면 생성·추적·정리를 대신해주는 도구가 시간을 법니다.

한눈에 보는 요약

worktree = 한 저장소, 여러 작업 폴더. add/list/remove 세 명령이 전부이고, 의존성 재설치와 정리 습관만 챙기면 됩니다. 병렬 에이전트 도구들이 전부 이 위에 서 있으니, 도구를 쓰든 안 쓰든 원리는 알아둘 가치가 있습니다.

함께 보면 좋은 글

Orca란? (worktree를 뼈대로 삼은 도구)
Cursor Agents Window 병렬 워크플로 실전
Cursor + Claude Code 조합 워크플로

참고 자료

git-worktree 공식 문서