Codex Desktop worktree 오류: invalid reference HEAD 확인 순서

fatal: invalid reference: HEAD가 나오면 Codex Desktop을 다시 설치하기 전에 선택한 폴더가 Git 저장소인지, Git이 어느 폴더를 저장소 루트로 보는지, 첫 커밋이 있는지를 확인하세요. 첫 커밋이 없는 빈 저장소에서는 worktree가 기준으로 삼을 커밋을 찾지 못할 수 있습니다.

아래 명령은 파일을 지우거나 바꾸지 않습니다. macOS에서는 Command + Space → 터미널 → Enter로 터미널을 열고, Codex에서 선택한 프로젝트 폴더로 이동한 뒤 실행합니다.

세 명령으로 원인을 구분하기

pwd
git rev-parse --show-toplevel
git rev-parse --verify HEAD

결과는 다음처럼 읽습니다.

결과	뜻	다음 행동
not a git repository	현재 폴더와 상위 폴더에서 Git 저장소를 찾지 못함	이 폴더를 새 Git 프로젝트로 쓸지 먼저 결정
--show-toplevel이 예상한 프로젝트가 아닌 상위 폴더를 출력	상위 폴더의 .git에 속한 것으로 인식됨	그 상위 저장소가 의도한 것인지 확인하고, 임의로 .git을 삭제하지 않음
--show-toplevel은 맞지만 --verify HEAD가 실패	Git 저장소는 있으나 현재 HEAD가 가리키는 첫 커밋이 없음	저장할 파일과 제외할 파일을 검토한 뒤 첫 커밋 생성
두 명령 모두 성공하고 커밋 ID가 출력	저장소와 HEAD는 존재함	일반 Git 초기화 문제로 단정하지 말고 Codex App 오류·버전·로그를 별도 확인

HEAD는 현재 작업 기준이 되는 커밋을 가리키는 이름입니다. Git 공식 문서에서 git worktree add는 별도 기준을 주지 않으면 기본적으로 HEAD를 바탕으로 새 작업 트리를 만듭니다. 따라서 앱이 HEAD를 명시해 호출하는 경로에서 유효한 첫 커밋이 없으면 invalid reference: HEAD가 날 수 있습니다.

첫 커밋이 없을 때 시작하는 순서

새 프로젝트가 맞고 저장할 파일을 확인했다면 다음 순서로 진행합니다.

1. 프로젝트 폴더에 비밀번호, API 키, 빌드 결과처럼 Git에 넣지 않을 파일이 있는지 확인합니다.
2. 필요한 항목을 .gitignore에 먼저 적습니다.
3. 저장할 파일만 git add로 선택합니다.
4. 첫 커밋을 만든 뒤 git rev-parse --verify HEAD가 커밋 ID를 출력하는지 확인합니다.
5. Codex Desktop에서 프로젝트를 다시 열고 worktree 생성을 한 번만 다시 시도합니다.

예시는 다음과 같습니다. README.md는 실제로 저장할 파일 이름으로 바꾸세요.

git status --short
git add README.md .gitignore
git commit -m "프로젝트 시작점 저장"
git rev-parse --verify HEAD

git add .를 곧바로 실행하면 폴더 안의 모든 새 파일이 선택될 수 있습니다. 비개발자라면 git status --short에서 파일 목록을 먼저 읽고 필요한 파일 이름만 지정하는 편이 안전합니다. 작성자 이름이나 이메일을 요구하면 임의 값을 넣기보다 자신이 사용할 Git 설정을 먼저 정하세요.

.gitignore에 넣은 파일이 계속 보이는 문제라면 이미 추적 중인 파일을 로컬에 남기고 추적에서 빼는 순서를 이어서 확인하세요.

상위 폴더가 Git 루트로 나오면

예를 들어 Codex에서 ~/Documents/my-app을 골랐는데 git rev-parse --show-toplevel이 홈 폴더를 출력한다면, my-app은 독립 저장소가 아니라 상위 저장소의 일부로 인식된 상태입니다.

이때 상위 폴더의 .git을 바로 지우면 다른 프로젝트의 기록까지 잃을 수 있습니다. 먼저 아래 두 값을 메모합니다.

pwd
git rev-parse --show-toplevel

의도한 저장소라면 그 저장소의 현재 상태와 첫 커밋을 확인합니다. 의도하지 않은 상위 저장소라면 삭제 전에 어떤 폴더가 그 저장소에 속해 있는지와 보존할 기록이 있는지 검토해야 합니다. 이 글은 사용자의 기존 저장소를 자동으로 분리하거나 삭제하는 명령을 제시하지 않습니다.

직접 재현한 결과

2026년 9월 19일 macOS, Git 2.38.1의 비민감 임시 폴더에서 확인했습니다.

조건	git rev-parse --verify HEAD	git worktree add … HEAD
Git 저장소가 아닌 폴더	저장소 아님, 종료 128	실행 대상 아님
git init만 한 빈 저장소	Needed a single revision, 종료 128	fatal: invalid reference: HEAD, 종료 128
README 첫 커밋 뒤	커밋 ID 출력, 종료 0	worktree 생성 성공, 종료 0

이 재현은 첫 커밋이 없는 저장소가 한 원인일 수 있음을 보여줍니다. Codex Desktop의 모든 invalid reference: HEAD 오류가 같은 원인이라는 뜻은 아닙니다. 공개 Codex 이슈에서도 저장소가 아닌 폴더, 첫 커밋이 없는 저장소, 의도하지 않은 상위 저장소가 조건으로 보고됐습니다.

HEAD가 정상인데도 앱만 실패하면

git rev-parse --show-toplevel과 git rev-parse --verify HEAD가 모두 성공한다면 첫 커밋을 다시 만들 필요가 없습니다. 다음 정보를 보존한 뒤 앱 쪽 문제로 범위를 좁힙니다.

Codex App 버전:
운영체제:
선택한 폴더:
git rev-parse --show-toplevel 결과:
git rev-parse --verify HEAD 결과:
앱에 표시된 오류 전문:

경로에 사용자 이름이나 회사명이 들어가면 공개 글이나 이슈에 올리기 전에 가리세요. 전체 앱 로그에는 대화나 로컬 경로가 포함될 수 있으므로 오류와 같은 시각의 필요한 부분만 검토합니다.

자주 묻는 질문

Codex Desktop을 다시 설치하면 해결되나요?

git rev-parse --verify HEAD가 실패하는 빈 저장소라면 재설치보다 첫 커밋이 먼저입니다. HEAD가 정상인데 앱만 실패할 때는 앱 버전과 오류 전문을 보존하고 별도 문제로 조사합니다.

상위 폴더의 .git을 지워도 되나요?

바로 지우지 마세요. 다른 프로젝트가 그 저장소의 기록을 공유할 수 있습니다. git rev-parse --show-toplevel의 출력과 보존할 커밋을 먼저 확인합니다.

정리

• Git 저장소가 아니면 이 폴더를 새 저장소로 만들지 먼저 결정합니다.
• 예상 밖의 상위 폴더가 Git 루트면 .git을 지우기 전에 저장소 범위를 확인합니다.
• 저장소는 맞지만 HEAD가 없으면 제외 파일을 검토하고 첫 커밋을 만듭니다.
• HEAD가 정상인데도 Codex Desktop만 실패하면 초기화를 반복하지 말고 앱 상태를 별도 조사합니다.

검증 기준

• 마지막 업데이트일: 2026-09-19
• 확인 환경: macOS, Git 2.38.1, 비민감 임시 로컬 저장소의 커밋 전후. Codex Desktop 내 동일 오류 화면과 Windows 동작은 직접 확인하지 않았습니다.
• 주요 근거: Git worktree 공식 문서, Git 저장소 구조 공식 문서
• 독자 질문 근거: OpenAI Codex 공개 이슈 #17474, 유사 오류 보고 #30469