Git Commit Message Style Guide - 개인/팀을 위한 커밋 메시지 스타일 가이드

munilive
Written by munilive on (Updated: )

개인/팀 프로젝트를 진행하면서 코드 관리에 Git을 많이 사용하고 있습니다. Git이 외 SVN(Subversion), Mercurial 등 다른 여러 종류의 버전 관리 툴들이 있지만, 오늘은 Git을 사용하는 데 있어서, 개인/팀에서 공통적으로 지켜야 할 커밋 메시지에 대한 가이드를 소개할까 합니다.
Git이 아닌 SVN, Mercurial 등 다른 버전 관리 툴에서도 적용한다면 도움이 되지 않을까 싶습니다.
여기서 대상을 개인/팀이라고 하였는데 개인의 경우 커밋 메시지를 자신이 원하는 대로 작성해도 아무런 문제가 없을 것입니다. 하지만, 개인 프로젝트라 하더라도, 나중에 히스토리를 파악하거나, 수정된 내용을 파악할 때 아무렇게나 지어둔 커밋 메시지로 인하여 정확한 수정사항을 파악하기란 쉽지 않습니다.
하나의 룰을 정해두고 습관을 들여 개인/팀 내에서 같이 사용한다면 차후 Commit 메시지 만으로도 어떠한 수정사항이 발생하였는지, 기능이 추가되었는지를 파악하기 쉽고, 추적하기 쉬울 것입니다.

아래 스타일 가이드는 Udacity Git Commit Message Style Guide를 기반으로 이전 회사에서 작성한 Commit 가이드에 다른 분들의 커밋가이드를 좀더 참고해서 제 생각이 들어간 커밋 가이드 입니다.
참고: 본 스타일 가이드의 기반이된 Udacity Git Commit Message Style Guide 가이드의 작성자는 영어를 사용하는 사람이고 저희는 한국어를 사용하는 사람입니다. 영어와 한국어의 차이가 있듯, 본 가이드에서도 해당 차이를 생각해서 일부 변경 하였음을 알려 드립니다.

목적

Git Commit Message Style Guide의 목적은 Commit Message를 통해서 추가/수정사항에 커밋 메시지만으로 파악이 가능하고, 빠르게 원하는 커밋 내용을 확인하고 파악하게 하는데 있습니다.

메시지 구조

  • 커밋 메시지의 기본적인 구조는 제목(Subject), 본문(Body), 꼬리말(Footer) 3개의 구역으로 나누며, 각 구역은 한 칸의 빈 줄로 구분합니다.

    type: [#issueNumber - ]Subject
    
    Body
    
    Footer
    
  • 각 구역별 가이드 내용을 공유하기 전 원문의 가이드 내용이 적용된 예시를 먼저 보여주겠다.
    이것을 보면 가이드의 내용을 보지 않더라도 어떤 형식을 취하는지 이해할 것이라 생각한다.

     feat: Summarize changes in around 50 characters or less
    
     More detailed explanatory text, if necessary. Wrap it to about 72
     characters or so. In some contexts, the first line is treated as the
     subject of the commit and the rest of the text as the body. The
     blank line separating the summary from the body is critical (unless
     you omit the body entirely); various tools like `log`, `shortlog`
     and `rebase` can get confused if you run the two together.
    
     Explain the problem that this commit is solving. Focus on why you
     are making this change as opposed to how (the code explains that).
     Are there side effects or other unintuitive consequenses of this
     change? Here's the place to explain them.
    
     Further paragraphs come after blank lines.
    
     - Bullet points are okay, too
    
     - Typically a hyphen or asterisk is used for the bullet, preceded
        by a single space, with blank lines in between, but conventions
        vary here
    
     If you use an issue tracker, put references to them at the bottom,
     like this:
    
     Resolves: #123
     See also: #456, #789
    

제목(Subject)

  • 제목은 항시 입력해야 하며 반드시 타입과 함께 작성되어야 합니다.
  • type: [#issueNumber - ]Subject형태로 작성합니다.
    • 개인/팀의 스타일에 따라 typeSubject의 위치 또는 표현 방식(:대신 []로 감싼 다던가)은 마음껏 변경해도 됩니다. 다만, 반드시 제목은 작성해야 하며, 제목에는 typeSubject가 함께 작성되어야 합니다.
    • []안의 내용은 옵션이며 Github등 이슈 트래킹이 가능한 도구를 함께 쓴다면 #1234와 같이 이슈트래킹에서 제공하는 이슈 번호를 제목 앞에 넣어 주면 됩니다. ex) feat: #1234 - 회원 생성 서비스 추가
    • 하나의 이슈에 대한 처리일 경우 이슈 번호를 다는 것도 좋지만 여러 개의 이슈가 합쳐진 경우 제목에 이슈 번호를 달지 않는 게 더 좋습니다.
  • 타입은 영문 소문자로 작성합니다.
  • 제목은 최대 50자를 넘지 않도록 주의합니다.
    • 요즘에는 모니터 해상도조 좋아지고 하드웨어 스펙들도 좋아져서 50자를 넘겨 70자 정도까진 괜찮은거 같다.
  • 제목은 해당 커밋에 대한 주요 내용을 간략하게 기록합니다.
    • 원문에서는 명령조로 작성하라고 되어 있지만, 실제 명령문이라기보다는 동사원형으로 쓰라는 설명입니다. 한국어를 명령조로 쓰게 되면 말이 이상할 뿐만 아니라 커밋 메시지를 보는 사람도 이상하게 느낄 겁니다. 우리나라 정서상 그런 것인 거죠.
      그래서 커밋 메시지는 50자를 넘지 않는 한도 내에서 작업한 내용을 의미하도록 작성하면 되도록 규칙을 정했습니다.
    • 단, 구문 형태, 또는 과거 형태 중 하나를 선택하도록 했습니다.
      • 예를 들어, 구문이면, 회원 생성 서비스 추가 이런 식으로 작성할 것이고, 과거 형태면, 회원 생성 서비스를 추가함 이런 식으로 작성하겠죠.
    • 커밋의 내용을 한방에 표현할 수 있는 제목이면 가장 좋습니다.
    • 또한 원문에서는 영어의 표현이기 때문에 첫 글자를 항시 대문자로 작성하고 있습니다.
  • 제목의 마지막에 마침표(.)을 찍지 않는다.

타입(type)의 종류

아래 타입의 종류를 모두 사용할 필요는 없다, 프로젝트의 성격이나 상황에 맞춰서 적절하게 골라서 사용하면 되는데 fix, docs, style, refactor, test, chore의 타입을 기본으로 하고, feat를 사용하거나 new, improve를 사용하는 것 중 하나를 선택하고, 릴리스에 대한 별도의 커밋을 남기고 싶은 경우 release 타입을 추가하면 된다.
전 회사의 경우 feat, fix, docs, sytle, refactor, test, chore를 사용했었다.

  • feat: 새로운 기능을 추가하거나 기존의 기능을 요구 사항 변경으로 변경한 경우
    기능 추가와 수정을 나누어서 쓰고 싶은 경우 아래 처럼 2개로 나누어서 타입을 지정할 수 있다.
    • new: 새로운 기능을 추가 한 경우
    • improve: 기존 기능을 수정 한 경우, 요구 사항이 변경되어 수정된 경우에도 improve 타입으로 한다.
  • fix: 기능상 버그 픽스를 했을 경우
  • docs: 문서(주석)의 추가/수정의 경우, 직접적인 코드의 변화 없이 순수하게 문서(주석)만 추가/수정했을 경우
  • style: 코드 스타일 변경의 경우, lint를 적용하기 위해서나, 코드 리뷰 등으로 로직(기능)의 변화 없이 단순 함수 내부에서만 사용하는 이름을 변경하였거나, 코드 pretty 등을 적용했을 경우
  • refactor: 기능의 변화가 아닌 코드를 리팩토링했을 경우
  • test: 테스트 코드를 별도로 추가하거나, 변경했을 경우, 만약 기능을 추가하면서 테스트 코드를 동시에 작성했으면 feat 타입으로 사용
  • chore: 기능/테스트 코드, 문서, 스타일, 리팩토링을 제외한, 배포, 빌드 등과 같이 프로젝트의 기타 작업들에 대해 추가/수정했을 경우
  • release: 릴리스를 하기 위해 패키지 버전을 올리거나, 릴리스 버전 커밋을 찍기 위한 경우

git emoji를 사용할 경우 타입을 이모지로 대체하거나 타입 앞에 이모지를 붙여 사용한다.

본문(Body)

  • 커밋에서 수정된 상세내역을 작성한다. 여기선 평서문으로 작성하면 된다.
  • 본문은 생략 가능하며, 제목(Subject) 라인과 반드시 한 줄을 띄운다.
  • 되도록 한 줄에는 72자 이하로 작성하고 길어질 경우 개행해서 다음 줄에 입력한다.
    • 제목과 마찬가지로 100자 정도까지는 괜찮은 거 같다.
  • 수정 내역을 블릿 기호(*) 이용해서 하나씩 입력하는 방법도 좋다.
  • 본문의 내용은 어떻게보다는 무엇을 왜에 맞춰 작성한다.
    • 본문에는 이 커밋이 무엇을 왜 고쳤는지 적혀 있는 것이 나중에 히스토리 파악하거나, 코드의 변경 의미를 파악하기에 훨씬 도움이 된다.
    • 어떻게 고쳐졌는지는 코드의 히스토리를 통해 충분히 파악할 수 있으니 반드시 무엇을 왜 했는지에 대해 작성하도록 한다.

꼬리말(Footer)

  • 꼬리말을 해당 커밋과 연관된 이슈 트래킹 번호를 입력합니다.
  • 제목에는 커밋이 온전히 한 개의 이슈에 해당하는 경우에만 추가해서 사용하고 그 외의 경우 대부분 꼬리말에 이슈 번호를 라벨과 함께 추가합니다.
  • 꼬리말은 생략 가능하며, 반드시 제목(Subject) 또는 본문(Body) 라인과는 반드시 한 줄을 띄운다.

     Resolves: #1234
     See also: #1235, #1236
    

라벨의 종류

  • Resolves: 문의나, 요청에 의한 이슈에 해당하는 경우 이슈 번호
  • Closes: 일반적인 개발과 관련된 이슈에 해당하는 경우 이슈 번호
  • Fixes: 버그 픽스, 핫 픽스 관련 이슈에 해당하는 경우 이슈 번호
  • See also: 커밋의 이슈와 연관되어 있는 이슈들이 존재 하는 경우, 또는 관련된 이슈들이 있는 경우 이슈 번호

마무리

마지막 꼬리말(Footer)의 라벨의 경우, Resolves 한 가지만 사용해도 된다, Github의 경우 Commit Message 또는 Pull Request의 경우 메시지에 있는 키워드로 이슈를 닫을 수 있는데 그때 위 라벨의 Resolves, Closes, Fixes로 닫을 수 있다.
그 외 추가로 필요하다면 꼬리말에 이슈 관련 번호를 입력해서 커밋을 통해 실제 해당 커밋의 배경이 어떠한지를 추적 가능하게 하게 하면 된다.
그리고, 제목 및 내용에서의 글자 제한을 두는 것을 git log통해 로그를 확인할 때 글자가 잘려 보이는 것들을 방지하기 위함도 있지만, 너무 길게 주저리주저리 쓰기보단 간결하게 쓰기를 원하는 것 같다.

위 가이드의 내용은 Udacity Git Commit Message Style Guide 기반으로 사용하면서 불편한점들을 다른 사용자들의 가이드를 참고해서 일부 수정한 것들이다.
개인/팀 단위의 작업을 하면서 위 가이드를 참고하여 새로운 자신만의 커밋 가이드를 만들어 보기 바란다.

참고한 사이트

Comments

comments powered by Disqus