좋은 커밋 메세지 작성

좋은 커밋 메세지 작성

 

▼ 커밋 메세지의 구조

[Type] 제목

본문 (선택사항)

꼬리말 (선택사항)

 

 

Type ( 태그 / 접두사 )

커밋의 성격을 나타내는 Type 을 제목 앞에 붙인다

 

핵심 Type

• feat : 새로운 기능 추가
• fix : 버그 수정

 

그 외 자주 사용하는 Type

• docs : 문서 수정
• style : 코드 포맷팅 , 세미콜론 누락 등 ( 동작에 영향이 없음 )
• test : 테스트 코드 추가 또는 수정
• perf : 성능 개선
• refactor : 리팩토링
• chore : 빌드 업무 , 패키지 설정 , 라이브러리 업데이트 등
• ci : CI / CD 관련 변경
• build : 빌드 시스템 수정

 

▼ 대괄호 방식 ( Bracket Style )

git commit -m "[feat] Implement enemy spawn manager"
git commit -m "[fix] Correct player movement speed issue"
git commit -m "[refactor] Cleanup game manager update logic"
git commit -m "[docs] Add setup instructions to README"
git commit -m "[style] Format UI script with consistent indentation"
git commit -m "[chore] Update .gitignore for Log files"

 

▼ 콜론 방식 ( Colon Style )

git commit -m "feat: implement enemy spawn manager"
git commit -m "fix: correct player movement speed issue"
git commit -m "refactor: cleanup game manager update logic"
git commit -m "docs: add setup instructions to README"
git commit -m "style: format UI script with consistent indentation"
git commit -m "chore: update .gitignore for log files"

 

 

좋은 커밋 메세지를 위한 7가지 규칙

크리스 빔즈 ( Chris Beams ) 는 소프트웨어 개발자이자 좋은 커밋 메세지 작성법 저자로 유명한 사람이다.

개발자들에게 거의 "전 세계 표준"처럼 쓰이는 커밋 메세지 규칙이 바로 chris Beams 가 작성한 글에서 비롯됐다.

 

 

1. 제목과 본문을 빈 행으로 구분한다

git commit

[fix] player movement freeze issue

Adjusted Rigidbody velocity reset logic

Removed conflicting animation flag

특정 상황에서 이동 애니메이션과 물리 업데이트가 충돌해
플레이어가 순간적으로 멈추는 현상이 발생했음.

제목과 본문 사이는 반드시 한 줄 비워야 한다. 

그래야 git log --oneline 같은 명령어가 제대로 동작한다.

 

 

2. 제목은 50자 이내로 제한한다

커밋 메세지의 제목은 한 눈에 봐도 뭘 했는지 알수 있어야 한다.

GitHub , GitLab 같은 플랫폼에서도 50자가 넘으면 제목이 잘린다.

<좋은 예시>
feat: add auto-heal feature when player HP is low
// 기능 추가 목적이 분명
refactor: simplify stage loading logic for clarity
// 리팩토링 이유가 명확

<나쁜 예시>
fix: this commit fixes the issue where sometimes players get stuck while moving because the physics engine does not properly reset constraints
// 제목이 너무 길다

 

 

3. 제목 첫 글자는 대문자로 작성

영어로 커밋 메세지를 작성할 때 규칙이다.

문장의 시작은 대문자로 작성하는게 문법 규칙이다.

Feat: Add player auto-save system
Fix: Prevent duplicate items in inventory
Docs: Update README with setup guide

 

 

4. 제목 끝에 마침표는 생략한다

제목은 말 그래도 제목일뿐 문장이 아니다. 마침표는 불필요하다.

<좋은 예시>
Feat: Add auto-save system for progress

<나쁜 예시>
Feat: Add auto-save system for progress.

 

 

5. 제목은 명령문으로 사용하며 과거형 미사용

영어로 작성할 때에는 동사 원형으로 시작하는 게 국룰이다.

Added 나 Adding 이 아니라 Add 로 작성하는 것이 좋다.

<좋은 예시>
Feat: Add player dash ability // Add = 명령문
Refactor: Improve enemy pathfinding logic // Improve = 명령문
Style: Format code with consistent spacing // Format = 명령문

<나쁜 예시>
Fixed crash when loading scene // Fixed = 과거형
Added player dash ability // Added = 과거형
Updating installation instructions // Updating = 진행형
This commit adds dash skill // 문장형 , 명령문 아님

 

 

6. 본문의 각 행은 72자 내로 제한

본문을 작성할 때에는 각 줄을 72자 이내로 끊는 것이 좋다.

터미널에서 git log 로 봤을 때 가독성이 좋아진다.

Fix player movement freeze issue

The movement system sometimes stops responding due to a conflict between
the physics update and animation state update. This change adjusts the
velocity reset logic and removes the conflicting animation flag.

 

 

7. 본문에는 "무엇을" , "왜" 변경했는지 작성

코드를 보면 "어떻게" 구현했는지는 알 수 있다.

하지만 "왜" 이렇게 작성 했는지는 커밋 메세지가 아니면 알 수 없다.

Fix player movement freeze issue

What:
- Adjusted velocity reset logic
- Removed conflicting animation flag

Why:
- Movement occasionally froze because physics and animation updates
  were fighting each other. By removing the conflicting state flag,
  the player can move smoothly again.

 

 

정리

좋은 커밋 메세지는 단순한 "메모"가 아니라 프로젝트의 변경 역사와 의도를 기록하는 중요한 문서이다

커밋 메세지를 명확하고 일관된 형식으로 작성하면 협업 , 유지보수 , 디버깅 , 코드 리뷰가 훨씬 수월해진다.

 

 

참고 자료

Chris Beams 가 저자한 "How to Write a Git Commit Message"

https://cbea.ms/git-commit/

Conventional Commits

https://www.conventionalcommits.org/en/v1.0.0/

Angular Commit Message Guidelines

https://github.com/angular/angular/blob/main/CONTRIBUTING.md