Git 체크아웃이 뭘까? — 브랜치를 작업 폴더에 펼친다는 것

소개

worktree로 작업하던 중 다른 브랜치로 옮기려고 git switch를 실행했더니 이런 에러가 났다.

fatal: 'feat/e2e-playwright' is already used by worktree at '/home/user/projects/app'

"이미 다른 worktree가 쓰고 있다"는 말인데, 그 전에 체크아웃이라는 단어부터 정확히 짚고 넘어가야 이 에러가 이해된다.

체크아웃이란?

하나의 Git 저장소에는 여러 브랜치(작업 갈래)가 들어 있다. 하지만 작업 폴더에서 실제로 보고 편집하는 파일은 한 시점에 한 브랜치의 내용일 수밖에 없다.

체크아웃은 **"이 브랜치의 내용을 지금 작업 폴더에 펼쳐서 꺼내 놓는 것"**이다.

책장에 비유하면 이렇다.

• 저장소 = 여러 권의 책이 꽂힌 책장 (각 책 = 브랜치)
• 체크아웃 = 그중 한 권을 꺼내 책상 위에 펼치는 것
• 책상(작업 폴더) 위에는 한 번에 한 권만 펼칠 수 있다

# feat/login 브랜치를 작업 폴더에 펼친다
git switch feat/login
# (예전 명령) git checkout feat/login

이 명령을 실행하면 작업 폴더의 파일들이 해당 브랜치 상태로 싹 바뀌고, 이후의 편집과 커밋은 그 브랜치에 쌓인다.

worktree: 책상을 여러 개 두기

보통은 저장소 폴더 하나에 브랜치 하나만 펼쳐 쓴다. 그런데 worktree를 쓰면 같은 저장소를 여러 폴더에 동시에 펼쳐 두고, 각 폴더마다 서로 다른 브랜치를 체크아웃할 수 있다. 책상을 여러 개 두고 각각 다른 책을 펼쳐 놓는 셈이다.

~/projects/app                      → feat/e2e-playwright  (메인 체크아웃)
~/projects/app/.worktrees/feature   → feat/login          (추가 worktree)

여기서 메인 체크아웃은 처음 git clone으로 만든 원래의 그 프로젝트 폴더를 말한다.

왜 같은 브랜치를 두 곳에 펼칠 수 없나

Git에는 규칙이 하나 있다. 하나의 브랜치는 동시에 한 worktree에서만 체크아웃할 수 있다.

만약 같은 브랜치를 두 폴더에 펼치면, 한쪽에서 커밋해 브랜치가 가리키는 위치가 바뀌었을 때 다른 쪽 폴더의 상태와 어긋나 버린다. 이 혼란을 막으려고 Git이 아예 중복 체크아웃을 거부한다.

앞의 에러도 바로 이것이었다. feat/e2e-playwright는 이미 메인 체크아웃 폴더가 펼쳐 두고 있어서, 다른 worktree에서 또 같은 브랜치로 옮기려다 거부당한 것이다.

어디에 무엇이 펼쳐져 있는지 확인하기

지금 어떤 폴더에 어떤 브랜치가 체크아웃되어 있는지는 한 줄로 볼 수 있다.

git worktree list

/home/user/projects/app                     b65681b [feat/e2e-playwright]
/home/user/projects/app/.worktrees/feature  adbbd87 [feat/login]

이미 어딘가에 펼쳐진 브랜치에서 이어서 작업하려면, 새로 체크아웃하려 들지 말고 그 브랜치가 펼쳐진 폴더로 이동해서 작업하면 된다.

마무리

체크아웃은 결국 작업 폴더에 어떤 브랜치를 활성 상태로 꺼내 놓는 동작이다. 이 한 가지만 잡고 나면, "같은 브랜치를 두 worktree에서 체크아웃할 수 없다"는 규칙도, 그때 나는 에러도 자연스럽게 이해된다. 브랜치를 옮기기 전에 git worktree list로 지금 무엇이 어디에 펼쳐져 있는지부터 확인하는 습관을 들이면 이런 혼란을 피할 수 있다.