Skip to content

WT_SCRIPT_GUIDE.md

Latest commit

 

History

History
300 lines (214 loc) · 6.02 KB

WT_SCRIPT_GUIDE.md

File metadata and controls

300 lines (214 loc) · 6.02 KB

Git Worktree 자동화 스크립트 (wt)

📋 개요

이 스크립트는 Git worktree를 자동으로 생성하고 설정하는 도구입니다. 새로운 작업 환경을 빠르게 준비할 수 있습니다.

✨ 주요 기능

  • ✓ 새로운 worktree 자동 생성
  • ✓ 패키지 자동 설치 (uv 사용)
  • ✓ .env 파일 자동 복사
  • ✓ 진행 상황 실시간 표시
  • ✓ 명확한 에러 메시지
  • ✓ 완료 후 다음 단계 가이드 제공

🚀 사용법

기본 사용법

./wt <브랜치명>

예시

# 새 기능 개발용 worktree 생성
./wt feature/new-feature

# 버그 수정용 worktree 생성
./wt bugfix/critical-issue

# 실험용 worktree 생성
./wt experiment/try-new-approach

📋 동작 절차

1단계: 유효성 검사

  • 현재 디렉토리가 git 저장소인지 확인
  • 브랜치가 이미 사용 중인지 확인
  • worktree 경로가 이미 존재하는지 확인

2단계: Worktree 생성

새 경로: ../프로젝트명-브랜치명
예시: ../fastcampus-lecture-feature/new-feature

3단계: .env 파일 복사

  • 기존 .env 파일이 있으면 새 worktree로 자동 복사

4단계: 패키지 설치

  • uv sync 명령어로 의존성 자동 설치

🔧 실행 권한 설정

스크립트를 처음 다운로드했을 때는 실행 권한이 없을 수 있습니다.

방법 1: chmod 명령어 (권장)

chmod +x wt

권한 확인:

ls -la wt
# -rwxr-xr-x@ 1 bong  staff  3536 Oct 19 15:36 wt

방법 2: Git 커밋 속성 설정

git config core.fileMode true
git add wt
git commit -m "Add executable permission to wt script"

방법 3: 다른 방식으로 실행

실행 권한이 없다면:

bash wt <브랜치명>
# 또는
sh wt <브랜치명>

📊 출력 메시지 해석

성공 메시지

✓ worktree 생성 완료
✓ .env 파일 복사 완료
✓ 패키지 설치 완료

진행 중 메시지

⟳ 새 worktree 생성 중...
⟳ .env 파일 복사 중...
⟳ 패키지 설치 중...

정보 메시지

ℹ .env 파일이 없습니다.

에러 메시지

❌ 에러: 현재 디렉토리가 git 저장소가 아닙니다.
❌ 에러: worktree가 이미 존재합니다.
❌ 에러: uv가 설치되어 있지 않습니다.

⚠️ 에러 상황별 해결 방법

"uv가 설치되어 있지 않습니다"

# macOS (Homebrew)
brew install uv

# Linux
pip install uv

# 또는 공식 설치 스크립트
curl -LsSf https://astral.sh/uv/install.sh | sh

"worktree가 이미 존재합니다"

# 기존 worktree 제거
git worktree remove ../fastcampus-lecture-feature/new-feature

# 또는 강제 제거
rm -rf ../fastcampus-lecture-feature/new-feature

"브랜치가 이미 worktree에서 사용 중입니다"

# 현재 worktree 목록 확인
git worktree list

# 해당 worktree 확인 및 제거
git worktree remove <worktree-path>

🔄 Worktree 관리 명령어

Worktree 목록 확인

git worktree list

출력 예시:

/Users/bong/github/fastcampus-lecture (main)
/Users/bong/github/fastcampus-lecture-feature/new-feature (feature/new-feature)

Worktree로 이동

cd ../fastcampus-lecture-feature/new-feature

Worktree 삭제

git worktree remove ../fastcampus-lecture-feature/new-feature

Worktree 정리 (손상된 링크 제거)

git worktree prune

💡 팁과 주의사항

✅ 권장 사항

  1. 명확한 브랜치명 사용: feature/user-auth, bugfix/api-error
  2. 주기적인 정리: 작업 완료 후 worktree 제거
  3. 메인 브랜치 유지: main/master 브랜치는 worktree로 사용하지 않기
  4. .env 관리: 민감한 정보가 있으면 수동으로 추가

⚠️ 주의사항

  1. 동시에 같은 브랜치 사용 금지: 같은 브랜치를 여러 worktree에서 체크아웃할 수 없음
  2. 디스크 공간: 각 worktree는 전체 코드베이스 복사본이므로 디스크 공간 필요
  3. 의존성 버전: 다른 worktree에서 다른 버전이 필요하면 별도로 설치

🐛 문제 해결

스크립트가 실행되지 않음

# 1. 파일이 존재하는지 확인
ls -la wt

# 2. 실행 권한 확인
chmod +x wt

# 3. bash로 직접 실행
bash wt <브랜치명>

uv 설치 확인

# uv 설치 확인
which uv

# uv 버전 확인
uv --version

# 설치 안 됨 경우 설치
curl -LsSf https://astral.sh/uv/install.sh | sh

권한 에러 발생

# 권한 확인
ls -l wt

# rwx 권한이 없으면
chmod +x wt

# sudo를 사용하지 말 것 (불필요하고 권장하지 않음)

📝 스크립트 커스터마이징

워크트리 경로 변경

기본값: ../프로젝트명-브랜치명

스크립트의 이 줄을 수정:

WORKTREE_PATH="../${PROJECT_NAME}-${BRANCH_NAME}"

예시:

WORKTREE_PATH="$HOME/worktrees/${PROJECT_NAME}-${BRANCH_NAME}"

추가 설정 파일 복사

.env 외에 다른 파일도 복사하려면 스크립트에 추가:

# .env 복사 후에 추가
if [ -f ".env.local" ]; then
    cp .env.local "$WORKTREE_PATH/.env.local"
fi

🎯 일반적인 워크플로우 예시

# 1. 새 기능 개발용 worktree 생성
./wt feature/user-dashboard

# 2. 새 worktree로 이동 (스크립트가 안내함)
cd ../fastcampus-lecture-feature/user-dashboard

# 3. 작업 수행
# ... 코드 작성 및 테스트 ...

# 4. 변경 사항 커밋 및 푸시
git add .
git commit -m "Add user dashboard feature"
git push -u origin feature/user-dashboard

# 5. Pull Request 생성

# 6. 작업 완료 후 main으로 돌아가기
cd ../fastcampus-lecture

# 7. Worktree 삭제
git worktree remove ../fastcampus-lecture-feature/user-dashboard

📞 추가 도움말

문제가 발생하면 다음 명령어로 Git worktree 공식 문서를 확인할 수 있습니다:

git worktree help
man git-worktree

스크립트 버전: 1.0 마지막 업데이트: 2025-10-19