Git Worktree 완벽 가이드 - 병렬 작업으로 개발 속도 2배 올리기 (2026)

Git을 쓰는 개발자라면 한 번쯤 이런 상황을 겪어봤을 것이다. A 기능을 개발하다가 급하게 B 버그를 고쳐야 할 때, 현재 작업을 stash하거나 다른 폴더에 별도 클론을 만든다. 이 문제를 우아하게 해결하는 것이 바로 Git Worktree다. 2026년에도 여전히 많은 개발자들이 모르고 지나치는 Git의 강력한 기능, 지금 완벽하게 마스터해보자.

Git Worktree란?

Git Worktree는 하나의 저장소에서 여러 브랜치를 동시에 서로 다른 디렉토리로 체크아웃할 수 있는 기능이다. 쉽게 말해 같은 .git 디렉토리를 공유하면서 여러 개의 작업 디렉토리를 가질 수 있다.

기존 방식과의 차이:

• 기존: 저장소를 2개 클론 → 각각 독립된 .git, 두 배의 디스크 사용
• Worktree: .git 하나 공유 → 브랜치만 다른 디렉토리에 체크아웃, 디스크 절약

기본 사용법

Git Worktree는 Git 2.5(2015년)부터 포함됐지만 2026년에도 모르는 개발자가 많다.

새 Worktree 추가

# 기본 문법
git worktree add <경로> <브랜치>

# 예시: hotfix 브랜치를 ../my-project-hotfix에 체크아웃
git worktree add ../my-project-hotfix hotfix/login-bug

# 새 브랜치 생성하면서 추가 (-b 옵션)
git worktree add -b feature/new-dashboard ../my-project-dashboard main

Worktree 목록 확인

git worktree list

# 출력 예시
# /Users/user/my-project         a1b2c3d [main]
# /Users/user/my-project-hotfix  e4f5g6h [hotfix/login-bug]
# /Users/user/my-project-dashboard 0000000 [feature/new-dashboard]

Worktree 제거

# Worktree 디렉토리 제거
git worktree remove ../my-project-hotfix

# 강제 제거 (변경사항 있어도)
git worktree remove --force ../my-project-hotfix

# 정리 (이미 삭제된 디렉토리 참조 제거)
git worktree prune

실전 시나리오

Git Worktree가 특히 빛나는 실제 상황들이다.

시나리오 1: 개발 중 긴급 버그 수정

가장 흔한 사용 케이스다. A 기능을 개발하다가 프로덕션 버그가 발생했을 때:

# 현재: feature/user-auth 브랜치에서 작업 중
git branch
# * feature/user-auth
#   main

# 긴급 hotfix worktree 생성
git worktree add -b hotfix/critical-bug ../project-hotfix main

# 별도 터미널에서 hotfix 작업
cd ../project-hotfix
# 버그 수정 작업...
git add .
git commit -m "fix: 결제 오류 수정"
git push origin hotfix/critical-bug

# 원본 디렉토리로 돌아와 feature 작업 계속
cd ../project
# feature/user-auth 작업 그대로 유지되어 있음!

# hotfix 완료 후 worktree 제거
git worktree remove ../project-hotfix

시나리오 2: 코드 리뷰와 동시 개발

PR 리뷰를 하면서 현재 작업을 멈추고 싶지 않을 때:

# 동료의 PR 브랜치를 별도 디렉토리에 체크아웃
git fetch origin feature/review-needed
git worktree add ../project-review origin/feature/review-needed

# 리뷰 디렉토리에서 실행해보기
cd ../project-review
npm install  # 필요한 경우
npm run dev  # 포트 충돌 주의!

# 원본에서는 내 작업 계속
cd ../project

시나리오 3: 여러 버전 동시 운영

SaaS 제품에서 여러 버전을 동시에 유지보수할 때:

# v2, v3 동시 운영
git worktree add ../project-v2 v2-stable
git worktree add ../project-v3 v3-stable

# 각 버전에 독립적으로 패치 적용 가능

팁과 주의사항

Git Worktree를 사용할 때 알아야 할 중요한 규칙들이다.

같은 브랜치는 두 번 체크아웃 불가

하나의 브랜치는 동시에 한 곳에만 체크아웃될 수 있다. 이미 main이 체크아웃된 상태에서 다른 worktree에 main을 추가하려 하면 에러가 발생한다.

# 에러 발생
git worktree add ../another-main main
# fatal: 'main' is already checked out at '/Users/user/project'

포트 충돌 주의

여러 worktree에서 동시에 개발 서버를 실행할 때 포트가 충돌한다. 각 worktree의 환경 변수나 설정에서 다른 포트를 사용해야 한다:

<code"># .env.local에서 포트 구분
PORT=3001  # worktree 1
PORT=3002  # worktree 2

.gitignore와 node_modules

각 worktree는 독립된 디렉토리이므로 node_modules를 별도로 설치해야 한다. 이는 디스크 공간을 많이 사용할 수 있다. pnpm 사용자라면 global store 덕분에 실제 디스크 사용량은 크게 늘지 않는다.

AI 코딩 에이전트와 Git Worktree (2026 트렌드)

2026년 AI 코딩 에이전트들이 Git Worktree를 적극 활용하기 시작했다. Claude Code, GitHub Copilot Agent 등의 도구들이 여러 기능을 병렬로 개발하거나 리뷰할 때 Worktree를 생성해 독립적으로 작업한다.

AI 에이전트 자동화 예시

#!/bin/bash
# ai-parallel-work.sh
# AI 에이전트가 여러 작업을 병렬 처리하는 패턴

TASKS=("feature/auth" "feature/dashboard" "feature/api")

for task in "${TASKS[@]}"; do
  git worktree add -b "$task" "../project-${task//\//-}" main
  echo "Worktree created for $task"
  # AI 에이전트가 각 디렉토리에서 독립적으로 작업
done

VS Code에서 Git Worktree 활용

VS Code에서는 여러 worktree를 각각 별도 창으로 열어 관리하는 것이 가장 편리하다.

# 각 worktree를 별도 VS Code 창에서 열기
code ../project-hotfix
code ../project-review

# 또는 멀티 루트 워크스페이스로 한 창에서 관리
# project.code-workspace 파일 생성
{
  "folders": [
    { "path": ".", "name": "main" },
    { "path": "../project-hotfix", "name": "hotfix" },
    { "path": "../project-review", "name": "review" }
  ]
}

생산성 향상 스크립트

자주 쓰는 worktree 작업을 스크립트로 만들어두면 편리하다:

#!/bin/bash
# wt.sh - Git Worktree 헬퍼

case $1 in
  "add")
    # wt add feature/login → ../current-dir-feature-login
    BRANCH=$2
    DIR_NAME=$(basename "$PWD")-${BRANCH//\//-}
    git worktree add "../$DIR_NAME" -b "$BRANCH" main
    echo "✅ Worktree created: ../$DIR_NAME"
    ;;
  "list")
    git worktree list --porcelain | grep -E "^worktree|^branch"
    ;;
  "clean")
    git worktree prune
    echo "✅ Pruned stale worktrees"
    ;;
  *)
    echo "Usage: wt [add|list|clean]"
    ;;
esac

결론

Git Worktree는 2026년에도 많은 개발자들이 모르고 지나치는 숨겨진 보석 같은 기능이다. 한 번 익숙해지면 "왜 이걸 이제야 알았지?"라는 생각이 들 것이다. 특히 긴급 버그 수정, 코드 리뷰, 여러 버전 동시 관리 등의 상황에서 stash나 별도 클론보다 훨씬 우아한 해결책을 제공한다.

오늘 당장 터미널을 열고 git worktree add를 써보자. 개발 워크플로우가 한 단계 업그레이드될 것이다.