Git Worktree는 하나의 저장소에 연결된 작업 디렉터리를 여러 개 둘 수 있게 한다. 진행 중인 변경을 stash로 밀어 넣지 않고도 핫픽스, 코드 리뷰, 버전 비교를 별도 폴더에서 진행할 수 있다.
이 글의 예시는 2026년 7월 23일 이 저장소에서 읽기 전용 명령으로 확인했다.
현재 저장소에서 확인한 결과
git --version
git worktree list --porcelain
확인 결과는 다음과 같았다.
| 항목 | 값 |
|---|---|
| Git | 2.40.1.windows.1 |
| 연결된 worktree | 1개 |
| 현재 브랜치 | v5 |
| HEAD 축약값 | f935cb2 |
현재는 추가 worktree가 없으므로 “이미 여러 브랜치를 병렬 운영 중”이라고 말할 근거는 없다. 아래 절차는 새 worktree가 필요할 때 재현하는 방법이다.
checkout, clone, worktree 비교
| 방식 | Git 객체 저장소 | 작업 파일 | 적합한 상황 | 주의점 |
|---|---|---|---|---|
| checkout 전환 | 공유 | 한 폴더 | 변경이 깨끗하고 한 브랜치만 볼 때 | 미커밋 변경과 실행 상태를 정리해야 함 |
| 별도 clone | 별도 | 별도 폴더 | 완전히 독립된 원격·설정이 필요할 때 | 객체와 의존성을 중복 저장 |
| worktree | 공유 | 별도 폴더 | 같은 저장소의 브랜치를 동시에 볼 때 | 브랜치별 ignored 파일과 의존성은 따로 준비 |
worktree는 Git 객체를 공유하지만 각 작업 폴더의 index와 HEAD는 분리한다. 공식 동작과 옵션은 git-worktree 매뉴얼이 기준이다.
새 브랜치를 별도 폴더에 추가하기
먼저 현재 상태를 확인한다.
git status --short
git worktree list
그다음 저장소 바깥의 명확한 경로에 새 브랜치를 만든다.
git worktree add -b docs/worktree-demo ../blog-worktree-demo HEAD
명령의 의미는 다음과 같다.
- -b docs/worktree-demo: 새 브랜치를 만든다.
- ../blog-worktree-demo: 별도 작업 폴더다.
- HEAD: 현재 커밋에서 분기한다.
기존 브랜치를 열 때는 -b를 빼고 브랜치 이름을 마지막 인수로 준다.
git worktree add ../blog-hotfix hotfix/login
같은 로컬 브랜치는 기본적으로 둘 이상의 worktree에서 동시에 체크아웃할 수 없다. 같은 기준점을 두 개 열고 싶다면 서로 다른 브랜치를 만들거나 detached worktree를 사용한다.
폴더마다 다시 준비할 것
Git 객체는 공유하지만 다음 항목은 자동 복사되지 않을 수 있다.
- .gitignore에 포함된 .env 파일
- node_modules 같은 설치 결과
- 에디터의 워크스페이스 설정
- 로컬 데이터베이스와 캐시
- 개발 서버 포트
이 블로그 저장소는 package.json에서 Node.js 22 이상을 요구한다. 두 worktree에서 사이트를 동시에 띄우려면 각 폴더에서 의존성을 설치하고 포트를 분리해야 한다.
npm ci
npm run dev -- --port 8081
다른 worktree에서는 8082처럼 다른 포트를 사용한다. package script가 포트 인수를 지원하는지는 실행 전에 확인해야 한다.
작업이 끝난 뒤 검증하고 정리하기
삭제 전에 어느 폴더가 어느 브랜치인지 다시 확인한다.
git worktree list --porcelain
git -C ../blog-worktree-demo status --short
미커밋 변경이 없다면 Git 명령으로 worktree를 제거한다.
git worktree remove ../blog-worktree-demo
git branch -d docs/worktree-demo
폴더를 탐색기에서 먼저 지웠다면 남은 관리 정보를 확인한 뒤 정리한다.
git worktree prune --dry-run
git worktree prune
dry-run 결과를 먼저 보는 이유는 Git이 어떤 항목을 오래된 worktree로 판단하는지 확인하기 위해서다. 이동식 드라이브나 잠시 분리되는 경로라면 prune 대신 worktree lock을 검토한다.
실무 체크리스트
| 시점 | 확인 명령 | 실패하면 할 일 |
|---|---|---|
| 추가 전 | git status —short | 현재 변경을 먼저 이해한다. |
| 추가 후 | git worktree list | 경로와 브랜치가 의도와 같은지 확인한다. |
| 실행 전 | node —version | 프로젝트 엔진 요구사항과 맞춘다. |
| 제거 전 | git -C 경로 status —short | 미커밋 파일을 커밋하거나 별도로 보관한다. |
| 수동 삭제 후 | git worktree prune —dry-run | 정리 대상을 확인한다. |
한계
- 이 글에서는 새 worktree를 실제로 만들지 않았다. 사용자의 저장소 밖에 폴더와 브랜치를 생성하는 변경을 피하기 위해 읽기 전용 상태만 확인했다.
- worktree마다 node_modules를 설치하면 디스크 사용량은 여전히 늘어난다.
- 추적되지 않는 비밀 파일은 공유되지 않는다. 복사할 때 저장소에 커밋하지 않도록 주의해야 한다.
- Git 공식 문서는 superproject를 여러 번 체크아웃할 때 submodule 지원이 불완전하다고 경고한다.
- 병렬 서버 실행은 포트뿐 아니라 데이터베이스, 캐시, 외부 웹훅 충돌도 분리해야 한다.
worktree의 장점은 “몇 분 절약” 같은 보장된 숫자가 아니라, 서로 다른 브랜치의 작업 파일과 실행 상태를 동시에 유지할 수 있다는 데 있다.