Git detached HEAD 해결: 브랜치 이동 전에 커밋을 보존하는 순서

detached HEAD는 저장소가 고장 났다는 뜻이 아닙니다. 브랜치 이름 대신 특정 커밋을 보고 있는 상태입니다. 그 상태에서 만든 커밋을 남기려면 다른 브랜치로 이동하기 전에 현재 커밋에 새 브랜치를 붙이세요. 이미 이동했다면 reflog에서 실제 커밋을 확인한 뒤 복구 브랜치를 만듭니다.

원인: 브랜치가 아니라 커밋을 체크아웃했다

태그나 커밋 ID로 이전 버전을 확인하면 현재 위치가 브랜치와 떨어질 수 있습니다. 이 상태에서도 커밋은 만들 수 있지만 새 커밋이 원래 브랜치를 자동으로 앞으로 이동시키지는 않습니다. CI가 특정 커밋을 정확히 빌드하려고 이런 상태를 만드는 경우도 있으므로 경고만 보고 수정할 필요는 없습니다.

상태	먼저 할 일	피할 일
현재 detached 커밋 유지	새 브랜치 생성	먼저 다른 곳 이동
이미 다른 브랜치로 이동	reflog·내용 조회	추측한 ID로 복구
미커밋 변경 존재	별도 보존 확인	강제 초기화
CI의 고정 커밋 빌드	의도된 상태인지 확인	불필요한 브랜치 변경

1. 현재 위치와 미커밋 변경부터 확인한다

아래 명령은 작업 중인 저장소 디렉터리에서 실행하는 읽기 전용 확인 예시입니다. 출력에는 파일명과 커밋 메시지가 포함될 수 있으므로 외부 공유 전에 필요한 부분만 남기세요. 이 글에서는 사용자 저장소에 명령을 실행하지 않았습니다.

git --version
git status --short --branch
git log -3 --oneline --decorate
git diff --stat

커밋에 들어간 변경과 아직 작업 폴더에만 있는 변경은 다릅니다. 브랜치 이름을 붙이는 것은 커밋에 도달할 경로를 만드는 일이며 미커밋 파일 전체를 백업하는 작업이 아닙니다. 중요한 미커밋·미추적 파일은 조직의 보존 절차로 별도 보호하고 상태를 확인합니다.

2. 아직 그 커밋에 있다면 새 브랜치를 만든다

다음 이름은 예시입니다. 기존에 없는 적절한 이름을 선택하세요. -c는 새 브랜치를 만들고 그 브랜치로 이동합니다. 기존 이름을 강제로 덮는 옵션으로 바꾸지 않습니다.

git switch -c rescue-detached-work
git status --short --branch
git log -3 --oneline --decorate

현재 커밋이 새 브랜치 이름과 함께 보이는지 확인합니다. 충돌이나 다른 작업 트리 관련 오류가 나오면 그대로 중단하고 원인을 확인하세요. 강제 이동이나 reset --hard로 경고를 없애는 것은 커밋 보존 절차가 아닙니다.

3. 이미 이동했다면 reflog에서 실제 커밋을 찾는다

로컬 reflog에는 참조가 이동한 기록이 남을 수 있습니다. 아래 조회 결과에서 시간·커밋 메시지·내용을 함께 확인합니다. 가장 위 항목이 반드시 잃어버린 작업인 것은 아닙니다.

git reflog --date=iso
git show --stat <확인한-커밋-ID>
git branch rescue-detached-work <확인한-커밋-ID>

꺾쇠 부분은 실제 확인한 ID로 바꾸는 자리입니다. 마지막 명령은 해당 커밋에 이름을 붙이며 현재 작업 폴더를 바꾸지 않습니다. reflog는 영구 백업이 아니고 저장소마다 기록과 보존 기간이 다릅니다. 없는 기록을 있다고 가정하거나 정리 명령을 먼저 실행하지 마세요.

확인 방법: 내용과 브랜치 참조를 함께 대조한다

복구 브랜치 로그와 변경 내용을 검토해 원하는 작업이 포함됐는지 확인합니다. 이후 원래 개발 브랜치에 반영하는 merge나 cherry-pick은 별도의 변경 작업입니다. 복구한 커밋을 찾은 것과 팀 브랜치에 반영한 것을 구분하고 리뷰와 시험을 거쳐 진행하세요.

원격 push도 자동으로 하지 않습니다. 민감한 변경이 없는지, 대상 원격과 브랜치가 맞는지 확인한 뒤 팀 절차로 공유합니다. 복구 이름은 작업 보존이 확인되기 전 삭제하지 않습니다.

FAQ

detached HEAD 자체가 오류인가요? 특정 커밋 점검·CI에서는 정상적인 상태일 수 있습니다.

브랜치를 만들면 미커밋 파일도 저장되나요? 아닙니다. 커밋과 작업 폴더의 변경을 구분해야 합니다.

다시 clone하면 복구되나요? 원격에 없는 로컬 커밋을 새 clone이 가져오지는 않습니다. 원래 저장소를 보존하세요.

공식 출처와 관련 글

자료 확인일: 2026년 10월 18일. 공식 문서 기반 설명이며 실제 서비스·명령 실행 시험은 수행하지 않았습니다. 설치 버전과 리전·지원 범위는 적용 전에 확인하세요.

Git switch

Git reflog

Git detached HEAD 설명

관련 글: Git 소유권 오류는 별도 문제로 진단

적용 전 원본 설정을 보존하고 승인된 시험 범위에서 결과를 확인하세요.

직접 생성한 개념 이미지입니다. 실제 서비스 화면이나 구축·성능 시험 결과가 아닙니다.