Git Worktree

맛없는콩두유·2025년 12월 17일
Git Worktreegit
post-thumbnail

Git Worktree 가이드

Git Worktree란?

Git Worktree는 하나의 Git 저장소에서 여러 브랜치를 동시에 체크아웃하여 작업할 수 있게 해주는 기능입니다. 각 worktree는 독립적인 작업 디렉토리를 가지며, 동일한 Git 데이터베이스를 공유합니다.

왜 Worktree를 사용하나요?

  • 브랜치를 전환하지 않고 여러 브랜치에서 동시에 작업 가능
  • 각 테마/기능을 별도 개발 서버로 실행하여 실시간 비교 가능
  • 브랜치 전환 시 발생하는 빌드 시간 절약
  • 동시에 여러 포트에서 다른 버전 테스트 가능

현재 Worktree 구조

메인 프로젝트 (main 브랜치)
└── worktree/
    ├── agent-1/ (theme-minimal 브랜치)
    ├── agent-2/ (theme-neon 브랜치)
    ├── agent-3/ (theme-nature 브랜치)
    └── agent-4/ (theme-luxury 브랜치)

1단계: Worktree 생성하기

1.1 브랜치 생성 (선택사항)

먼저 각 테마를 위한 브랜치를 생성합니다:

# 메인 프로젝트 루트에서 실행
git branch theme-minimal
git branch theme-neon
git branch theme-nature
git branch theme-luxury

참고: 브랜치가 이미 존재한다면 이 단계를 건너뛰세요.

1.2 Worktree 디렉토리 생성

# worktree를 담을 디렉토리 생성
mkdir -p worktree

1.3 각 Worktree 생성

# agent-1: theme-minimal 브랜치를 위한 worktree 생성
git worktree add worktree/agent-1 theme-minimal

# agent-2: theme-neon 브랜치를 위한 worktree 생성
git worktree add worktree/agent-2 theme-neon

# agent-3: theme-nature 브랜치를 위한 worktree 생성
git worktree add worktree/agent-3 theme-nature

# agent-4: theme-luxury 브랜치를 위한 worktree 생성
git worktree add worktree/agent-4 theme-luxury

1.4 Worktree 목록 확인

git worktree list

출력 예시:

/path/to/project                        38358d6 [main]
/path/to/project/worktree/agent-1       38358d6 [theme-minimal]
/path/to/project/worktree/agent-2       38358d6 [theme-neon]
/path/to/project/worktree/agent-3       38358d6 [theme-nature]
/path/to/project/worktree/agent-4       38358d6 [theme-luxury]

2단계: 각 Worktree에서 의존성 설치

각 worktree는 독립적인 node_modules가 필요합니다:

# agent-1 의존성 설치
cd worktree/agent-1
pnpm install
cd ../..

# agent-2 의존성 설치
cd worktree/agent-2
pnpm install
cd ../..

# agent-3 의존성 설치
cd worktree/agent-3
pnpm install
cd ../..

# agent-4 의존성 설치
cd worktree/agent-4
pnpm install
cd ../..

3단계: 다른 포트로 개발 서버 실행

Next.js 개발 서버는 기본적으로 3000 포트를 사용합니다. 여러 개를 동시에 실행하려면 각각 다른 포트를 지정해야 합니다.

방법 1: 명령어에서 직접 포트 지정

각 터미널 창에서 실행:

# 터미널 1: agent-1을 3001 포트로 실행
cd worktree/agent-1
pnpm dev -p 3001

# 터미널 2: agent-2를 3002 포트로 실행
cd worktree/agent-2
pnpm dev -p 3002

# 터미널 3: agent-3을 3003 포트로 실행
cd worktree/agent-3
pnpm dev -p 3003

# 터미널 4: agent-4를 3004 포트로 실행
cd worktree/agent-4
pnpm dev -p 3004

방법 2: 환경 변수 사용

# 터미널 1
cd worktree/agent-1
PORT=3001 pnpm dev

# 터미널 2
cd worktree/agent-2
PORT=3002 pnpm dev

# 터미널 3
cd worktree/agent-3
PORT=3003 pnpm dev

# 터미널 4
cd worktree/agent-4
PORT=3004 pnpm dev

방법 3: package.json 스크립트 추가 (각 worktree별로)

각 worktree의 package.json에 포트별 스크립트 추가:

{
  "scripts": {
    "dev": "next dev",
    "dev:3001": "next dev -p 3001",
    "dev:3002": "next dev -p 3002",
    "dev:3003": "next dev -p 3003",
    "dev:3004": "next dev -p 3004"
  }
}

그 다음 실행:

cd worktree/agent-1 && pnpm dev:3001
cd worktree/agent-2 && pnpm dev:3002
cd worktree/agent-3 && pnpm dev:3003
cd worktree/agent-4 && pnpm dev:3004

4단계: 브라우저에서 확인

각 포트로 접속하여 다른 테마를 확인할 수 있습니다:

위와 같이 각 템플릿에 맞게 한번에 확인하고 싶을 때 worktree가 굉장히 유용하다!

Worktree 관리 명령어

Worktree 목록 보기

git worktree list

Worktree 상세 정보 보기

git worktree list --porcelain

Worktree 제거하기

# worktree 디렉토리 삭제
rm -rf worktree/agent-1

# Git에서 worktree 정보 제거
git worktree prune

# 또는 한 번에 제거
git worktree remove worktree/agent-1

특정 Worktree로 이동

cd worktree/agent-1

Worktree에서 브랜치 상태 확인

cd worktree/agent-1
git status
git branch

동시 개발 워크플로우

시나리오: 4개 테마를 동시에 개발하고 비교

  1. 4개의 터미널 창을 엽니다

  2. 각 터미널에서 다른 worktree의 개발 서버 실행:

    # 터미널 1
cd worktree/agent-1 && pnpm dev -p 3001

# 터미널 2
cd worktree/agent-2 && pnpm dev -p 3002

# 터미널 3
cd worktree/agent-3 && pnpm dev -p 3003

# 터미널 4
cd worktree/agent-4 && pnpm dev -p 3004

  3. 브라우저에서 4개 탭을 열어 동시 확인:

    • 각 포트(3001~3004)를 다른 탭에서 열어 실시간으로 변경사항 비교

  4. 각 worktree에서 독립적으로 코드 수정:

    # agent-1에서 작업
cd worktree/agent-1
# 파일 수정...
git add .
git commit -m "Update minimal theme colors"

# agent-2에서 작업
cd ../agent-2
# 파일 수정...
git add .
git commit -m "Add neon glow effects"

  5. 메인 브랜치로 병합:

    # 메인 프로젝트로 돌아가기
cd ../..

# theme-minimal 브랜치 병합
git checkout main
git merge theme-minimal

# 다른 브랜치도 필요시 병합
git merge theme-neon

모든 Worktree 한 번에 실행하는 스크립트

start-all-worktrees.sh 파일을 생성하여 모든 서버를 한 번에 실행:

#!/bin/bash

echo "Starting all worktree development servers..."

# agent-1
cd worktree/agent-1
pnpm dev -p 3001 &
cd ../..

# agent-2
cd worktree/agent-2
pnpm dev -p 3002 &
cd ../..

# agent-3
cd worktree/agent-3
pnpm dev -p 3003 &
cd ../..

# agent-4
cd worktree/agent-4
pnpm dev -p 3004 &
cd ../..

echo "All servers started!"
echo "agent-1: http://localhost:3001"
echo "agent-2: http://localhost:3002"
echo "agent-3: http://localhost:3003"
echo "agent-4: http://localhost:3004"
echo ""
echo "Press Ctrl+C to stop all servers"

# Wait for all background processes
wait

실행 권한 부여 및 실행:

chmod +x start-all-worktrees.sh
./start-all-worktrees.sh

모든 서버 종료:

# Ctrl+C를 누르거나
pkill -f "next dev"

주의사항

  1. 의존성 관리: 각 worktree는 독립적인 node_modules를 가지므로 디스크 공간을 많이 사용합니다.

  2. Git 데이터베이스 공유: 모든 worktree는 동일한 Git 데이터베이스를 공유하므로 한 worktree에서 커밋하면 다른 worktree에서도 해당 커밋을 볼 수 있습니다.

  3. 포트 충돌: 항상 다른 포트를 사용해야 합니다. 동일한 포트를 사용하면 "Port already in use" 에러가 발생합니다.

  4. 브랜치 체크아웃 제한: 한 브랜치는 한 번에 하나의 worktree에서만 체크아웃할 수 있습니다.

  5. .gitignore: worktree 디렉토리는 .gitignore에 추가하는 것이 좋습니다:

    worktree/

팁

  • tmux/screen 사용: 여러 터미널 세션을 관리하기 위해 tmux나 screen을 사용하면 편리합니다.
  • VS Code: 각 worktree를 별도의 VS Code 창에서 열 수 있습니다: code worktree/agent-1
  • 브랜치 이름 규칙: 체계적인 브랜치 이름을 사용하면 관리가 쉽습니다 (예: theme-*, feature-*).

문제 해결

"worktree is locked" 에러

# worktree 잠금 해제
git worktree unlock worktree/agent-1

Worktree 정보가 동기화되지 않을 때

# worktree 정보 정리
git worktree prune

포트가 이미 사용 중일 때

# 사용 중인 포트 프로세스 확인 (macOS/Linux)
lsof -i :3001

# 프로세스 종료
kill -9 <PID>

결론

Git Worktree를 사용하면 여러 테마나 기능을 동시에 개발하고 비교할 수 있어 개발 효율성이 크게 향상됩니다. 특히 암호화폐 대시보드처럼 여러 디자인 테마를 동시에 작업할 때 매우 유용합니다.

profile
맛없는콩두유
하루하루 기록하기!
이전 포스트

[NestJS] 파일 업로드(Multer/S3)

0개의 댓글