Git worktree 사용법

Git worktree 사용법

git worktree는 하나의 Git 저장소에 여러 working tree를 연결해서, 서로 다른 브랜치를 동시에 체크아웃할 수 있게 하는 기능이다. 2026년 6월 1일 기준 Git 공식 문서에서는 main worktree 하나와 0개 이상의 linked worktree를 둘 수 있다고 설명한다.

실무에서 이 기능이 필요한 이유는 단순하다. 기능 개발 브랜치를 유지한 채 hotfix를 바로 열거나, 리뷰 재현용 작업 디렉터리를 따로 만들거나, 실험용 checkout을 기존 작업과 분리할 수 있기 때문이다. 이 글은 Git 공식 문서를 기준으로 add, list, remove, lock, prune, repair를 어떻게 판단하면 되는지 정리한다.

Git worktree는 정확히 무엇을 만들까?

공식 문서는 worktree를 "repository에 연결된 working tree와 그를 구분하기 위한 추가 메타데이터"로 설명한다. 즉 저장소를 통째로 여러 번 복제하는 방식이 아니라, 하나의 저장소 이력을 공유하면서 작업 디렉터리만 추가로 여는 구조에 가깝다.

Git은 처음 git init이나 git clone으로 만들어진 디렉터리를 main worktree로 보고, 이후 git worktree add로 만든 디렉터리를 linked worktree로 관리한다. linked worktree를 다 썼다면 공식 문서 기준 정식 정리 방법은 git worktree remove다.

언제 clone보다 worktree가 더 직접적일까?

이미 같은 저장소를 로컬에 받아 둔 상태에서 브랜치 하나만 더 열어야 한다면 git worktree가 더 직접적이다. 새 clone은 저장소 메타데이터와 원격 설정을 다시 준비해야 하지만, worktree는 기존 저장소에 연결된 새 작업 디렉터리를 추가하는 방식이라 맥락 전환이 빠르다.

반대로 서로 완전히 다른 Git 설정, 별도의 object store, 완전히 독립된 인증이나 hook 구성이 필요한 경우에는 별도 clone이 더 분명할 수 있다. 공식 문서도 worktree를 "같은 repository에 연결된 복수의 working tree"로 설명하므로, 독립 저장소가 필요한 상황까지 대체하는 기능으로 보면 과하다.

git worktree add는 어떻게 동작할까?

Git 공식 문서에 따르면 가장 단순한 형태의 git worktree add <path>는 새 worktree를 만들면서, 경로의 마지막 요소를 이름으로 하는 새 브랜치를 자동 생성해 체크아웃할 수 있다. 예를 들어 ../hotfix를 주면 hotfix 브랜치를 새로 만들고 그 경로에 연결하는 식이다.

기존 브랜치를 새 worktree에서 열고 싶다면 git worktree add <path> <branch> 형태를 쓴다. 문서는 실험이나 테스트처럼 브랜치에 묶지 않을 작업이라면 git worktree add -d <path>로 detached HEAD worktree를 만드는 예도 제시한다.

가장 많이 쓰는 패턴은 무엇일까?

상황	예시 명령	해석
새 기능 브랜치를 별도 디렉터리에서 시작	git worktree add ../feature-login	경로 이름을 따라 새 브랜치를 만들 가능성이 있다.
기존 브랜치를 따로 열기	git worktree add ../release release	이미 있는 브랜치를 다른 디렉터리에서 동시에 본다.
실험용 임시 checkout	git worktree add -d ../scratch	브랜치 없이 detached HEAD로 연다.

핵심 판단 기준은 "브랜치 이력을 남길 작업인지"와 "잠깐 확인만 할 실험인지"다. 브랜치로 이어질 작업이면 branch 기반 add가 맞고, 잠깐 빌드 확인이나 비교만 할 경우에는 detached HEAD가 더 깔끔하다.

git worktree list는 무엇을 보여줄까?

공식 문서에서 list는 main worktree를 먼저, 그 다음 linked worktree를 나열한다고 설명한다. 출력에는 현재 체크아웃한 revision, 연결된 branch 또는 detached HEAD 여부, 잠금 여부, prune 대상 여부가 포함될 수 있다.

즉 여러 작업 디렉터리가 생기면 list가 사실상 인벤토리 역할을 한다. 어떤 경로가 아직 살아 있고, 어느 브랜치가 어느 디렉터리에 연결돼 있는지, 잠금이나 정리 대상이 있는지 확인할 때 가장 먼저 보는 명령이다.

정리할 때는 왜 수동 삭제보다 remove가 낫나?

공식 문서는 linked worktree를 다 썼다면 git worktree remove로 정리하라고 안내한다. 디렉터리만 수동으로 지워 버리면 저장소 내부의 administrative files가 바로 함께 정리되지 않을 수 있기 때문이다.

문서에 따르면 수동 삭제로 남은 administrative files는 시간이 지나 자동 정리되거나, 사용자가 git worktree prune를 실행해 치울 수 있다. 그래서 작업 종료 시점에는 remove, 잔여 메타데이터 청소에는 prune라는 구분이 가장 단순하다.

lock과 prune는 언제 같이 봐야 할까?

Git 공식 문서는 외장 디스크나 네트워크 공유처럼 항상 마운트되지 않는 경로의 worktree라면 git worktree lock으로 잠글 수 있다고 설명한다. 필요하면 --reason으로 잠금 이유도 기록할 수 있다.

이 잠금은 단순 표시가 아니라 pruning 방지와 연결된다. Git 저장소 레이아웃 문서는 worktrees/<id>/locked 파일이 있으면 해당 linked worktree가 자동 또는 수동 git worktree prune 대상에서 제외된다고 설명한다. 그래서 휴대용 장치 위 worktree는 lock을 먼저 고려하는 편이 맞다.

이동이 필요한 경우에는 무엇을 주의해야 할까?

공식 문서에서 git worktree move는 worktree 경로를 새 위치로 옮기는 명령이지만, main worktree는 이동할 수 없고 submodule을 포함한 linked worktree도 이 명령으로는 옮길 수 없다고 설명한다.

대신 문서는 main worktree를 수동으로 옮긴 뒤 연결을 다시 세워야 하는 경우 git worktree repair를 언급한다. 즉 이동이 필요한 상황이라면 "그냥 파일 시스템에서 경로를 바꾸는가"보다, "Git이 연결 정보를 다시 인식할 수 있는가"를 함께 봐야 한다.

worktree별 설정은 어디에 저장될까?

Git 공식 문서에서 git config --worktree는 extensions.worktreeConfig가 켜져 있을 때 $GIT_DIR/config.worktree를 읽고 쓰는 방식으로 설명된다. linked worktree에서는 이 $GIT_DIR가 공용 저장소 루트가 아니라 $GIT_DIR/worktrees/<id>/ 형태가 될 수 있다.

저장소 레이아웃 문서도 main working directory용 config.worktree와 linked worktree별 worktrees/<id>/config.worktree가 존재할 수 있음을 명시한다. 따라서 모든 설정을 공용 .git/config에 넣는다고 가정하면 worktree별 동작을 오해할 수 있다.

FAQ

Q. 브랜치 없이도 worktree를 만들 수 있나?

그럴 수 있다. Git 공식 문서는 실험이나 테스트처럼 기존 브랜치를 건드리지 않을 작업이라면 git worktree add -d <path>로 detached HEAD worktree를 만드는 예를 제시한다.

Q. worktree 디렉터리를 Finder나 파일 탐색기에서 그냥 지워도 되나?

가능은 하지만 권장되는 정리 방식은 아니다. Git 공식 문서는 수동 삭제 후 남은 administrative files가 나중에 자동 정리되거나 prune로 치워질 수 있다고 설명하므로, 처음부터 git worktree remove를 쓰는 편이 더 명확하다.

Q. 외장 SSD에 둔 worktree가 가끔 사라진 것처럼 보이면 어떻게 봐야 하나?

공식 문서 기준으로 그런 경로는 git worktree lock 대상이다. 잠금을 걸면 pruning으로 메타데이터가 지워지는 일을 줄일 수 있고, 이유를 함께 남겨 두면 나중에 정리 판단도 쉬워진다.

정리

git worktree의 핵심은 같은 저장소를 유지한 채 브랜치별 작업 디렉터리를 분리하는 데 있다. 현재 Git 공식 문서 기준으로 새 작업 시작은 add, 현황 확인은 list, 정상 정리는 remove, 휴대용 경로 보호는 lock, 잔여 메타데이터 청소는 prune, 이동 후 연결 복구는 repair로 이해하면 된다.

대부분의 개발 환경에서는 기능 브랜치 하나당 worktree 하나라는 규칙만 잡아도 운영이 단순해진다. 반대로 임시 실험이나 재현 작업은 detached HEAD worktree로 분리하면 현재 작업 디렉터리를 건드리지 않고 확인 범위를 좁힐 수 있다.

참고 자료

• Git Documentation: git-worktree
• Git Documentation: git-config
• Git Documentation: gitrepository-layout