Git 커밋 메시지 컨벤션 가이드

소프트웨어 개발 과정에서 Git을 사용하여 코드를 관리할 때, 각 코드 변경(커밋)에는 메시지를 필수로 작성해야 합니다. 하지만 종종 이 커밋 메시지가 모호하거나 일관성이 없어, 추후 코드 이력을 추적하거나 유지보수할 때 어려움을 겪는 경우가 많습니다. 'fix bug'와 같은 일반적인 메시지는 변경 내용의 본질을 파악하기 어렵게 만들며, 이는 결국 개발 효율성 저하로 이어집니다.

이러한 문제를 해결하고 코드 품질을 향상시키기 위해, Git 커밋 메시지 작성에 대한 표준화된 규칙을 적용하는 것이 중요합니다. 일관된 커밋 메시지 컨벤션은 코드 이력 추적을 용이하게 하고 팀원 간의 협업을 강화하는 데 크게 기여합니다.

커밋 메시지 컨벤션 구축

현재 가장 널리 사용되고 합리적인 Git 커밋 메시지 컨벤션은 Angular 프로젝트에서 사용하는 방식입니다. 이 컨벤션은 체계적이며, IntelliJ IDEA나 VS Code 같은 통합 개발 환경(IDE)에서 플러그인을 통해 지원되기도 합니다.

커밋 메시지 형식

커밋 메시지는 크게 세 가지 부분으로 구성됩니다: 헤더(header), 본문(body), 푸터(footer).

  • 헤더는 필수이며, 본문과 푸터는 선택 사항입니다.
  • 각 라인은 가독성을 위해 72자(또는 최대 100자)를 넘지 않도록 하는 것이 좋습니다.
<type>(<scope>): <subject>

<BLANK LINE>
<body>

<BLANK LINE>
<footer>

헤더 (Header)

type: 변경 유형 (필수)

커밋의 성격을 나타내는 유형으로, 다음 목록 중 하나를 사용해야 합니다.

  • feat: 새로운 기능 추가
  • fix: 버그 수정 (QA 또는 개발자가 발견한 버그)
    • fix: 변경 사항을 포함하며 즉시 문제를 해결하는 단일 커밋에 적합
    • to: 변경 사항만 포함하고 문제 해결은 다른 커밋에서 완료될 때 사용 (최종 해결 시 fix 사용)
  • docs: 문서 변경
  • style: 코드 포맷팅, 세미콜론 누락 등 코드 동작에 영향을 주지 않는 변경
  • refactor: 코드 리팩토링 (기능 추가나 버그 수정이 아닌 코드 구조 개선)
  • perf: 성능 또는 사용자 경험 최적화
  • test: 테스트 코드 추가 또는 수정
  • build: 빌드 시스템 또는 외부 의존성 변경
  • ci: CI(지속적 통합) 구성 파일 또는 스크립트 변경
  • chore: 빌드 프로세스 변경, 라이브러리 추가, 도구 업데이트 등 기타 변경
  • revert: 이전 커밋으로 되돌리기
  • merge: 코드 병합
  • sync: 주 브랜치 또는 다른 브랜치로부터 버그 수정 동기화

scope: 변경 범위 (선택 사항)

커밋이 영향을 미치는 범위를 나타냅니다. 데이터 계층, 제어 계층, 뷰 계층 등 프로젝트 특성에 따라 다양할 수 있습니다. 만약 변경 사항이 여러 범위에 영향을 미친다면 *를 사용할 수 있습니다.

스코프는 강제 사항은 아니지만, 팀의 협의에 따라 정의할 수 있습니다. 일반적으로 기술적 관점 또는 비즈니스 모듈 관점으로 나눌 수 있습니다.

  • 기술적 관점: controller, dto, service, dao 등으로 나눌 수 있지만, 하나의 기능이 여러 기술 스코프에 걸쳐 있는 경우가 많아 잘 사용되지 않습니다.
  • 비즈니스 모듈 관점: user, order 등 비즈니스 모듈별로 나누면 어떤 모듈에 변경이 있었는지 쉽게 파악할 수 있어 유용합니다.

subject: 짧은 설명 (필수)

커밋 목적을 간결하게 요약한 설명으로, 50자를 넘지 않도록 합니다. 기술 문서의 대제목이나 기능의 개요 역할을 합니다. 가급적 한글을 사용하여 명확하게 작성하는 것을 권장합니다.

  • 문장 끝에 마침표나 기타 구두점을 사용하지 않습니다.

위의 규칙에 따라 작성된 Git 커밋 메시지 예시:

fix(order): 1원 결제 오류 수정

테스트 팀에서 1원으로 상품을 구매할 수 있는 버그를 발견했으며, 이미 200건의 주문이 발생했습니다.

Closes #2677
[skip ci]

본문 (Body) (선택 사항)

body: 상세 설명

본문은 이번 커밋의 상세 내용을 설명하는 부분으로, 여러 줄로 나눌 수 있습니다.

  • 헤더 다음 두 번째 줄은 반드시 빈 줄이어야 합니다.
  • 코드 변경의 동기와 이전 동작과의 비교를 포함하여 설명합니다.

푸터 (Footer) (선택 사항)

BREAKING CHANGE: 중대한 변경

이전 버전과 호환되지 않는 API 변경 또는 환경 변수 변경과 같은 중대한 변경이 있을 경우 명시합니다.

모든 중대한 변경은 푸터에 BREAKING CHANGE: 키워드로 시작하고, 한 칸 또는 두 개의 줄 바꿈 후 변경에 대한 설명, 변경 이유, 참고 사항을 포함해야 합니다.

BREAKING CHANGE: isolate scope bindings definition has changed and
    the inject option for the directive controller injection was removed.

    To migrate the code follow the example below:

    Before:

    <!-- 이전 코드 예시 -->

    After:

    <!-- 변경 후 코드 예시 -->

    The removed `inject` wasn't generaly useful for directives so there should be no code using it.

Closes: 문제 해결

이번 커밋이 특정 이슈를 해결하는 경우, 푸터에서 해당 이슈를 참조합니다.

Closes 키워드로 시작합니다 (예: Closes #234).

여러 버그를 수정한 경우 쉼표로 구분할 수 있습니다.

Closes #123, #245, #992

skipCi: CI 건너뛰기

CI(Continuous Integration, 지속적 통합)는 코드 변경이 있을 때마다 미리 정의된 빌드, 테스트, 배포 프로세스를 자동으로 실행하여 코드 품질을 보장하는 절차입니다. [skip ci] 옵션을 사용하면 CI 도구에 해당 커밋에 대한 자동 빌드를 건너뛰도록 지시할 수 있습니다. 이는 특정 빌드 위험을 예상했거나 단순히 빌드를 원하지 않을 때 유용합니다.

Revert: 커밋 되돌리기

이전 커밋을 되돌리는 커밋의 경우, 반드시 revert:로 시작하며 그 뒤에 되돌려지는 커밋의 헤더를 명시해야 합니다.

revert: feat(pencil): add 'graphiteWidth' option

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

Git 커밋 메시지 표준화를 위한 도구

위의 규칙들을 모두 기억하기는 번거로울 수 있습니다. 다행히 IDE 확장을 통해 이러한 작업을 쉽게 할 수 있습니다.

  • IntelliJ IDEA: 플러그인 마켓플레이스에서 'git commit message helper'를 검색하여 설치한 후, IDE를 재시작하면 됩니다.
  • VS Code: 'Git-commit-plugin For Vscode' 확장 프로그램을 설치할 수 있습니다.

예시 (플러그인 사용 후 생성된 메시지):

feat(dao): 사용자 저장소 클래스 추가

신규 사용자 데이터 처리를 위한 DAO 계층 클래스 추가
필드 추가: user_id, user_name
기존 필드 삭제: old_field_name

BREAKING CHANGE: 새로운 사용자 관리 API 2.0 적용으로 기존 1.0 API 제거

Closes #1257
[skip ci]

태그: Git Commit Message 컨벤션 개발 워크플로우 코드 품질

7월 14일 00:33에 게시됨

인기 태그

©2026 괴물 클럽