Git worktrees

Git worktree는 하나의 Git 저장소에서 여러 개의 작업 트리(working tree)를 동시에 관리할 수 있게 해주는 기능입니다. 이를 통해 브랜치 전환 없이 여러 브랜치에서 동시에 작업할 수 있습니다.

하나의 저장소는 다음을 가질 수 있습니다:

• Main worktree: git init 또는 git clone으로 생성된 기본 작업 트리 (저장소당 1개)
• Linked worktrees: git worktree add로 생성된 추가 작업 트리 (여러 개 가능)

해당 개념이 필요한 이유

• 긴급 수정 시 작업 보존: 리팩토링 중 긴급 버그 수정이 필요할 때, stash 없이 별도 worktree에서 작업
• 병렬 개발: 여러 기능을 동시에 개발하며 각각 독립된 작업 공간 유지
• 브랜치 비교 테스트: 여러 브랜치를 동시에 체크아웃하여 side-by-side 비교 및 테스트
• 실험적 변경: 메인 작업에 영향 없이 “일회용” worktree에서 실험

AS-IS

브랜치 전환 방식에서는 긴급 수정을 위해 현재 작업을 stash하거나 커밋해야 합니다.

sequenceDiagram
    autonumber
    participant Dev
    participant Git
    participant Boss

    Dev->>Git: refactoring 브랜치에서 작업 중
    Note over Dev: 코드 리팩토링 진행 중 (미완성)
    Boss->>Dev: 긴급 버그 수정 필요! (main 브랜치)
    Dev->>Git: git stash (작업 임시 저장)
    Dev->>Git: git checkout main
    Dev->>Git: 버그 수정 후 커밋
    Dev->>Git: git checkout refactoring
    Dev->>Git: git stash pop (작업 복원)
    Note over Dev: 충돌 해결 필요할 수도...

TO-BE

Worktree를 사용하면 현재 작업을 유지한 채 별도 공간에서 작업할 수 있습니다.

sequenceDiagram
    autonumber
    participant Dev
    participant Main at /project
    participant Temp at /temp (hotfix 브랜치)
    participant GitHub
    participant Boss

    Dev->>Main: refactoring 브랜치에서 작업 중
    Note over Dev: 코드 리팩토링 진행 중 (미완성)
    Boss->>Dev: 긴급 버그 수정 필요!

    Dev->>Temp: git worktree add -b hotfix ../temp main
    Note over Temp: main 기반으로 hotfix 브랜치 생성

    Dev->>Temp: cd ../temp
    Dev->>Temp: 버그 수정 작업
    Dev->>Temp: git commit -m "fix: critical bug"
    Note over Temp: hotfix 브랜치에 커밋 (main 아님!)

    Dev->>GitHub: git push origin hotfix
    Dev->>GitHub: PR 생성 (hotfix -> main)
    Note over GitHub: 코드 리뷰 & 머지

    Dev->>Temp: git worktree remove ../temp
    Dev->>Main: cd /project (refactoring 작업 계속)
    Note over Main: 작업 내용 그대로 유지됨

Worktrees vs Branches 비교

측면	Branches	Worktrees
체크아웃 상태	Worktree당 하나	여러 브랜치 동시 체크아웃
작업 디렉토리	단일 디렉토리	여러 디렉토리
용도	커밋 히스토리 구성	병렬 개발 워크플로우
전환 비용	빠름 (포인터만 업데이트)	디렉토리 이동 필요
리소스 사용	최소	더 많은 디스크 공간
복잡도	단순	더 고급
Stash 필요	자주 필요	불필요

Worktrees를 사용해야 할 때

✅ 리팩토링 중 긴급 수정

git worktree add -b emergency-fix ../temp master
cd ../temp
# 버그 수정
git commit -a -m 'emergency fix'
cd -
git worktree remove ../temp

✅ 여러 브랜치 동시 테스트

git worktree add ../test-v1.0 v1.0
git worktree add ../test-v2.0 v2.0
# 브랜치 전환 없이 병렬 테스트

✅ 복잡한 실험

git worktree add -d ../experiment
# 메인 작업에 영향 없이 실험

Branches를 사용해야 할 때

✅ 코드 히스토리 구성

• 브랜치는 개발 타임라인을 나타냄

✅ 간단한 기능 전환

• git checkout으로 빠른 브랜치 전환
• 적은 리소스 오버헤드

✅ 일반적인 Git 워크플로우

• 대부분의 표준 워크플로우는 단일 작업 디렉토리를 가정

주요 워크플로우 시나리오

시나리오 1: 리팩토링 중 긴급 수정

sequenceDiagram
    autonumber
    participant Dev
    participant Main as /project (refactoring)
    participant Temp as /temp (emergency-fix)
    participant GitHub

    Note over Main: refactoring 브랜치 작업 중
    Dev->>Temp: git worktree add -b emergency-fix ../temp master
    Note over Temp: master 기반 새 브랜치 생성

    Dev->>Temp: cd ../temp
    Dev->>Temp: 버그 수정 & 커밋
    Dev->>GitHub: git push origin emergency-fix
    Dev->>GitHub: PR 생성 및 머지

    Dev->>Main: cd /project
    Dev->>Temp: git worktree remove ../temp
    Note over Main: refactoring 작업 계속 (영향 없음)

시나리오 2: 병렬 기능 개발

flowchart TD
    A["Main Worktree
    /project
    (master)"] --> B[git worktree add ../feature-a]
    A --> C[git worktree add ../feature-b]
    A --> D[git worktree add -d ../testing]

    B --> E["Worktree A
    /feature-a
    (feature-branch-a)"]
    C --> F["Worktree B
    /feature-b
    (feature-branch-b)"]
    D --> G["Worktree C
    /testing
    (detached HEAD)"]

    E --> H[팀원 A 작업]
    F --> I[팀원 B 작업]
    G --> J[통합 테스트]

    H --> K[git push & PR]
    I --> L[git push & PR]
    J --> M[테스트 결과 확인]

    K --> N[main으로 머지]
    L --> N

시나리오 3: 휴대용 장치 설정

sequenceDiagram
    autonumber
    participant Dev
    participant Main at /project
    participant USB at /media/usb/project
    participant Git

    Dev->>USB: git worktree add --lock /media/usb/project
    Note over USB: --lock으로 실수 삭제 방지

    Dev->>Git: git worktree list -v
    Note over Git: /project [master]<br/>/media/usb/project (feature) locked

    Note over Dev: USB 장치 언마운트
    Note over USB: 물리적으로 연결 해제

    Note over Dev: USB 장치 재마운트
    Dev->>USB: cd /media/usb/project
    Dev->>USB: git status
    Note over USB: 정상 작동!

    Dev->>USB: 작업 완료
    Dev->>Git: git worktree unlock /media/usb/project
    Dev->>Git: git worktree remove /media/usb/project

시나리오 4: 머지 전 테스트

sequenceDiagram
    autonumber
    participant Dev
    participant Main as /project (main)
    participant Test as /testing (test-feature)
    participant CI

    Note over Main: feature-branch 개발 완료

    Dev->>Test: git worktree add -b test-feature ../testing feature-branch
    Note over Test: feature-branch 복사본 생성

    Dev->>Test: cd ../testing
    Dev->>Test: npm test
    Dev->>Test: python -m pytest
    Note over Test: 전체 테스트 스위트 실행

    alt 테스트 통과
        Dev->>CI: 테스트 성공 확인
        Dev->>Main: git worktree remove ../testing
        Dev->>Main: git checkout main
        Dev->>Main: git merge feature-branch
        Note over Main: 머지 진행
    else 테스트 실패
        Dev->>CI: 테스트 실패 확인
        Dev->>Main: git worktree remove -f ../testing
        Dev->>Main: feature-branch에서 이슈 수정
        Note over Main: 다시 테스트 반복
    end

Worktree 타입

Main worktree

• git init 또는 git clone으로 생성
• 저장소당 하나만 존재
• 삭제 불가능
• .git/ 디렉토리가 실제 Git 저장소

Linked worktrees

• git worktree add로 생성
• 여러 개 생성 가능
• 삭제 가능
• .git 파일이 main worktree의 메타데이터를 가리킴

디렉토리 구조:

/path/main/                          # Main worktree
├── .git/                            # 실제 Git 저장소
│   ├── worktrees/                   # Linked worktrees 메타데이터
│   │   └── hotfix/                  # Linked worktree 1
│   │       ├── HEAD                 # Per-worktree
│   │       ├── index                # Per-worktree
│   │       └── gitdir               # 위치 포인터
│   ├── refs/heads/                  # 공유 (모든 worktree)
│   └── objects/                     # 공유 (모든 worktree)
└── source-files/

/path/other/hotfix/                  # Linked worktree
├── .git                             # 파일 (디렉토리 아님!)
│   내용: gitdir: /path/main/.git/worktrees/hotfix
└── source-files/

공유 vs Per-worktree 컴포넌트

컴포넌트	공유 여부
HEAD	Per-worktree (각 worktree마다 다름)
index (staging area)	Per-worktree
refs/heads/* (브랜치)	공유 (모든 worktree)
refs/tags/* (태그)	공유
objects/ (커밋 데이터)	공유

주요 명령어

add - 새 worktree 생성

기본 사용:

git worktree add <path> [<commit-ish>]

예시:

# 경로 기반 브랜치명 자동 생성
git worktree add ../hotfix
# "hotfix" 브랜치를 생성하고 ../hotfix에 체크아웃
 
# 기존 브랜치 체크아웃
git worktree add ../new-feature feature-branch
 
# 새 브랜치 생성하며 worktree 추가
git worktree add -b new-branch ../path main
 
# Detached HEAD (브랜치 없음)
git worktree add -d ../experimental
 
# 잠금과 함께 생성 (실수로 삭제 방지)
git worktree add --lock ../mounted-device

주요 옵션:

• -b <new-branch>: 새 브랜치 생성
• -B <new-branch>: 브랜치 생성/리셋
• -d, --detach: Detached HEAD 상태
• --lock: 생성 후 잠금
• --no-checkout: 체크아웃 생략

list - 모든 worktree 조회

git worktree list

출력 예시:

/path/to/main              abcd1234 [master]
/path/to/linked-worktree   1234abc  [feature-a]
/path/to/other             5678def  (detached HEAD)

옵션:

git worktree list -v              # 상세 정보 (잠금 이유 등)
git worktree list --porcelain     # 기계 판독 가능 형식

remove - worktree 삭제

git worktree remove <worktree>

예시:

# 깨끗한 worktree 삭제
git worktree remove ../hotfix
 
# 커밋되지 않은 변경사항이 있어도 강제 삭제
git worktree remove -f ../dirty-worktree
 
# 잠긴 worktree 강제 삭제
git worktree remove -ff ../locked-worktree

prune - 오래된 메타데이터 정리

# 오래된 관리 파일 제거
git worktree prune
 
# Dry run (삭제될 항목 확인)
git worktree prune -n
 
# 특정 시간 이전 항목만 제거
git worktree prune --expire=2.weeks.ago

lock / unlock - 실수 삭제 방지

# Worktree 잠금 (예: 휴대용 장치)
git worktree lock ../portable-worktree
git worktree lock --reason "USB 드라이브" ../usb-drive
 
# Worktree 잠금 해제
git worktree unlock ../portable-worktree

move - worktree 위치 변경

git worktree move <worktree> <new-path>

repair - 깨진 worktree 링크 복구

# Worktree 연결 복구
git worktree repair
 
# 수동으로 이동한 후 특정 worktree 복구
git worktree repair /path/to/worktree1

사용 시나리오:

• Main worktree를 수동으로 이동한 경우
• git worktree move 없이 linked worktree 이동
• 손상되거나 오래된 관리 파일

설정

worktree.guessRemote

# 원격 브랜치 자동 매칭 활성화
$ git config worktree.guessRemote true
 
# 이제 다음이 작동:
$ git worktree add ../feature-x
# 존재하면 remote/origin/feature-x 자동 매칭

worktree.useRelativePaths

# 이식성을 위해 상대 경로 사용
$ git config worktree.useRelativePaths true
 
# 저장소와 worktree가 위치 간 이동할 때 유용

Worktree별 설정

# Per-worktree config 활성화
$ git config extensions.worktreeConfig true
 
# Worktree별 설정: .git/config.worktree
$ git config --worktree core.sparseCheckout true

주의사항

제한사항

⚠️ Main worktree는 삭제 불가능 ⚠️ Submodule이 있는 worktree는 git worktree move로 이동 불가 ⚠️ Multiple checkout 지원은 아직 실험적 기능 ⚠️ Submodule 지원이 불완전

Best Practices

✅ 수동 삭제 대신 항상 git worktree remove 사용 ✅ 휴대용 장치의 worktree는 잠금 설정 ✅ 수동 이동 후 git worktree repair 사용 ✅ Worktree별 설정이 크게 다르면 extensions.worktreeConfig 활성화

참고 문서

• Official Documentation - git-worktree