Git 커밋 메시지 컨벤션

Git 커밋 메시지 컨벤션은 커밋 메시지의 형식과 어휘를 팀 차원에서 통일하는 규칙이다. 잘 정리된 커밋 메시지는 코드 리뷰와 디버깅에서 변경 의도를 빠르게 파악하게 해 주고, 컨벤셔널 커밋(Conventional Commits)처럼 기계가 읽을 수 있는 형식을 따르면 체인지로그(changelog) 생성과 버전 관리까지 자동화할 수 있다. 핵심은 제목 한 줄로 무엇을 했는지 드러내고, 본문에서 왜 그렇게 했는지 설명하는 것이다.

커밋 메시지가 중요한 이유

커밋 메시지는 코드에 남길 수 없는 맥락을 기록하는 유일한 공식 통로다. 코드 자체는 무엇이 바뀌었는지 보여 주지만, 왜 그렇게 바꿨는지, 어떤 대안을 검토했다가 버렸는지는 보여 주지 못한다. 몇 달 뒤 git blame이나 git log로 이력을 추적할 때, 좋은 커밋 메시지는 당시의 의사 결정을 그대로 복원해 준다.

또한 커밋 단위가 잘 쪼개져 있고 메시지가 명확하면 리뷰어는 커밋을 따라가며 변경을 이해할 수 있고, 문제가 생겼을 때 git revert로 특정 변경만 안전하게 되돌릴 수 있다. 버그가 언제 유입되었는지 이분 탐색으로 찾아 주는 git bisect도 커밋이 논리적 단위로 나뉘어 있을 때 제 성능을 낸다. 반대로 "수정", "fix bug" 같은 메시지가 쌓이면 이력은 검색할 수 없는 잡음이 되고, 되돌리기와 원인 추적 모두 어려워진다.

좋은 커밋의 단위는 하나의 논리적 변경이다. 기능 추가와 무관한 포매팅 변경을 한 커밋에 섞으면 리뷰어가 실제 변경을 골라내기 어려워지므로, 관련 없는 변경은 커밋을 나누고 필요하면 git add -p로 파일의 일부만 스테이징해서 단위를 다듬는다.

메시지의 기본 구조

커밋 메시지는 제목(subject), 본문(body), 꼬리말(footer)의 세 부분으로 구성하며 각 부분은 빈 줄로 구분한다. 널리 통용되는 작성 규칙은 다음과 같다.

• 제목은 50자 안팎으로 짧게 쓰고 끝에 마침표를 찍지 않는다.
• 제목과 본문 사이에는 반드시 빈 줄을 하나 둔다. 많은 도구가 첫 줄만 요약으로 취급하기 때문이다.
• 본문은 72자 정도에서 줄바꿈하고, 무엇을 왜 바꿨는지 설명한다. 어떻게 바꿨는지는 코드가 보여 주므로 반복하지 않는다.
• 꼬리말에는 이슈 번호 참조나 호환성이 깨지는 변경(breaking change) 안내를 적는다.

영어로 쓸 때는 제목을 명령형 현재 시제로 쓰는 관례가 있다. "Added feature"가 아니라 "Add feature"로 쓰는데, 이는 "이 커밋을 적용하면 무엇을 한다"라는 문장으로 자연스럽게 읽히게 하기 위해서다. 한국어 팀이라면 "로그인 실패 시 재시도 로직 추가"처럼 명사형으로 끝내거나 팀이 정한 문체를 일관되게 유지하면 된다.