Git describe 사용법

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

Git describe 사용법

git describe는 현재 커밋을 사람이 읽기 쉬운 이름으로 바꿔 보여 주는 Git 명령이다. 2026년 7월 25일 확인 기준 Git 공식 문서는 이 명령이 사용 가능한 ref를 바탕으로 객체에 사람이 읽을 수 있는 이름을 붙인다고 설명한다.

실무에서는 배포 산출물 버전 문자열, 태그 기준 릴리스 거리 확인, 태그 정책 점검에 자주 쓴다. 이 글은 Git 공식 git describe와 git tag 문서를 기준으로 기본 출력 형식, annotated tag 우선 규칙, --tags, --all, --dirty, --abbrev=0 선택 기준을 정리한다.

Git describe는 무엇을 출력할까?

가장 기본 동작은 현재 커밋에서 도달 가능한 가장 가까운 태그를 찾는 것이다. 입력한 커밋이 그 태그 자체라면 태그 이름만 출력하고, 태그보다 뒤에 있는 커밋이면 태그 이름 뒤에 추가 커밋 수와 축약 커밋 해시를 붙인다.

git describe

예를 들어 출력이 v2.4.1-3-g1a2b3c4라면, 현재 커밋이 v2.4.1 태그보다 3개 앞서 있고 끝의 g1a2b3c4가 현재 커밋의 축약 식별자라는 뜻이다. Git 공식 문서도 추가 커밋 수는 tag..input 범위에 보일 커밋 수와 같은 의미라고 설명한다.

왜 릴리스 버전 문자열에 자주 쓰일까?

태그가 정확히 찍힌 커밋에서는 단순한 릴리스 이름이 나오고, 태그 이후 개발 중인 커밋에서는 "어느 태그에서 얼마나 멀어졌는지"가 함께 드러나기 때문이다. 그래서 정식 배포와 태그 이후 개발 커밋을 같은 규칙으로 구분하기 쉽다.

다만 이 결과는 저장소의 태그 상태에 직접 의존한다. 릴리스 태그가 없거나 로컬에 필요한 태그 이력이 없으면 기대한 문자열이 나오지 않을 수 있으므로, 자동화에서는 태그 수집 정책을 함께 봐야 한다.

기본적으로 annotated tag만 보는 이유는 무엇일까?

Git 공식 문서에 따르면 git describe는 기본적으로 annotated tag만 사용한다. 그리고 git tag 문서는 annotated tag가 생성 시각, 태거 정보, 메시지, 선택적으로 서명을 담는 tag object이며, lightweight tag는 보통 객체를 가리키는 단순한 이름이라고 설명한다.

같은 git tag 문서는 annotated tag는 release용, lightweight tag는 private 또는 temporary label용이라고 구분한다. 그래서 릴리스 기준점을 안정적으로 삼으려는 기본 동작에서는 annotated tag 우선이 더 보수적이다.

--tags와 --all은 언제 써야 할까?

--tags를 붙이면 lightweight tag까지 포함한 모든 태그를 후보로 본다. 릴리스 태그를 lightweight로만 운영하는 저장소라면 이 옵션이 없을 때 결과가 비거나 예상보다 오래된 태그가 잡힐 수 있다.

git describe --tags

--all은 범위를 더 넓혀 refs/ 아래의 branch, remote-tracking branch, lightweight tag까지 후보로 본다. 태그가 거의 없는 저장소에서 "현재 커밋이 어느 브랜치 계열에 가까운가"를 사람이 읽을 수 있게 보고 싶을 때는 유용하지만, 릴리스 버전 문자열 용도로는 태그보다 의미가 흐려질 수 있다.

가장 가까운 태그 이름만 필요하면 어떻게 할까?

추가 커밋 수와 해시를 빼고 태그 이름만 보고 싶다면 --abbrev=0이 가장 직접적이다. Git 공식 문서는 이 옵션값이 0이면 long format을 억제하고 가장 가까운 태그만 보여 준다고 설명한다.

git describe --abbrev=0

배포 스크립트에서 "현재 브랜치가 어떤 최신 릴리스 태그 위에 서 있나"만 확인하려면 이 형태가 읽기 쉽다. 반대로 태그 이후 몇 커밋이 쌓였는지까지 필요하면 기본 출력이나 --long 쪽이 더 낫다.

 

 

--long와 --dirty는 어떤 상황에서 유용할까?

--long는 입력 커밋이 태그와 정확히 같아도 항상 tag-0-g<sha> 형태를 유지한다. 산출물 문자열 형식을 항상 고정하고 싶을 때 유용하다.

git describe --long
git describe --dirty

--dirty는 작업 트리가 HEAD와 다르면 기본적으로 -dirty 접미사를 붙인다. Git 공식 문서는 저장소가 손상돼 변경 여부를 판단할 수 없을 때는 에러를 내고, 그 경우 --broken을 주면 -broken을 붙일 수 있다고 설명한다.

즉 재현 가능한 빌드 문자열이 중요하다면 --dirty 결과를 그대로 릴리스 버전에 쓰기보다, 로컬 개발 빌드 표시에만 쓸지 정책을 먼저 정하는 편이 안전하다.

--contains는 기본 동작과 무엇이 다를까?

기본 git describe는 현재 커밋보다 앞선 태그, 즉 현재 커밋이 도달 가능한 과거 태그를 찾는다. 반면 --contains는 현재 커밋을 포함하는 이후 태그를 찾는 모드이며, 공식 문서 기준 자동으로 --tags도 함께 의미한다.

git describe --contains <commit>

이 모드는 "이 커밋이 어떤 릴리스에 포함됐는가"를 역으로 볼 때 유용하다. 다만 아직 어떤 태그에도 포함되지 않은 개발 중 커밋에는 원하는 답을 주지 못할 수 있다.

정확한 태그 일치만 검사할 수도 있을까?

그럴 수 있다. --exact-match는 입력 커밋을 직접 가리키는 태그가 있을 때만 출력하며, Git 공식 문서는 이것이 --candidates=0의 동의어라고 설명한다.

git describe --exact-match HEAD

CI에서 "지금 빌드가 태그된 릴리스인지"를 판정할 때는 기본 describe보다 이 옵션이 더 분명하다. 태그가 없으면 실패로 처리하고, 태그가 있으면 그 이름을 릴리스 기준으로 쓰는 식이다.

언제 결과가 기대와 다르게 나올까?

첫째, annotated tag가 없고 lightweight tag만 있는 저장소인데 --tags를 붙이지 않은 경우다. 둘째, 필요한 태그가 fetch되지 않은 shallow clone이나 일부 CI 체크아웃 환경이다. 셋째, merge가 많은 히스토리에서 원하는 브랜치 계열만 보려는데 기본 탐색이 다른 태그를 먼저 선택한 경우다.

이런 상황에서는 태그 정책부터 확인하고, 필요하면 --first-parent, --match, --exclude, --all을 조합해 후보 범위를 좁히는 편이 낫다. 공식 문서도 기본 탐색이 최근 태그 후보 일부만 먼저 보고, --candidates를 늘리면 더 정확할 수 있다고 안내한다.

FAQ

Q. lightweight tag만 있어도 git describe가 항상 동작하나?

기본 동작만으로는 그렇지 않다. Git 공식 문서 기준 기본값은 annotated tag만 본다. lightweight tag까지 후보에 넣으려면 --tags를 붙여야 한다.

Q. 태그가 정확히 일치하는 커밋인데도 긴 형식을 강제로 유지할 수 있나?

가능하다. --long를 쓰면 exact match여도 tag-0-g<sha> 형태를 유지한다. 버전 문자열 포맷을 항상 동일하게 맞추고 싶을 때 유용하다.

Q. 저장소에 태그가 전혀 없으면 어떻게 되나?

기본적으로는 설명 가능한 태그가 없어서 실패할 수 있다. 이런 환경에서 최소한 축약 커밋 해시라도 받고 싶다면 --always를 고려할 수 있다. Git 공식 문서는 이 옵션이 고유하게 축약된 커밋 객체 이름을 fallback으로 보여 준다고 설명한다.

정리

git describe의 핵심은 현재 커밋을 "가장 가까운 태그 기준으로 얼마나 떨어져 있는가"라는 형태로 바꾸는 데 있다. 기본값은 release 성격의 annotated tag를 우선하고, 저장소 정책에 따라 --tags, --all, --abbrev=0, --long, --dirty를 골라 쓰면 된다.

대부분의 팀에서는 release 태그를 annotated tag로 통일하고, 자동화에서는 태그 fetch 누락 여부를 함께 점검하는 방식이 가장 단순하다. 그 위에서 릴리스 판정은 --exact-match, 빌드 문자열은 기본형 또는 --long, 로컬 작업 표시에는 --dirty를 나누면 운영 기준이 분명해진다.

참고 자료

• Git Documentation: git-describe
• Git Documentation: git-tag