커밋 메세지 어떻게 써야할까?

들어가기 전에

지금까지는 커밋 메시지를 컨벤션 맞춰서 쓰라니까 그렇게만 맞춰서 써왔다. 그런데 이렇게 쓰다 보니 글쓰기 실력에 자신감이 없던 나는 진짜 이렇게만 쓰면 되는 건가? 현업에서도 이렇게 쓰면 되나? 이런 의혹이 커져만 갔다. 

 

그래서 한번 커밋 메시지를 제대로 쓰려면 어떻게 써야 하는지에 대해서 알아보았다. 

 

커밋 메시지를 잘 써야 하는 이유?

아래 이미지는 코딩을 처음 시작했을 때, 깃과 깃헙이라는 것을 처음 접하고 커밋의 중요성을 하나도 느끼지 못했던 시절에 썼던 커밋 기록이다.

무슨 일을 했는지 전혀 알아볼 수가 없다. git blame을 써서 저 커밋 내역을 본다면 비난을 받아야 마땅한 기록이다.

정말 같이 팀플 했던 동료들에게 지금이라도 죄송하다는 말을 하고 싶다... 

 

 

그럼 커밋 메세지를 잘 쓰면 뭐가 좋을까?

• 좋은 커밋을 작성하면 미래의 내가 쉽게 이해
• 도움이 되는 설명을 제공하여 문제 해결 중에 동료가 작업하는 시간을 절약

협업과 의사소통 능력이 코딩 실력만큼 중요하다고 여겨지기 때문에 커밋 메시지 같은 문서화 능력은 개발자가 절대 무시해서는 안될 필수 요소라고 볼 수 있다.

 

커밋할 때 권장사항

1. 하나의 커밋에는 한 단위의 작업을 넣는다.
   • 한 작업을 여러 버전에 걸쳐 커밋하지 않는다.
   • 여러 작업을 한 버전에 커밋하지 않는다.
2. 커밋 메시지는 어떤 작업이 이뤄졌는지 알아볼 수 있도록 작성한다.

 

커밋 컨벤션

커밋 컨벤션은 일관된 커밋 메세지 구조를 만들기 위한 약속이다. 이를 따르면 다른 개발자들이 커밋을 읽고 쉽게 따라갈 수 있으며, 프로젝트의 유지 보수와 이해가 용이해질 것이다.

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Subject

명확하고 간결한 주제 줄과 명령형 문체를 사용함으로써 커밋의 의도를 명확하게 전달할 수 있다. 이는 다른 팀원들이 커밋을 빠르게 파악하고 이해하는 데 도움을 준다.

 

💡 커밋 주제 작성 팁!

1. 첫 단어는 대문자로 쓰고 마침표로 끝내지 않음 (commit type을 사용한다면 모두 소문자로 작성)
2. 주제 줄에서 명령형 문체를 사용 (ex:  Add fix for dark mode toggle state)
3. 변경 사항을 설명하는데 일관된 단어들을 사용하는 것이 권장 (ex: Bugfix, Update, Refactor)
4. 첫 줄은 50자 이내로 작성
5. 주제와 본문은 빈 줄로 구분
6. 첫 번째 줄은 주요한 정보를 담고 있으므로 꼼꼼히 작성

📋 커밋 타입

type	설명
feat	새로운 기능 추가
fix	버그 수정
env	개발 환경 관련 설정
style	코드 스타일 수정 (세미 콜론, 인덴트 등의 스타일적인 부분만)
refactor	버그를 수정하거나 기능을 추가하지 않은 리팩토링된 코드
design	CSS 등 디자인 추가/수정
comment	주석 추가/수정
docs	README나 다른 마크다운 파일과 같은 문서 업데이트
test	테스트 추가/수정
chore	수정이나 기능과 관련이 없으며 소스 코드나 테스트 파일을 수정하지 않는 변경 사항  (ex: 빌드 스크립트 수정, assets image, 패키지 매니저 등)
rename	파일 및 폴더명 수정
remove	파일 삭제
init	프로젝트 초기 생성

 

Commit Body (선택사항)

변경 사항에 대한 추가적인 정보를 제공할 수 있다. 왜 변경이 필요했는지, 어떻게 해결되었는지 등의 세부사항을 기록함으로써 팀의 협업과 이해력을 향상시킨다.

 

💡 커밋 본문 작성 팁!

1. 본문은 72자로 줄 바꿈
2. 불필요한 단어와 구절을 제거하고 직접적으로 표현 (examples: though, maybe, I think, kind of) 
3. 변경 사항을 왜 만드는지 설명
4. 변경 사항이 어떻게 문제를 해결하는지 설명
   
5. 변경 사항이 어떤 영향을 미치는지 설명
6. 변경된 코드의 구조에 대해 명확하게 설명
7. 변경된 코드의 한계를 명확히 설명
8. 리뷰어가 원래 문제를 이미 알고 있다고 가정해서는 안 됨

Commit Footer (선택사항)

커밋 메시지의 푸터 부분은 변경 사항에 관련된 이슈 정보를 기재하는 데 사용할 수 있다. 이를 통해 다른 개발자들이 변경 사항의 문맥을 이해하고 관련 정보를 더 쉽게 찾을 수 있다.

 

💡 커밋 푸터 작성 팁!

1. type: #이슈 번호의 형식으로 작성
2. 이슈 트래커 ID를 작성
3. 여러 개의 이슈 번호는 쉼표로 구분

📋 이슈 트래커 타입

type	설명
Fixes:	이슈 수정중(아직 해결되지 않은 경우)
Resolves:	이슈를 해결한 경우
Ref:	참조할 이슈가 있을 때 사용
Related to:	코드 스타일 수정 (세미 콜론, 인덴트 등의 스타일적인 부분만)

ex) Fixes: #5 Related to: #7, #18

 

커밋 컨벤션 예시

fix: fix foo to enable bar

This fixes the broken behavior of the component by doing xyz. 

Fixes: #45 
Related to: #34, #23

 

커밋 템플릿 만들어보기

커밋 템플릿 적용 방법 

1. 커밋 메시지 템플릿을 적용할 프로젝트에 진입
2. .gitmessage.txt 파일을 생성
3. 아래 명령어를 입력한다. 
    $ git config --global commit.template <.gitmessage.txt 경로> 

커밋 템플릿 예시

# subject ex) feat: Add Key mapping

# body

# footer: ex) Fixes: #5 Related to: #7, #18

# --- COMMIT TYPE ---  
#   feat  :  새로운 기능 추가 
#   fix  :  버그 수정
#   env  :  개발 환경 관련 설정
#   style  :  코드 스타일 수정
#   refactor  :  코드 리팩토링
#   design  :  CSS 등 디자인 추가/수정
#   comment  :  주석 추가/수정
#   docs  :  문서 수정
#   test  :  테스트 추가/수정
#   chore  :  수정이나 기능과 관련이 없는 변경 사항
#   rename  :  파일 및 폴더명 수정
#   remove  :  파일 삭제
#   init  :  프로젝트 초기 생성
# --- ISSUE TRACKER TPYE ---
#   Fixes  :  이슈 수정중 (아직 해결되지 않은 경우)  
#   Resolves  :  이슈 해결했을 때 사용  
#   Ref  :  참고할 이슈가 있을 때 사용  
#   Related to  :  해당 커밋에 관련된 이슈번호 (아직 해결되지 않은 경우)  
# --- Subject 작성 팁 ---
#   1. 첫 단어는 대문자로 쓰고 마침표로 끝내지 않음 (commit type을 사용한다면 모두 소문자로 작성)
#   2. 주제 줄에서 명령형 문체를 사용
#   3. 변경 사항을 설명하는데 일관된 단어들을 사용하는 것이 권장
#   4. 첫 줄은 50자 이내로 작성
#   5. 주제와 본문은 빈 줄로 구분
#   6. 첫 번째 줄은 주요한 정보를 담고 있으므로 꼼꼼히 작성
# --- Body 작성 팁 ---
#   1. 본문은 72자로 줄바꿈
#   2. 불필요한 단어와 구절을 제거하고 직접적으로 표현 (examples: though, maybe, I think, kind of) 
#   3. 변경 사항을 왜 만드는지 설명
#   4. 변경 사항이 어떻게 문제를 해결하는지 설명
#   5. 변경 사항이 어떤 영향을 미치는지 설명
#   6. 변경된 코드의 구조에 대해 명확하게 설명
#   7. 변경된 코드의 한계를 명확히 설명
#   8. 리뷰어가 원래 문제를 이미 알고 있다고 가정해서는 안 됨
# --- Footer 작성 팁 ---
#   1. 유형: #이슈 번호의 형식으로 작성
#   2. 이슈 트래커 ID를 작성
#   3. 여러개의 이슈 번호는 쉼표로 구분

 

참조

https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/

https://kdjun97.github.io/git-github/commit-convention/

https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53