my-project/               ← Main worktree (main 브랜치)
├── .git/                 ← 실제 저장소 데이터 (공유됨)
│   └── worktrees/        ← Linked worktree 메타데이터
├── src/
└── ...

../my-project-hotfix/     ← Linked worktree (hotfix 브랜치)
├── .git                  ← 실제로는 파일 하나 (포인터)
├── src/
└── ...

../my-project-feature/    ← Linked worktree (feature 브랜치)
├── .git                  ← 실제로는 파일 하나 (포인터)
├── src/
└── ...

gitdir: /path/to/my-project/.git/worktrees/my-project-hotfix

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

# 예시 1: 기존 브랜치를 새 디렉토리에 체크아웃
git worktree add ../my-project-hotfix hotfix/login-bug

# 예시 2: 새 브랜치를 동시에 생성하면서 추가 (-b 옵션)
git worktree add -b feature/new-api ../my-project-feature main

# 예시 3: 특정 커밋 해시로 체크아웃 (Detached HEAD 상태)
git worktree add ../my-project-review abc1234

git worktree list

/Users/sangwook/my-project           abc1234 [main]
/Users/sangwook/my-project-hotfix    def5678 [hotfix/login-bug]
/Users/sangwook/my-project-feature   ghi9012 [feature/new-api]

git worktree list --porcelain

# 권장 방법: git 명령어로 제거 (메타데이터도 함께 정리)
git worktree remove ../my-project-hotfix

# 강제 제거 (수정된 파일이 있어도 강제 삭제)
git worktree remove --force ../my-project-hotfix

# 디렉토리를 수동으로 삭제한 경우, 남은 메타데이터 정리
git worktree prune

# 잠금
git worktree lock ../my-project-hotfix --reason "외장 드라이브에 위치"

# 잠금 해제
git worktree unlock ../my-project-hotfix

# 현재 feature 브랜치에서 작업 중
# (stash 없이 바로 핫픽스 디렉토리 생성)
git worktree add ../my-project-hotfix -b hotfix/critical-bug main

# 새 터미널 탭 or 새 에디터 창에서 핫픽스 디렉토리 열기
cd ../my-project-hotfix

# 버그 수정 및 커밋
vim src/auth/login.ts
git add .
git commit -m "fix: 로그인 토큰 만료 처리 누락 수정"
git push origin hotfix/critical-bug

# 핫픽스 완료 후 worktree 제거
cd ../my-project
git worktree remove ../my-project-hotfix

# PR 리뷰용 worktree 추가
git worktree add ../my-project-review feature/teammate-pr

cd ../my-project-review
# 리뷰 대상 브랜치 실행해보기
npm run dev  # 포트 3001에서 실행

# 동시에 main worktree에서 내 작업 계속
cd ../my-project
npm run dev  # 포트 3000에서 실행

# v1.x 유지보수 브랜치를 상시 열어두기
git worktree add ../my-project-v1 release/v1.x

# 필요할 때 언제든 패치 작업
cd ../my-project-v1
git cherry-pick <커밋해시>  # main의 버그픽스를 v1에 적용

git worktree add ../my-project-staging staging
git worktree add ../my-project-prod main

# 병렬 빌드
(cd ../my-project-staging && npm run build) &
(cd ../my-project-prod && npm run build) &
wait

~/projects/
├── my-project/           ← main worktree
├── my-project-hotfix/    ← hotfix용
├── my-project-review/    ← PR 리뷰용
└── my-project-exp/       ← 실험적 작업

~/projects/my-project/
├── .bare/               ← Bare 저장소 (실제 Git 데이터)
├── main/                ← main worktree
├── hotfix/              ← hotfix worktree
└── feature-x/           ← feature worktree

# 방법 1: 심볼릭 링크
ln -s ../my-project/.env ../my-project-hotfix/.env

# 방법 2: 공유 경로 참조 (.env.shared 등 별도 관리)
# 방법 3: 각 worktree마다 별도 .env 생성

# 해결책 1: 심볼릭 링크 (패키지 버전이 같을 경우)
ln -s ../my-project/node_modules ../my-project-hotfix/node_modules

# 해결책 2: pnpm 사용 (글로벌 패키지 캐시로 중복 최소화)
# pnpm은 하드링크 기반으로 디스크 사용량을 대폭 줄여준다

# 해결책 3: 그냥 각각 npm install
# (브랜치마다 패키지 버전이 다를 수 있으므로 이게 가장 안전함)

# 1. 프로젝트 폴더 생성
mkdir my-project && cd my-project

# 2. Bare clone (--bare는 작업 파일 없이 .git 데이터만 클론)
git clone --bare git@github.com:my-org/my-project.git .bare

# 3. .git 파일 생성 (일반 git 명령어가 bare 저장소를 인식하게)
echo "gitdir: ./.bare" > .git

# 4. 원격 브랜치 fetch 설정 (bare clone은 기본적으로 fetch 설정이 없음)
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch

# 5. 이제 worktree 추가
git worktree add main main
git worktree add feature feature/new-api

my-project/
├── .bare/         ← 실제 Git 데이터
├── .git           ← "gitdir: ./.bare" 한 줄짜리 파일
├── main/          ← main 브랜치 worktree
└── feature/       ← feature 브랜치 worktree

# worktree 빠르게 추가하는 함수
function gwt() {
  local branch=$1
  local path="../$(basename $(pwd))-${branch//\//-}"
  git worktree add "$path" "$branch"
  echo "✅ Worktree created at: $path"
  echo "   cd $path"
}

# 사용법
gwt hotfix/login-bug
# → ../my-project-hotfix-login-bug 에 worktree 생성

# 현재 저장소의 worktree 간 빠른 이동
function gwtcd() {
  local worktree
  worktree=$(git worktree list | fzf | awk '{print $1}')
  [ -n "$worktree" ] && cd "$worktree"
}

# 각 worktree를 새 VS Code 창으로 열기
code ../my-project-hotfix

# 현재 창에서 새 worktree 폴더 추가 (멀티루트 워크스페이스)
# VS Code: File > Add Folder to Workspace

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

cd ../my-project-hotfix
git submodule update --init --recursive

┌─────────────────────┬─────────────────────┐
│ my-project (main)   │ my-project-hotfix   │
│ $ npm run dev       │ $ git log --oneline │
├─────────────────────┼─────────────────────┤
│ my-project-feature  │ my-project-review   │
│ $ vim src/api.ts    │ $ npm test          │
└─────────────────────┴─────────────────────┘

# my-project-hotfix/.envrc
export NODE_ENV=production
export PORT=3001

git worktree add ../$(basename $(pwd))-hotfix -b hotfix/my-first-worktree main