Git name-rev 사용법

git name-rev는 commit ID를 사람이 읽기 쉬운 ref 기준 이름으로 바꿔 볼 때 쓰는 명령입니다. 로그나 에러 메시지에 긴 commit hash만 있을 때, 그 commit이 어느 branch나 tag 근처에 있는지 빠르게 파악하는 데 유용합니다.

2026년 8월 5일 기준 Git 공식 문서에서 git-name-rev 매뉴얼은 Git 2.43.0 이후 2.55.0까지 내용 변경이 없습니다. 공식 설명의 핵심은 단순합니다. git name-rev는 git rev-parse가 해석할 수 있는 revision을 입력으로 받아, 사람이 이해하기 쉬운 symbolic name을 찾아 줍니다.

무엇을 알려 주는 명령인가

commit hash는 정확하지만 맥락을 바로 보여 주지는 않습니다. git name-rev는 같은 commit을 branch, tag, 그리고 그 기준점에서의 상대 위치로 표현합니다. 예를 들어 어떤 commit이 tags/v1.0~12처럼 표시되면, 해당 commit이 v1.0 tag에서 12단계 전 조상 쪽에 있다는 뜻으로 읽을 수 있습니다.

이 명령은 commit을 새 이름으로 바꾸거나 ref를 만드는 명령이 아닙니다. 이미 repository에 있는 ref를 기준으로 commit에 설명용 이름을 붙여 보는 조회 명령입니다.

기본 사용 흐름

가장 단순한 형태는 commit-ish 하나를 넘기는 방식입니다. commit hash, branch name, tag name처럼 Git이 revision으로 해석할 수 있는 값을 사용할 수 있습니다.

git name-rev 2ae0a9cb8298185a94e5998086f380a355dd8907

여러 commit을 한 번에 확인하려면 인자를 여러 개 넘길 수 있고, 도달 가능한 모든 commit을 대상으로 보려면 --all을 씁니다. 다만 --all은 repository 크기에 따라 출력이 많아질 수 있으므로, 사람이 직접 읽는 상황에서는 보통 특정 commit을 좁혀 쓰는 편이 낫습니다.

--tags와 --refs는 언제 쓰나

기본 동작은 사용 가능한 ref를 기준으로 이름을 찾습니다. release tag 기준으로만 위치를 보고 싶다면 --tags를 쓰고, 특정 branch나 tag 패턴만 기준으로 삼고 싶다면 --refs=<pattern>을 씁니다. 반대로 특정 ref를 제외하려면 --exclude=<pattern>을 사용할 수 있습니다.

옵션	의미	적합한 상황
--tags	branch 이름을 쓰지 않고 tag만 기준으로 이름을 찾음	release 기준 거리를 보고 싶을 때
--refs=<pattern>	패턴에 맞는 ref만 이름 후보로 사용	특정 branch 계열이나 tag 계열로 기준을 제한할 때
--exclude=<pattern>	패턴에 맞는 ref를 이름 후보에서 제외	임시 branch나 자동 생성 ref를 빼고 볼 때

--refs와 --exclude를 함께 쓰면, 먼저 포함 패턴에 맞고 제외 패턴에는 맞지 않는 ref만 사용됩니다. 기준 ref가 많아 이름이 기대와 다르게 잡힐 때 이 조합이 특히 중요합니다.

표시 방식은 어떻게 조정하나

--name-only는 commit hash와 이름을 함께 출력하지 않고 이름만 출력합니다. 스크립트에서 결과 문자열만 쓰고 싶을 때 적합합니다. --no-undefined는 이름을 찾지 못한 revision이 있을 때 undefined를 출력하는 대신 실패하도록 만들고, --always는 이름을 찾지 못했을 때 abbreviated commit object를 fallback으로 보여 줍니다.

git name-rev --name-only HEAD
git name-rev --tags --name-only HEAD
git name-rev --no-undefined 2ae0a9cb8298185a94e5998086f380a355dd8907

스크립트에서는 실패를 명확히 다루고 싶으면 --no-undefined가 낫고, 사람이 보는 진단 출력에서는 빈 결과보다 fallback이 필요한 경우 --always가 더 편할 수 있습니다. 두 방식은 실패를 어떻게 취급할지의 차이로 보면 됩니다.

--annotate-stdin은 무엇이 다른가

--annotate-stdin은 표준 입력에서 40자 SHA-1 hex를 찾아 그 뒤에 사람이 읽기 쉬운 이름을 덧붙입니다. 공식 문서에 따르면 예전 이름인 --stdin은 이 옵션으로 대체되었고, 기능적으로 같은 목적을 가집니다.

주의할 점은 abbreviated hash가 아니라 40자 전체 SHA-1 hex를 대상으로 치환한다는 점입니다. 이미 만들어진 로그나 텍스트 파일에 full hash가 많이 들어 있을 때 맥락을 덧붙이는 용도에 맞습니다.

git log --format=%H | git name-rev --annotate-stdin

git describe와 어떻게 다른가

git describe도 commit을 사람이 읽을 수 있는 이름으로 표현하지만 기준이 다릅니다. 공식 git describe 문서는 기본 동작이 commit에서 도달 가능한 가장 가까운 annotated tag를 찾는 것이라고 설명합니다. 반면 git name-rev는 revision을 branch나 tag 같은 symbolic ref 기준으로 이름 붙이는 데 초점이 있습니다.

그래서 release version 문자열을 만들거나 tag 기반 버전 표기가 필요하면 git describe가 더 자연스럽습니다. 반대로 "이 hash가 현재 ref 구조에서 어디쯤인가"를 살피거나, 텍스트 안의 full hash에 branch/tag 맥락을 덧붙이고 싶다면 git name-rev가 맞습니다.

선택 기준

• commit hash의 위치 맥락을 빠르게 보고 싶으면 git name-rev <commit>를 씁니다.
• release tag 기준으로만 보고 싶으면 --tags를 붙입니다.
• 기준 branch나 tag를 제한해야 하면 --refs와 --exclude를 조합합니다.
• 스크립트에서 이름만 필요하면 --name-only를 씁니다.
• 텍스트 안의 full hash에 설명을 붙이려면 --annotate-stdin을 씁니다.

핵심은 이름을 "생성"하는 명령이 아니라, 현재 repository의 ref를 기준으로 commit을 "해석"하는 명령으로 보는 것입니다. 기준 ref가 바뀌면 표시되는 이름도 달라질 수 있으므로, 재현 가능한 출력이 필요할 때는 어떤 ref를 기준으로 삼을지 옵션으로 좁혀야 합니다.

FAQ

git name-rev 결과는 항상 같은가

같은 repository 상태와 같은 ref 집합에서는 같은 기준으로 해석됩니다. 하지만 branch나 tag가 추가되거나 삭제되면 더 적합한 symbolic name이 달라질 수 있습니다. 재현성이 중요하면 --tags, --refs, --exclude로 후보 ref를 제한하는 편이 좋습니다.

짧은 hash도 --annotate-stdin에서 바뀌나

공식 예시는 abbreviated revision은 치환되지 않는다고 설명합니다. 이 옵션은 텍스트 안의 40자 SHA-1 hex를 찾아 이름을 덧붙이는 용도입니다.

버전 문자열 생성에는 무엇을 써야 하나

tag 기반 릴리스 버전 문자열이 목적이면 보통 git describe가 더 적합합니다. git name-rev는 commit이 어떤 ref 근처에 있는지 설명하는 진단용 이름에 더 가깝습니다.