git worktree target path already exists가 나오면 기존 폴더부터 보존한다

git worktree add에서 fatal: '.../새폴더' already exists가 나오면 Git이 가리킨 것은 브랜치가 아니라 대상 폴더 경로다. 폴더를 바로 지우거나 --force로 덮으려 하지 말고, 안의 파일을 확인해 다른 이름으로 보존한다. 첫 실패에서 새 브랜치가 만들어졌을 수도 있으므로 브랜치 존재까지 확인한 뒤 빈 경로에 연결한다.

git worktree list
if git show-ref --verify --quiet refs/heads/작업브랜치; then echo "브랜치 있음"; else echo "브랜치 없음"; fi
test -e "../새폴더" && ls -la "../새폴더"

이 세 명령은 각각 등록된 worktree, 실패 뒤 브랜치, 기존 폴더 내용을 확인한다. 파일이 있다면 삭제하지 않는다.

오류에서 폴더와 브랜치를 구분한다

두 오류는 비슷해 보여도 대상이 다르다.

fatal: '/경로/새폴더' already exists

따옴표 안에 경로가 나오면 폴더 충돌이다. 반면 아래처럼 branch라는 말과 이름이 나오면 브랜치 이름 충돌이다.

fatal: a branch named '작업브랜치' already exists

브랜치 이름 충돌은 기존 브랜치를 worktree에 연결하는 순서에서 다룬다. 이 글은 파일이 든 대상 폴더가 이미 있는 경우만 해결한다.

1. 기존 폴더 안의 파일을 확인한다

저장소 폴더에서 대상 경로를 확인한다.

ls -la "../새폴더"

원래 작업 파일이 보이면 별도 이름으로 보존한다. 아래 예시는 같은 부모 폴더 안에서 이름만 바꾼다.

mv "../새폴더" "../새폴더.saved"

mv 전에 pwd와 ls -la로 경로를 다시 확인한다. .saved 경로도 이미 있다면 다른 고유 이름을 사용한다. 이동 권한이 없거나 파일이 사용 중이면 여기서 멈추고 복사본을 확보한다.

2. 실패한 명령이 브랜치를 남겼는지 확인한다

Git 2.38.1의 비민감 임시 저장소에서 다음 명령을 실행했다.

git worktree add -b review ../review HEAD

../review에 notes.txt가 이미 들어 있자 결과는 exit 128이었다.

Preparing worktree (new branch 'review')
fatal: '/tmp/.../review' already exists

그런데 실패 뒤 review 브랜치는 존재했다.

if git show-ref --verify --quiet refs/heads/review; then echo "브랜치 있음"; else echo "브랜치 없음"; fi

이번 재현에서는 브랜치 있음이 출력됐다.

따라서 폴더만 옮긴 뒤 같은 -b review 명령을 반복하면 이번에는 다음 오류가 났다.

fatal: a branch named 'review' already exists

첫 오류 뒤 브랜치가 항상 남는다고 모든 Git 버전에 일반화할 수는 없다. 실제 저장소에서 위 show-ref 명령으로 확인해야 한다.

3. 브랜치가 남았다면 -b 없이 빈 경로에 연결한다

show-ref가 성공하고 git worktree list에 그 브랜치가 없다면 새 브랜치를 다시 만들지 않는다.

git worktree add "../새폴더" 작업브랜치

직접 재현에서는 다음 결과와 exit 0을 확인했다.

Preparing worktree (checking out 'review')
HEAD is now at 9c89af4 base

연결 결과를 확인한다.

git -C "../새폴더" branch --show-current
git worktree list

첫 명령이 작업브랜치를 출력하고, 목록에 새 경로와 같은 브랜치가 보이면 worktree 생성은 끝났다. 보존한 폴더의 파일은 자동으로 새 worktree에 합쳐지지 않는다. 필요한 파일만 내용을 확인한 뒤 새 worktree로 옮기고 git status로 변경을 검토한다.

4. 브랜치가 없다면 새 브랜치 생성 명령을 다시 쓴다

show-ref가 실패하고 목록에도 같은 브랜치가 없다면 빈 대상 경로에서 새 브랜치를 만든다.

git worktree add -b 작업브랜치 "../새폴더" HEAD

여기서 HEAD는 현재 저장소가 가리키는 커밋이다. 다른 기준에서 시작하려면 그 브랜치나 커밋을 명시하고, 실행 전 git log -1 --oneline HEAD로 기준을 확인한다.

--force로 기존 폴더를 덮을 수 있나?

이번 Git 2.38.1 재현에서는 파일이 든 같은 경로에 --force를 붙여도 exit 128과 already exists가 그대로 나왔다.

git worktree add --force "../새폴더" HEAD

Git 공식 문서의 --force는 점유된 브랜치나 누락됐지만 등록이 남은 worktree 같은 보호 조건을 재정의하는 데 쓰인다. 기존 파일이 든 일반 폴더를 안전하게 합쳐 주는 옵션으로 보지 않는다. 파일을 보존하고 빈 경로를 만드는 순서가 먼저다.

오류가 이어지면 문구별로 멈춘다

다음 오류	뜻	행동
a branch named ... already exists	실패 뒤 또는 이전부터 로컬 브랜치가 존재	-b를 빼고 기존 브랜치를 연결한다.
is already checked out at	같은 브랜치를 다른 worktree가 사용	git worktree list의 기존 경로를 사용하거나 새 브랜치를 만든다.
목록에는 있지만 폴더가 없음	stale 등록 가능성	바로 삭제하지 말고 git worktree prune --dry-run으로 후보만 확인한다.
Permission denied	부모 경로 쓰기 권한 없음	접근 가능한 새 경로를 선택하고 기존 폴더를 유지한다.

폴더가 사라졌는데 등록만 남은 문제는 stale worktree 등록을 정리하는 순서로 분리한다.

한 번에 실행하는 안전한 순서

1. git worktree list로 이미 등록된 경로와 브랜치를 확인한다.
2. ls -la "../새폴더"로 기존 파일을 확인한다.
3. 파일이 있으면 ../새폴더.saved처럼 별도 경로에 보존한다.
4. if git show-ref --verify --quiet refs/heads/작업브랜치; then echo "브랜치 있음"; else echo "브랜치 없음"; fi로 실패 뒤 브랜치 존재를 눈으로 확인한다.
5. 브랜치가 있으면 git worktree add "../새폴더" 작업브랜치를 실행한다.
6. 브랜치가 없으면 git worktree add -b 작업브랜치 "../새폴더" HEAD를 실행한다.
7. git -C "../새폴더" branch --show-current와 git worktree list로 결과를 확인한다.

핵심은 폴더 삭제나 강제 옵션부터 시작하지 않는 것이다. 경로 충돌을 해결한 다음, 첫 실패가 남긴 브랜치 상태에 맞춰 명령을 고르면 기존 파일과 Git 이력을 함께 보존할 수 있다.

자주 묻는 질문

기존 폴더에 바로 worktree를 붙일 수 있나?

비어 있지 않은 일반 폴더는 이번 Git 2.38.1 재현에서 일반 add와 --force 모두 실패했다. 파일을 보존 위치로 옮기고 대상 경로를 비운 뒤 worktree를 만든다.

첫 실패 뒤 같은 -b 명령을 반복해도 되나?

먼저 위의 if git show-ref ...; then echo ...; fi 명령으로 브랜치 있음 또는 브랜치 없음을 눈으로 확인한다. 남아 있으면 -b를 빼고 기존 브랜치를 빈 경로에 연결한다.

검증 기준

• 주요 근거: Git 공식 git-worktree 문서
• 공개 질문: 기존 폴더에 worktree를 추가하려다 난 오류, 비어 있지 않은 디렉터리를 붙이려는 질문
• 마지막 업데이트일: 2026-09-20
• 확인 환경: macOS 비민감 임시 저장소, Git 2.38.1
• 직접 결과: 기존 notes.txt가 든 경로는 일반 add와 --force 모두 exit 128이었다. 첫 실패 뒤 review 브랜치가 남았고, 원래 폴더를 보존 이동한 뒤 -b 없이 연결하자 exit 0이었다. 원래 파일 내용도 유지됐다.
• 한계: 정확 월간 검색량과 seoin.dev 독자의 직접 반응은 미확인이다. 최신 Git 모든 버전과 GUI 도구의 내부 호출은 이번 재현 범위가 아니다.