Codex worktree invalid reference, 원격 브랜치만 있을 때 확인 순서

Codex Desktop의 브랜치 목록에서 골랐는데 worktree 생성이 fatal: invalid reference: feature/...로 멈춘다면, 먼저 그 이름이 로컬 브랜치인지 origin 원격 추적 브랜치인지 구분하세요. 원격에만 있다면 저장소를 다시 만들지 말고, 로컬 추적 브랜치를 만든 뒤 Codex에서 다시 선택하면 됩니다.

로컬 이름과 origin 이름은 어떻게 구분하나요?

이 작업은 Codex 입력창이 아니라 Mac의 터미널에서 합니다. Command + Space를 누르고 터미널을 연 뒤, 저장소/경로를 Finder에서 확인한 실제 폴더로 바꾸세요.

git -C "/저장소/경로" fetch origin
git -C "/저장소/경로" show-ref --verify --quiet "refs/heads/feature/작업이름"
echo $?
git -C "/저장소/경로" show-ref --verify --quiet "refs/remotes/origin/feature/작업이름"
echo $?

echo $?는 바로 앞 명령의 결과를 숫자로 보여줍니다.

로컬 refs/heads	원격 refs/remotes/origin	뜻
0	0	로컬과 원격 추적 ref가 둘 다 있음
1	0	원격에만 있음. 이 글의 다음 단계로 진행
1	1	이름을 잘못 입력했거나 fetch한 origin에 해당 브랜치가 없음

fetch에서 로그인이나 네트워크 오류가 난다면 그 문제를 먼저 해결해야 현재 원격 브랜치 목록을 확인합니다. 에러를 무시하고 이전에 받은 목록으로 판단하지 마세요.

원격에만 있다면 무엇을 해야 하나요?

위 결과가 로컬 1, 원격 0이어도 먼저 현재 작업을 확인하세요. 다음 switch 명령은 지정한 저장소의 현재 작업 폴더 브랜치를 실제로 바꿉니다.

git -C "/저장소/경로" status --short

출력이 한 줄이라도 있으면 진행하지 마세요. 변경을 커밋하거나 안전하게 보관한 뒤 다시 확인합니다. 출력이 없고 현재 폴더의 브랜치를 바꿔도 된다면 로컬 추적 브랜치를 만듭니다.

git -C "/저장소/경로" switch --track -c "feature/작업이름" "origin/feature/작업이름"
git -C "/저장소/경로" status --short --branch

첫 명령은 origin/feature/작업이름을 추적하는 로컬 feature/작업이름을 만들고 현재 폴더를 그 브랜치로 전환합니다. 두 번째 출력의 첫 줄에 현재 브랜치와 origin/...의 추적 관계가 보이는지 확인하세요. 그런 다음 Codex Desktop으로 돌아가 새로고침하고 로컬 브랜치를 다시 선택합니다.

현재 폴더의 브랜치를 바꾸고 싶지 않다면 별도 경로에 새 worktree를 만듭니다. /새/worktree/경로는 아직 존재하지 않는 빈 경로로 바꾸세요.

git -C "/저장소/경로" worktree add -b "feature/작업이름" \
  "/새/worktree/경로" "origin/feature/작업이름"

정상 완료되면 새 경로에 로컬 추적 브랜치의 파일이 생깁니다. already exists 또는 already used by worktree가 나오면 같은 브랜치나 경로를 이미 쓰고 있으므로 새로 덮어쓰지 말고 git -C "/저장소/경로" worktree list로 기존 위치를 확인하세요.

fatal: a branch named 'feature/...' already exists가 나면 이미 로컬 브랜치가 있다는 뜻입니다. 새로 만들지 말고 첫 단계의 refs/heads/... 입력이 맞는지 다시 확인하세요.

다른 invalid reference 오류는 어떻게 구분하나요?

오류의 마지막 값이 중요합니다.

• fatal: invalid reference: feature/...: 해당 이름의 로컬 ref가 없는지 이 글의 순서로 확인합니다.
• fatal: invalid reference: HEAD: 브랜치 이름보다 저장소 루트와 첫 커밋 유무를 확인해야 합니다. invalid reference HEAD 확인 순서를 따르세요.
• '<branch>' is already used by worktree at ...: ref가 없는 문제가 아니라 다른 worktree가 이미 점유한 상태입니다. 점유 경로 확인 순서로 이동하세요.

서로 다른 오류에 저장소 초기화나 worktree 삭제를 함께 적용하면 현재 작업을 잃을 수 있습니다. 정확한 오류 값과 ref 존재 여부로 분기하세요.

실제 Git 재현에서 확인한 결과

2026-09-19에 macOS의 Git 2.38.1 비민감 임시 저장소에서 다음 상태를 만들었습니다.

1. origin/feature/remote-only를 push했습니다.
2. 로컬 feature/remote-only를 삭제했습니다.
3. feature/remote-only를 커밋 위치로 주고 detached worktree를 만들면 exit 128과 fatal: invalid reference: feature/remote-only가 나왔습니다.
4. 같은 커밋을 origin/feature/remote-only로 지정하면 worktree가 생성됐고, HEAD는 detached 상태였습니다.

이 결과는 Git이 로컬 이름과 원격 추적 ref를 다르게 해석한다는 점을 확인합니다. Codex Desktop의 현재 버전이 모든 원격 전용 브랜치에서 같은 명령을 생성한다는 뜻은 아닙니다. 제품 현상은 OpenAI 공개 이슈 #22635의 단일 재현으로만 표시합니다.

자주 묻는 질문

fetch만 하면 로컬 브랜치가 생기나요?

아닙니다. 일반적인 fetch는 refs/remotes/origin/...을 갱신하지만 같은 이름의 refs/heads/...를 자동으로 만들지는 않습니다. 두 ref의 종료 코드를 따로 확인하세요.

현재 작업 폴더의 브랜치를 바꾸지 않고 만들 수 있나요?

현재 폴더를 그대로 두고 별도 worktree를 직접 만들려면 git worktree add -b "feature/작업이름" "/새/worktree/경로" "origin/feature/작업이름"처럼 새 로컬 브랜치와 경로를 함께 지정할 수 있습니다. 이 글의 기본 절차는 Codex Desktop에서 다시 선택하기 쉽도록 먼저 로컬 추적 브랜치를 준비하는 경우입니다.

정리

1. fetch origin으로 현재 원격 목록을 갱신합니다.
2. refs/heads/...와 refs/remotes/origin/...을 따로 확인합니다.
3. 원격에만 있으면 git switch --track -c로 로컬 추적 브랜치를 만듭니다.
4. Codex Desktop을 새로고침하고 그 로컬 브랜치를 다시 선택합니다.
5. 오류가 HEAD 부재나 다른 worktree 점유라면 해당 절차로 분기합니다.

검증 기준

• 마지막 업데이트일: 2026-09-19
• 확인 환경: macOS, Git 2.38.1, 비민감 임시 bare remote·clone
• 주요 근거: Git worktree 공식 문서 · Git switch 공식 문서 · OpenAI Codex 공개 이슈 #22635
• 재현 범위: remote-only ref 생성 → 로컬 브랜치 삭제 → 짧은 이름의 exit 128 → origin/... ref의 성공 → worktree 제거
• 미확인: 정확 월간 검색량, seoin.dev 독자 직접 피드백, 현재 Codex Desktop 버전의 수정 여부와 실제 화면 문구
• Google 실제 검색에서는 OpenAI 원격 전용 브랜치 이슈와 일반 Git 답이 함께 노출됐고, Naver는 일반 git pull 답과 원격 브랜치용 새 worktree 답이 중심이었다. 이 글은 로컬·원격 ref를 종료 코드로 구분하고 로컬 추적 브랜치를 만드는 순서를 한곳에 묶는다.
• 대표이미지는 실제 앱 화면이 아닌 원격 ref 확인→로컬 추적 연결 흐름을 사물로 표현한 개념도다.