Git Commit Message Convention

Photo by Arnold Francisca on Unsplash

 우리는 개발을 하다보면 개인 개발을 하든 동료들과 함께 개발을 하든 자연스럽게 git을 쓰게 된다. 이때 commit 마다 메시지를 작성하는데, 이 메시지를 대충 쓰고 커밋을 대충 나누게 되면 혼자 개발하더라도 나중에 기록들을 봐야 할 일이 있을 때 가독성이 매우 떨어진다. 여러 사람과 함께 개발을 하는 경우라면 이런 현상이 더 심해지고 코드를 유지보수함에 있어서도 효율이 떨어진다.

 커밋 메시지를 어떻게 작성할지 스타일을 정해둠으로써 이전의 커밋 로그들을 볼 때 가독성을 높일 수 있고, 유지보수도 더 수월하게 할 수 있다. 이뿐만 아니라 서로 코드리뷰를 할 때, 약속한 커밋 메시지 스타일을 통해 어떤 커밋인지 금방 이해하고 어떻게 코드 리뷰를 할지 방향을 잡을 수 있어서 코드 리뷰 측면에서도 도움이 된다. 이번 글에서는 커밋 메시지를 어떤 형식으로 정하면 좋을지 정리해본다.

 

반응형

 

Git Commit Message Style Guide

 앞서 말한 커밋 메시지에 대한 필요성과 고민들은 많이 있어왔고, 고민들에 대한 결과로 유명한 가이드가 몇 가지 있다. 여기에 개인적인 경험을 추가해서 메시지 스타일을 정해본다. (참고한 스타일 가이드 사이트들은 하단 References 참고)

 

필요성

 서두에서 커밋 메시지의 필요성과 중요성을 이야기 했지만, 생각보다 많이 중요하니 한번 더 짚고 넘어가자. Java Spring의 commit 기록을 예로 들어볼 수 있다.

 

 2009년의 git log 커밋 메시지들이다. 서로 제각각이어서 눈에 잘 들어오지도 않으며 문장의 길이와 형태, 대소문자 시작 여부 모두 다르다. 정확히 어떤 작업을 했는지 파악할 수 없는 커밋 메시지들도 있다.

 

 2014년의 git log 커밋 메시지이다. 큰 규칙까지 정한 걸로 보이지는 않지만, 우선 보이는 점들만 짚어보면 다음과 같다.

• 대문자로 시작
• 과거형이 아닌 현재시제 동사로 시작
• 코드에서 사용하는 용어(클래스명, Annotation 등)는 대소문자 그대로 사용
• 마지막에 마침표(.)를 찍지 않음
• 글자수 제한이 있고, 한 문장으로 표현

 이와 같이 그렇게 많은 규칙을 적용하지 않은 경우에도 간결하고 일관된 스타일 덕분에 읽기가 쉬우며 어떤 작업을 한 것인지 감이 온다. 읽는 사람이 빠르게 정보를 획득할 수 있고, 동료와 자신이 추후에 작업 내용을 다시 파악하기 쉽다. 또, CHANGELOG를 작성할 때도 커밋 메시지를 기반으로 자동으로 생성할 수도 있다.

 

기본 구조

 많은 오픈 소스 프로젝트들은 저마다 커밋 메시지 스타일을 명시하는 경우도 많고, 현업에서 일을 하는 경우에도 일관된 스타일을 사용하는 경우가 대부분이다. 이 중에서 일반적으로 통용되는 구조는 다음과 같다.

 

 이런 형태로 첫째줄에는 제목을 적고, 본문과 꼬리말은 한 줄씩 띄어서 작성해주면 된다. 제목만 필수고 본문과 꼬리말은 필요에 따라 작성하면 된다. 일반적으로 git log를 찍어보거나 IDE에서 각 라인에 따라 git commit 내역을 보여주는 기능도 1차적으로는 제목만 출력해주는 경우가 많기 때문에 제목이 제일 중요하다.

 

반응형

 

---

제목에 대한 규칙

 제목은 커밋 메시지의 유형과 내용을 함께 작성해준다. 이슈 트래커 번호를 사용하는 경우 꼬리말에 넣기도 하지만, 제목의 type과 내용 사이에 적어줘도 된다.

타입

 커밋이 어떠한 종류인지를 알려주는 정보다. 다음과 같은 타입들을 사용할 수 있다.

• Feat : 새 기능 (new feature)
• Fix : 버그 수정
• Docs : 문서 수정
• Style : 코드 스타일 관련 수정 (포맷팅 등 실제 코드 변화는 아닌 경우)
• Refactor : 리팩토링 작업
• Test : 테스트 코드의 추가나 테스트 코드에 대한 리팩토링 작업 (메인 코드는 변경 X)
• Chore : 빌드와 관련된 것들을 업데이트하는 경우
• Design : UI 변경 작업
• Comment : 주석의 작성이나 변경
• Rename : 파일, 폴더, 패키지 등의 이름만 수정하거나 옮기기만 한 경우
• Remove : 파일 삭제만 한 경우

 앵귤러 컨벤션을 기반으로 하는 @commitlint/config-conventional에서 권고하는 타입들이다.

 

 이런 식으로 추가적인 문맥 정보 제공을 위해 적용 범위를 괄호 안에 추가해서 사용할 수도 있다.

 

 단절적 변경(Breaking Change)에 주의를 주기 위해 타입 뒤에 느낌표(!)를 추가해도 된다.

 

제목의 내용 부분

• 50글자를 넘지 않는다.
• 대문자로 시작하고 마침표를 찍지 않는다. (대문자든 소문자든 통일!)
• 명령형으로 사용한다. (Added가 아니라 Add)
• 필요시 제목 마지막에 이슈 트래킹 번호를 추가

 

최종 제목 형태

 커밋 메시지의 제목 부분은 이런 식으로 사용하면 된다.

 

반응형

 

---

본문

• 본문은 한 줄당 72자 이내로 작성
• 상세히 작성할 필요가 있다면 제한 없이 최대한 상세하게 작성 가능
• 어떻게 변경했는지가 아니라 무엇을, 왜 변경했는지에 초점

꼬리말

• 보통 이슈 트래커 번호를 적을 때 사용하지만, 번호는 제목에 작성하기로 했으므로 크게 적을 것은 없다.
• 추가 이슈나 관련된 이슈가 있을 경우 해당 번호 등을 적어주면 좋을 것 같다.

 본문과 꼬리말을 포함하면 위와 같은 형태가 된다.

 

 

마치며

 관련된 글과 규칙들이 굉장히 상세하고 자세하게 적혀 있어서 커밋을 하기 위해 이런 것들을 또 공부하고 외우고 있어야 하나 생각이 들었는데, 다 합리적인 이유로 생긴 규칙들이고 이렇게 작성함으로써 읽기가 더 수월해져서 좋아보인다. 말 그대로 convention이니까 외운다기보다는 편하게 사용하면서 체득할 수 있는 내용들이다. 다음 레퍼런스들에 더 자세한 내용들이 나와있으니 이 글과 레퍼런스들을 참고해서 각 팀의 상황에 맞게 적용하여 사용하면 되겠다.

 

References

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

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

https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional