커밋 메시지 규칙

관련 STEP: STEP 03 커밋과 이력 기록

커밋 메시지는 나중에 이력을 읽는 사람에게 변경 이유를 전달한다. git log --oneline에서는 제목만 보이므로 제목이 모호하면 어떤 커밋인지 찾기 어렵다. 이 부록은 수업에서 바로 쓸 수 있는 일반적인 작성 규칙만 정리한다.

학습 목표

• 제목과 본문의 역할을 구분한다.
• 제목을 50자 안팎의 요약형으로 쓴다.
• 본문에 무엇을 왜 바꿨는지 적는다.
• 대표 접두어를 변경 성격에 맞게 고른다.

왜 필요한가

시간이 지나면 코드보다 변경 이유를 기억하기 어렵다. 제목만 수정이나 업데이트로 남기면 나중에 이력을 검색해도 어떤 작업이었는지 알 수 없다. 제목과 본문을 나누어 적으면 동료가 리뷰할 때도 변경 범위를 빠르게 파악할 수 있다.

핵심 개념

• 제목은 한 줄로 쓴다. 50자 안팎을 넘기지 않는다.
• 제목은 고쳤다보다 고친다처럼 현재형·요약형으로 쓴다. 영어권 관례에서는 명령형(Fix)을 쓴다.
• 제목 끝에 마침표를 찍지 않는다.
• 제목과 본문 사이에는 빈 줄을 하나 둔다. Git은 이 빈 줄을 기준으로 제목과 본문을 나눈다.
• 본문에는 무엇을 바꿨고 왜 바꿨는지 적는다. 어떻게 바꿨는지는 diff로 확인할 수 있으므로 길게 쓰지 않는다.
• 접두어는 변경 성격을 드러내는 짧은 단어다. 접두어: 제목 형태로 쓴다.
• 한 커밋에는 한 가지 변경을 담는다. 여러 변경이 섞이면 제목도 모호해진다.
• 팀이나 저장소에 정한 규칙이 있으면 그 규칙을 먼저 따른다.

대표 접두어

접두어	뜻	예
feat	새 기능이나 화면 추가	feat: 로그인 화면 추가
fix	버그나 깨진 동작 수정	fix: 모바일 메뉴 겹침 수정
docs	문서·설명 수정	docs: 설치 순서 보완
style	동작을 바꾸지 않는 스타일·형식 변경	style: 버튼 색상 통일
refactor	동작을 바꾸지 않는 코드 구조 개선	refactor: 저장소 목록 조회 분리
test	테스트 추가·수정	test: 로그인 실패 경우 추가
chore	설정·도구·기타 작업	chore: .gitignore 추가

작성 예시

feat: 로그인 실패 메시지 추가

로그인에 실패했을 때 이유를 알 수 없어 다시 시도하는 경우가 많았다.
실패 원인을 화면에 표시해 사용자가 다음 행동을 고를 수 있게 했다.

• 첫 줄은 제목이다. 무엇을 했는지 한눈에 보인다.
• 빈 줄 뒤의 두 줄은 본문이다. 무엇이 문제였고 왜 바꿨는지 적었다.
• 수정, 업데이트, ㅇㅇ처럼 짧기만 한 제목은 피한다.

접두어와 내용이 있는 제목은 git log --oneline에서 무엇을 바꿨는지 바로 읽힌다.

update, fix, wip처럼 짧기만 한 제목은 이력만 봐서는 변경 내용을 알 수 없다.

체크리스트

• 제목이 50자 안팎으로 짧다.
• 제목만 읽어도 변경 내용을 알 수 있다.
• 제목과 본문 사이에 빈 줄이 있다.
• 본문에 무엇을 왜 바꿨는지 적었다.
• 접두어가 변경 성격과 맞다.
• git log --oneline에서 제목이 읽힌다.

주의할 점

• 제목에 마침표를 찍지 않는다.
• 수정, 업데이트처럼 범위가 넓은 말만 쓰지 않는다.
• 본문에 코드 전체를 붙이지 않는다. 코드는 diff에 남는다.
• 한 커밋에 서로 다른 변경을 섞지 않는다.
• 비밀번호, 토큰, 개인정보를 커밋 메시지에 쓰지 않는다.
• 자동 생성 메시지를 그대로 쓰기 전에 내용이 맞는지 확인한다.

복습 퀴즈

1. 제목과 본문 사이에는 을 하나 둔다.
2. 버그를 고친 커밋에 붙이는 대표 접두어는 이다.
3. 커밋 이력을 한 커밋당 한 줄로 요약해 보는 명령은 이다.

참고 자료

• Conventional Commits (한국어)
• Chris Beams, How to Write a Git Commit Message
• Git 공식 문서 git-commit