Git detached HEAD 커밋을 브랜치로 보존하는 법

HEAD detached at ... 경고를 본 뒤 코드를 고쳐 커밋했다면 다른 브랜치로 이동하기 전에 현재 커밋에 새 브랜치 이름부터 붙여야 한다. 아직 그 커밋 위에 있다면 git switch -c save/my-work 한 줄로 브랜치를 만들고 그 브랜치로 이동할 수 있다. 이미 이동했다면 git reflog에서 커밋을 찾아 브랜치를 만든다.

detached HEAD가 가리키는 커밋에 새 브랜치를 연결하는 Git 구조

먼저 현재 위치와 커밋 유무를 확인한다

Git 공식 checkout 문서가 설명하는 detached HEAD는 파일이 망가졌다는 뜻이 아니다. 보통 HEAD는 main 같은 브랜치를 가리키고, 브랜치가 최신 커밋을 가리킨다. 과거 커밋이나 태그를 직접 checkout하면 HEAD가 브랜치 대신 그 커밋을 직접 가리킨다.

브랜치를 바꾸기 전에 다음 세 명령의 결과를 남긴다.

git status
git branch --show-current
git log -1 --oneline

git branch --show-current가 빈 줄이고 status에 detached 상태가 보이면 현재 브랜치 이름이 없다.
git log -1 --oneline의 해시는 현재 HEAD가 가리키는 커밋이다.
status에 수정 파일이 남아 있다면 아직 커밋 전 작업도 함께 있다. 먼저 어떤 파일을 커밋할지 검토한다.

AI에게 큰 수정을 맡기기 전 아직 커밋하지 않은 작업부터 분리해야 한다면 Git stash로 작업을 보관하는 순서를 먼저 적용할 수 있다. detached commit 보존과 working tree 임시 보관은 다른 문제다.

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

Git switch 공식 문서는 detached HEAD에서 만든 작업을 유지하려면 현재 위치에서 새 브랜치를 만들 수 있다고 안내한다. 작업을 계속할 목적이라면 새 브랜치를 만들고 바로 이동하는 명령이 단순하다.

git switch -c save/detached-work

-c는 현재 HEAD를 시작점으로 save/detached-work 브랜치를 만들고 그 브랜치로 전환한다. 성공하면 이후 커밋은 새 브랜치 끝에 이어진다.

git branch --show-current
git log -1 --oneline

첫 명령이 save/detached-work를 출력하고 두 번째 명령의 해시가 앞에서 기록한 해시와 같으면 커밋에 이름이 붙었다. 이 확인이 끝나기 전에는 원래 브랜치로 이동하지 않는다.

구형 흐름에 익숙하다면 git checkout -b save/detached-work도 같은 목적에 쓸 수 있다. 다만 한 글 안에서는 파일 복원과 브랜치 이동을 함께 맡는 checkout보다 브랜치 이동 의도가 분명한 switch 명령을 사용한다.

커밋을 만들지 않았다면 원래 브랜치로 돌아간다

과거 커밋을 읽기만 했고 working tree도 깨끗하다면 보존할 새 커밋은 없다. 다음으로 직전에 있던 브랜치로 돌아갈 수 있다.

git switch -

다만 git status에 수정 파일이 있다면 바로 이동하지 않는다. Git이 이동을 막을 수도 있고, 겹치지 않는 변경은 따라갈 수도 있어서 의도한 작업 구분이 흐려질 수 있다. 변경 내용을 검토해 커밋할지, stash할지, 버릴지 먼저 선택한다.

현재 detached 위치, 이미 이동한 상태, 커밋이 없는 상태를 가르는 Git 복구 경로

이미 다른 브랜치로 이동했다면 reflog에서 찾는다

원래 브랜치로 이동한 뒤 detached 커밋이 log에서 보이지 않아도 즉시 삭제된 것은 아니다. Git reflog 공식 문서는 HEAD의 브랜치 이동 기록도 reflog에 남는다고 설명하며, checkout 문서는 이미 떠난 커밋의 object name을 보통 reflog로 찾도록 안내한다.

git reflog --date=local

출력에서 detached 상태에서 작성한 커밋 메시지와 시각을 찾는다. 예를 들어 해시가 a1b2c3d라면 먼저 내용을 확인한다.

git show --stat a1b2c3d

원하는 변경이 맞을 때 그 해시에 브랜치를 만든다.

git branch save/detached-work a1b2c3d
git switch save/detached-work

reflog는 현재 로컬 저장소에서 HEAD와 ref가 이동한 기록이다. 원격 백업이 아니며 항목은 영구 보존을 약속하지 않는다. 커밋을 찾았다면 검토만 반복하지 말고 바로 이름 있는 브랜치에 연결한다.

reset과 clean으로 먼저 밀어붙이지 않는다

detached HEAD를 해결한다는 이유로 git reset --hard, git clean -fd, 강제 branch 재생성을 먼저 실행할 필요는 없다. 이 명령들은 working tree나 브랜치 위치를 바꾸는 별도 작업이라, 보존할 변경을 확인하기 전에 쓰면 문제를 키울 수 있다.

안전한 순서는 다음과 같다.

git status로 커밋 전 변경을 확인한다.
git log -1 --oneline으로 현재 커밋을 기록한다.
현재 커밋 위라면 git switch -c <새-브랜치>를 실행한다.
이미 이동했다면 git reflog와 git show로 해시를 검증한다.
검증한 해시에 git branch <새-브랜치> <해시>를 만든다.

AI 실험을 원래 작업과 처음부터 분리하고 싶다면 Git worktree로 별도 작업 폴더를 만드는 기준도 연결된다. detached HEAD는 임시 탐색에는 쓸 수 있지만, 계속할 작업에는 이름 있는 브랜치가 더 명확하다.

브랜치와 커밋이 함께 남았는지 검증한다

복구 뒤에는 아래 세 결과를 한 묶음으로 확인한다.

git branch --show-current
git log -1 --oneline
git status

현재 브랜치 이름이 방금 만든 이름이다.
마지막 커밋 해시와 메시지가 보존하려던 커밋과 같다.
status의 수정 파일이 예상과 맞다.

detached HEAD 커밋 보존 뒤 브랜치 이름, 마지막 커밋, status를 확인하는 체크리스트

원격에도 보관해야 한다면 이 검증 뒤 git push -u origin save/detached-work를 실행한다. push 성공 후 원격 저장소에서 같은 브랜치와 커밋을 확인하면 작은 복구 훈련이 끝난다.

참고 출처

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.

Git detached HEAD에서 커밋했다면, 브랜치로 보존하는 순서