worktree는 브랜치를 폴더로 펼친 것이다

이 글은 를 브랜치와 구분해서 설명한다. 범위는 같은 저장소에서 작업을 여러 갈래로 동시에 진행할 때 무엇이 폴더 하나를 차지하는가이다. 특정 편집기나 에이전트 제품의 사용법은 이 글의 범위가 아니다.

같은 저장소를 두 창에 띄워 놓고 작업 위치를 잃는 일이 있다. 화면이 둘 다 편집기처럼 생겼기 때문에 생기는 혼동이 아니다. 브랜치를 바꾸는 일과 폴더를 하나 더 여는 일이 서로 다른 동작이라는 점을 구분하지 않아서 생긴다.

정의

단위: 저장소를 디스크에 따로 펼쳐 둔 폴더 하나다.

범위: 한 저장소에서 여러 작업을 동시에 진행할 때의 작업 공간을 다룬다.

제외 대상: 커밋을 어떻게 나눌지, 리뷰를 어떻게 받을지, 어느 편집기를 쓸지는 이 단위와 다르다.

실패 조건: 지금 고치는 파일이 어느 브랜치의 파일인지 확인하지 않고 저장하는 상태다.

세 가지 말을 나눈다

브랜치와 worktree와 작업 카드는 층위가 다르다. 아래 셋을 섞으면 “어느 브랜치에 있는가”와 “어느 폴더에 있는가”가 같이 흔들린다.

작업 공간을 가리키는 말

브랜치 커밋을 가리키는 이름이다. 디스크를 차지하지 않는다.
worktree 저장소를 디스크에 펼쳐 둔 폴더다. 보통 그 안에 체크아웃된 브랜치가 하나 있다.
작업 카드 그 폴더 위에 터미널과 에이전트와 진행 상태를 얹은 도구의 표현이다. git의 개념이 아니다.

폴더 하나에서 checkout만 바꾸면 브랜치는 옮겨지지만 작업 공간은 하나다. 이때 이전 브랜치에서 하던 일은 커밋하거나 따로 치워 두어야 한다. worktree를 하나 더 만들면 두 브랜치가 각자의 폴더에 동시에 펼쳐진다. 버그 하나와 리뷰 하나를 같은 저장소에서 나란히 진행할 수 있는 이유가 이것이다.

왜 필요한가

작업이 갈래로 나뉘는데 작업 공간이 하나면, 갈래를 바꿀 때마다 하던 일을 치워야 한다. 치우는 동작 자체가 사고의 원인이 된다. 특히 여러 세션이 같은 저장소를 볼 때 그렇다.

한 저장소가 갈라지는 자리

저장소 커밋 기록과 브랜치 이름을 보관한다.
worktree 브랜치 하나를 폴더 하나에 펼친다. 여러 개를 동시에 둘 수 있다.
작업 각 폴더에서 편집, 실행, 커밋이 서로 간섭 없이 진행된다.

아닌 것

worktree는 브랜치를 대체하지 않는다. 브랜치는 여전히 커밋을 가리키는 이름이고, worktree는 그 이름을 펼쳐 둔 자리다. 브랜치 없이 worktree만 만들 수는 없다.

worktree는 에이전트 전용 개념도 아니다. git이 오래전부터 제공하는 기능이고, 사람이 손으로 두 갈래를 동시에 진행할 때도 같은 방식으로 쓴다. 에이전트에게 일을 맡기는 도구가 이 기능을 작업 카드로 감싸서 보여 줄 뿐이다.

worktree는 저장소의 사본도 아니다. 커밋 기록은 한 벌만 있고, 각 폴더는 그 기록을 공유한다. 그래서 한 폴더에서 만든 커밋을 다른 폴더에서 바로 볼 수 있다. 다만 공유되기 때문에 조심할 자리도 생긴다. 예를 들어 임시 저장 스택은 저장소 전체가 함께 쓰므로, 여러 폴더에서 동시에 꺼내면 남의 작업을 꺼낼 수 있다.

손을 어디에 둘지

작업 공간을 나누고 나면 남는 질문은 하나다. 그 폴더에 내가 들어갈 것인가, 다른 실행 주체에게 넘길 것인가.

한 줄씩 확인하면서 이어 가야 하는 일은 손이 닿는 자리에 둔다. 리팩터와 문서 수정이 여기에 속한다. 넘기고 나면 그 폴더의 진행은 넘겨받은 쪽이 가진다. 옆에서 계속 만지려면 애초에 넘기지 않는다.

다음에 열 것

이 글의 범위는 작업 공간의 단위까지다. 아직 다루지 않은 내용은 아래와 같다.

폴더를 정리하는 시점: 작업이 끝난 worktree를 언제 지울지, 지우지 않으면 무엇이 쌓이는지.
여러 주체가 같은 저장소를 볼 때의 규칙: 임시 저장 스택처럼 공유되는 상태를 어떻게 다룰지.

명령의 영어 이름과 옵션은 아래 출처에 있다.