브랜치 전환이 아니라 작업 디렉터리 자체가 부족한 문제입니다
같은 저장소에서 기능 A를 작업하다 급한 버그 수정이 생기면 보통 git stash로 A를 잠시 치워두고 브랜치를 옮깁니다. 파일이 몇 개면 괜찮지만, node_modules 재설치나 빌드 캐시가 얽힌 프로젝트라면 전환마다 몇 분씩 깨집니다. worktree는 stash 없이 같은 저장소를 가리키는 디렉터리를 하나 더 만들어, 두 브랜치를 각자의 폴더에서 동시에 열어두는 방식으로 이 문제를 없앱니다.
코딩 에이전트 시대에 이 기능이 다시 주목받는 이유는 단순합니다. Claude Code나 Codex 같은 터미널 에이전트에게 같은 저장소에서 서로 다른 작업 두 개를 동시에 맡기면, 같은 디렉터리를 쓰는 한 한쪽이 저장한 파일을 다른 쪽이 덮어쓸 위험이 있습니다. 작업마다 별도 worktree를 만들어 에이전트를 그 안에 가둬두면 서로 부딪히지 않고 병렬로 진행할 수 있습니다.
git worktree add·list를 빈 저장소에서 그대로 실행합니다
테스트용 저장소를 하나 만들어 순서대로 실행한 결과입니다. 로컬 git 버전은 다음과 같습니다.
$ git --version git version 2.50.1 (Apple Git-155)
새 브랜치와 함께 worktree를 만들 때는 -b로 브랜치 이름을 지정합니다.
$ git worktree add ../wt-feature -b feature/x Preparing worktree (new branch 'feature/x') HEAD is now at 5987850 init
$ git worktree list /path/repo 5987850 [main] /path/wt-feature 5987850 [feature/x]
메인 저장소(main)와 새로 만든 worktree(feature/x)가 나란히 나열됩니다. 두 디렉터리는 .git 메타데이터를 공유하지만 작업 파일은 완전히 분리돼 있어, 한쪽에서 파일을 고쳐도 다른 쪽에는 영향이 없습니다.
이미 worktree에서 쓰고 있는 브랜치를 다른 worktree에서 또 체크아웃하려 하면 git이 막습니다. 직접 재현한 에러 메시지는 이렇습니다.
$ git worktree add ../wt-feature2 feature/x Preparing worktree (checking out 'feature/x') fatal: 'feature/x' is already used by worktree at '/path/wt-feature'
한 브랜치는 한 번에 한 worktree에서만 열 수 있다는 뜻입니다. 병렬 작업마다 새 브랜치를 만들어 쓰는 이유이기도 합니다.
git worktree add는 세 가지 형태로 씁니다
앞에서 쓴 -b는 새 브랜치를 만들면서 여는 형태입니다. 실무에서는 이미 있는 브랜치를 여는 경우(PR 리뷰)와 브랜치 없이 특정 커밋만 잠깐 보는 경우도 자주 나옵니다. 같은 테스트 저장소에서 세 형태를 모두 실행한 결과입니다.
| 형태 | 명령 | 쓰는 상황 |
|---|---|---|
| 새 브랜치 생성 | git worktree add ../wt-feature -b feature/x | 새 기능·버그 수정을 에이전트에 맡길 때 |
| 기존 브랜치 열기 | git worktree add ../wt-review review/pr-42 | 동료 PR 브랜치를 내 작업과 나란히 놓고 리뷰·실행할 때 |
| detached HEAD | git worktree add --detach ../wt-detached HEAD | 특정 커밋 상태를 잠깐 재현만 하고 브랜치를 남기고 싶지 않을 때 |
$ git worktree add ../wt-review review/pr-42 Preparing worktree (checking out 'review/pr-42') HEAD is now at 66ebd66 init $ git worktree add --detach ../wt-detached HEAD Preparing worktree (detached HEAD 66ebd66) HEAD is now at 66ebd66 init $ git worktree list /path/repo 66ebd66 [main] /path/wt-detached 66ebd66 (detached HEAD) /path/wt-review 66ebd66 [review/pr-42]
목록에서 detached worktree는 브랜치 이름 대신 (detached HEAD)로 표시됩니다. 여기서 커밋을 만들면 브랜치가 없어 잃어버리기 쉬우니, 에이전트에게 맡기는 작업은 항상 첫 번째 형태로 브랜치를 붙여 여는 편이 안전합니다.
덜 알려진 하위 명령 두 개도 병렬 작업에서 쓸모가 있습니다. move는 worktree 디렉터리를 옮기면서 git 메타데이터까지 같이 갱신하고, lock은 실수로 지워지지 않게 잠급니다. 잠근 상태에서 remove를 시도하면 git이 이유와 함께 거부합니다.
$ git worktree move ../wt-review ../wt-review-42 $ git worktree lock --reason "리뷰 중" ../wt-review-42 $ git worktree remove ../wt-review-42 fatal: cannot remove a locked working tree, lock reason: 리뷰 중 use 'remove -f -f' to override or unlock first $ git worktree unlock ../wt-review-42 && git worktree remove ../wt-review-42
에이전트가 한창 작업 중인 worktree를 다른 에이전트나 정리 스크립트가 지우는 사고를 막고 싶다면, 작업을 맡기는 시점에 lock을 걸고 끝나면 unlock하는 습관이 단순하고 효과적입니다.
디렉터리는 형제 폴더 또는 저장소 안 .worktrees, 둘 중 하나로 통일합니다
지금까지 예시는 ../wt-feature처럼 저장소의 형제 폴더에 두는 방식입니다. 가장 흔하고 IDE에서 별도 프로젝트로 열기도 쉽지만, worktree가 열 개를 넘어가면 상위 폴더가 어지러워지고 어떤 저장소 소속인지 이름만으로 구분해야 합니다. 대안은 저장소 안에 .worktrees/ 같은 하위 폴더를 두는 방식입니다. 실제로 해보면 한 가지가 바로 걸립니다.
$ git worktree add .worktrees/feature-z -b feature/z Preparing worktree (new branch 'feature/z') HEAD is now at 66ebd66 init $ git status --short ?? .worktrees/
메인 체크아웃에서 .worktrees/가 추적되지 않은 파일로 잡힙니다. 이 상태로 두면 에이전트가 git add .를 실행하는 순간 다른 worktree의 파일 전체를 커밋하려 듭니다. 저장소 안에 두려면 .gitignore에 .worktrees/를 먼저 추가해야 하고, 에디터의 검색·린트 범위에서도 그 폴더를 빼야 같은 파일이 여러 번 검색되는 일을 피할 수 있습니다. 어느 쪽이든 팀 안에서 하나로 정해 두는 것이 중요합니다. Orca 같은 도구는 자기 관리 디렉터리 아래에 worktree를 모아 두는 방식을 택해 이 고민을 없애 줍니다.
쓰던 worktree는 remove로 지우고, 수동으로 지웠다면 prune합니다
작업이 끝난 worktree는 git worktree remove로 정리합니다.
$ git worktree remove ../wt-feature $ git worktree list /path/repo 5987850 [main]
디렉터리를 rm -rf로 먼저 지워버리면 git의 메타데이터에는 여전히 그 worktree가 남아 “prunable”로 표시됩니다. 실제로 재현한 결과입니다.
$ git worktree add ../wt-temp -b temp/y $ rm -rf ../wt-temp $ git worktree list /path/repo 5987850 [main] /path/wt-temp 5987850 [temp/y] prunable
$ git worktree prune -v Removing worktrees/wt-temp: gitdir file points to non-existent location $ git worktree list /path/repo 5987850 [main]
즉 worktree 디렉터리를 지울 때는 git worktree remove를 쓰는 것이 정석이고, 실수로 파일 탐색기나 rm -rf로 먼저 지웠다면 git worktree prune으로 뒤늦게 메타데이터를 정리하면 됩니다.
에이전트 한 마리당 worktree 하나가 기본 원칙입니다
여러 코딩 에이전트를 같은 저장소에서 동시에 굴리려면 절차는 단순합니다. 작업 단위마다 git worktree add로 새 디렉터리를 만들고, 그 디렉터리 안에서 claude나 codex를 실행합니다. 설치가 안 돼 있다면 Claude Code 설치와 Codex CLI 설치 글을 먼저 확인하세요.
| 단계 | 명령 |
|---|---|
| 작업별 worktree 생성 | git worktree add ../wt-login -b feature/login |
| 해당 디렉터리로 이동 | cd ../wt-login |
| 에이전트 실행 | claude 또는 codex |
| 결과 확인 후 머지 | 메인 저장소에서 git merge feature/login |
여러 worktree에 공통으로 적용할 규칙(코딩 스타일, 테스트 실행 방법, 금지 사항)은 AGENTS.md에 적어 저장소 루트에 두면 각 worktree의 에이전트가 동일하게 읽습니다. 머지는 에이전트가 자동으로 하게 두지 않고, 사람이 각 worktree의 diff를 하나씩 검토한 뒤 순서대로 처리하는 편이 충돌을 줄입니다. 동시에 여러 worktree를 머지할 때는 먼저 머지된 쪽의 변경이 나중 worktree의 작업 기준과 어긋나지 않는지 다시 확인해야 합니다.
Orca는 이 과정을 앱 하나로 자동화합니다
지금까지의 add·remove·prune, 그리고 에이전트를 worktree별로 띄우고 결과를 비교해 머지하는 흐름을 수동 명령 없이 앱으로 묶은 도구가 Orca입니다. 작업을 등록하면 자동으로 worktree를 만들고, 각 worktree에 터미널과 Chromium 브라우저 창을 붙여 Claude Code·Codex 같은 에이전트를 실행하며, 한 프롬프트를 여러 에이전트에 뿌려 나온 결과의 diff를 비교해 고른 쪽만 머지할 수 있게 해줍니다. 설치와 첫 worktree 생성 순서는 Orca IDE 설치 글에, 다른 바이브코딩 툴과의 비교는 바이브코딩 툴 비교 글에 정리했습니다. worktree 명령 몇 개만으로 충분한 경우라면 굳이 앱을 새로 설치할 필요는 없습니다.
흔한 실수
untracked 파일이 안 보임node_modules, .env처럼 git이 추적하지 않는 파일은 새 worktree에 자동으로 따라오지 않습니다. 의존성 설치나 환경변수 설정을 worktree마다 다시 해야 합니다.
같은 브랜치 중복 체크아웃 시도이미 다른 worktree에서 쓰는 브랜치는 새 worktree에서 열 수 없습니다. 작업 단위마다 새 브랜치를 만드세요.
rm -rf로 지우고 방치디렉터리만 지우면 git 메타데이터에는 남아 있습니다. remove를 쓰거나, 이미 지웠다면 prune으로 정리하세요.
서브모듈이 있는 저장소서브모듈은 worktree마다 별도로 초기화해야 하는 경우가 있어, 서브모듈이 많은 저장소라면 worktree 도입 전에 먼저 작은 저장소로 연습해보는 편이 안전합니다.
자주 묻는 질문
worktree와 clone의 차이는 무엇인가요?
clone은 저장소 전체를 새로 복사해 별도의 .git을 만듭니다. worktree는 같은 .git을 공유하면서 작업 디렉터리만 추가하므로 디스크 공간을 훨씬 적게 쓰고, 커밋·브랜치가 즉시 서로에게 보입니다.
worktree 안에서 다시 worktree를 만들 수 있나요?
가능합니다. 어느 worktree에서 실행하든 같은 저장소의 worktree 목록에 추가됩니다. 다만 경로가 헷갈리기 쉬우므로 메인 저장소에서 관리하는 편이 낫습니다.
몇 개까지 만들 수 있나요?
공식 문서에 개수 제한은 명시돼 있지 않습니다. 실무에서는 디스크 용량과 동시에 돌리는 에이전트 수만큼만 만드는 것이 관리하기 편합니다.
git-scm.com 공식 문서(git-worktree)와 Orca 공식 사이트를 2026년 9월 4일 확인했습니다. add·list·remove·prune 명령과 에러 메시지는 로컬 테스트 저장소에서 직접 재현한 실제 출력입니다.