Git reflog 사용법

Git reflog 사용법

git reflog는 로컬 저장소에서 브랜치나 HEAD가 이전에 어디를 가리켰는지 추적할 때 쓰는 기록이다. 2026년 7월 17일 기준 Git 공식 문서는 reflog를 "로컬 저장소에서 ref tip이 어떻게 바뀌었는지 기록하는 로그"로 설명한다.

실무에서 중요한 점은 두 가지다. 첫째, reflog는 원격과 공유되는 히스토리가 아니라 로컬 저장소 기준 기록이다. 둘째, HEAD@{1}, main@{yesterday} 같은 표기와 함께 쓰면 reset, rebase, branch switch 이전 지점을 다시 찾는 데 유용하다. 이 글은 Git 공식 문서를 기준으로 git reflog를 언제 보고, 어떤 표기를 기억하면 되는지 정리한다.

Git reflog는 무엇을 기록할까?

Git 공식 문서에 따르면 reflog는 branch tip이나 다른 ref가 갱신된 시점을 로컬 저장소 안에 기록한다. 일반 커밋 히스토리가 프로젝트 자체의 변경 이력을 보여준다면, reflog는 "내 로컬 ref가 언제 어디로 움직였는지"를 보여주는 관리 로그에 가깝다.

특히 HEAD reflog는 branch switching까지 기록한다. 그래서 단순히 이전 커밋을 보는 용도뿐 아니라, 방금 전에 어느 브랜치에 있었는지 확인하거나 직전 checkout 위치를 다시 찾는 데도 쓸 수 있다.

가장 자주 쓰는 표기는 무엇일까?

표기	의미	언제 유용한가
HEAD@{1}	HEAD의 직전 값	직전 reset, checkout, rebase 이전 위치를 확인할 때
main@{1}	main 브랜치의 직전 값	특정 브랜치 tip이 바로 전에 어디였는지 볼 때
main@{yesterday}	어제 시점의 로컬 main 값	시간 기준으로 이전 상태를 확인할 때
@{-1}	현재 전의 checkout 대상	방금 전 브랜치로 다시 돌아갈 때

Git의 gitrevisions 문서는 <ref>@{<n>}가 n번째 이전 값, <ref>@{<date>}가 특정 시점의 값을 뜻한다고 설명한다. 빈 ref를 둔 @{1}은 현재 브랜치의 reflog 엔트리를 뜻하고, @{-1}은 직전에 checkout했던 브랜치나 commit을 가리킨다.

조회는 어떤 명령부터 보면 될까?

가장 단순한 시작점은 git reflog 또는 git reflog show다. Git 공식 문서에 따르면 show는 subcommand를 생략했을 때의 기본 동작이며, git log -g --abbrev-commit --pretty=oneline의 별칭처럼 동작한다.

그래서 먼저 전체 흐름을 본 뒤 필요한 엔트리를 특정 revision으로 다시 조회하면 된다. 예를 들어 이전 위치를 안전하게 확인하고 싶다면 바로 되돌리기보다 git show HEAD@{1}처럼 내용을 먼저 확인하는 방식이 보수적이다.

실무에서는 언제 가장 도움이 될까?

reflog는 "커밋이 사라졌다"기보다 "ref가 다른 위치를 가리키게 됐다"는 상황에서 가장 유용하다. 예를 들어 reset --hard, rebase, branch 이동 뒤에 직전 위치를 확인하고 싶을 때 reflog가 가장 직접적이다.

다만 reflog가 있다고 해서 모든 과거 상태가 영구 보존되는 것은 아니다. reflog는 ref 이동 기록이므로, 보존 기간이 지나 prune되면 오래된 엔트리는 사라질 수 있다.

보존 기간 기본값은 어떻게 되나?

Git 공식 git-reflog 문서는 git reflog expire의 기본 동작을 설명하면서, reachable entry는 gc.reflogExpire 기본값 90일을 따르고, unreachable entry는 gc.reflogExpireUnreachable 기본값 30일을 따른다고 적고 있다.

즉 "예전에 한번 움직였던 포인터는 언제든 복구할 수 있다"라고 생각하면 위험하다. 복구 가능성을 운영 기준으로 삼아야 하는 저장소라면 reflog를 마지막 안전망 정도로 보고, 중요한 변경 전에는 명시적인 branch나 tag를 남겨 두는 편이 더 확실하다.

git reflog expire나 drop는 직접 자주 쓸까?

Git 공식 문서는 delete, drop, expire를 제공하지만, 이들 중 일부는 일반 end user가 직접 자주 쓰는 용도는 아니라고 설명한다. 특히 expire는 오래된 엔트리를 정리하는 기능이고, 문서도 보통은 git gc를 보라고 안내한다.

따라서 일상적인 사용 기준은 "조회와 참조에는 reflog, 정리 정책은 gc와 설정값"으로 나누는 편이 단순하다. reflog 자체를 지우거나 오래된 엔트리를 즉시 삭제하는 명령은 목적이 분명할 때만 쓰는 편이 낫다.

주의할 점은 무엇일까?

첫째, reflog는 로컬 저장소 기록이라 다른 개발자의 저장소나 원격 서버 reflog를 자동으로 대신해 주지 않는다. 둘째, <ref>@{<date>} 문법은 해당 ref에 reflog가 있어야만 동작한다. Git 공식 문서도 이 표기가 기존 reflog가 있는 ref에만 적용된다고 설명한다.

셋째, 복구 전에 바로 reset하기보다 git show나 git log -g로 먼저 대상을 확인하는 편이 안전하다. reflog는 강력하지만, 잘못된 엔트리로 다시 reset하면 상태를 더 복잡하게 만들 수 있다.

FAQ

Q. git reflog는 원격 저장소에서도 같은 기록을 볼 수 있나?

그렇게 보면 안 된다. Git 공식 문서 기준으로 reflog는 로컬 저장소에서 ref가 어떻게 갱신됐는지 기록하는 로그다.

Q. HEAD@{1}과 main@{1}은 왜 다를 수 있나?

HEAD reflog는 branch switching까지 기록하지만, 특정 브랜치 reflog는 그 브랜치 ref 자체가 움직인 기록만 남긴다. 따라서 checkout을 많이 했다면 두 기록은 서로 다를 수 있다.

Q. 실수로 reset한 뒤 가장 먼저 무엇을 보는 편이 좋을까?

보통은 git reflog로 직전 엔트리를 보고, 필요한 경우 git show HEAD@{1}처럼 대상을 먼저 확인하는 편이 안전하다. reflog는 이전 위치를 찾는 데 유용하지만, 복구 명령 자체는 상황에 따라 달라질 수 있다.

정리

git reflog의 핵심은 "로컬 ref가 이전에 어디를 가리켰는지 추적한다"는 점이다. 조회는 git reflog, 직전 값 참조는 HEAD@{1}, 시간 기준 참조는 main@{yesterday}, 직전 checkout 대상은 @{-1}처럼 이해하면 대부분의 실무 상황을 커버할 수 있다.

운영 기준을 한 줄로 줄이면 이렇다. reflog는 복구와 추적에 매우 유용하지만 로컬 전용이며 영구 보관도 아니다. 그래서 "마지막 안전망"으로는 좋지만, 장기 복구 수단을 대신하는 것으로 보면 안 된다.

참고 자료

• Git Documentation: git-reflog
• Git Documentation: gitrevisions