Git show-ref 사용법

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

Git show-ref 사용법

git show-ref는 로컬 저장소 안에 있는 ref를 object ID와 함께 나열하거나, 특정 ref가 실제로 있는지 확인할 때 쓰는 Git plumbing 명령이다. 2026년 7월 31일 확인 기준 Git 공식 문서는 이 명령이 heads, tags, remotes 같은 ref를 보여 주고, 태그 역참조나 존재 확인에도 쓸 수 있다고 설명한다.

실무에서는 브랜치나 태그를 스크립트에서 안전하게 확인할 때 유용하다. 이 글은 Git 공식 git-show-ref 문서를 기준으로 출력 형식, --verify와 --exists 차이, --dereference와 --hash 선택 기준을 정리한다.

Git show-ref는 언제 쓰는 명령일까?

git branch나 git tag가 사람에게 보기 좋은 출력을 만드는 쪽이라면, git show-ref는 ref 목록을 기계적으로 확인하고 후속 명령으로 넘기기 쉬운 형태로 보여 주는 쪽에 가깝다. 공식 문서 기준 기본 출력 대상은 tags, heads, remote refs다.

특히 Git은 .git 아래 파일을 직접 읽는 대신 관련 plumbing 명령을 쓰는 편이 안전하다. git show-ref 문서도 ref를 확인할 때 .git 디렉터리 파일을 직접 다루기보다 이 유틸리티 사용을 권장한다.

기본 출력은 어떤 형식일까?

기본 출력은 한 줄에 object-id ref-name 형식이다. 그래서 결과를 다른 셸 명령이나 스크립트에 넘기기 쉽다.

git show-ref
git show-ref --head

공식 문서 기준 --head를 주면 일반적으로 숨겨지는 HEAD도 함께 표시한다. 브랜치 ref 목록만 보려면 --branches, 태그만 보려면 --tags를 붙이면 된다.

git show-ref --branches
git show-ref --tags
git show-ref --branches --tags

두 옵션을 같이 쓰면 local branch와 tag만 남고, 그 밖의 ref는 제외된다. remote-tracking branch까지 같이 보고 싶은 경우에는 기본 출력이나 패턴 검색 쪽이 더 맞다.

패턴 검색은 정확히 어떻게 동작할까?

공식 문서 기준 git show-ref master처럼 패턴을 넘기면 ref 전체 이름의 끝부분을 기준으로 매칭한다. 그리고 부분 문자열이 아니라 complete part 단위로 비교한다.

git show-ref main
git show-ref release

예를 들어 master는 refs/heads/master나 refs/tags/jedi/master에는 매칭될 수 있지만, refs/heads/mymaster에는 매칭되지 않는다. 따라서 사람이 보기에는 비슷해도 ref 이름 끝부분 구조가 다르면 잡히지 않을 수 있다.

정확한 ref 경로를 검사할 때는 왜 --verify가 중요할까?

--verify는 패턴 매칭이 아니라 exact ref path를 요구한다. 공식 문서 기준 이 모드는 결과가 없으면 종료 코드 1을 반환하고, --quiet가 없으면 오류 메시지도 출력한다.

git show-ref --verify refs/heads/main
git show-ref --quiet --verify -- "refs/heads/$branch"

스크립트에서 "브랜치 이름처럼 보이는 문자열"이 아니라 실제 refs/heads/... 경로가 존재하는지 확인하려면 이 방식이 가장 명확하다. partial match를 피할 수 있기 때문이다.

--exists와 --verify는 무엇이 다를까?

두 옵션 모두 존재 확인에 쓰이지만 기준이 다르다. 공식 문서에 따르면 --exists는 ref가 있는지만 확인하고, 그 ref가 실제 객체로 해석되는지까지는 검증하지 않는다. 반면 --verify는 stricter reference checking을 수행한다.

git show-ref --exists refs/heads/main
git show-ref --verify refs/heads/main

종료 코드도 다르게 봐야 한다. --exists는 존재하면 0, 없으면 2, 그 외 조회 오류는 1이다. 자동화에서 "없음"과 "기타 오류"를 구분해야 하면 --exists가 더 직접적이다.

 

 

태그가 가리키는 실제 객체까지 보고 싶다면?

annotated tag는 tag 객체와 실제 대상 객체가 다를 수 있다. 이때 --dereference를 쓰면 태그 자체 ref와 함께 역참조된 대상 object ID를 ^{} 표기와 함께 보여 준다.

git show-ref --tags --dereference

공식 문서 예시도 같은 방식을 사용한다. release 태그가 어떤 commit을 가리키는지까지 확인해야 할 때 유용하고, lightweight tag처럼 별도 tag 객체가 없는 경우와 차이를 보는 데도 도움이 된다.

해시만 필요할 때는 어떻게 줄일까?

후속 명령이 ref 이름보다 object ID만 필요로 하면 --hash를 쓴다. 길이를 줄이고 싶다면 --hash=<n>이나 --abbrev[=<n>]를 조합할 수 있다.

git show-ref --branches --hash
git show-ref --branches --hash=12
git show-ref --verify --hash -- refs/heads/main

공식 문서 기준 --hash는 ref 이름을 생략하고 object ID만 출력한다. 다만 --dereference와 함께 쓰면 역참조된 태그 정보는 여전히 뒤에 남는다. 따라서 "정말 한 줄 해시만" 필요한지, "태그 해석 결과도" 필요한지 먼저 구분하는 편이 좋다.

--exclude-existing는 언제 유용할까?

이 모드는 입력으로 받은 ref 목록 중 로컬 저장소에 아직 없는 ref만 걸러 낸다. 공식 문서 기준 표준 입력을 한 줄씩 읽고, 형식이 맞지 않는 ref는 경고 후 건너뛴다.

printf '%s\n' refs/heads/main refs/heads/topic-x | git show-ref --exclude-existing

예를 들어 외부 목록이나 생성 후보 목록을 받아 "이미 있는 이름은 빼고 새로 만들 후보만 남기기" 같은 필터 작업에 맞다. 단일 ref 존재 확인은 --exists가 더 단순하고, 여러 후보를 한꺼번에 처리할 때는 이 모드가 더 잘 맞는다.

FAQ

Q. 브랜치 존재 확인은 git branch --list보다 show-ref가 나은가?

스크립트 기준으로는 그렇다. git show-ref --quiet --verify -- "refs/heads/NAME"처럼 exact ref path를 검사하면 partial match나 출력 포맷 차이를 덜 신경 써도 된다.

Q. --exists가 성공했다고 해서 대상 객체도 반드시 정상인가?

아니다. 공식 문서 기준 --exists는 ref 존재만 확인하고, 그 ref가 실제 객체로 해석되는지까지 검증하지 않는다. 그 구분이 중요하면 --verify 쪽을 우선 검토해야 한다.

Q. remote branch만 따로 보고 싶다면?

git show-ref에는 remote refs 전용 필터 옵션이 따로 없다. 기본 출력이나 패턴 검색 결과에서 refs/remotes/ 경로를 기준으로 후속 처리하는 편이 현실적이다.

정리

git show-ref는 로컬 저장소의 ref를 안정적으로 나열하고 검사하는 명령이다. 목록 확인은 기본 출력, 정확한 존재 검사는 --verify, 상태 코드를 세분해서 보려면 --exists, 태그가 가리키는 실제 객체까지 보려면 --dereference로 정리하면 된다.

실무 선택 기준은 단순하다. 사람이 읽을 목록인지, 스크립트가 exact path를 확인해야 하는지, 태그 대상 객체까지 필요한지, 여러 후보 중 없는 ref만 골라야 하는지에 따라 옵션을 나누면 된다.

참고 자료

• Git Documentation: git-show-ref