# 커밋 메시지 규칙

> 제목·본문·접두어로 읽기 쉬운 커밋 메시지를 작성한다.

관련 STEP: [STEP 03 커밋과 이력 기록](https://echo.qus0in.dev/git/03-commit-history.md)

커밋 메시지는 나중에 이력을 읽는 사람에게 변경 이유를 전달한다. `git log --oneline`에서는 제목만 보이므로 제목이 모호하면 어떤 커밋인지 찾기 어렵다. 이 부록은 수업에서 바로 쓸 수 있는 일반적인 작성 규칙만 정리한다.

## 학습 목표

- 제목과 본문의 역할을 구분한다.
- 제목을 50자 안팎의 요약형으로 쓴다.
- 본문에 무엇을 왜 바꿨는지 적는다.
- 대표 접두어를 변경 성격에 맞게 고른다.

## 왜 필요한가

시간이 지나면 코드보다 변경 이유를 기억하기 어렵다. 제목만 `수정`이나 `업데이트`로 남기면 나중에 이력을 검색해도 어떤 작업이었는지 알 수 없다. 제목과 본문을 나누어 적으면 동료가 리뷰할 때도 변경 범위를 빠르게 파악할 수 있다.

## 핵심 개념

- 제목은 한 줄로 쓴다. 50자 안팎을 넘기지 않는다.
- 제목은 `고쳤다`보다 `고친다`처럼 현재형·요약형으로 쓴다. 영어권 관례에서는 명령형(`Fix`)을 쓴다.
- 제목 끝에 마침표를 찍지 않는다.
- 제목과 본문 사이에는 빈 줄을 하나 둔다. Git은 이 빈 줄을 기준으로 제목과 본문을 나눈다.
- 본문에는 무엇을 바꿨고 왜 바꿨는지 적는다. 어떻게 바꿨는지는 diff로 확인할 수 있으므로 길게 쓰지 않는다.
- 접두어는 변경 성격을 드러내는 짧은 단어다. `접두어: 제목` 형태로 쓴다.
- 한 커밋에는 한 가지 변경을 담는다. 여러 변경이 섞이면 제목도 모호해진다.
- 팀이나 저장소에 정한 규칙이 있으면 그 규칙을 먼저 따른다.

## 대표 접두어

| 접두어 | 뜻 | 예 |
| --- | --- | --- |
| `feat` | 새 기능이나 화면 추가 | `feat: 로그인 화면 추가` |
| `fix` | 버그나 깨진 동작 수정 | `fix: 모바일 메뉴 겹침 수정` |
| `docs` | 문서·설명 수정 | `docs: 설치 순서 보완` |
| `style` | 동작을 바꾸지 않는 스타일·형식 변경 | `style: 버튼 색상 통일` |
| `refactor` | 동작을 바꾸지 않는 코드 구조 개선 | `refactor: 저장소 목록 조회 분리` |
| `test` | 테스트 추가·수정 | `test: 로그인 실패 경우 추가` |
| `chore` | 설정·도구·기타 작업 | `chore: .gitignore 추가` |

## 작성 예시

```text
feat: 로그인 실패 메시지 추가

로그인에 실패했을 때 이유를 알 수 없어 다시 시도하는 경우가 많았다.
실패 원인을 화면에 표시해 사용자가 다음 행동을 고를 수 있게 했다.
```

- 첫 줄은 제목이다. 무엇을 했는지 한눈에 보인다.
- 빈 줄 뒤의 두 줄은 본문이다. 무엇이 문제였고 왜 바꿨는지 적었다.
- `수정`, `업데이트`, `ㅇㅇ`처럼 짧기만 한 제목은 피한다.

접두어와 내용이 있는 제목은 `git log --oneline`에서 무엇을 바꿨는지 바로 읽힌다.

![`$ git log --oneline`에 `docs: add index`, `feat: add card`, `fix: correct title`이 보인다.](/shot-appendix09-log-good-1000.webp)

`update`, `fix`, `wip`처럼 짧기만 한 제목은 이력만 봐서는 변경 내용을 알 수 없다.

![`$ git log --oneline`에 `update`, `fix`, `wip`만 있는 커밋이 보인다.](/shot-appendix09-log-bad-1000.webp)


## 체크리스트

- [ ] 제목이 50자 안팎으로 짧다.
- [ ] 제목만 읽어도 변경 내용을 알 수 있다.
- [ ] 제목과 본문 사이에 빈 줄이 있다.
- [ ] 본문에 무엇을 왜 바꿨는지 적었다.
- [ ] 접두어가 변경 성격과 맞다.
- [ ] `git log --oneline`에서 제목이 읽힌다.

## 주의할 점

- 제목에 마침표를 찍지 않는다.
- `수정`, `업데이트`처럼 범위가 넓은 말만 쓰지 않는다.
- 본문에 코드 전체를 붙이지 않는다. 코드는 diff에 남는다.
- 한 커밋에 서로 다른 변경을 섞지 않는다.
- 비밀번호, 토큰, 개인정보를 커밋 메시지에 쓰지 않는다.
- 자동 생성 메시지를 그대로 쓰기 전에 내용이 맞는지 확인한다.

## 복습 퀴즈

1. 제목과 본문 사이에는 ::빈 줄::을 하나 둔다.
2. 버그를 고친 커밋에 붙이는 대표 접두어는 ::fix::이다.
3. 커밋 이력을 한 커밋당 한 줄로 요약해 보는 명령은 ::git log --oneline::이다.

## 참고 자료

- [Conventional Commits (한국어)](https://www.conventionalcommits.org/ko/)
- [Chris Beams, How to Write a Git Commit Message](https://cbea.ms/git-commit/)
- [Git 공식 문서 git-commit](https://git-scm.com/docs/git-commit)