Git worktree 사용법: 브랜치 작업 폴더 나누기

긴급 수정과 새 기능 개발을 동시에 해야 할 때 브랜치를 번갈아 전환하면 작업 중인 파일과 의존성 상태가 뒤섞이기 쉽다. 별도 clone을 두 개 만들 수도 있지만, 같은 저장소의 커밋·브랜치를 공유하면서 작업 폴더만 분리하는 Git worktree가 더 간단한 경우가 있다. 이 글은 임시 예제 저장소를 만들어 추가 작업 트리를 만들고, 수정·병합·정리까지 한 번에 따라간다.

언제 유용한가

메인 폴더에서 기능 개발을 진행하는 동안 다른 폴더에서 긴급 수정 브랜치를 checkout할 수 있다. 각 작업 트리의 파일·인덱스·HEAD는 별도로 관리되지만 같은 저장소의 커밋과 브랜치를 공유한다. 따라서 “두 폴더가 서로 완전히 독립된 저장소”라는 뜻은 아니다. 같은 브랜치를 여러 작업 트리에서 동시에 checkout하려 하면 Git이 기본적으로 막는다.

준비 조건

Git이 설치된 터미널에서 git --version을 실행한다. 아래 예제는 git init -b main을 사용하므로 이를 지원하는 Git 버전을 쓰거나, 구버전이라면 초기화 후 기본 브랜치 이름을 직접 맞춰야 한다. macOS·Linux의 POSIX 셸을 기준으로 작성했으며 Windows는 Git Bash에서 같은 흐름을 따라갈 수 있다. 예제는 새 폴더에서만 실행하며 기존 업무 저장소의 변경 사항을 지우지 않는다.

git --version
mkdir worktree-demo
cd worktree-demo
git init -b main
git config user.name "Worktree Demo"
git config user.email "[email protected]"
printf "# Worktree demo\n" > README.md
git add README.md
git commit -m "Initial demo"
git status --short

마지막 git status --short의 출력이 비어 있으면 작업 폴더가 깨끗하다. user.name과 user.email은 이 예제 저장소의 로컬 설정이며 실제 팀 저장소에서는 본인의 이름·이메일을 사용한다. 기존 저장소에 적용할 때는 이미 커밋이 있고 깨끗한 작업 폴더인지 먼저 확인한다.

첫 worktree

메인 폴더에서 다음 명령을 실행한다. -b hotfix는 새 브랜치를 만들고 ../worktree-demo-hotfix는 그 브랜치를 펼칠 별도 폴더다. 형제 폴더가 이미 있으면 다른 경로를 골라야 한다.

git worktree add -b hotfix ../worktree-demo-hotfix
git worktree list

두 줄이 나오면 성공이다. 하나는 메인 폴더의 main, 다른 하나는 추가 폴더의 hotfix다. 두 폴더의 .git 구조가 같은 형태일 필요는 없다. 추가 worktree 안의 .git은 보통 메인 저장소의 관리 정보를 가리키는 파일이다. 따라서 이 파일이나 메인 .git/worktrees를 임의로 옮기거나 지우지 않는다.

두 작업의 경계

이 그림에서 화살표는 파일 복사 방향이 아니라 저장소와 작업 폴더의 연결 관계다. 저장소가 같다고 한 폴더의 미커밋 파일 변경이 다른 폴더에 곧바로 나타나는 것은 아니다. 커밋을 만들고 브랜치를 병합·체리픽하는 일반 Git 절차를 거쳐야 반영된다.

실무 예제

이번에는 긴급 수정 폴더에서 README를 고치고 커밋한다. 명령은 worktree-demo 폴더에서 시작한다고 가정한다.

cd ../worktree-demo-hotfix
printf "Hotfix: handle failed payments.\n" >> README.md
git status --short
git add README.md
git commit -m "Document payment hotfix"
cd ../worktree-demo
git log --oneline main..hotfix
git merge --ff-only hotfix
git log --oneline -2

git log --oneline main..hotfix가 새 hotfix 커밋을 보이고, git merge --ff-only hotfix가 fast-forward로 끝나면 긴급 수정이 main에 들어온 것이다. 다른 사람이 이미 main에 커밋을 쌓았다면 fast-forward가 불가능할 수 있다. 이때 강제로 덮어쓰지 말고 팀의 병합·리베이스 정책에 따라 충돌을 해결한다. 명령을 실제 업무 저장소에서 그대로 붙여 넣기 전에 브랜치·경로를 자신의 상황에 맞게 바꾼다.

주요 명령

• git worktree list: 연결된 작업 폴더와 브랜치, 상태를 확인한다. 자동화에서는 --porcelain 형식을 이용한다.
• git worktree add -b 새브랜치 경로: 현재 HEAD에서 새 브랜치를 만들며 작업 폴더를 추가한다. 기존 브랜치를 열 때는 -b 없이 브랜치 이름을 지정한다.
• git worktree add --detach 경로: 브랜치를 점유하지 않는 실험용 작업 트리를 만든다. 중요한 커밋은 브랜치를 붙여 보존한다.
• git worktree lock --reason "external drive" 경로: 외장 드라이브처럼 잠시 분리될 경로의 관리 정보가 자동 정리되지 않도록 잠근다.
• git worktree repair 경로: 작업 폴더를 수동 이동한 뒤 연결을 복구할 때 사용한다. 먼저 현재 경로를 확인한다.

--force는 이미 다른 곳에서 checkout한 브랜치나 변경된 폴더를 다루는 안전장치를 우회할 수 있다. 원인을 파악하지 못했다면 사용하지 않는다. 각 worktree마다 빌드 산출물과 의존성 디렉터리가 별도로 생길 수 있으므로 디스크 사용량과 무시 규칙도 확인한다.

정리와 되돌리기

병합을 확인했고 hotfix 폴더의 미커밋 파일이 없다면 메인 폴더에서 다음 순서로 정리한다. git worktree remove는 해당 작업 폴더를 지우므로 그 안에 보관해야 할 파일이 없는지 git -C ../worktree-demo-hotfix status --short로 먼저 확인한다.

git -C ../worktree-demo-hotfix status --short
git worktree remove ../worktree-demo-hotfix
git branch -d hotfix
git worktree list

브랜치를 병합하지 않았다면 git branch -d가 삭제를 거절할 수 있다. 이때 먼저 커밋의 보존 여부와 병합 대상을 확인한다. 강제 브랜치 삭제나 git worktree remove --force를 복구 수단처럼 쓰지 않는다. 폴더를 파일 관리자에서 이미 지웠다면 git worktree list로 상태를 확인하고 git worktree prune -n으로 정리 대상만 미리 본 다음 필요할 때 git worktree prune을 실행한다. prune은 잃어버린 파일을 복원하지 않는다.

흔한 오류

• already checked out: 같은 브랜치가 다른 worktree에 있다. git worktree list로 위치를 찾고 다른 브랜치를 쓰거나 기존 폴더에서 작업한다.
• 경로가 이미 존재함: 새 빈 경로를 선택한다. 기존 폴더를 무작정 덮어쓰지 않는다.
• 제거가 거절됨: 변경되거나 추적되지 않은 파일이 있는지 해당 폴더의 git status --short를 확인한다. 필요한 파일을 먼저 커밋하거나 안전한 위치로 옮긴다.
• 경로 이동 후 연결 오류: 수동 이동을 했다면 git worktree repair를 검토한다. 처음부터 이동할 계획이라면 git worktree move의 제한 사항을 확인한다.

선택 기준

브랜치를 빈번하게 오가거나 여러 작업을 병렬로 테스트할 때 worktree는 값어치를 한다. 그러나 디스크가 작고 빌드 산출물이 매우 크거나 같은 폴더만 쓰면 충분한 단일 작업에는 오히려 관리 비용이 늘 수 있다. 핵심은 “커밋은 공유, 미커밋 파일은 분리”라는 경계를 알고 쓰는 것이다.

출처

• Git 공식 git-worktree 설명서
• Git 공식 git-switch 설명서