개요
프로젝트를 개발하다 보면 수많은 커밋을 남기게 되는데, 일관성 없는 커밋 메시지는 나중에 되돌아보면 변경 사항을 파악하기 어렵게 만든다. 처음에는 별 문제가 없어 보여도, 시간이 지나면서 "이 커밋이 정확히 어떤 내용이지?" 라며 과거의 나를 원망하게 될 때가 많았다.
이런 문제를 해결하기 위해 찾아보니 'Git 커밋 컨벤션' 이라는 개념이 있다는걸 알게 되었고 더 체계적으로 커밋을 관리할 수 있도록 정리해 두고자 이 글을 작성하게 되었다.
Git 커밋 메시지 기본 형식
<타입>: <제목>
<본문>
<Footer>
- 타입: 어떤 변경사항인지 나타내는 키워드
- 제목: 짧고 간결하게 변경 사항 요약 (최대 50자 권장)
- 본문: 변경 이유와 상세 내용
- Footer: 관련된 이슈 번호 (#이슈번호), 추가 정보 등
대표적인 커밋 타입
| 타입 | 설명 |
| feat | 새로운 기능 추가 |
| fix | 버그 수정 |
| test | 테스트 코드 추가/수정 |
| chore | 빌드, 설정 파일 수정 (CI/CD, 패키지 업데이트 등) |
| refactor | 코드 리팩토링 (기능 변화 없음) |
| perf | 성능 개선 |
| docs | 문서 (readme 등) 수정 |
| style | 코드 스타일 변경 (포맷, 세미콜론 추가 등) |
| revert | 이전 커밋 되돌리기 |
💡 코드를 수정하였을 때, fix와 refactor 중에 어떤거를 써야할지 고민이 될 때가 많았다. 어떤 기준점으로 두 커밋 메시지를 나눠야할까?
- fix: 버그를 수정할 때 사용한다. - 기능이 잘못 동작하거나, 예외가 발생하는 문제를 해결할 때 사용한다.
- refactor: 코드 리팩토링 시 사용한다. - 기능 변화 없이 코드 구조만 개선할 때 사용한다.
-> 실제 버그를 수정하였을 때는 fix를 사용하고, 기능에 영향을 주지 않고 구조만 개선한 경우에는 refactor를 사용하자.
예시 커밋 메시지
- feat (새로운 기능 추가)
feat: 운동 기록 저장 기능 추가
운동한 날짜, 운동 종류, 중량, 세트 수를 입력 받아 저장하는 기능을 추가함.
- fix (버그 수정)
fix: 운동 기록 저장 시 날짜 형식 오류 수정
운동 기록을 저장할 때 'yyyy-MM-dd' 형식이 아닌 경우 예외가 발생하도록 수정함
추가 컨벤션 (옵션)
더 체계적으로 커밋 메시지를 관리하고 싶으면, 확장해서 사용할 수 있다.
1. 제목의 범위(scope) 추가하기
'타입(범위): 제목' 형태로 작성하면, 어떤 기능과 관련된 변경인지 알기 쉽다.
feat(exercise): 운동 기록 저장 기능 추가
fix(auth): 로그인 인증 오류 수정
2. 본문을 자세히 작성하기
본문을 추가하면 변경 이유와 상세 내용을 기록할 수 있어서 나중에 커밋 메시지를 확인할 때 더 이해하기가 쉽다.
feat(exercise): 운동 기록 조회 기능 추가
운동 기록을 날짜별로 조회할 수 있는 API를 추가함.
- GET/exercise/list 엔드포인트 추가
- 날짜 범위를 지정하여 검색조건 필터링 가능
3. 관련 이슈 번호 작성하기
이슈 트래커(GitHub Issues, Jira 등)를 사용할 결우 관련 이슈 번호를 남길 수 있다.
fix: 운동 기록 삭제 시 발생하는 버그 수정
운동 기록 삭제 시, 연관된 데이터가 삭제되지 않는 문제 수정
Closes #15
결론
팀원들과 협업할 때 뿐만 아니라 혼자 작업할 때도 아래 규칙을 지켜서 커밋을 깔끔하게 관리하는 습관을 가지면 좋을 것 같다.
커밋 내역이 잘 정리 되어있으면 나중에 변경 사항을 추적할 때도 훨씬 수월해진다..
- 커밋 타입을 명확하게 지정한다. (feat, fix, refactor, docs, chore 등)
- 제목은 50자 이내로 작성한다.
- 본문 작성 시, 변경 이유와 상세 설명을 포함한다.
- 이슈 번호가 있다면 Closes #번호 또는 Refs #번호 를 추가한다.
작은 습관이 쌓여서 더 나은 개발자로 성장할 수 있기를 바라면서, 앞으로는 깔끔하고 의미 있는 커밋을 남기는 습관을 가져보자. 💪