이런 상황을 겪어본 적이 있으신가요? 복잡한 신규 기능을 개발하는 중에 갑자기 긴급 버그 수정 요청이 들어와 즉시 처리해야 하는 상황 말입니다.
브랜치를 전환하기 위해 어쩔 수 없이 git stash를 실행하여 작성 중이던 코드를 임시로 숨깁니다. 버그를 고치고 돌아온 뒤에는 조심스럽게 git stash pop을 실행하지만, 때로는 코드 충돌이라는 악몽에 직면하기도 합니다.
사실 Git에는 이러한 불편함을 해결해 주는 강력한 도구가 오래 전부터 존재했습니다. 그것이 바로 Git Worktree입니다.
복잡한 브랜치 전환과 Stash에서 벗어나 Worktree로 멀티스레드 개발 시작하기
이 글에서는 Git Worktree의 핵심 동작 원리와 실전 활용법을 알아봅니다.
Git Worktree와 Git Branch의 차이점은 무엇인가요?
Git Worktree를 이해하기 위해 먼저 Git Branch와의 차이점을 정리해 보겠습니다.
버전 관리를 책을 읽는 과정에 비유할 수 있습니다:
Commit은 책의 판/버전Branch는 특정 페이지에 끼워둔 책갈피Worktree는 책을 펼쳐놓고 작업하는 책상
기존 방식에서는 책상이 하나뿐이었습니다. 책갈피를 바꿀 때마다 책상 위의 작업 중인 서류를 모두 치우거나 서랍에 숨겨야 했습니다 (이것이 git stash입니다).
반면 Git Worktree를 사용하면 여러 개의 독립된 책상을 동시에 소유할 수 있습니다.
| 비교 항목 | Git Branch | Git Worktree |
|---|---|---|
| 작업 공간 개념 | 단일 실체 작업 디렉토리를 공유 | 독립된 여러 실체 작업 디렉토리를 소유 |
| 전환 비용 | 커밋, Stash 또는 임시 저장 필요 | Stash 없이 디렉토리 이동만으로 즉시 전환 |
| 격리 및 안전성 | 미커밋 파일로 인한 충돌이나 잔여물 발생 가능 | 디렉토리가 완전 격리되어 변경 사항 상호 간섭 없음 |
| 이력 관리 | Git Commit 이력 및 브랜치 공유 | Git Commit 이력 및 브랜치 공유 |
각 Worktree의 현재 브랜치, 스테이징 영역, 미커밋 변경 사항은 완전히 독립되어 있지만, 모든 Commit 이력과 브랜치 기록은 서로 공유합니다.
Branch는 버전 책갈피이고, Worktree는 실체 작업 책상입니다
이로 인해 작업 전환이 필요할 때 다른 폴더 디렉토리를 열기만 하면 되며, 현재 개발 상태를 변경할 필요가 전혀 없습니다.
Git Worktree 시작하는 방법
실제 프로젝트에 Git Worktree를 도입할 때는 체계적인 디렉토리 계획을 세우는 것이 개발을 훨씬 원활하게 만듭니다.
원래 git clone 받은 프로젝트 디렉토리를 깨끗한 main 본부로 유지하고, 새 Worktree 디렉토리는 프로젝트 외부에배치하여(예: ../my-app-worktrees) 개발 도구의 재귀 탐색 오류를 방지하는 것이 좋습니다.
자주 사용하는 명령어 흐름은 다음과 같습니다:
| 프로세스 | 명령어 |
|---|---|
| 1. 새 Worktree 생성과 동시에 새 브랜치 생성 | git worktree add ../my-app-worktrees/feature-login -b feature-login |
| 2. 현재 전체 Worktree 목록 확인 | git worktree list |
Git Worktree는 AI Agent의 개발 작업을 관리하는 데 특히 유용합니다.
AI Agent에게 독립된 Worktree 디렉토리를 부여하여 마음껏 수정하고 테스트하게 하고, 개발자는 다른 Worktree에서 코드 리뷰(Review) 및 테스트를 진행할 수 있습니다.
AI Agent에 독립된 Worktree를 부여하여 AI 개발과 인간 리뷰를 병렬로 처리하세요
두 작업이 각각의 물리 디렉토리에서 수행되므로 안전하고 명확합니다.
개발 완료 후 병합 및 안전한 정리 방법
독립된 Worktree에서 개발을 마친 후 결과물을 병합하고 정리하려면 어떻게 해야 할까요?
한 가지 중요한 개념을 기억하세요: Worktree 디렉토리 자체를 병합하는 것이 아니라, 실제로 병합해야 하는 것은 Branch 브랜치입니다.
main 작업 책상 디렉토리로 돌아가 해당 기능 브랜치에 대해 git merge를 실행하기만 하면 통합이 완료됩니다.
정리는 다음 표준 2단계 절차를 따릅니다:
| 단계 | 명령어 |
|---|---|
| 1. Worktree 실체 디렉토리 제거 | git worktree remove ../my-app-worktrees/feature-login |
| 2. 완료된 기능 브랜치 삭제 | git branch -d feature-login |
Worktree 디렉토리를 먼저 제거한 후 Branch 브랜치를 삭제하세요
파일 탐색기에서 폴더를 수동으로 직접 삭제하지 말고 반드시 git worktree remove 명령어를 사용하여 정리하세요.
Git Worktree 사용 시주의해야 할 함정
Git Worktree는 매우 편리하지만 사용할 때 주의해야 할 함정이 몇 가지 있습니다.
함정 1: 커밋되지 않은 변경 사항의 손실
Worktree를 삭제해도 Branch 자체가 삭제되지는 않지만, 해당 디렉토리에 아직 커밋되지 않은 변경 사항이 남아있는 상태에서 강제로 삭제하면 해당 작업 내용이 손실됩니다.
함정 2: 브랜치 중복 체크아웃 충돌
Git의 보호 메커니즘은 동일한 Branch를 두 개의 다른 Worktree에서 동시에 Checkout하는 것을 허용하지 않습니다. 이미 사용 중인 브랜치를 두 번째 Worktree에서 체크아웃하려고 하면 Git이 오류 메시지를 출력하고 차단합니다.
Worktree 강제 삭제 시 아직 Commit되지 않은 변경 사항이 손실될 수 있습니다
이러한 특성과 원칙을 잘 숙지하면 문제 발생을 방지할 수 있습니다.
결론
Git Worktree를 활용하면 번거로운 브랜치 전환과 git stash 작업에서 완전히 벗어나 진정한 멀티스레드 개발을 실현할 수 있습니다.
다음에 긴급 버그 수정이 필요하거나 여러 기능을 동시에 개발할 때, 혹은 AI Agent에게 코딩 작업을 할당할 때 새로운 작업 책상을 펼쳐보세요!