Git Worktree 알아보기

AI Agent 활용과 관련되어 많은 유스케이스들이 나오는 가운데 중심이 되는 키워드는 생산성이다.

기존에 손이 부족하여 작업하지 못했던 작업들도 동시 작업을 통해 생산성을 극한으로 끌어올리며 이를 실현시키는 요즘에 진행 중인 작업 외에 다른 작업을 병렬로 진행하는 경우가 더러 발생하는 것 같다.

이와 관련해 최근 멀티 에이전트와 오케스트레이션이 화두로 떠오르는 가운데, 비교적 오래된 기능인 Git Worktree가 새삼 주목받고 있다. Claude Code 공식 문서 에서도 세션 병렬 실행을 위해 Git Worktree를 활용하는 워크플로우를 설명하고 있으며, 이를 계기로 해당 기능에 대해 살펴보게 되었다.

병렬 실행 외에도 실무에 바로 적용할 수 있는 기능이라고 판단해 간단히 학습을 진행했고, 실제 적용 경험을 바탕으로 후기를 정리해 보고자 한다.

Git Worktree란

Git Worktree는 하나의 Git 저장소에서 여러 개의 작업 디렉토리를 동시에 사용할 수 있게 해주는 기능이다.

일반적으로 Git 저장소는 하나의 작업 디렉토리만 가진다. 다른 브랜치를 확인하려면 git checkout이나 git switch로 브랜치를 전환해야 하고, 그때마다 작업 디렉토리의 파일들이 통째로 바뀌게 된다.

Git Worktree는 이 제약을 깨준다. 별도의 디렉토리에 다른 브랜치를 체크아웃해두고, 각 디렉토리에서 독립적으로 작업할 수 있다.

쉽게 말해, 하나의 저장소를 여러 폴더에서 동시에 열어놓는 것이다.

기본 사용법

Worktree 생성

git worktree add ../project-hotfix hotfix/login-bug

위 명령어는 현재 저장소의 상위 경로에 project-hotfix라는 디렉토리를 만들고, 그 안에 hotfix/login-bug 브랜치를 체크아웃한다.

새 브랜치를 만들면서 worktree를 생성할 수도 있다.

git worktree add -b feature/new-ui ../project-new-ui main

main 브랜치를 기반으로 feature/new-ui 브랜치를 생성하고, ../project-new-ui 디렉토리에 체크아웃한다.

Worktree 목록 확인

git worktree list

현재 저장소에 연결된 모든 worktree 경로와 브랜치를 확인할 수 있다.

Worktree 제거

git worktree remove ../project-hotfix

작업이 끝난 worktree는 remove 명령어로 정리한다. 디렉토리와 함께 worktree 연결이 해제된다.

실무에서 유용했던 순간들

Git Worktree의 개념 자체는 단순하지만, 실무에 적용하면서 체감한 이점은 꽤 컸다.

핫픽스와 스프린트 작업 분리

스프린트 작업을 진행하다가 갑작스러운 핫픽스 요청이 들어오는 상황은 꽤 빈번하다.

기존에는 이런 흐름이었다.

1. 작업 중인 변경사항을 git stash로 임시 저장
2. 핫픽스 브랜치로 전환
3. 수정 후 커밋, 푸시
4. 다시 원래 브랜치로 전환
5. git stash pop으로 복원
6. 가끔 stash 충돌까지 해결

Git Worktree를 사용하면 이 과정이 사라진다. 핫픽스용 worktree를 하나 만들어두면, 스프린트 작업 디렉토리는 그대로 둔 채 핫픽스 디렉토리에서 바로 작업하면 된다.

stash를 떠올릴 필요가 없다는 것만으로도 충분히 가치가 있었다.

마이그레이션 작업처럼 규모가 크고 장기적으로 진행되는 작업도 마찬가지다. 별도의 worktree로 분리해두면 백로그나 스프린트 작업과 독립적으로 관리할 수 있다.

의존성과 환경 변수가 다른 브랜치 작업

실무에서 특히 유용하다고 느낀 부분은 의존성이나 환경 변수가 다른 브랜치 간 전환이 필요한 경우다.

브랜치를 전환할 때마다 발생하는 일들을 생각해보자.

• package.json이 다르면 npm install을 다시 실행해야 한다
• .env 파일이 브랜치마다 다르면 매번 수정하거나 교체해야 한다
• 빌드 캐시가 꼬여서 node_modules를 날리고 다시 설치하는 경우도 있다

Git Worktree를 사용하면 각 디렉토리가 독립적인 node_modules와 .env를 가질 수 있기 때문에, 브랜치를 옮겨가며 의존성을 재설치하는 번거로움에서 벗어날 수 있다.

주의할 점

편리한 기능이지만 몇 가지 유의할 부분이 있다.

• worktree 디렉토리 위치: 프로젝트 내부가 아닌 상위 혹은 형제 경로에 생성하는 것이 깔끔하다. 프로젝트 내부에 만들면 IDE가 혼란스러워할 수 있다.
• 정리 습관: 작업이 끝난 worktree는 바로 제거하는 습관을 들이자. git worktree list로 현황을 수시로 확인하면 좋다.
• IDE 설정: 각 worktree 디렉토리를 별도의 프로젝트 창으로 열어야 한다. 같은 IDE 창에서 여러 worktree를 다루기는 어렵다.

마무리

Git Worktree는 새로운 기능은 아니지만, 병렬 작업이 일상이 된 요즘 환경에서 다시 꺼내 볼 만한 도구라고 생각한다.

특히 핫픽스와 스프린트 작업을 분리하거나, 의존성이 다른 브랜치 사이를 오가야 하는 상황에서 브랜치 전환의 비용을 크게 줄여주었다.

stash와 브랜치 전환에 지친 적이 있다면 한번 시도해보는 것을 권한다.