Git: detached HEAD — 돌아가서 커밋 지키기

안녕하세요, BlueByte입니다. git checkout <something>을 실행했더니 Git이 "detached HEAD state"라는 긴 안내를 출력하고, 이제 git status가 브랜치 이름 대신 HEAD detached at 8fd6bda라고 말합니다. 깨진 것도, 아직 잃은 것도 없습니다 — 브랜치에서 내려와 특정 커밋 위에 선 것뿐입니다. 오늘은 이 상태가 뜻하는 것, 어쩌다 이렇게 됐는지, 안전하게 돌아가는 법, detached 상태에서 만든 커밋을 지키는 법, 그리고 이미 옮긴 뒤 되살리는 법까지 하나씩 짚어보겠습니다.

"detached HEAD"가 알려주는 것

평소 HEAD는 브랜치(예: main)를 가리키고, 브랜치가 커밋을 가리킵니다. "detached"는 중간에 브랜치 없이 HEAD가 커밋을 곧장 가리킨다는 뜻입니다. Git은 그 순간 경고합니다 — 아래는 풀어 쓴 게 아니라 실제 메시지입니다:

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.
 
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:
 
  git switch -c <new-branch-name>

진짜 위험은 하나뿐입니다: 여기서 만든 커밋은 어느 브랜치에도 속하지 않아, 저장하지 않고 떠나면 Git의 일상적인 garbage collection이 결국 지웁니다. 마음껏 살펴보고 작업하되, 남기고 싶다면 떠나기 전에 작업에 브랜치를 붙이세요.

어쩌다 detached가 됐는가

로컬 브랜치가 아닌 것을 checkout할 때마다 Git은 HEAD를 detach합니다:

• git checkout <sha>나 git checkout HEAD~2 — 특정 커밋.
• git checkout v1.4.0 — 태그.
• git checkout origin/main — remote-tracking 참조(거의 항상 git switch main을 의도한 것).
• 중단된 git rebase, git bisect 세션, 또는 커밋을 해시로 checkout하는 CI 작업.

이들 자체는 잘못이 아닙니다 — 태그를 checkout해 빌드하는 건 일상입니다. detached 상태임을 잊고 커밋을 시작할 때만 문제가 됩니다.

CI 안에서 git branch --show-current가 비어 나오는 걸 본 적이 있다면, 그것은 의도된 detached HEAD입니다: GitHub Actions, GitLab CI, 대부분의 러너는 재현 가능한 빌드를 위해 브랜치가 아니라 정확한 커밋 SHA를 checkout합니다. 그곳에서는 무해합니다 — 작업이 커밋하지 않으니까요 — 하지만 파이프라인에서 git rev-parse --abbrev-ref HEAD가 브랜치 이름 대신 HEAD를 찍는 이유입니다.

detached인지, 어디인지 확인

두 명령이 분명히 알려줍니다:

git status
# HEAD detached at 8fd6bda
 
git branch --show-current
# (아무것도 출력하지 않음 — 빈 줄은 현재 브랜치가 없다는 뜻)

git branch도 목록 맨 위에 * (HEAD detached at 8fd6bda)로 표시합니다. 그 짧은 SHA가 지금 서 있는 위치입니다.

아무것도 바꾸지 않았다면 브랜치로 돌아가기

살펴보기만 했다면 브랜치로 다시 switch하면 됩니다. Git이 있던 자리로 되돌려 줍니다:

git switch main
git switch -      # 또는: 이전 브랜치로 돌아가기

흔한 경우엔 이게 전부입니다 — git checkout main도 같은 일을 합니다.

detached 상태에서 만든 커밋 지키기

경고를 알아채기 전에 커밋을 몇 개 만들었다고 합시다. 아직 옮기지 말고, 지금 커밋에 먼저 브랜치를 붙이세요:

git switch -c hotfix-cache    # 브랜치가 작업을 가리키고 HEAD가 다시 붙음
git branch hotfix-cache       # 또는: 커밋에서 옮기지 않고 브랜치만 생성

git switch -c는 브랜치를 만들고 그 위로 한 번에 옮겨 주므로, 커밋이 이제 hotfix-cache에 안전히 놓입니다. 거기서 git switch main 후 git merge hotfix-cache로 브랜치에 합칩니다.

이미 옮긴 뒤 커밋 되살리기

이미 git switch main을 했고 detached 커밋이 사라진 듯 보여도 — 대개 아닙니다. reflog는 HEAD가 가리켰던 모든 위치를 기본 90일 동안 기록합니다:

git reflog -5 HEAD
# 8fd6bda HEAD@{0}: checkout: moving from a1b2c3d to main
# a1b2c3d HEAD@{1}: commit: fix cache key
# 9e8d7c6 HEAD@{2}: commit: add null guard

마지막 detached 커밋의 SHA(여기서는 a1b2c3d)를 찾아 브랜치를 그 위에 고정하세요:

git branch recovered a1b2c3d
git log --oneline recovered -3   # 커밋이 거기 있는지 확인

작업이 이름 있는 브랜치로 돌아왔습니다. "detached HEAD에서 커밋을 잃었다"가 거의 언제나 되살릴 수 있는 이유가 이것입니다 — reflog가 기억하기 때문입니다. 여러 detached 커밋 중 하나만 필요하다면, 대상 브랜치에서 git cherry-pick a1b2c3d가 작업 전체에 브랜치를 붙이는 대신 그 커밋 하나만 옮겨 옵니다.

reflog가 이미 사라진 경우

reflog는 영원하지 않습니다. 도달 불가능한 항목은 기본 30일 뒤 만료되고(gc.reflogExpireUnreachable), git gc가 더 일찍 지울 수도 있습니다. git reflog에 커밋이 더는 보이지 않아도, Git이 그 객체를 dangling(만들어졌지만 아무것도 가리키지 않는) 상태로 쥐고 있을 수 있습니다. 끊긴 끝을 물어보세요:

git fsck --lost-found --no-reflogs
# dangling commit a1b2c3d4e5f6...

후보를 git show a1b2c3d로 살펴보며 본인 작업을 알아본 뒤, 앞과 똑같이 고정하세요: git branch recovered a1b2c3d. 이것이 더 깊은 안전망입니다 — 객체는 git gc가 실제로 돌기 전까지 지워지지 않으므로, reflog가 정리됐어도 커밋은 대개 아직 객체 저장소에서 이름 붙기를 기다리고 있습니다.

실제 사례: checkout한 태그 위에서 만든 두 개의 수정

버그를 재현하려 git checkout v1.4.0을 하고 두 커밋으로 고친 뒤 PR을 열려 git switch main을 했는데, 두 커밋이 없습니다. main의 git status는 깨끗해 사라진 듯 보입니다. git reflog -3 HEAD가 a1b2c3d에서 commit: fix null deref를 보여주고, git branch fix-v14 a1b2c3d 후 git switch fix-v14를 하면 두 커밋이 push할 수 있는 실제 브랜치에 놓입니다. 1분도 안 걸립니다. 아무것도 지워진 적 없이 참조만 없었기 때문입니다.

실수로 여기 다시 오지 않기

브랜치 사이를 옮길 때는 git checkout 대신 git switch를 쓰세요: --detach를 주지 않으면 detach하지 않으므로, 잘못 친 git switch origin/main은 조용히 detach하는 대신 오류를 냅니다. 커밋이나 태그를 탐색하고 싶을 때는 미리 브랜치를 만드세요: git switch -c try-upgrade v1.4.0. 그리고 advice.detachedHead는 켜 두세요(기본값 on). Git이 계속 알림을 출력하도록요 — git config advice.detachedHead false로 끄는 것이 나중에 조용한 사고로 이어집니다.

reset --hard로 잃은 것·평범한 checkout과 어떻게 다른가

평범한 git checkout main은 HEAD를 브랜치에 붙입니다 — 경고가 없습니다. 만든 커밋이 main에 놓이기 때문입니다. detached HEAD는 반대입니다: 이름을 붙이기 전까지 커밋이 어디에도 놓이지 않습니다. git reset --hard로 작업을 잃는 것과도 다릅니다 — 그건 브랜치가 이동하며 커밋을 버리는 것이지만, 되살리는 도구는 같습니다: git reflog가 reset 이전 SHA를 찾고 git branch(또는 git reset)가 되돌립니다. git status가 브랜치 이름을 말하면 붙어 있어 안전한 것이고, HEAD detached at ...라고 하면 switch 전에 작업을 저장하세요.