Codex branch name is already used by worktree 오류 해결 순서

branch name is already used by worktree가 뜨면 폴더를 지우거나 브랜치를 강제로 바꾸지 마세요. Git이 그 브랜치를 이미 checkout한 다른 worktree 경로를 먼저 찾은 뒤, 그 폴더에서 계속할지 새 브랜치를 만들지 결정하면 됩니다.

실제 Codex App 오류 화면이 아니라, 한 브랜치가 한 worktree 경로에 연결되는 원리를 설명한 개념도입니다.

먼저 worktree 경로를 확인하세요

macOS에서 Command + Space → 터미널 입력 → Enter로 터미널을 엽니다. cd와 한 칸을 먼저 입력한 다음 Codex App에서 연 프로젝트 폴더를 터미널 창에 끌어 놓고 Enter를 누릅니다. 경로를 직접 아는 경우에는 아래 첫 줄의 예시를 자신의 절대경로로 바꿉니다.

cd "/path/to/project"
git worktree list --porcelain

명령이 성공하면 worktree, HEAD, branch가 묶인 목록이 나옵니다. fatal: not a git repository가 나오면 Git 저장소가 아닌 폴더를 연 것이므로 Codex의 프로젝트 루트 폴더를 다시 끌어 놓습니다.

출력은 worktree마다 worktree, HEAD, branch를 묶어서 보여줍니다.

다음은 경로를 짧게 바꿔 쓴 설명용 출력입니다. 실제 명령은 사용자의 홈 폴더 아래 절대경로를 보여 줍니다.

worktree /path/to/project
HEAD 2812a0a...
branch refs/heads/main

worktree /path/to/project-feature
HEAD 2812a0a...
branch refs/heads/feature

오류에 나온 브랜치가 feature라면 branch refs/heads/feature 바로 위의 worktree 경로가 이미 그 브랜치를 사용하는 폴더입니다. 이 경로를 Finder에서 열려면 다음처럼 입력합니다.

open "/path/to/project-feature"

경로는 예시를 그대로 쓰지 말고 자신의 출력에 나온 값으로 바꿉니다.

결과에 따라 세 가지 중 하나를 고르세요

확인 결과	다음 행동	피할 행동
기존 worktree에 작업이 남아 있음	출력된 worktree 폴더를 Codex App에서 프로젝트로 열고 그곳에서 계속 작업	원본 폴더에서 같은 브랜치를 강제 checkout
같은 코드에서 별도 작업을 시작하려 함	현재 폴더에서 이름이 다른 새 브랜치를 만든 뒤 사용	기존 작업 브랜치를 재사용
기존 worktree 작업이 끝났고 변경사항도 없음	상태를 확인한 뒤 git worktree remove로 정상 제거	Finder에서 폴더만 먼저 삭제

기존 worktree에서 계속하려면 먼저 open "/path/to/project-feature"로 Finder에서 그 폴더가 맞는지 확인합니다. Codex App의 시작 화면에서 Open folder 또는 폴더 열기를 선택하고 같은 절대경로를 엽니다. 앱 버전에 따라 문구가 다르거나 시작 화면이 보이지 않으면 메뉴 막대의 File → Open Folder…에서 같은 폴더를 선택합니다. 열린 프로젝트의 터미널에서 git branch --show-current가 오류에 나온 브랜치를 표시하면 작업 위치를 제대로 연 것입니다.

별도 작업이라면 명령을 실행할 폴더부터 확인합니다. 다음 세 명령의 pwd, 현재 브랜치, 변경 파일을 읽고 예상한 프로젝트인지 확인합니다. status --short에 파일이 나오면 그 변경도 새 브랜치로 따라가므로 먼저 보존 방법을 결정합니다.

pwd
git branch --show-current
git status --short
git switch -c feature-second

브랜치 이름은 실제 작업 목적에 맞게 바꿉니다. 이 방법은 기존 feature worktree의 파일과 브랜치를 그대로 둡니다.

기존 worktree를 지우기 전 확인할 것

먼저 오류 출력에 나온 worktree 폴더의 상태를 확인합니다.

git -C "/path/to/project-feature" status --short
git -C "/path/to/project-feature" branch --show-current

status --short에 파일이 나오면 커밋하지 않은 변경이 있다는 뜻입니다. 그 변경을 보존하거나 커밋할지 먼저 결정합니다. 출력이 비어 있고 해당 worktree가 정말 필요 없을 때만 원본 저장소에서 제거합니다.

git worktree remove "/path/to/project-feature"
git worktree list --porcelain

마지막 목록에서 해당 경로가 사라졌는지 확인합니다. 폴더를 Finder에서 먼저 삭제했다면 바로 다른 명령을 실행하지 말고 다음 읽기 전용 검사로 Git에 남은 등록 상태부터 봅니다.

git worktree list --porcelain

왜 같은 브랜치를 두 곳에서 열 수 없나요?

Git worktree는 한 저장소의 여러 작업 폴더를 만들 수 있게 하지만, 같은 로컬 브랜치를 여러 linked worktree에서 동시에 checkout하는 동작은 기본적으로 막습니다. 한 브랜치가 어느 작업 폴더에 연결됐는지 명확히 유지하는 동작이며, “두 폴더의 파일이 합쳐졌다”는 뜻은 아닙니다.

2026-09-19 비민감 임시 저장소에서 feature 브랜치를 별도 worktree에 checkout한 뒤 원본 폴더에서 git switch feature를 실행했습니다. Git 2.38.1은 exit 128과 함께 다음 오류를 반환했습니다.

fatal: 'feature' is already checked out at '/.../feature-worktree'

git worktree list --porcelain에서는 원본 main 경로와 feature 경로가 따로 표시됐고, git worktree remove 뒤에는 feature 경로가 목록에서 사라졌습니다.

Codex App 오류와 Git 상태를 구분하세요

OpenAI Codex 공개 이슈 #12863에는 수동으로 만든 worktree의 브랜치를 Codex App에서 다시 선택하다 같은 종류의 오류를 만난 사례가 기록돼 있습니다. 이 공개 사례 하나만으로 현재 모든 Codex App 버전이 외부 worktree를 같은 방식으로 처리한다고 단정할 수는 없습니다.

이 글에서 직접 확인한 범위는 Git의 브랜치 점유 오류와 경로 확인·정상 제거 절차입니다. Codex App 화면에서 같은 오류를 직접 재현하지는 않았습니다. 따라서 앱을 재설치하는 해결책을 주장하지 않고, 먼저 Git이 알려 주는 실제 worktree 경로를 확인하는 데 답의 범위를 둡니다.

invalid reference: HEAD가 함께 나온다면 브랜치 점유 문제와 다른 진단이 필요합니다. Codex Desktop worktree의 invalid reference HEAD 확인 순서에서 저장소 루트와 첫 커밋부터 확인하세요. worktree에서 환경 파일이 보이지 않는 문제라면 Codex worktree에서 .env가 빠질 때 확인할 것처럼 파일 추적 여부와 복사 규칙을 따로 봐야 합니다.

3분 요약

1. git worktree list --porcelain을 실행합니다.
2. 오류에 나온 브랜치와 같은 branch refs/heads/...를 찾습니다.
3. 바로 위 worktree 경로에서 기존 작업을 계속할지 확인합니다.
4. 별도 작업이면 새 브랜치를 만듭니다.
5. 끝난 worktree만 상태 확인 뒤 git worktree remove로 제거합니다.

자주 묻는 질문

같은 브랜치를 두 worktree에서 강제로 열어도 되나요?

일반적인 해결책으로 권하지 않습니다. 기존 worktree 경로에서 계속 작업하거나, 별도 작업에는 새 브랜치를 만드는 편이 현재 변경사항을 보존하기 쉽습니다.

Finder에서 worktree 폴더를 먼저 지웠다면 어떻게 하나요?

git worktree list --porcelain로 등록이 남아 있는지 먼저 확인합니다. 이 글은 정상적으로 남아 있는 worktree의 점유 오류를 다루며, 사라진 폴더의 메타데이터 정리는 별도 문제입니다.

검증 기준

• 마지막 업데이트일: 2026-09-19
• 확인 환경: macOS, Git 2.38.1 비민감 임시 저장소
• 주요 근거: Git 공식 git-worktree 문서
• 직접 확인: linked worktree 생성, 같은 브랜치 전환 exit 128, 점유 경로 출력, 정상 제거 뒤 목록 변화
• 확인하지 못한 범위: 최신 Codex App에서 동일 오류가 나타나는 실제 화면과 모든 버전의 UI 동작
• 2026-09-19 KST Google·Naver에서 정확 오류 문구의 실제 결과를 대조했습니다. 검색 결과 존재와 순서는 검색량이 아닙니다.
• 대표 이미지는 개념도이며 실제 Codex App 오류 화면이 아닙니다.

참고: Git 공식 worktree 문서 · OpenAI Codex 공개 이슈 #12863