Quartz 5

git worktree: 저장소 하나에 작업 디렉터리 여러 개

Properties1
tagsdomain/ai-agent, type/concept

15 min read

git worktree는 하나의 저장소에 작업 디렉터리를 여러 개 붙여 쓰는 git 기능입니다. Claude Code 문서는 이를 “자기 파일과 브랜치를 가진 별도의 작업 디렉터리로, 메인 체크아웃과 같은 저장소 기록과 원격을 공유한다”고 정의합니다.

worktree마다 자기 파일과 브랜치를 가지므로, 브랜치마다 디렉터리를 따로 두고 동시에 열어 둘 수 있습니다. 이 성질 덕분에 Claude Code에서는 여러 세션이나 서브에이전트가 같은 저장소에서 서로의 파일을 덮어쓰지 않고 병렬로 일하는 수단으로 쓰입니다. 이 노트에서는 git의 기본 명령과 제약, Claude Code의 --worktree와 isolation: worktree, 관련 설정을 정리합니다. 내용은 git 공식 문서와 Claude Code 공식 문서(2026-10 기준)를 확인한 것입니다.

1. main worktree와 linked worktree

git 문서는 worktree를 두 종류로 나눕니다.

구분만드는 방법특징
main worktreegit init, git clone저장소마다 하나(bare 저장소가 아니면). 지울 수 없음
linked worktreegit worktree add0개 이상. 다 쓰면 git worktree remove로 지움

linked worktree는 저장소를 통째로 복제한 것이 아닙니다. 메인 .git 디렉터리 아래 worktrees/에 worktree마다 전용 디렉터리가 생기고, worktree 안에서 $GIT_DIR은 그 전용 디렉터리를, $GIT_COMMON_DIR은 메인 .git을 가리킵니다. 브랜치와 태그 같은 refs는 공유되며, refs/bisect, refs/worktree, refs/rewritten만 worktree마다 따로 둡니다. 그래서 어느 worktree에서 커밋해도 같은 저장소 기록에 쌓입니다.

2. 기본 명령

2-1. 만들기: git worktree add

명령동작
git worktree add <path><path>의 마지막 이름과 같은 브랜치를 체크아웃. 그 이름의 브랜치가 없으면 HEAD에서 새로 만듦. git worktree add ../hotfix는 브랜치 hotfix를 대상으로 함
git worktree add <path> <branch>기존 브랜치를 새 worktree에 체크아웃
git worktree add -b <new-branch> <path> [<commit-ish>]<commit-ish>(기본 HEAD)에서 새 브랜치를 만들어 체크아웃. 브랜치가 이미 있으면 거부
git worktree add -B <new-branch> <path> [<commit-ish>]-b와 같지만 브랜치가 이미 있으면 <commit-ish>로 리셋
git worktree add -d <path>현재 커밋에서 detached HEAD인 임시 worktree를 만듦

2-2. 보기와 지우기

Claude Code 문서가 worktree를 손으로 관리하는 예로 든 명령입니다. 경로와 브랜치 이름은 예시입니다.

git worktree add ../project-feature-a -b feature-a   # 새 브랜치로 worktree 만들기
git worktree add ../project-bugfix fix-issue-456     # 기존 브랜치로 worktree 만들기
cd ../project-feature-a
claude                                               # 이 worktree에서 Claude Code 실행
git worktree list                                    # worktree 목록
git worktree remove ../project-feature-a             # 다 쓴 worktree 지우기
  • list: 저장소에 붙은 worktree 목록을 봅니다.
  • remove: 깨끗한 worktree(추적 파일에 수정이 없고 untracked 파일도 없는 것)만 지웁니다. 수정이 남았거나 서브모듈이 있으면 --force가 필요하고, main worktree는 지울 수 없습니다.
  • prune: remove를 쓰지 않고 디렉터리를 직접 지웠다면 남은 관리 파일을 정리합니다. 그냥 두어도 gc.worktreePruneExpire에 따라 결국 자동으로 정리됩니다.
  • lock / unlock: 잠긴 worktree는 가지치기, 이동, 삭제에서 보호됩니다. 잠긴 worktree를 move나 remove 하려면 --force를 두 번 줘야 합니다.

3. 제약과 주의

이미 체크아웃된 브랜치는 거부합니다

git worktree add에 준 브랜치가 이미 다른 worktree에 체크아웃되어 있으면 git이 거부합니다. 경로 이름으로 브랜치를 추론할 때도 마찬가지입니다. 이 검사는 -f(--force)로 무시할 수 있습니다.

  • 새 체크아웃이라 환경을 다시 준비해야 합니다: 의존성 설치를 다시 해야 하고, .env처럼 gitignore된 파일은 새 worktree에 없으므로 따로 복사해야 합니다. (Claude Code에는 이를 돕는 .worktreeinclude가 있습니다. 6장)
  • 서브모듈 지원은 불완전합니다: 서브모듈이 있는 worktree는 move할 수 없고 remove에는 --force가 필요합니다. git 문서의 BUGS 절은 다음과 같이 적고 있습니다.

git-worktree 문서, BUGS

Multiple checkout in general is still experimental, and the support for submodules is incomplete. It is NOT recommended to make multiple checkouts of a superproject.

4. Claude Code에서 worktree를 쓰는 이유

Claude Code는 세션을 현재 디렉터리에 묶습니다. 그래서 Claude Code 문서는 병렬 세션을 돌릴 때 브랜치마다 worktree를 만들어 각 세션을 따로 돌리라고 안내합니다. 세션과 디렉터리의 관계는 Claude Code 기본 구조에서 정리합니다.

  • 파일 사본이 따로: 세션마다 편집할 파일 사본이 따로 있어서, 한 세션은 기능을 만들고 다른 세션은 버그를 고치는 식으로 충돌 없이 병렬 작업을 할 수 있습니다.
  • 기록과 원격은 공유: 저장소를 다시 clone하지 않아도 되고, worktree 안에서 한 커밋이 같은 저장소에 쌓입니다.

위 이유는 Claude Code 문서의 설명입니다. clone과 비교한 일반적인 이점(디스크 사용량 등)은 git 문서 본문에서 직접 확인하지 못해 여기에 쓰지 않았습니다.

5. claude --worktree

--worktree(-w) 플래그로 시작하면 Claude Code가 worktree를 만들고 그 안에서 세션을 엽니다.

claude --worktree feature-auth
  • 위치와 브랜치: 저장소 루트의 .claude/worktrees/<name>/에 만들고, 새 브랜치 이름은 worktree-<name>입니다. 이름을 생략하면 bright-running-fox 같은 이름을 자동으로 붙입니다.
  • 병렬 세션: 다른 터미널에서 다른 이름으로 실행하면 두 번째 격리 세션이 됩니다. 이미 있는 이름을 주면 새로 만들지 않고 기존 worktree를 엽니다.
  • PR에서 시작: claude --worktree "#1234"나 GitHub PR URL, GitLab MR URL을 주면 .claude/worktrees/pr-<number>에 만듭니다.
  • 세션 중에 들어가기: 대화 중 “work in a worktree”라고 요청하면 EnterWorktree 도구로 만들고, ExitWorktree 도구로 나옵니다.
  • 작업 공간 trust: 대화형 실행은 trust가 필요합니다. 처음이면 그 디렉터리에서 claude를 한 번 실행해 trust를 수락합니다. -p(비대화형)는 이 검사를 건너뜁니다.

.claude/worktrees/는 .gitignore에

메인 체크아웃에서 worktree 디렉터리가 untracked 파일로 보이지 않도록 .gitignore에 추가하라고 문서가 권합니다.

정리 방식은 세션을 어떻게 끝내느냐에 따라 다릅니다.

  1. 대화형 세션을 끝낼 때 변경 사항, untracked 파일, 새 커밋이 있는지 검사합니다.
  2. 깨끗하면 이름 없는 세션은 worktree와 브랜치를 자동으로 지우고, 이름 붙은 세션은 먼저 묻습니다.
  3. 작업이 남아 있으면 보관할지 지울지 묻습니다. 보관한 worktree는 claude --worktree <name> --resume으로 돌아갑니다.
  4. -p 실행은 정리하지 않고 잠금을 남깁니다. 손으로 지울 때는 git worktree remove를 쓰고, 필요하면 먼저 git worktree unlock을 합니다.

격리 강제도 있습니다. worktree에 격리된 세션은 메인 체크아웃 경로를 대상으로 한 Edit, Write, NotebookEdit과, 작업 디렉터리나 git 대상을 메인 체크아웃으로 돌리는 명령(cd, git -C, --git-dir, GIT_DIR)을 막습니다. 다만 cp나 셸 리다이렉트처럼 git을 거치지 않고 메인 체크아웃에 쓰는 명령은 이 검사가 막지 않고, 일반 권한·샌드박스 규칙을 따릅니다.

6. 서브에이전트 격리: isolation: worktree

서브에이전트도 각자 worktree에서 일하게 할 수 있습니다. 대화에서 “use worktrees for your agents”라고 요청하거나, 서브에이전트 정의의 프론트매터에 isolation: worktree를 넣어 고정합니다. 아래는 Claude Code 문서의 예시입니다.

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---
  • 임시 worktree: 서브에이전트마다 임시 worktree를 받습니다. 변경 없이 끝나면 자동으로 지워지고, 변경이 있으면 주기적 정리가 안전하게 지울 수 있을 때까지 디스크에 남습니다.
  • 기준 브랜치: --worktree와 같은 기준(worktree.baseRef)에서 분기합니다.
  • 지침 파일: 서브에이전트가 자기 worktree에서 일해도, 시작할 때 읽는 CLAUDE.md 같은 지침 파일은 메인 대화에서 가져옵니다.
  • 잠금: 에이전트가 실행되는 동안 Claude Code가 worktree에 git worktree lock을 걸어 동시 정리를 막고, 끝나면 풉니다.
  • 주기적 정리: 서브에이전트와 백그라운드 세션용 worktree는 cleanupPeriodDays(기본 30일)보다 오래되면 지워집니다. 변경이나 untracked 파일, push하지 않은 커밋이 남은 것, git worktree add로 직접 만든 것은 남깁니다.

이 격리는 서브에이전트에 대한 기능입니다. Agent Teams는 팀원을 worktree로 격리하지 않으므로, 두 팀원이 같은 파일을 고치면 덮어쓰게 됩니다. 그래서 여러 작업자가 같은 파일을 건드리는 일에는 isolation: worktree를 쓸 수 있는 서브에이전트가 맞고, Agent Teams에서는 팀원마다 맡을 파일을 나눠야 합니다.

7. 관련 설정

settings.json의 worktree 키로 동작을 조정합니다.

설정값설명
worktree.baseRef"fresh"(기본) / "head"fresh는 origin/<기본 브랜치>에서, head는 현재 로컬 HEAD(push 안 한 커밋 포함)에서 분기. 브랜치 이름은 지정할 수 없어서, 특정 브랜치에서 시작하려면 git으로 직접 만듦
worktree.symlinkDirectories디렉터리 목록node_modules 같은 큰 디렉터리를 메인 저장소에서 각 worktree로 심볼릭 링크
worktree.sparsePaths디렉터리 목록git sparse-checkout으로 나열한 디렉터리만 체크아웃 (대형 모노레포용)
worktree.bgIsolation"worktree"(기본) / "none"기본값이면 백그라운드 세션은 EnterWorktree를 호출하기 전까지 메인 체크아웃에 Edit, Write를 못 함
{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules"]
  }
}

gitignore된 파일을 새 worktree에 복사하려면 프로젝트 루트에 **.worktreeinclude**를 둡니다. .gitignore와 같은 문법이고, 패턴에 맞으면서 gitignore된 파일만 복사합니다(추적 파일은 복제하지 않음). --worktree, 서브에이전트 worktree, 데스크톱 앱 병렬 세션에 적용되며, WorktreeCreate 훅을 쓰면 적용되지 않습니다.

.env
.env.local
config/secrets.json

worktree 사이에서 공유되는 것과 따로인 것도 알아 두면 좋습니다.

구분항목
공유저장소의 .git, 권한 승인(메인 체크아웃의 .claude/settings.local.json에 저장), auto memory, 메인 체크아웃의 프로젝트 범위 플러그인
따로작업 파일, gitignore된 파일(.env, CLAUDE.local.md 등), 설치한 의존성

이 밖에 git이 아닌 VCS는 WorktreeCreate/WorktreeRemove 훅으로 대체해야 하고, git lfs install --local을 쓰는 저장소는 Claude Code가 만든 worktree에서 git lfs pull이 필요합니다.

연관 노트와 구현

worktree가 에이전트 기능 선택과 어떻게 이어지는지는 아래 글에서 확인할 수 있습니다.

Graph View

Backlinks