Waylog Blog

좋은 커밋 메시지 작성하는 법 (Conventional Commits)

Git

우리는 왜 커밋 메시지를 작성할까요? 단순히 "저장"하기 위해서가 아닙니다. 커밋 메시지는 협업을 위한 대화이고, 과거의 나에게서 미래의 나에게 보내는 편지입니다. "fixed bug", "update" 같은 무의미한 메시지가 가득한 Git 로그는, 버그가 발생했을 때 범인을 찾기 어렵게 만들고 프로젝트의 역사를 불투명하게 만듭니다.

전 세계적으로 가장 널리 쓰이는 커밋 규칙인 Conventional Commits를 소개합니다.

1. 기본 구조

커밋 메시지는 크게 Header, Body, Footer 세 부분으로 나뉩니다.

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

<body>

<footer>

2. Type (필수)

어떤 종류의 변경인지 명확히 알립니다.

  • feat: 새로운 기능 추가 (사용자에게 영향을 미침)
  • fix: 버그 수정 (사용자에게 영향을 미침)
  • docs: 문서 수정 (README, 주석 등)
  • style: 코드 포맷팅, 세미콜론 누락 등 (로직 변경 없음)
  • refactor: 리팩터링 (기능 추가나 버그 수정이 아님)
  • test: 테스트 코드 추가, 수정
  • chore: 빌드 업무 수정, 패키지 매니저 설정 등 (소스 코드 변경 없음)

3. Subject (필수)

제목은 50자 이내로, 명령문(Imperative mood)으로 작성합니다.

  • Good: "Add login page" (로그인 페이지 추가하라 -> 추가)
  • Bad: "Added login page" (과거형), "Adding login page" (진행형)

4. Body (선택)

왜 수정했는지, 무엇을 수정했는지 구체적으로 적습니다. "어떻게"는 코드를 보면 알 수 있습니다.

  • "로그인 시 세션이 만료되는 문제를 해결함"
  • "UserAPI의 리턴 타입을 DTO로 변경하여 일관성 확보"

5. 실무 팁

  • Git Hooks 활용: Husky 같은 도구를 써서, 커밋할 때 자동으로 메시지 형식을 검사(commitlint)하거나 린트를 돌리는 것이 좋습니다."실수할 기회를 주지 않는 것"이 가장 좋은 규칙입니다.
  • 작은 커밋 권장: 커밋 하나가 하나의 논리적 단위여야 메시지를 쓰기도 쉽습니다. feat: 버튼 추가와 fix: API 에러 수정이 한 커밋에 섞여 있으면 제목을 정하기 어렵습니다.

좋은 커밋 메시지는 동료 개발자의 출근길 기분을 낫게 해줍니다.