6개월 전, 당신이 만들었던 기능에서 치명적인 버그가 발견되었습니다. 원인을 찾기 위해 Git 히스토리를 뒤져 문제의 코드를 찾아냈습니다. 떨리는 마음으로 git blame을 실행해 어떤 커밋이 이 코드를 수정했는지 확인합니다. 화면에 뜬 커밋 메시지: "수정". 🤯
"대체 뭘... 왜 수정한 거지?" 당신은 아무런 단서도 얻지 못한 채, 수백 줄의 코드를 처음부터 다시 분석해야 하는 절망적인 상황에 빠집니다.
이처럼, 좋은 커밋 메시지는 단순히 변경 사항을 기록하는 행위를 넘어, 미래의 나 자신과 동료들을 위한 가장 친절한 설명서이자 선물입니다. 오늘은 '대충' 쓰는 커밋 메시지를 '제대로' 쓰는 7가지 구체적인 팁으로 바꿔보겠습니다.
좋은 커밋 메시지의 구조: 제목, 본문, 꼬리말
전문적으로 관리되는 오픈 소스 프로젝트들은 대부분 다음과 같은 구조로 커밋 메시지를 작성합니다.
타입: 제목 (50자 이내)
본문 (어떻게 보다는 '왜' 변경했는지 상세히 설명)
꼬리말 (이슈 트래커 번호 등)
✍️ 디테일 팁 7가지
1. 제목은 '명령문'으로, 동사 원형으로 시작하세요.
가장 중요하고 기본적인 규칙입니다. "내가 이렇게 했다"가 아니라, "이 커밋은 이렇게 한다"는 관점에서 작성하세요.
- ❌ Bad: Fixed login bug, Adding new feature
- ✅ Good: Fix: 로그인 폼 유효성 검사 버그 수정, Feat: 사용자 프로필 이미지 업로드 기능 추가
Tip: Git이 커밋을 합칠 때 Merge commit '...' 이라고 명령문을 사용하는 것을 떠올려보세요. 당신의 커밋 메시지도 Git의 관례를 따르는 것이 좋습니다.
2. 제목에 '타입(Type)'을 명시하여 의도를 보여주세요.
제목 가장 앞에 변경 사항의 성격을 나타내는 타입을 붙이면, 커밋 히스토리만 훑어봐도 어떤 종류의 작업이었는지 즉시 파악할 수 있습니다. (AngularJS 커밋 규칙에서 유래)
- Feat: 새로운 기능 추가
- Fix: 버그 수정
- Docs: 문서 수정
- Style: 코드 포맷팅, 세미콜론 누락 등 (코드 로직 변경 없음)
- Refactor: 코드 리팩토링
- Test: 테스트 코드 추가/수정
- Chore: 빌드 관련 파일 수정 등 (프로덕션 코드 변경 없음)
3. 제목은 50자 이내로, 마침표는 찍지 마세요.
제목은 커밋을 요약하는 헤드라인입니다. 간결함을 유지해야 GitHub이나 다른 Git 도구에서 줄바꿈 없이 깔끔하게 보입니다.
4. 제목과 본문 사이에는 반드시 한 줄을 비워두세요.
이는 Git이 제목과 본문을 명확하게 구분하기 위한 규칙입니다. 이 한 줄을 비우지 않으면 많은 Git 도구들이 전체를 제목으로 인식해버릴 수 있습니다.
5. 본문에는 '어떻게'가 아닌 '왜'를 설명하세요.
'어떻게' 코드를 바꿨는지는 코드 변경 내역(git diff)을 보면 알 수 있습니다. 커밋 메시지의 본문은 왜 이 변경이 필요했는지, 어떤 문제를 해결하기 위함인지, 이전에는 어떤 문제가 있었는지와 같은 맥락(Context) 을 설명하는 데 집중해야 합니다.
6. 본문은 한 줄에 72자 내외로 줄바꿈 해주세요.
이는 터미널이나 다양한 Git UI 도구에서 가독성을 최상으로 유지하기 위한 오래된 관례입니다. 긴 문장을 적절히 줄바꿈하면 동료들이 훨씬 편안하게 메시지를 읽을 수 있습니다.
7. 꼬리말(Footer)을 활용하여 이슈를 연결하세요.
만약 이 커밋이 특정 이슈(Jira, GitHub Issue 등)와 관련이 있다면, 꼬리말에 이슈 번호를 적어주세요. 이렇게 하면 이슈 트래커에서 자동으로 해당 커밋을 링크해 주어 추적성이 극대화됩니다.
- Closes #123: 이 커밋이 123번 이슈를 해결하고 종료시킴을 의미.
- Refs #456: 456번 이슈를 참고했다는 의미.
좋은 예시 vs 나쁜 예시
- ❌ 나쁜 예시
-
버그 수정함 - ✅ 좋은 예시
-
Fix: 주문 취소 시, 특정 조건에서 환불 금액이 누락되는 문제 해결 기존에는 할인 쿠폰이 적용된 주문을 취소할 경우, 환불 로직에서 쿠폰 할인액을 제대로 계산하지 못하는 버그가 있었습니다. 이로 인해 사용자에게 실제 결제액보다 적은 금액이 환불되는 치명적인 문제가 발생할 수 있었습니다. 주문 취소 서비스의 환불 금액 계산 로직에 쿠폰 할인액을 다시 포함하도록 수정하여 이 문제를 해결했습니다. Closes: #789
마치며
좋은 커밋 메시지를 작성하는 것은 몇 초의 시간을 더 쓰는 사소한 습관처럼 보일 수 있습니다. 하지만 이 작은 습관이 쌓여, 6개월 뒤 원인 모를 버그 앞에서 절망하고 있을 미래의 당신을 구하고, 동료들에게는 신뢰감을 주는 훌륭한 개발자로 만들어 줄 것입니다. 🎁