[Git] Worktree란? (feat. is already userd by worktree)

최근 git worktree를 사용한 경험을 정리합니다.

Git Worktree

 

최근에는 AI sub-agent / multi-agent 환경에서 각 `agent`가 독립된 작업 디렉토리를 사용할 수 있도록 할 때도 worktree를 사용한다고 해서 사용해 봤다.

Git Worktree는 하나의 repository에서 여러 branch를 동시에 checkout 하여 각각 다른 working directory에서 작업할 수 있게 해주는 기능이다.

Git worktree란

`Git`에는 여러 브랜치를 동시에 작업할 수 있는 기능이 있다.

worktree 생성

git worktree add <path> <branch>

결과

repo/
 ├ main (현재 작업)
 └ feature-login/ (worktree)

즉, 하나의 repository에서 여러 working directory를 사용할 수 있다!

원래는 하나의 레포에서는 하나의 브랜치만 작업 가능하다고 생각했는데..

 

에러 발생 상황

worktree를 사용하면서, 기존 깃 허브에서 브랜치를 변경해서 확인해 보기 위해, `git checkout`을 하려고 했는데, 에러가 발생했다.

 

fatal: 'feature/login' is already used by worktree

 

is already used by worktree 에러는 Git에서 어떤 브랜치가 이미 다른 worktree에서 체크아웃되어 있을 때 발생하는 오류이다.

Github Error alert

 

이는, 이미 다른 worktree에서 `checkout` 되어있어서 발생한다.

feature/login 브랜치가
이미 다른 worktree에서 checkout 되어 있다

 

 

`Git`은 같은 브랜치를 두 worktree에서 동시에 `checkout`하는 것을 막기 때문이다.

 

확인 방법

현재 worktree 목록 확인

git worktree list

예시

/repo                main
/repo-feature-login  feature/login

 

 

 

 

해결 방법

방법 1: 해당 worktree 이동

이미 존재하는 worktree에서 작업한다.

cd ../repo-feature-login

 

 

방법 2: worktree 삭제

필요 없다면 worktree를 삭제한다.

git worktree remove <path>

 

 

방법 3: 브랜치 detach

다른 worktree에서

git checkout --detach

 

 

 

왜 Git에서 막을까

같은 브랜치를 여러 worktree에서 동시에 수정하면 충돌이 생길 수 있기 때문이다.

commit history
working tree state
HEAD

 

 

 

 

요약

에러 의미

브랜치가 이미 다른 worktree에서 사용 중

확인

git worktree list

해결

git worktree remove <path>

worktree를 `remove` 하거나 해당 worktree에서 작업한다.