커밋 메세지 작성(2023년 버전)

10 Feb, 2023

글

글의 모티베이션

약 8년 전, Git을 막 사용하기 시작할 때 이런 글을 올리고나서, 상상 이상의 반응을 받았습니다.

당시에는 Subversion에서 Git으로 넘어오고나서, 시행착오하고 있는 중이기도 했고, 많은 반응을 받은 것이 동기부여가 되었습니다.

그리고 시간이 흘러, 당연하게도 현재는 글과 작성 방법이 달라진 부분이 있고, 생각이 변하지 않은 부분도 있으며, 지금도 종종 Like를 받다보니 업데이트해야겠구나 느꼈습니다.

그래서, 현 포맷도 수년 후에는 변할 가능성이 높아지겠지만, 종종 스냅샷을 공개하는 것도 어떠한 의미가 있다 느껴, "지금 내가 이렇게 커밋 메시지를 쓰고있어"를 정리했습니다.

Git 사용환경

개발 흐름이나 호스팅 서비스마다 UI의 diff에 의해 적절한 포맷은 달라진다 생각하므로, 제 환경부터 적습니다.

• 개발 흐름
  • 기본적으로는 티켓(이슈) 또는 Pull (Merge) Request 주도 개발을 하고 있습니다.
• 호스팅 서비스
  • 거의 Github지만 종종 GitLab도 사용합니다.

컨셉

3가지 컨셉으로 운용중입니다.

• 거인의 어깨에 서다
• 포맷을 기억하는 비용을 낮추다
• 미니멀함을 잡는다

포맷을 만드는 이유

여러 이유가 있지만, 저는 이렇게 생각합니다

• 애초에 커밋메세지는...
  • 레포지토리의 단편
  • 자기 포함 미래 개발자를 위해 쓰는 것
  • 레포지토리 역사나 컨텍스트를 이해하기 위한 흔적이 될 것
• 이 전제로, 일정 규칙 = 포맷 (Not 룰)을 만듦으로...
  • 팀이 커져도 흔적을 잃지 않도록 하고 싶다
  • 포맷을 만들어서 생각하는 걸 하나라도 덜 하고 싶다

포맷

Semantic Commit Message를 사용합니다.

• 포맷: <Type>: <Emoji> #<Issue Number> <Title>
• 예시: feat: ✨ #123 로그인 기능 구현
• Type, Title 필수
• Issue Number은 강한 권장
• Emoji는 임의
• Description(쓰리라인) 임의

Type

• 어떤 커밋인지 한 번에 알 수 있도록 Prefix 종류
• Semantic Commit Message랑 같이 상황마다 사용
  • chore
    • 태스크 파일 같이 제품에 영향하지 않는 수정
  • docs
    • 문서 갱신
  • feat
    • 유저 대상 기능 추가/변경
  • fix
    • 유저 대상 버그 수정
  • refactor
    • 리팩터링 목적으로 한 수정
  • style
    • 포맷 등 스타일 관련 수정
  • test
    • 테스크 코드 추가/수정

과거에는 내멋대로 룰로 운용하던 것도 있었지만, 뭐가 있었는지 까먹거나, 자연스럽지 않았기에 Semantic Commit Message 레일 위에 올라갔다.

Emoji

• Type를 보다 "컬러풀"하게 만드는 Emoji
  • 뭐라도 좋지만 gitmoji에서 고르면 좋을거라 생각한다
• 다만 Emoji를 기억하는 비용이 있으므로 필수는 아님
  • 저는 대부분 프로젝트에 작성하지 않음

Issue Number

• 해당 커밋을 엮는 Issue 번호 작성한다
  • 링크되어, 추적하기 쉽게하기 위함
• Issue를 만들지 않은 경우나 hotfix 경우에는 생략 가능
• 다만 Issue가 있으면 수정 의도가 이해하기 쉽기에 Issue를 작성하는 걸 강력히 권장한다
• 또한 기본 설정이면 #가 주석 취급이므로 이곳에 위치한다

Subject

• 흔히 말하는 변경 내용을 작성한다
• 현재형으로 ("ㅇㅇ했다"가 아니라 "ㅇㅇ한다") 쓰도록 하고 있다
  • fyi: https://minus9d.hatenablog.com/entry/2014/02/11/125222
• 문자수는 특히 제한하지 않지만, 20 ~ 30자 이내가 적절하다 느낀다
  • fyi: https://twitter.com/_mono/status/1240075582164983809
• Description 필수는 아님
  • 저는 거의 작성하지 않음

좋은 커밋 메세지란?

종종 커밋 메세지는 Why를 적도록하자는 말이 있지만, 최근은 그렇게까지 엄격히 지킬 필요가 없습니다. 물론 주장에는 찬성하고 있어서 Why를 작성한다면 최고겠지만 한 줄로 why까지 적기에는 난이도가 높고, 커밋메세지가 "컬러풀"해지지 않는다 생각합니다.

이럴려면, Why를 쓰기 위해서 description을 활용할 필요가 있습니다만, description에 Why를 쓰려한다면, 커밋 메세지에 Issue를 엮어서, Issue (혹은 PR) 에 Why 세세히 쓰는 것이 더 현명한 것 같다 생각합니다. 또 커밋 메시지만으로 Why를 전달하기보다 그 소속이기도한 Issue나 PR로 Why를 전달하는 것이 의도를 쉽게 전달되는 경우가 많다 느낍니다.

그렇기에, 저는 커밋 메시지에는 거의 반드시 Issue를 엮어서, Why는 Issue나 PR에서 표현하고, Subject인 What 정도만 쓰도로 하고 있습니다. 물론 "~를 위해 ㅇㅇ했다" 이런 표현을 써야하는 경우에도 싸며, "테스트를 쓴다"나 "Lint 에러 수정했다" 같이 cardinality 높은 커밋 메세지는 피해야한다 생각합니다.

모국어? 영어?

통일감은 중요하므로, 팀에서 협의했다면, 어느쪽이든 (당연히 모국어나 영어 외에도) 좋다 생각합니다만, 저는 도메스틱한 팀, 도메스틱한 서비스라면 모국어로 쓰는 경우가 많습니다.

과거를 돌아보면 영어로 적었던 것도 있습니다만, 네이티브하지 않아서 시간을 잡아먹거나, 급하게 대충 "Fix a sorting bug" 이런 문법조차 수상한 cardinality 높은 커밋 메세지를 남기는 경우가 있어, 본말전도같아 영어로 적는 경우가 적어었습니다.

물론 글로벌한 팀에서는 영어로 쓰는 경우가 좋은게 대부분이면서, 영어를 쓰므로 손해가 없으므로 영어를 쓰는 것 자체는 전혀 문제가 아니지만, 네이티브가 아닌 경우는 자신 외에도 팀 전원이 어느정도의 각오가 필요하다 생각합니다.

기타

• Merge Commit이나 Revert Commit은 이 포맷을 따른 필요없습니다
• 커밋 크기를 자잘하게 하는 것을 기본으로 합니다
  • 다만, 1줄 수정할 때마다 커밋하라는 것이 아니라, 리뷰어가 PR 커밋 목록을 볼 때, "이야기"를 알 수 있도록 하는 것을 의식합니다

자신만의 커밋 메세지로 라이벌과 차이를 벌리자!

글 초반에도 조금 다뤘지만, 여기에 유일한 정답이 아닙니다, 저 자신은 현시점에서 이게 최선이다 생각하지만, 내일이 되서 더 좋은 방법을 발견하고 이 방법을 버릴 가능성이 있습니다. 그렇기에 이글 글도 언젠가 낡아질 것이라 생각합니다. 커밋 메세지 뿐만 아니라 매일 시행착고를 계속하는 것이 소프트웨어 엔지니어링의 즐거움 중 하나라 생각하므로, 이 글이 누군가의 커밋 메세지에 대해 생각할 계기가 되었다면 다행입니다.