git worktree 사용법

혹시 git worktree라는 Git 명령어를 아시나요? 사실 이 명령어는 Git 2.5(2015년)에 도입된 꽤 오래된 기능인데요. 그동안 잘 알려지지 않았다가 최근 Claude Code, Cursor 같은 AI 코딩 에이전트들이 적극적으로 활용하면서 다시 주목받고 있습니다. 여러 작업을 병렬로 처리하면서 변경사항을 안전하게 격리하기 위해서인데요. 이처럼 git worktree는 사람뿐 아니라 AI에게도 빠질 수 없는 도구가 되어가고 있습니다.

이번 글에서는 git worktree의 기본 개념과 실전 활용법에 대해 알아보겠습니다.

워크트리란?

먼저 워크트리(worktree)라는 개념부터 짚고 넘어가볼까요?

Git에서 워크트리는 실제로 파일들이 존재하는 디렉토리를 말합니다. 우리가 평소에 코드를 수정하고 저장하는 바로 그 폴더죠. 보통 Git 저장소를 클론(clone)하면 .git 폴더와 함께 하나의 워크트리가 만들어지는데요. 우리는 이 워크트리 안에서 파일을 수정하고 스테이징하고 커밋합니다.

git worktree 명령어는 이 기본 구조를 확장하여 하나의 저장소에 여러 개의 작업 디렉토리, 즉 워크트리를 연결할 수 있게 해줍니다. 각 워크트리는 서로 다른 브랜치를 체크아웃할 수 있고 완전히 독립적으로 작업이 가능합니다.

중요한 점은 모든 워크트리가 Git 메타데이터(커밋 객체, 브랜치 참조, 설정 등)을 담고 있는 .git 폴더를 공유한다는 것입니다. 커밋 히스토리, 브랜치 정보, 설정 등이 모두 공유되기 때문에 한 워크트리에서 커밋한 내용은 다른 워크트리에서도 즉시 접근할 수 있습니다.

왜 git worktree를 사용할까?

git worktree가 특히 빛을 발하는 상황들이 있습니다.

우선 긴급한 핫픽스 대응 상황을 생각해볼까요? 새로운 기능을 열심히 개발하고 있는데 갑자기 프로덕션에 버그가 발생했다면, 기존 작업을 stash하거나 커밋하지 않고도 별도의 워크트리에서 즉시 핫픽스 작업을 할 수 있습니다.

또한 코드 리뷰 시에도 유용한데요. 동료의 PR을 리뷰할 때 실제로 코드를 실행해보고 싶다면, 현재 작업 중인 브랜치를 건드리지 않고 별도의 워크트리에서 리뷰 대상 브랜치를 체크아웃할 수 있습니다.

그리고 서로 관련 없는 여러 기능을 동시에 개발해야 할 때도 좋습니다. 각 기능별로 별도의 워크트리를 만들어 작업하면 컨텍스트 스위칭 비용을 크게 줄일 수 있거든요.

마지막으로 서로 다른 버전의 코드를 나란히 두고 비교하거나 테스트해야 할 때도 유용합니다.

워크트리 생성

새로운 워크트리를 추가하는 기본 명령어는 git worktree add입니다.

$ git worktree add <경로> <브랜치명>

예를 들어, main 브랜치를 위한 워크트리를 상위 디렉토리에 만들려면 다음과 같이 실행합니다.

$ git worktree add ../my-project-main main

이 명령어를 실행하면 ../my-project-main 디렉토리가 생성되고, 그 안에 main 브랜치가 체크아웃됩니다.

새 브랜치를 생성하면서 동시에 워크트리를 만들 수도 있습니다.

브랜치명을 생략하면 경로의 마지막 디렉토리 이름으로 새 브랜치가 자동 생성됩니다.

$ git worktree add ../hotfix

위 명령어는 hotfix라는 새 브랜치를 만들고, ../hotfix 디렉토리에서 해당 브랜치를 체크아웃합니다.

만약에 디렉토리 이름과 다른 이름의 브랜치명을 사용하고 싶다면 -b 옵션을 사용하면 됩니다.

$ git worktree add -b feature/new-feature ../feature-worktree

이렇게 하면 feature/new-feature라는 새 브랜치가 생성되고, ../feature-worktree 디렉토리에서 작업을 시작할 수 있습니다.

워크트리 디렉토리는 일반적으로 기존 저장소 디렉토리 바깥에 만드는 것이 권장됩니다. 저장소 안에 만들면 .gitignore에 추가해야 하는 번거로움이 생기기 때문입니다.

워크트리 목록 확인

현재 저장소에 연결된 모든 워크트리를 확인하려면 list 명령어를 사용합니다.

$ git worktree list

예를 들어, 다음과 같은 결과를 볼 수 있습니다.

/Users/dale/projects/my-project       a1b2c3d [main]
/Users/dale/projects/my-project-main  e4f5g6h [feature/login]
/Users/dale/projects/feature-worktree i7j8k9l [feature/new-feature]

각 라인은 워크트리 경로, HEAD 커밋 해시, 그리고 현재 체크아웃된 브랜치를 보여줍니다.

워크트리 간 이동

생성된 워크트리는 일반적인 디렉토리이므로 단순히 cd 명령어로 이동하면 됩니다.

# 메인 워크트리에서 작업 중
$ pwd
/Users/dale/projects/my-project

# 다른 워크트리로 이동
$ cd ../feature-worktree

# 이제 feature/new-feature 브랜치에서 작업 가능
$ git branch --show-current
feature/new-feature

각 워크트리는 완전히 독립적인 작업 환경을 제공합니다. IDE나 에디터에서 각 워크트리 디렉토리를 별도의 창이나 프로젝트로 열어서 작업할 수 있습니다.

워크트리 삭제

더 이상 필요 없는 워크트리는 remove 명령어로 삭제할 수 있습니다.

$ git worktree remove <worktree-경로>

예를 들어, 아까 만든 피처 워크트리를 삭제하려면 다음과 같이 입력합니다.

$ git worktree remove ../feature-worktree

만약 워크트리에 커밋되지 않은 변경사항이 있다면 Git이 경고를 보여줍니다. 이 경우 -f 또는 --force 옵션으로 강제 삭제할 수 있습니다.

$ git worktree remove --force ../feature-worktree

worktree 디렉토리를 직접 삭제한 경우(예: rm -rf)에는 prune 명령어로 정리해야 합니다.

$ git worktree prune

이 명령어는 더 이상 존재하지 않는 워크트리 디렉토리에 대한 참조를 정리해줍니다.

실전 활용: 코드 리뷰

실제로 git worktree를 활용하는 시나리오를 살펴볼까요? 동료가 올린 PR을 실제로 실행해보면서 리뷰하고 싶습니다.

# 리뷰 대상 브랜치를 위한 워크트리 생성
$ git fetch origin
$ git worktree add ../review-pr123 origin/feature/payment

# 리뷰 워크트리로 이동하여 테스트
$ cd ../review-pr123
$ npm install
$ npm run dev

# 리뷰 완료 후 정리
$ cd ../my-project
$ git worktree remove ../review-pr123

실전 활용: 긴급 핫픽스

현재 feature/user-profile 브랜치에서 새로운 기능을 개발 중입니다. 그런데 갑자기 프로덕션에서 심각한 버그가 발견되었습니다!

$ git status
On branch feature/user-profile
Changes not staged for commit:
  modified:   src/components/Profile.js
  modified:   src/api/user.js

# 핫픽스를 위한 워크트리 생성 (main 브랜치 기준)
$ git worktree add -b hotfix/critical-bug ../my-project-hotfix main

# 핫픽스 워크트리로 이동
$ cd ../my-project-hotfix

# 버그 수정 후 커밋
$ vim src/api/auth.js
$ git add .
$ git commit -m "Fix critical authentication bug"

# 메인에 머지 (협업 프로젝트에서는 Pull Request 생성 후 리뷰/승인 후 병합)
$ git switch main
$ git merge hotfix/critical-bug

# 핫픽스 작업 완료 후 워크트리 삭제
$ cd ../my-project
$ git worktree remove ../my-project-hotfix
$ git branch -d hotfix/critical-bug

이 과정에서 원래 feature/user-profile 브랜치의 작업은 전혀 건드리지 않았습니다. 핫픽스가 끝나면 바로 원래 작업을 이어갈 수 있죠!

주의사항

git worktree를 사용할 때 알아두면 좋은 몇 가지 주의사항이 있습니다.

우선 동일한 브랜치를 여러 워크트리에서 동시에 체크아웃할 수 없습니다. 이는 워크트리 간의 충돌을 방지하기 위한 것입니다.

$ git worktree add ../another-main main
fatal: 'main' is already checked out at '/Users/dale/projects/my-project-main'

그리고 워크트리 디렉토리를 저장소 내부에 만들면 Git이 해당 디렉토리를 추적하려고 할 수 있습니다. 가급적 저장소 디렉토리 외부에 워크트리를 생성하는 것이 좋습니다.

마지막으로 워크트리는 .git 폴더 대신 메인 저장소를 가리키는 .git 파일만 가지고 있어서, 일부 IDE에서 Git 저장소로 인식하지 못할 수 있습니다. 이럴 때는 해당 워크트리 디렉토리를 IDE에서 별도의 프로젝트로 열어보세요. 대중적으로 많이 쓰이는 VS Code나 그 포크 IDE의 경우 각 워크트리 디렉토리를 별도의 창으로 열면 정상적으로 작동합니다.

git stash와 비교

여러 브랜치를 오가며 작업해야 할 때 가장 흔히 사용하는 방법은 git stash입니다. 현재 작업 중인 변경사항을 잠시 저장해두고, 다른 브랜치로 전환한 후, 할 일을 마치고 다시 원래 브랜치로 돌아와 git stash pop을 하는 방식이죠.

하지만 이 과정이 자주 반복되면 꽤 번거롭습니다. 😅 stash를 여러 개 쌓아두다 보면 어떤 stash가 어떤 작업이었는지 헷갈리기도 하고, 잘못된 브랜치에서 pop을 해버리는 실수도 생기죠.

git worktree는 이런 문제를 근본적으로 해결합니다. 브랜치마다 별도의 디렉토리가 있으니 stash 없이도 터미널 탭만 바꾸면 바로 다른 브랜치 작업을 할 수 있거든요. 각 워크트리가 완전히 독립된 작업 공간이기 때문에 변경사항을 임시 저장하거나 복원하는 과정 자체가 필요 없습니다.

git clone과 비교

“그냥 저장소를 여러 번 클론하면 되지 않나요?”라고 생각하실 수 있습니다.

물론 가능하지만, git worktree가 더 나은 점들이 있습니다. 우선 .git 폴더를 공유하기 때문에 대용량 저장소에서 디스크 공간을 크게 절약할 수 있습니다. 또한 한 워크트리에서 커밋하면 다른 워크트리에서도 즉시 접근할 수 있어서 별도로 fetch/pull할 필요가 없습니다. 저장소 설정도 공유되고, 무엇보다 하나의 저장소로 모든 워크트리를 관리할 수 있어서 훨씬 깔끔하죠.

AI 코딩 에이전트와 git worktree

요즘 AI 코딩 에이전트들이 git worktree를 적극적으로 활용하고 있다는 사실, 알고 계셨나요? 🤖

AI 에이전트는 파일을 직접 읽고 수정하기 때문에 워크트리와 궁합이 좋습니다. 두 에이전트 세션이 같은 디렉토리에서 동시에 파일을 고치면 한쪽이 다른 쪽의 변경을 덮어쓰거나, 반쯤 수정된 파일을 읽어서 엉뚱한 결과를 낼 수 있거든요. 워크트리로 격리하면 이런 충돌이 원천적으로 차단됩니다.

잘못된 코드가 나와도 그 워크트리만 삭제하면 되니 실험 비용도 낮고, 여러 해결책을 동시에 탐색한 뒤 가장 좋은 결과를 골라 쓸 수 있어서 LLM의 비결정적 특성을 오히려 장점으로 활용할 수 있습니다.

Claude Code는 --worktree 플래그로 워크트리를 공식 지원하고, Cursor의 Parallel Agents는 최대 8개의 에이전트를 각각 독립된 워크트리에서 동시에 돌릴 수 있으며, OpenAI의 Codex CLI도 워크트리 기반 병렬 실행을 지원합니다.

여기서는 Claude Code를 기준으로 AI 에이전트에서 워크트리를 활용하는 방법을 좀 더 자세히 살펴보겠습니다.

Claude Code에서 워크트리 사용하기

--worktree (또는 줄여서 -w) 플래그를 붙이면 Claude Code가 새 워크트리를 만들고 그 안에서 세션을 시작합니다.

# "feature-auth"라는 이름의 워크트리 생성
claude --worktree feature-auth

# 다른 터미널에서 별도 워크트리 생성
claude --worktree bugfix-123

이렇게 하면 <repo>/.claude/worktrees/feature-auth/ 디렉토리가 생기고 worktree-feature-auth라는 브랜치가 만들어져요. 이름을 생략하면 bright-running-fox 같은 임의 이름이 자동으로 붙습니다.

# 이름 자동 생성
claude --worktree

세션 도중에도 워크트리를 만들 수 있어요. Claude에게 “work in a worktree”나 “start a worktree”라고 말하면 알아서 처리합니다.

이제 두 터미널에서 각각 다른 Claude 세션이 완전히 독립된 파일에서 작업하게 됩니다. 한쪽에서 인증 모듈을 리팩토링하는 동안 다른 쪽에서 버그를 수정해도 전혀 간섭이 없어요.

워크트리 자동 정리

워크트리를 만들기만 하고 정리를 안 하면 디스크가 금방 지저분해지겠죠? Claude Code가 이 부분을 자동으로 처리해줍니다.

세션을 종료할 때 변경사항이 없으면 워크트리와 브랜치가 자동으로 삭제돼요. 변경사항이 있으면 유지할지 삭제할지 물어봅니다. 유지하면 나중에 다시 돌아올 수 있고, 삭제하면 디렉토리와 브랜치가 모두 제거되면서 커밋되지 않은 변경사항도 사라집니다.

.gitignore에 .claude/worktrees/를 추가해두는 게 좋아요. 안 그러면 워크트리 안의 파일이 메인 저장소에서 untracked 파일로 잡힙니다.

.claude/worktrees/

--worktree 플래그는 편리하지만 몇 가지 제약이 있습니다. 워크트리가 항상 .claude/worktrees/ 안에 생기고, 리모트의 기본 브랜치에서 분기하며, 브랜치 이름이 worktree-<name> 패턴으로 고정되거든요. 기존 브랜치를 체크아웃하거나 워크트리 위치를 직접 지정하고 싶다면 앞서 살펴본 git worktree add 명령어를 직접 쓴 뒤 해당 디렉토리에서 claude를 실행하면 됩니다.

서브 에이전트에서 워크트리 격리

Claude Code의 서브 에이전트도 워크트리 격리를 지원합니다. 메인 세션에서 Claude가 서브 에이전트를 띄울 때 각각 독립된 워크트리에서 작업하게 할 수 있어요.

가장 간단한 방법은 대화 중에 직접 요청하는 겁니다.

use worktrees for your agents

좀 더 체계적으로 하려면 커스텀 서브 에이전트의 frontmatter에 isolation: worktree를 지정합니다.

---
name: code-reviewer
description: 코드 리뷰 담당 서브 에이전트
isolation: worktree
tools:
  - Read
  - Grep
  - Glob
---

서브 에이전트 워크트리는 작업이 끝나면 자동으로 정리돼요. 변경사항이 없으면 바로 삭제되고, 변경사항이 있으면 메인 세션에 결과를 보고한 뒤 처리됩니다.

이 방식이 특히 유용한 건 메인 Claude가 여러 서브 에이전트에게 작업을 분배할 때입니다. 테스트 작성, 코드 리뷰, 문서화를 각각 다른 서브 에이전트가 동시에 처리하면서도 서로 간섭하지 않거든요. 에이전트 팀 기능과 결합하면 공유 태스크 목록과 메시지를 통해 더 체계적인 병렬 작업도 가능합니다.

세션 관리와 함께 쓰기

워크트리는 세션 관리 기능과 함께 쓸 때 더 빛납니다. Claude Code의 세션은 프로젝트 디렉토리별로 저장되는데, 워크트리도 같은 Git 저장소에 속하기 때문에 /resume 피커에서 워크트리 세션까지 함께 보여요.

워크트리 세션에 이름을 붙여두면 나중에 찾기가 한결 편합니다.

# 워크트리에서 세션 시작 후 이름 붙이기
claude --worktree feature-auth
# 세션 안에서:
# /rename auth-oauth2-migration

나중에 그 워크트리와 세션을 다시 열고 싶으면 이렇게 합니다.

claude --resume auth-oauth2-migration

PR과도 연동됩니다. 워크트리에서 gh pr create로 PR을 생성하면 세션이 자동으로 PR에 연결돼요. 나중에 claude --from-pr 123으로 바로 이어갈 수 있습니다.

마치며

git worktree는 여러 브랜치를 동시에 작업해야 할 때 매우 유용한 기능입니다. 브랜치 전환 없이 각각 독립된 작업 환경을 유지할 수 있어 컨텍스트 스위칭 비용을 크게 줄여줍니다.

특히 긴급한 핫픽스 대응, 코드 리뷰, 병렬 개발 등의 상황에서 빛을 발합니다. 처음에는 조금 낯설 수 있지만, 한번 익숙해지면 없어서는 안 될 워크플로우가 되실 거예요.

오늘부터 git worktree를 활용해보시는 건 어떨까요? 🚀

Git의 브랜치 전환에 대해서는 git switch 사용법에서, 변경사항 임시 저장에 대해서는 git stash 사용법에서 자세히 다루고 있으니 참고 바랍니다.

더 자세한 내용은 Git 공식 문서를 참고하세요.