좋은 Git 커밋 메시지 작성법

좋은 Git 커밋 메시지 작성법: 개발자를 위한 완벽 가이드

왜 커밋 메시지가 중요할까요?

여러분의 프로젝트 Git 로그를 한번 살펴보세요. 아마 이런 커밋 메시지들을 발견하실 겁니다:

버그 수정
코드 정리함
업데이트
오타 수정
급한 수정

반면, 잘 관리된 프로젝트의 커밋 로그는 이렇게 생겼습니다:

사용자 인증 모듈의 메모리 누수 문제 해결
상품 목록 API에 페이지네이션 기능 추가
더 이상 사용하지 않는 결제 게이트웨이 연동 코드 제거
사용자 프로필 유효성 검사 규칙 업데이트

어떤 게 더 읽기 좋고 유용한가요? 두 번째 예시죠.

좋은 커밋 메시지는 단순히 기록이 아닙니다. 팀원들과의 소통 수단이자, 미래의 나 자신을 위한 메모입니다. 코드 변경 내역(diff)은 '무엇이' 바뀌었는지 보여주지만, 커밋 메시지만이 '왜' 바뀌었는지 제대로 설명할 수 있습니다.

좋은 커밋 메시지의 7가지 규칙

1. 제목과 본문은 빈 줄로 구분하기

나쁜 예:

로그인 버그 수정
세션 타임아웃 문제로 사용자들이 자꾸 로그아웃되는 현상 해결

좋은 예:

로그인 시스템의 세션 타임아웃 버그 수정

사용자들이 15분마다 자동 로그아웃되는 문제를 수정했습니다.
세션 만료 시간을 30분에서 2시간으로 변경하고,
'로그인 상태 유지' 옵션 선택 시 7일간 유지되도록 개선했습니다.

빈 줄 하나가 git log --oneline이나 git shortlog 같은 명령어가 제대로 작동하게 만듭니다.

2. 제목은 50자 이내로 제한하기

50자는 엄격한 제한이 아니라 가이드라인입니다. 이 길이는 가독성을 보장하고, 핵심만 간결하게 전달하도록 유도합니다.

팁: 요약하기 어렵다면 한 번에 너무 많은 변경을 커밋하는 건 아닌지 확인해보세요!

GitHub은 50자를 넘으면 경고를 표시하고, 72자가 넘으면 말줄임표(...)로 잘라버립니다.

3. 제목 첫 글자는 대문자로

좋은 예:

사용자 프로필 이미지 업로드 기능 추가

나쁜 예:

사용자 프로필 이미지 업로드 기능 추가

간단하지만 일관성 있는 로그를 만드는 기본입니다.

4. 제목 끝에 마침표 금지

제목 줄에서는 공간이 귀중합니다. 불필요한 마침표는 생략하세요.

좋은 예:

다크 모드 테마 구현

나쁜 예:

다크 모드 테마 구현.

5. 제목은 명령형으로 작성하기

이게 가장 헷갈리는 부분일 수 있습니다. 명령형이란 "~하라", "~하세요"처럼 명령이나 지시를 내리는 어조입니다.

좋은 예:

데이터베이스 연결 로직 리팩토링
API 문서 업데이트
사용하지 않는 의존성 제거

나쁜 예:

로그인 버그를 수정했습니다 (과거형)
홈페이지 디자인을 업데이트하는 중 (진행형)
알림 기능을 위한 새로운 기능 (명사형)

간단한 테스트 방법: 제목이 이 문장을 완성할 수 있어야 합니다:

"이 커밋을 적용하면, [여기에 제목] 할 것입니다"

예시:

• ✅ 이 커밋을 적용하면, 데이터베이스 연결 로직을 리팩토링 할 것입니다
• ✅ 이 커밋을 적용하면, API 문서를 업데이트 할 것입니다
• ❌ 이 커밋을 적용하면, 로그인 버그를 수정했습니다 할 것입니다 (어색함!)

Git 자체가 명령형을 사용합니다:

feature/payment 브랜치 병합
"실험적 기능 추가" 커밋 되돌리기

우리도 Git의 컨벤션을 따르는 겁니다.

6. 본문은 72자마다 줄바꿈

Git은 자동으로 텍스트를 줄바꿈하지 않습니다. 본문 작성 시 직접 줄을 나눠야 합니다.

72자 기준을 추천하는 이유는 Git이 텍스트를 들여쓰기해도 전체적으로 80자 내에 유지되기 때문입니다.

Vim 같은 텍스트 에디터를 설정하면 자동으로 72자마다 줄바꿈이 가능합니다.

7. 본문에는 '무엇을', '왜'를 설명 ('어떻게'는 X)

훌륭한 예시:

사용자 인증 플로우 단순화

기존 인증 시스템이 3단계 검증으로 복잡했고, 평균 로그인 시간이
5초 이상 걸렸습니다. 

이번 커밋에서는:
- 불필요한 중복 검증 단계를 제거
- JWT 토큰 유효성 검사를 한 번만 수행하도록 변경
- 캐싱을 도입하여 반복 검증 최소화

결과적으로 로그인 시간이 평균 1.5초로 단축되었고,
서버 부하도 30% 감소했습니다.

이슈 해결: #245

코드 자체가 '어떻게' 구현했는지 보여줍니다. 커밋 메시지는 왜 이 방식을 선택했는지, 어떤 문제를 해결했는지에 집중하세요.

실전 예시: 한국 스타트업 시나리오

예시 1: 기능 추가

카카오톡 소셜 로그인 연동 추가

기존에는 이메일/비밀번호 회원가입만 지원하여 전환율이 낮았습니다.
(가입 완료율 약 35%)

카카오톡 소셜 로그인을 추가하여:
- 사용자가 2초 만에 가입 가능
- 국내 사용자의 95% 이상이 보유한 카카오톡 계정 활용
- 별도 비밀번호 관리 부담 제거

A/B 테스트 결과 전환율이 68%까지 상승했습니다.

관련 이슈: #156

예시 2: 버그 수정

삼성 인터넷 브라우저에서 결제 실패 문제 수정

삼성 인터넷 브라우저에서 결제 실패율이 23%로 매우 높았습니다.
원인은 폴리필(Polyfill)이 누락되어 Promise 객체가 제대로 작동하지 
않는 것이었습니다.

core-js 폴리필을 추가하고 삼성 인터넷 11+ 버전을
명시적으로 지원하도록 babel 설정을 업데이트했습니다.

QA 테스트 결과 삼성 인터넷에서의 결제 성공률이 97%로 개선되었습니다.

버그 수정: #892

예시 3: 성능 개선

상품 목록 조회 쿼리 성능 최적화

상품 목록 페이지 로딩이 평균 4.2초로 느려 이탈률이 높았습니다.

개선 사항:
- N+1 쿼리 문제 해결 (join 활용)
- 자주 조회되는 카테고리 정보를 Redis에 캐싱
- 불필요한 연관 데이터 로딩 제거 (지연 로딩)
- 페이지네이션 인덱스 최적화

결과: 평균 로딩 시간 0.8초로 단축 (81% 개선)

참고: #445, #467

자주 하는 실수들

❌ 나쁜 커밋 메시지들

수정
업데이트
버그 수정
코드 정리
작업중
테스트
ㅁㄴㅇㄹ
급함

✅ 개선된 버전

주문 처리 중 널 포인터 예외 수정
테스트 용이성을 위한 결제 모듈 리팩토링
더 이상 사용하지 않는 API 엔드포인트 제거 (버전 1.0)
사용자 회원가입 폼에 입력 유효성 검사 추가

커밋 메시지 작성 체크리스트

커밋하기 전에 이 질문들을 스스로에게 던져보세요:

1. 제목만 봐도 무슨 변경인지 알 수 있나요?
2. 왜 이 변경이 필요했는지 설명했나요?
3. 6개월 뒤 내가 봐도 이해할 수 있을까요?
4. 새로 합류한 팀원이 봐도 맥락을 이해할 수 있을까요?
5. 명령형 문장인가요? (테스트: "이 커밋을 적용하면 ___ 할 것입니다")

실용적인 팁

커맨드 라인 활용하기

IDE의 커밋 도구보다 터미널에서 직접 커밋하는 것을 추천합니다:

# 간단한 커밋
git commit -m "사용자 이메일 인증 기능 추가"

# 본문이 필요한 커밋 (에디터 열림)
git commit

# 특정 에디터 사용
git config --global core.editor "code --wait"  # VS Code

커밋 템플릿 만들기

매번 형식을 고민하기 싫다면 템플릿을 만드세요:

# ~/.gitmessage.txt 파일 생성
# [타입]: 50자 이내 제목
#
# 무엇을, 왜 변경했는지 설명
# - 이전 상황
# - 변경 내용
# - 예상 효과
#
# 이슈 해결: #이슈번호

# 템플릿 설정
git config --global commit.template ~/.gitmessage.txt

커밋 수정하기

이미 커밋했는데 메시지를 고치고 싶다면:

# 마지막 커밋 메시지 수정
git commit --amend

# 이미 push한 경우 (조심해서 사용!)
git push --force-with-lease

마치며

좋은 커밋 메시지는 습관입니다. 처음엔 번거롭게 느껴지지만, 곧 자연스러워지고 결국엔 팀 전체의 생산성을 높이는 강력한 도구가 됩니다.

오늘부터 시작해보세요. 모든 규칙을 완벽히 따르려 하지 말고, 한 가지씩 개선해나가면 됩니다. 가장 먼저 "명령형 제목" 규칙부터 적용해보는 건 어떨까요?

---

참고 자료:

• Pro Git 책 (한국어판)
• Conventional Commits (한국어)