git tag로 릴리스 버전 관리하기

소프트웨어를 릴리스할 때 “이 커밋이 v1.0.0이다”라고 표시해두면 나중에 특정 버전의 코드를 찾기가 훨씬 수월해지는데요. git tag는 바로 이런 용도로 특정 커밋에 이름표를 붙이는 명령어입니다. 커밋 해시를 외울 필요 없이 v1.0.0, v2.1.3 같은 의미 있는 이름으로 중요한 시점을 기록할 수 있죠.

태그 종류

Git 태그에는 두 가지 종류가 있습니다.

Lightweight 태그는 단순히 특정 커밋을 가리키는 포인터입니다. 이름만 붙이고 별도의 정보는 저장하지 않습니다.

Annotated 태그는 태그를 만든 사람, 날짜, 메시지 등의 메타 정보를 함께 저장합니다. Git 객체로 별도 관리되기 때문에 더 많은 정보를 담을 수 있습니다.

릴리스 버전을 표시하는 용도라면 annotated 태그를 사용하는 것이 권장됩니다. 임시 표시나 개인적인 메모 용도로는 lightweight 태그면 충분합니다.

태그 만들기

Annotated 태그는 -a 옵션과 함께 -m으로 메시지를 지정합니다.

$ git tag -a v1.0.0 -m "첫 번째 정식 릴리스"

Lightweight 태그는 옵션 없이 태그 이름만 입력합니다.

$ git tag v1.0.0-beta

기본적으로 현재 HEAD가 가리키는 커밋에 태그가 붙는데, 특정 커밋에 태그를 붙이고 싶다면 커밋 해시를 뒤에 추가합니다.

$ git tag -a v0.9.0 -m "베타 릴리스" a1b2c3d

지난주에 릴리스했어야 하는데 태그를 깜빡 잊었을 때 유용합니다.

태그 목록 확인

등록된 태그 목록을 보려면 git tag만 실행합니다.

$ git tag
v0.9.0
v1.0.0
v1.0.0-beta
v1.1.0

태그가 많을 때 패턴으로 필터링할 수 있습니다.

$ git tag -l "v1.*"
v1.0.0
v1.0.0-beta
v1.1.0

Annotated 태그의 상세 정보를 보려면 git show 명령어를 사용합니다.

$ git show v1.0.0
tag v1.0.0
Tagger: Dale Seo <dale@example.com>
Date:   Mon Feb 23 10:00:00 2026 +0900

첫 번째 정식 릴리스

commit a1b2c3d4e5f6...
Author: Dale Seo <dale@example.com>
Date:   Sun Feb 22 18:30:00 2026 +0900

    배포 준비 완료

태그를 만든 사람, 날짜, 메시지는 물론 해당 커밋의 정보까지 함께 보여줍니다.

태그를 원격에 올리기

태그는 git push를 해도 자동으로 원격 저장소에 올라가지 않습니다. 태그를 원격에 올리려면 명시적으로 push해야 합니다.

$ git push origin v1.0.0

모든 태그를 한 번에 올리려면 --tags 옵션을 사용합니다.

$ git push origin --tags

GitHub 같은 서비스에서는 태그를 push하면 자동으로 “Releases” 페이지에 표시됩니다. 많은 오픈소스 프로젝트가 이런 방식으로 릴리스를 관리하고 있죠.

태그로 체크아웃

특정 태그 시점의 코드를 확인하고 싶다면 체크아웃할 수 있습니다.

$ git switch --detach v1.0.0

이렇게 하면 “detached HEAD” 상태가 되는데, 이 상태에서는 코드를 둘러볼 수는 있지만 새 커밋을 남기기에는 적합하지 않습니다.

해당 시점에서 작업을 하고 싶다면 새 브랜치를 만드는 것이 좋습니다.

$ git switch -c hotfix/v1.0.1 v1.0.0

이 명령어는 v1.0.0 태그 시점에서 hotfix/v1.0.1이라는 새 브랜치를 만들어줍니다. 릴리스된 버전에서 긴급 버그 수정이 필요할 때 자주 사용하는 패턴입니다.

태그 삭제

로컬에서 태그를 삭제하려면 -d 옵션을 사용합니다.

$ git tag -d v1.0.0-beta
Deleted tag 'v1.0.0-beta' (was a1b2c3d)

원격 저장소의 태그도 삭제하려면 push로 삭제합니다.

$ git push origin --delete v1.0.0-beta

이미 공개된 릴리스 태그를 삭제하면 해당 버전을 참조하고 있던 사용자에게 혼란을 줄 수 있으니, 공개 태그 삭제는 신중하게 결정해야 합니다.

시맨틱 버저닝

태그 이름을 지을 때는 시맨틱 버저닝(Semantic Versioning) 규칙을 따르는 것이 일반적입니다.

v주.부.수 형식에서 주(major) 버전은 호환되지 않는 변경이 있을 때, 부(minor) 버전은 기능이 추가될 때, 수(patch) 버전은 버그 수정이 있을 때 올립니다.

$ git tag -a v1.0.0 -m "최초 안정 릴리스"
$ git tag -a v1.1.0 -m "검색 기능 추가"
$ git tag -a v1.1.1 -m "검색 결과 정렬 버그 수정"
$ git tag -a v2.0.0 -m "API 응답 형식 변경 (하위 호환 불가)"

이 규칙을 따르면 태그 이름만 보고도 어떤 종류의 변경이 있었는지 짐작할 수 있습니다.

마치며

git tag는 프로젝트의 이정표를 관리하는 간단하면서도 중요한 명령어입니다. 릴리스마다 태그를 붙이는 습관을 들이면, 버전 관리가 체계적으로 이루어지고 특정 버전의 코드를 찾아볼 때도 편리합니다.

더 자세한 내용은 Git 공식 문서를 참고하세요.