git worktree란?

워크트리가 해결하는 문제

폴더 하나엔 브랜치 하나만 체크아웃할 수 있습니다. 워크트리는 다른 브랜치가 있는 폴더를 하나 더 만듭니다.

보통 저장소는 폴더 하나에 브랜치 하나가 체크아웃되어 있습니다. 두 가지를 동시에 작업하려면 변경 사항을 stash하고, 브랜치를 바꾸고, 다른 작업을 하고, 다시 돌아와 stash를 풀어야 합니다. 되긴 하지만 느리고 실수하기 쉽습니다.

워크트리를 쓰면 이미 다른 브랜치에 있는 두 번째 폴더가 생깁니다. 기능 A는 한 폴더에, 기능 B는 다른 폴더에 두고 둘 다 동시에 열어 둡니다. stash도 브랜치 전환도 필요 없습니다.

AI 에이전트에 중요한 이유

한 저장소에서 여러 에이전트를 안전하게 돌리게 해 주는 게 워크트리입니다.

AI 에이전트 두 개가 같은 폴더에 있으면 서로 덮어씁니다. 에이전트 A가 auth.ts를 수정하고, 1분 뒤 에이전트 B가 auth.ts를 수정하면, 마지막에 저장한 쪽이 이깁니다. 다른 에이전트의 작업은 사라지고, 둘 다 그 사실을 모릅니다.

에이전트마다 워크트리가 있으면 각자 자체 폴더, 브랜치, 파일을 가집니다. 둘이 동시에 auth.ts를 수정해도 서로의 사본에 손대지 않습니다. 작업이 끝나면 각 브랜치를 따로 검토하고 병합하세요.

디스크에서는 이렇게 보입니다

기록은 같고, 파일은 따로입니다. 폴더를 어디에 둘지는 나나 도구가 정합니다.

my-project/                 ← your main checkout (main)
my-project/worktrees/
  ├─ add-auth/              ← worktree, branch add-auth
  └─ fix-nav/               ← worktree, branch fix-nav

모든 워크트리는 같은 git 기록을 공유하므로, 한 곳에서 한 커밋은 다른 곳에서도 보입니다. 커밋하지 않은 수정은 각자의 폴더에 남습니다. git 자체는 워크트리가 어디에 있든 상관하지 않습니다. 저장소 옆이든, 별도 폴더든, Pane처럼 저장소 안이든 됩니다.

Pane의 워크트리 자동화 방식

Pane은 pane마다 워크트리를 만들고, 채우고, 정리하므로 명령을 직접 입력할 일이 없습니다.

git 명령을 직접 실행할 필요가 없습니다. pane을 만들면 Pane이:

1. 해당 프로젝트와 브랜치용으로 미리 준비해 둔 워크트리를 가져와 새 브랜치를 줍니다. 그래서 pane이 거의 바로 열립니다.
2. .env 파일, .claude와 .codex 같은 에이전트 설정, node_modules를 복사해 넣어 에이전트가 바로 시작할 수 있게 합니다. 목록은 Settings에서 바꿀 수 있습니다.
3. pane을 보관하면 커밋하지 않았거나, 추적되지 않거나, 푸시하지 않은 작업이 있는지 확인한 뒤 워크트리를 제거합니다. 보관한 pane은 나중에 복원할 수 있습니다.

직접 하는 방법

만들고 시작하는 데 명령 세 개, 정리하는 데 두 개.

도구 없이 하면 git 명령 몇 개가 필요합니다:

echo "worktrees/" >> .git/info/exclude   # once: keep them out of git status
git worktree add worktrees/add-auth -b add-auth
cd worktrees/add-auth
claude                      # start your agent here

# once the branch is merged:
git worktree remove worktrees/add-auth
git branch -d add-auth

병합한 뒤엔 워크트리를 제거하고 브랜치를 삭제하는 걸 잊지 마세요. 대부분 잊어버리고, 그래서 도구가 이를 자동화합니다.

관련 문서

• → Pane과 워크트리 - Pane이 워크트리를 관리하는 방식
• → 에이전트 병렬 실행 - 전체 병렬 작업 흐름
• → 모노레포 - 모노레포에서 워크트리 사용하기
• → AI 에이전트용 Git 워크트리 - 한눈에 보는 개요

출처

정정

틀렸거나 오래된 내용이 있으면 알려 주세요. 수정하고 맨 위의 날짜를 갱신하겠습니다. GitHub에 이슈 열기

출처

• → git-worktree documentation
• → Panes & Worktrees (Pane docs)
• → Git worktree tools for AI agents