👨‍💻 [IT] GitHub 의 WorkTree 는 무엇인가요?

"이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다."

---

👨‍💻 안녕하세요, 윌리 프로젝트의 윌리 입니다.

GitHub 의 WorkTree 는 무엇인지 간략히 알아보았습니다.

---

질문 >

GitHub 의 WorkTree 는 무엇인가요?

답변 >

GitHub의 기능이라기보다는 Git 자체 기능인 git worktree에 대해 설명드릴게요.

---

git worktree란?

하나의 Git 저장소로 여러 개의 작업 디렉터리(워크트리)를 동시에 사용하는 기능입니다.

보통 Git 저장소는

• 1개의 저장소 = 1개의 작업 폴더

이 구조인데, git worktree를 사용하면:

• 1개의 저장소 = 여러 개의 작업 폴더 + 각기 다른 브랜치

를 만들 수 있습니다.

---

왜 필요한가요?

일반적인 상황

• main 브랜치에서 작업 중
• 갑자기 hotfix 브랜치를 수정해야 함
• 👉 git stash, git checkout 반복

worktree 사용 시

• main 작업 폴더는 그대로 유지
• hotfix 전용 작업 폴더를 새로 하나 생성
• 👉 브랜치 전환 없이 동시에 작업 가능

---

기본 개념 구조

repo/
 ├─ main-worktree/     (main 브랜치)
 ├─ feature-ui/        (feature/ui 브랜치)
 └─ hotfix-crash/      (hotfix/crash 브랜치)

• 실제 .git 디렉터리는 하나
• 각 폴더는 서로 다른 브랜치를 체크아웃

---

기본 사용법

1️⃣ worktree 추가

git worktree add ../my-feature feature/my-feature

• ../my-feature : 새 작업 폴더 경로
• feature/my-feature : 사용할 브랜치
• (없으면 자동 생성 가능)

---

2️⃣ 브랜치 새로 만들면서 worktree 생성

git worktree add -b hotfix/login ../hotfix-login

---

3️⃣ worktree 목록 보기

git worktree list

출력 예:

/repo/main        [main]
/repo/hotfix      [hotfix/login]

---

4️⃣ worktree 제거

git worktree remove ../hotfix-login

---

중요한 제약 사항 ⚠️

1. 한 브랜치는 한 worktree에서만 체크아웃 가능
   • 같은 브랜치를 두 폴더에서 동시에 사용 ❌
2. index(스테이징 영역)는 공유하지 않음
   • 각 worktree는 독립적인 작업 상태 유지
3. .git 디렉터리는 공용
   • fetch, pull, commit 이력은 동일

---

이런 경우에 특히 좋습니다

✔ 멀티 브랜치 동시 작업

• 기능 개발 + 버그 수정 병행

✔ 빌드 환경이 무거운 프로젝트

• Unity, Unreal, Android, iOS
• 브랜치 전환 시 재빌드 피할 수 있음

👉 Unity 1인 개발이나 대형 리소스 프로젝트에 특히 유리합니다.

✔ 코드 리뷰 대응

• 리뷰 요청 받은 브랜치를 별도 폴더로 바로 열기

---

git worktree vs clone

항목	worktree	clone
디스크 사용	매우 적음	큼
.git 이력	공유	독립
브랜치 동시 사용	가능	가능
관리 편의성	높음	보통

---

언제 쓰면 안 좋을까?

• 저장소 구조가 단순하고
• 브랜치를 자주 바꾸지 않는 경우
• 👉 오히려 복잡해질 수 있음

---

한 줄 요약

• git worktree는 “브랜치 전환 없이 여러 브랜치를 동시에 작업하기 위한 Git의 공식 기능”입니다.

---

---

🎬 유튜브 채널 🎬

위로그@WiLog

🎬 치지직 채널 🎬

위로그 채널 - CHZZK

---