Git Commit Message Style Guide

Seoyeon·2025년 9월 1일

백엔드기초

목록 보기

15/17

참고 : https://udacity.github.io/git-styleguide/

Udacity Git Commit Message Style Guide 요약

1. 커밋 메시지 구조

커밋 메시지는 세 부분으로 구성됨 (빈 줄로 구분):

type: Subject

body

footer

Title: type: subject
Body: (선택) 변경 이유와 배경 설명
Footer: (선택) 이슈 번호 참조

2. Type (커밋 유형)

feat: 새로운 기능 추가
fix: 버그 수정
docs: 문서 변경
style: 코드 포맷팅, 세미콜론 등 (코드 로직 변화 없음)
refactor: 리팩토링 (기능 변화 없음)
test: 테스트 추가/변경 (프로덕션 코드 변화 없음)
chore: 빌드, 패키지 매니저, 설정 변경 등 (코드 변화 없음)

3. Subject (제목)

50자 이내
첫 글자는 대문자
끝에 마침표(.) 쓰지 않음
명령형 사용 (예: Change → O, Changed → X)

4. Body (본문, 선택)

필요할 때만 작성
**무엇(what), 왜(why)**를 설명 (어떻게는 코드가 설명함)
제목과 본문 사이에 반드시 빈 줄
한 줄은 72자 이내

이슈 트래커 ID 참조 용도
예시:
```
Resolves: #123
See also: #456, #789
```

6. 예시

feat: Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. Explain what and why, not how.

 - Bullet points are fine
 - Keep lines wrapped to 72 characters

Resolves: #123
See also: #456

1) 왜 커밋 컨벤션이 필요한가

로그 가독성↑, 코드 리뷰↑, 원인 추적↑, 릴리스 노트 자동화↑
팀이 같은 규칙을 쓰면 협업 비용이 크게 줄어듭니다.

2) 커밋 메시지 구조

type: Subject

body

footer

type: 변경 의도 (feat, fix 등)
subject(제목): 한 줄 요약 (≤ 50자, 명령형, 마침표 X)
body(본문, 선택): 무엇/왜(why) 중심, 한 줄 ≤ 72~75자 권장
footer(선택): 이슈 참조/종료 (예: Resolves: #123, Related to: #45)

영어면 동사원형(명령형: Add/Change/Fix), 한글이면 “추가/변경/고침” 같은 개조식 표현 추천.

3) 타입(태그) 분류 & 매핑

A. 기능 계열

태그(글의 용례)	의미	Conventional Commits 대응
Feat	새 기능 추가	`feat`
Fix	버그 수정	`fix`
Design	UI/CSS 변경	보통 `style` 또는 `feat`(사용자 기능 변화면)
!BREAKING CHANGE	호환성 깨짐	`feat!` 또는 본문/푸터에 `BREAKING CHANGE:`

중요: “큰 변경”은 제목에 feat!:처럼 느낌표 또는 푸터/본문에 BREAKING CHANGE:로 남기는 게 표준적입니다.

B. 개선/리팩토링 계열

태그	의미	Conventional Commits
Style	포맷/세미콜론/공백 등, 로직 변화 없음	`style`
Refactor	리팩토링(기능 변화 없음)	`refactor`
Comment	주석 추가/변경	보통 `docs` 또는 `chore` (코드 주석은 `style`로 보는 팀도)

C. 기타(문서/테스트/환경 등)

태그	의미	Conventional Commits
Docs	문서 변경(README 등)	`docs`
Test	테스트 추가/수정(프로덕션 미변경)	`test`
Chore	빌드/도구/패키지/환경 변경	`chore`
Rename	파일/폴더명 변경만	`chore` (또는 `refactor`로 보는 팀도)
Remove	파일/폴더 삭제만	`chore` 또는 `refactor`

D. 긴급/핫픽스

태그	의미	Conventional Commits
!HOTFIX	치명적 이슈 긴급 수정	보통 `fix`(필요하면 `fix!`)

팀 내 허용 태그 목록을 짧게 유지하는 게 좋습니다. (예: feat, fix, docs, style, refactor, test, chore + 필요 시 perf, ci)

4) 제목(Subject) 작성 규칙

50자 이내, 마침표 X, 명령형 (“추가/변경/수정/고침…”)
영어면 첫 글자 대문자 + 동사원형(“Add”, “Change”, “Fix”)
괄호로 범위를 표기해 문맥 제공 가능
- 예: feat(auth): JWT 로그인 추가, fix(db): NPE 방지

5) 본문(Body) 작성 규칙

무엇을, 왜(why) 했는지 설명. (어떻게는 코드가 말함)
필요 시 불릿/번호 목록 OK, 한 줄 72~75자 정도로 개행
사이드이펙트, 대안, 마이그레이션 안내 등을 명확히

이슈 연결:
- Resolves: #123 (머지 시 자동 종료)
- Fixes: #45 (유사)
- Related to: #34, #23 (참조)
- Ref: #456 (참고)
호환성 파괴 공지는 여기에도 가능:
- BREAKING CHANGE: 토큰 필드명이 변경되어 클라이언트 수정 필요

7) 예시 (로그인 API 개발)

feat(auth): 로그인 API 추가

사용자 이메일/비밀번호로 인증 후 JWT를 발급합니다.
비밀번호는 bcrypt 해시 검증, 실패 시 401을 반환합니다.
토큰 만료는 30분이며 갱신 엔드포인트는 추후 추가 예정.

Resolves: #123
Related to: #48, #45

호환성 파괴 예시

feat!(auth): 로그인 응답 스키마 변경

기존 token → accessToken으로 필드명 변경.
클라이언트 파싱 로직 업데이트 필요.

BREAKING CHANGE: 응답 필드명이 변경되었습니다.

8) 이모지(선택)

팀이 허용하면 보조적으로만 사용하세요(과도하면 검색/자동화에 불리).
예: ✨ feat: 새 기능, 🐛 fix: 버그, 📝 docs: 문서, 🎨 style: 포맷

9) 안티패턴 → 개선 예

나쁜 예: 수정, 고침, fix, Update, 잡다한 수정
좋은 예:
- fix(order): 결제 시 NPE 발생 원인 제거
- refactor(user): 서비스 레이어 의존성 정리
- docs(readme): 실행 방법 및 환경 변수 표 추가

10) 팀 적용 팁

허용 타입 목록 간결화 + BREAKING CHANGE 통일 규칙(제목 ! 또는 푸터)

커밋 템플릿으로 습관화:

git config --global commit.template ~/.gitmessage.txt

~/.gitmessage.txt 예:

type(scope): subject (≤50)

body (what & why, wrap at 72)

Resolves: #123
Related to: #456
BREAKING CHANGE:

잘된 커밋 메시지 vs 나쁜 커밋 메시지

기능 추가 (feat)

잘된 예

feat(auth): 이메일 기반 회원가입 API 추가

사용자가 이메일과 비밀번호로 가입할 수 있도록 엔드포인트를 추가했습니다.
비밀번호는 bcrypt 해시를 사용하며 중복 이메일은 400을 반환합니다.

Resolves: #12

나쁜 예
```
회원가입 구현
```
```
feat: 회원가입 기능
```
-> 문제: 너무 포괄적/불명확, 왜/무엇을 추가했는지 설명 없음

버그 수정 (fix)

잘된 예

fix(order): 결제 시 null pointer exception 수정

결제 요청 시 배송지 주소가 null일 경우 발생하는 NPE를 방지했습니다.
기본 배송지 로직을 추가해 null 검증 후 처리합니다.

Resolves: #45

나쁜 예
```
고침
```
```
버그 수정
```
-> 문제: 어떤 버그인지, 어떻게 해결했는지 알 수 없음

리팩토링 (refactor)

잘된 예

refactor(user): 서비스 레이어 의존성 정리

UserService에서 직접 DB 접근하던 코드를 Repository 계층으로 이동했습니다.
서비스 책임을 분리하고 테스트 가능성을 개선했습니다.

나쁜 예
```
코드 정리
```
-> 문제: 무엇을 정리했는지 추적 불가

문서 변경 (docs)

잘된 예

docs(readme): 실행 방법과 환경 변수 설정 가이드 추가

나쁜 예
```
README 수정
```
-> 문제: 어떤 내용이 바뀌었는지 불명확

스타일 변경 (style)

잘된 예

style(lint): Prettier 규칙에 따라 코드 포맷 적용

나쁜 예
```
오타 고침
```
-> 문제: 오타/스타일의 범위, 이유 불분명

안 좋은 습관 예시

"Update", "수정", "변경" → 의미 불명확, 로그 뒤져도 알 수 없음
한글/영문 혼용, 접두사 없음 → 검색·자동화 툴에서 잡히지 않음
본문 없음 → 중요한 변경인데도 설명 없이 제목만 있음

Seoyeon

이전 포스트

역할/권한

다음 포스트

Git Commit Message Style Guide

백엔드기초

Udacity Git Commit Message Style Guide 요약

1. 커밋 메시지 구조

2. Type (커밋 유형)

3. Subject (제목)

4. Body (본문, 선택)

5. Footer (푸터, 선택)

6. 예시

1) 왜 커밋 컨벤션이 필요한가

2) 커밋 메시지 구조

3) 타입(태그) 분류 & 매핑

A. 기능 계열

B. 개선/리팩토링 계열

C. 기타(문서/테스트/환경 등)

D. 긴급/핫픽스

4) 제목(Subject) 작성 규칙

5) 본문(Body) 작성 규칙

6) 꼬리말(Footer) 규칙

7) 예시 (로그인 API 개발)

8) 이모지(선택)

9) 안티패턴 → 개선 예

10) 팀 적용 팁

잘된 커밋 메시지 vs 나쁜 커밋 메시지

기능 추가 (feat)

버그 수정 (fix)

리팩토링 (refactor)

문서 변경 (docs)

스타일 변경 (style)

안 좋은 습관 예시

역할/권한

PR Template

0개의 댓글