[Git] Commit Message Convention
난잡한 커밋 메시지를 줄이고 협업 탐색성을 높이기 위한 Git Commit Message Convention 정리
깃을 이용해 작업을 하다 보면 특정 시점으로 checkout을 할 때 난잡한 커밋을 일일이 클릭해 가면서 변경 내역을 찾는 일이 종종 있습니다.
보통 한눈에 알아보기 쉽게 작성하는 것이 Commit Message인데, 규칙 없이 작성하면 알아보기 어렵습니다.
이 문제를 보완하기 위해 찾다가 발견한 것이 Git Commit Message Convention입니다.
예시
나쁜 예시
과거에 자주 사용했던 어처구니없는 커밋 메시지 예시입니다.
위 스크린샷의 Backup-20231207, For Test 같은 메시지는
어떤 파일을 수정했는지, 왜 바꿨는지, 지금 되돌려도 되는 변경인지 파악하기 어렵습니다.
좋은 예시
아래는 Seal Repository의 커밋 메시지 예시입니다.
예를 들어 아래와 같은 형태입니다.
feat : action sheet style tweak
fix : remove hardcoded user shared directory
docs(readme) : update sponsor info
커밋 메시지만 봐도 어떤 의도로 무엇을 바꿨는지 대략 파악할 수 있습니다.
구조
Type : Subject
body(필요 시 작성)
footer(필요 시 작성)
제목(Title)
Type(유형)
Type은 변경 사항을 대략 표현하며 보통 아래와 같은 분류를 사용합니다.
| Type | 내용 |
|---|---|
| feat | 새로운 기능(feature) 추가 |
| fix | 버그 수정 |
| docs | 문서 변경(README, API 문서 등) |
| style | 코드 포맷팅, 세미콜론 누락 수정 등(코드 로직 변경 없음) |
| refactor | 운영 코드 리팩토링(성능 개선, 가독성 향상 등) |
| test | 테스트 코드 추가 또는 기존 테스트 리팩토링(운영 코드 변경 없음) |
| chore | 빌드 시스템, 패키지 매니저 설정 변경 등(운영 코드 변경 없음) |
필요하다면 팀 내 합의를 통해 추가 타입을 정의할 수 있습니다.
Subject(제목 요약)
- 영문 기준 50자 이내로 간결하게 작성합니다.
- 첫 글자는 대문자로 시작합니다.
- 문장 끝에 마침표(
.)는 사용하지 않습니다. - 가능하면 명령형으로 작성합니다.
본문(Body) - 선택사항
제목만으로 설명이 부족해 추가 설명이 필요한 경우 사용합니다.
- 제목과 본문 사이에는 반드시 빈 줄 한 줄을 둡니다.
- 각 줄의 길이는 영문 기준 72자 이내를 권장합니다.
- 변경을 통해 해결하려는 문제와 부수 효과를 설명하는 공간으로 사용합니다.
푸터(Footer) - 선택사항
이슈 트래커 ID를 참조하거나 추가 정보를 적을 때 사용합니다.
- 특정 이슈를 해결한 경우:
Resolves: #123 - 여러 이슈를 참조하는 경우:
See also: #456, #678
커밋 메시지 예시
feat: 사용자 정보 조회 API 엔드포인트 추가 (GET /api/v1/users/{id})
특정 사용자의 상세 정보를 조회할 수 있는 RESTful API 엔드포인트를 구현합니다.
이 기능은 클라이언트 애플리케이션에서 사용자 프로필 화면을 표시하는 데 사용됩니다.
이번 커밋을 통해 사용자는 자신의 ID를 통해 시스템에 등록된 개인 정보를
안전하게 조회할 수 있게 됩니다.
주요 변경 사항:
- `GET /api/v1/users/{id}` 엔드포인트 신규 생성
- `UserController`에 `getUserById` 메소드 추가
- `UserService`에 사용자 ID 기반 조회 로직 구현
- 사용자 정보를 담는 `UserResponseDto` DTO 클래스 정의
- 존재하지 않는 사용자 ID 요청 시 404 Not Found 응답 처리 로직 추가
이 API는 향후 사용자 정보 수정 및 삭제 기능의 기반이 될 것입니다.
또한, 현재는 기본적인 정보만을 반환하며, 추가적인 상세 정보(예: 활동 내역)는
별도의 엔드포인트로 분리하거나 요청 파라미터를 통해 선택적으로 제공하는 방안을
고려 중입니다.
데이터베이스 조회 시 발생할 수 있는 예외 상황에 대한 기본적인 오류 처리 로직을
포함하고 있습니다. 성능 최적화를 위한 캐싱 전략은 추후 적용 예정입니다.
Resolves: #USR-101 (사용자 상세 정보 조회 기능 구현)
See also: #ARC-005 (API Naming Convention), #SEC-012 (API 접근 권한 논의)
마치며
최근에 친구와 게임 개발을 시작하면서 Git Commit Message Convention을 전파한 적이 있습니다.
전파하기 전에도 내용을 요약하여 커밋 메시지를 작성하던 친구였지만,
한국어의 특성상 서술어가 뒤에 오기 때문에 Type이 앞에 붙는 것만으로도
탐색이 훨씬 쉬워졌던 것 같습니다.
Body나 Footer는 필수가 아니니, Title만으로도 쉽게 알아볼 수 있는 커밋 메시지를 작성해
협업에 도움이 되었으면 좋겠습니다.