Git rev-parse 사용법

Git rev-parse 사용법

git rev-parse는 Git이 이해하는 revision, ref, 경로 관련 인자를 해석해서 스크립트나 사용자가 바로 쓸 수 있는 형태로 바꿔 주는 명령이다. 2026년 7월 27일 확인 기준 Git 공식 문서는 이 명령의 핵심 목적을 상위 명령이 받는 여러 인자 중 revision 계열을 구분하고, 객체 이름·ref 이름·저장소 경로 정보를 다루는 데 있다고 설명한다.

실무에서는 현재 브랜치 이름 확인, 저장소 루트 경로 찾기, 사용자가 준 커밋 이름 검증, @{upstream} 같은 ref 해석에 자주 쓴다. 이 글은 Git 공식 git-rev-parse와 gitrevisions 문서를 기준으로 많이 쓰는 옵션과 선택 기준을 정리한다.

Git rev-parse는 언제 쓰는 명령일까?

git log나 git show처럼 결과를 사람이 읽게 보여 주는 명령과 달리, git rev-parse는 다른 명령이나 셸 스크립트에 넘길 값을 안정적으로 뽑아내는 쪽에 가깝다. 그래서 "지금 어느 저장소 루트에서 실행 중인가", "입력한 값이 실제 커밋인가", "현재 브랜치의 upstream ref가 무엇인가" 같은 질문에 답할 때 유용하다.

특히 자동화에서 문자열을 직접 조합하기보다 Git이 해석한 값을 다시 받는 편이 안전하다. ref 이름 모호성, 하위 디렉터리 실행, tag와 commit 구분 같은 문제를 줄일 수 있기 때문이다.

저장소 루트와 현재 위치를 확인할 때 무엇을 쓰면 될까?

가장 많이 쓰는 조합은 --show-toplevel과 --show-prefix다. 공식 문서 기준 --show-toplevel은 working tree 최상위 경로를 보여 주고, --show-prefix는 현재 디렉터리가 저장소 루트 기준 어디에 있는지 상대 경로를 알려 준다.

git rev-parse --show-toplevel
git rev-parse --show-prefix
git rev-parse --show-cdup

스크립트가 어느 하위 디렉터리에서 실행되더라도 루트로 이동한 뒤 동일한 기준으로 파일을 다루고 싶다면 이 조합이 가장 단순하다. 루트까지 ../ 형태가 필요하면 --show-cdup이 더 직접적이다.

현재 브랜치나 ref 이름은 어떻게 안전하게 얻을까?

현재 HEAD가 가리키는 브랜치의 짧은 이름이 필요하면 --abbrev-ref가 실용적이다. 반대로 완전한 ref 이름이 필요하면 --symbolic-full-name을 쓴다.

git rev-parse --abbrev-ref HEAD
git rev-parse --symbolic-full-name HEAD
git rev-parse --symbolic-full-name @{upstream}

공식 문서 기준 --abbrev-ref는 비모호한 짧은 이름을 출력하고, --symbolic-full-name은 branch나 tag 같은 ref만 남겨 refs/heads/main 같은 전체 ref 이름으로 보여 준다. CI나 배포 스크립트처럼 원격 추적 브랜치까지 정확히 구분해야 하면 전체 ref 이름 쪽이 더 안전하다.

사용자가 준 커밋이나 태그 이름이 진짜인지 확인하려면?

이때 가장 중요한 옵션은 --verify다. Git 공식 문서는 이 옵션이 인자가 정확히 하나인지 확인하고, 이를 객체 데이터베이스에서 쓸 수 있는 raw object id로 바꿀 수 있을 때만 출력한다고 설명한다.

git rev-parse --verify HEAD
git rev-parse --verify v1.2.0^{commit}
git rev-parse --verify feature-branch^{object}

^{commit}를 붙이면 annotated tag가 가리키는 commit까지 허용하면서 commit-ish인지 확인할 수 있고, ^{object}는 타입과 무관하게 객체 존재만 검사할 때 쓴다. 축약 해시가 필요하면 --short를 조합할 수 있다.

git rev-parse --short HEAD

공식 문서는 신뢰하지 않는 입력을 검증할 때 --end-of-options 사용을 권장한다. 인자가 옵션처럼 해석되는 일을 막기 위해서다.

git rev-parse --verify --end-of-options "$REV^{commit}"

@{upstream}, @{push}, @{-1}는 무엇을 뜻할까?

이 표기들은 gitrevisions 문서에서 정의하는 revision 문법이다. @{upstream} 또는 @{u}는 현재 브랜치가 추적하는 remote-tracking branch를 뜻하고, @{push}는 지금 git push를 실행하면 대상으로 삼을 쪽을 뜻한다.

git rev-parse --symbolic-full-name @{u}
git rev-parse --symbolic-full-name @{push}
git rev-parse @{-1}

공식 문서는 pull 대상과 push 대상이 다른 triangular workflow에서는 @{upstream}과 @{push}가 달라질 수 있다고 설명한다. 그리고 @{-1}은 현재 브랜치 바로 전에 checkout했던 브랜치나 커밋을 가리킨다. 브랜치 전환 스크립트나 비교 작업에서 유용하다.

HEAD^, HEAD~3, v1.0^{commit} 같은 표기는 어떻게 읽어야 할까?

git rev-parse는 이런 revision 문법을 그대로 해석한다. ^는 부모 커밋을, ~n은 첫 번째 부모를 따라 n단계 올라간 조상을 뜻한다. 그리고 ^{commit}, ^{tree}, ^{object} 같은 표기는 원하는 객체 타입까지 역참조하는 용도다.

git rev-parse HEAD^
git rev-parse HEAD~3
git rev-parse v1.0^{commit}
git rev-parse HEAD:README.md

HEAD:README.md처럼 rev:path 문법을 쓰면 특정 커밋 시점의 blob이나 tree도 가리킬 수 있다. 파일 내용을 다른 명령에 넘기거나, 현재 워킹트리와 과거 트리의 특정 파일을 비교할 때 유용하다.

경로 출력은 절대 경로와 상대 경로 중 무엇을 써야 할까?

공식 문서 기준 --path-format=(absolute|relative)는 뒤따르는 일부 경로 옵션의 출력 방식을 제어한다. 여러 도구가 같은 값을 재사용해야 하면 절대 경로가 안정적이고, 현재 셸에서 바로 후속 명령을 붙일 때는 상대 경로가 읽기 쉽다.

git rev-parse --path-format=absolute --git-dir
git rev-parse --path-format=relative --show-toplevel

다만 옵션마다 기본값이 같지 않으므로, 자동화에서는 원하는 형식을 명시하는 편이 실수를 줄인다.

저장소 밖에서 실행하면 왜 실패할까?

Git 공식 문서는 별도 예외가 명시되지 않은 대부분의 모드가 Git 저장소 또는 그 working tree 안에서 실행돼야 한다고 설명한다. 그래서 --show-toplevel, --verify HEAD, --abbrev-ref HEAD 같은 호출은 저장소 밖에서 fatal error를 낸다.

반면 --parseopt와 --sq-quote 같은 일부 모드는 저장소 밖에서도 쓸 수 있다. 일반적인 블로그 글 독자 기준에서는 저장소 내부 정보를 다루는 옵션이 훨씬 중요하므로, 실무에서는 먼저 저장소 안에서 실행되는지 확인하는 습관이 필요하다.

FAQ

Q. 현재 브랜치 이름만 알고 싶으면 git branch --show-current 대신 rev-parse를 써도 되나?

가능하다. 다만 스크립트 호환성과 ref 해석까지 함께 다룰 계획이면 git rev-parse --abbrev-ref HEAD가 일관적이다. 단, detached HEAD에서는 일반 브랜치 이름을 기대하면 안 된다.

Q. 태그가 commit을 가리키는지 확인하면서 object id도 얻고 싶다?

git rev-parse --verify --end-of-options "$TAG^{commit}" 형태가 가장 분명하다. 공식 문서 기준 ^{commit}는 commit-ish로 역참조할 수 있을 때만 성공한다.

Q. upstream 브랜치가 설정되지 않았으면 @{u}는 어떻게 되나?

해당 브랜치에 upstream 설정이 없으면 해석에 실패한다. 따라서 자동화에서는 @{u}를 바로 쓰기보다 실패 가능성을 전제로 처리해야 한다.

정리

git rev-parse의 핵심은 사람이 대충 적은 revision 문자열을 Git이 실제로 이해하는 객체 이름, ref 이름, 저장소 경로로 바꿔 준다는 점이다. 저장소 루트 확인은 --show-toplevel, 브랜치 이름 확인은 --abbrev-ref, 안전한 객체 검증은 --verify와 ^{type} 조합으로 정리하면 대부분의 실무 상황을 커버할 수 있다.

자동화 기준으로는 세 가지가 중요하다. 경로는 필요하면 --path-format을 명시하고, 외부 입력 검증에는 --end-of-options를 붙이며, branch 추적 관계는 @{upstream}과 @{push}를 구분하는 것이다. 이 정도만 잡아도 Git 스크립트의 오해와 실패를 많이 줄일 수 있다.

참고 자료

• Git Documentation: git-rev-parse
• Git Documentation: gitrevisions