[Git] 알아두면 좋은 git 커밋 메시지 작성법

임재영·2025년 9월 29일

이전 포스팅과 마찬가지로, "우아한프리코스"에서 출제된 지난 회차 문제들을 푸는 과정에서 커밋 메시지 작성법에 대해 새로 알게 되었다.

커밋 메시지를 처음 작성해 보는 분들도 이해할 수 있도록 최대한 쉽고 간단하게 포스팅해 볼 예정이다.

해당 메시지 작성법은 프리코스의 과제 진행 요구 사항에 나와있는 커밋 메시지 컨벤션 가이드를 기반으로 한다.

❓ 커밋 메시지(Commit Message)란?

커밋(Commit)은 우리가 개발을 진행하여 생긴 '변경 사항'을 로컬 레포지토리에 저장(기록)하는 데 사용된다.

(이미지 출처: 예전 git/github 공부 내용)

개발을 마치고 나면 우리는 git add 명령어를 통해 변경된 파일을 스테이징 영역에 임시로 저장한다. 이 과정은 우리가 실수로 커밋에 포함시키고 싶지 않은 파일이나, 일부만 커밋하고 싶을 때 유연하게 관리할 수 있는 커밋 전 최종 검토 단계이다.

스테이징된 파일은 git commit 명령어를 통해 커밋 단계를 거치며 로컬 레포지토리에 반영 되고, 이러한 과정을 통해 변경된 파일이 git에 의해 기록되어 하나의 버전으로써 관리가 된다.

개발 과정에서 우리는 수많은 커밋을 하게 되고, 이는 다른 말로 수많은 변경 사항(버전)이 있다는 것을 의미한다. 우리는 각각의 버전을 구분하고, 변경 사항을 빠르게 이해하기 위해 커밋 시 커밋 메시지를 작성하는 것이다.

특히 커밋 메시지는 원격 레포지토리(github)를 통해 협업할 때 팀원들에게 변경 사항을 쉽고 빠르게 알려줄 수 있는 훌륭한 메모가 된다.

적절한 커밋 메시지 작성의 중요성

위 글에서 보다시피, 수많은 변경 사항에 대해 빠르게 인지하기 위해선 좋은 커밋 메시지가 필수적이다. 그리고 당연하게도 이는 협업 시에 더 큰 장점을 발휘하며 그 중요성 또한 매우 커지게 된다.

적절한 커밋 메시지 규칙이 중요한 이유 :

1. 커뮤니케이션의 효율이 증가한다.

일관적이고 명확한 커밋 메시지는 다른 개발자가 더 쉽게 이해하도록 돕기 때문에 서로의 작업에 대한 이해도를 높이고 프로젝트 관리와 협업에 중요한 역할을 한다.

2. 빠른 문제 해결이 가능하다.

시간이 지남에 따라 전체 코드는 매우 복잡해질 수 있다. 이때 적절한 커밋 메시지 규칙은 프로젝트의 유지 및 보수에 큰 도움이 되며, 나중에 변경할 때 더 쉽게 작업할 수 있도록 돕는다.
또, 좋은 커밋 메시지를 사용하면 코드에서 발생하는 문제를 고치는 과정(디버깅, Debugging)이 훨씬 원활해진다. 문제가 발견되면 개발자는 커밋 메시지를 사용하여 언제 어디서 문제가 발생했는지 빠르게 식별할 수 있다.

3. 변경 사항의 문서화 기능을 한다.

적절한 커밋 메시지 규칙은 전체 코드의 변경 내역을 제공하는 문서 역할을 할 수 있다. 이 기능은 프로젝트를 처음 접하거나 프로젝트에 신속하게 적응해야 하는 개발자에게 특히 유용할 수 있다.

이처럼, 잘 작성한 커밋 메시지는 해당 프로젝트에서 작업하는 다른 개발자와 미래의 자신에게 변경 사항의 배경이나 맥락을 전달하는데 있어 가장 좋은 수단이 된다.

( '적절한 커밋 메시지 작성의 중요성' 내용 참고 : Hailie's InfoGrab Blog )

💡 커밋 메시지 작성법

올바른 커밋 메시지 작성을 위해, Stephen Parish의 "커밋 메시지 컨벤션(Commit Message Conventions)" 가이드를 기반으로 그 규칙을 알아보자.

1️⃣ 커밋 메시지 구조

컨벤션 가이드에 따른 커밋 메시지 작성 구조:

<type>(<scope>): <subject>

<body>

<footer>

type : 변경의 성격을 나타냄 (필수)
scope : 영향을 받은 모듈, 패키지, 도메인 등 (선택)
subject : 간단한 변경 요약 (필수)
body : 상세한 설명, 변경 이유, 동기 (선택)
footer : 이슈 번호, Breaking Change 명시 등 (선택)

우측에 나와있다시피, 선택은 권장사항이지만 타입(type)과 주제(subject)는 필수로 적어야 한다.

커밋 메시지 최소 작성 기준:

<type>: <subject>

커밋 메시지를 처음 보는 분들은 이게 뭔가 싶겠지만, 이후로 보여줄 커밋 메시지 예시를 보면 좀 더 이해하기 쉬울 것이다.

2️⃣ Type 종류

해당 커밋이 무슨 성격인지를 알려주는 태그이다.
이를 보고 개발자들이 "이 커밋은 무슨 목적이구나"하고 한 눈에 알 수 있도록 해준다.

타입	설명
feat	새로운 기능 추가
fix	버그 수정
docs	문서 관련 변경
style	코드 스타일 변경 (포맷팅, 세미콜론 등 기능 변화 없음)
refactor	리팩토링 (기능 추가·수정 아님)
perf	성능 개선
test	테스트 추가/수정
chore	빌드 프로세스, 도구, 라이브러리 변경 등

3️⃣ Subject 규칙

해당 커밋에서 무엇을 했는지, 변경 내용을 간단하게 한 줄로 요약하는 문장이다.
이를 보고 어떤 작업을 했는지 바로 감이 올 수 있도록 작성해야 한다.

제목은 50자를 넘기지 않는다.
마침표를 붙이지 않는다.
현재형으로 작성하며, 명령형으로 쓴다.
대문자로 시작하지 않는다. (영문 작성 시)
본문(body)과 한 줄 띄워 분리한다.

4️⃣ Body 규칙 (선택)

왜 그렇게 수정했는지, 구체적으로 무슨 문제가 있었는지를 적는다.
내용을 읽고, "이런 이유 때문에 바꿨구나"하고 맥락을 이해할 수 있어야 한다.
이는 필수는 아니며, 선택 사항이다.

본문은 72자를 넘기지 않는다.
어떻게(How)보다는 무엇을, 왜(What, Why)에 맞춰서 작성한다.
설명뿐만 아니라, 커밋의 이유를 작성할 때에도 쓴다.

부가 정보/이슈 번호나 큰 변경 사항을 알릴 때 사용한다.
협업 도구(github, jira)와 연결되거나, 중요한 변화임을 명시할 때 필요하다.
이 또한 선택 사항이며, 필수가 아니다.

주로 Clses(종료), Fixes(수정), Resolves(해결), Ref(참고), Related to(관련) 키워드를 사용한다.
해당 커밋과 관련된 이슈 번호를 작성할 때 사용한다.
- 해결: 해당 이슈 해결 시 사용
- 참고: 참고할 이슈가 있는 경우 사용
- 관련: 해당 커밋에 관련된 이슈가 있을 때 사용

📌 실제 커밋 메시지 예시

# 한글 작성 예시

feat(회원): 로그인 기능 추가

사용자 인증을 위한 로그인 API를 구현.
JWT 토큰 발급 및 유효성 검증 로직 포함.

fix(장바구니): 총 가격 계산 오류 수정

이전 로직에서 할인 쿠폰이 반영되지 않았음.
할인 적용된 가격이 총합에 포함되도록 수정.

Closes #101

docs: 설치 및 실행 방법 추가

refactor(게임로직): 점수 계산 알고리즘 단순화

# 영문 작성 예시

feat(auth): add login API

Add new REST endpoint for user authentication.
Handles JWT token generation and validation.

fix(cart): correct total price calculation

The previous logic didn’t include discount coupons.
Now total includes discounts properly.

Closes #42

정리

커밋 메시지를 올바른 규칙에 따라 작성하는 것은 본인은 물론이고, 팀원들과의 협업에서도 매우 유용하게 활용된다. 그런 만큼 기본적인 작성 원칙이나 해당 팀에서 정한 커밋 메시지 규칙에 잘 맞도록 작성하는 것이 매우 중요하다.

임재영

이전 포스트

[개발] 기능 목록 작성

다음 포스트

[우아한테크코스 8기] 프리코스 1주차 회고

1개의 댓글

전민경

2026년 4월 4일

쉽게 이해가 덜 된채 넘어갈 수 있는 부분을 정확히 집고 넘어가서 자세하게 파악 할 수 있었던 것 같아요!! 좋은 글 감사합니다~

답글 달기