좋은 깃(Git) 커밋 메시지 작성하기
부. 어떻게 깃 커밋 메시지를 작성해야 잘 썼다고 소문이 날까요? 안나요 그런거.
들어가기 전에
우리가 왜 깃 커밋 메시지를 작성하는지 생각해 봅시다.
- 코드 리뷰를 빠르게 하기 위해. (speed up the reviewing process)
- 릴리즈 노트를 작성할 때 도움이 되기 때문에. (help us write a good release note)
- 심지어 5년 후에 그 코드를 다시 봤을 때 왜 그 기능이 추가됐는지, 그리고 왜 그 코드를 변경했는지 알 수 있게 하기 위해.
이는 코드의 리뷰 및 디자인을 더욱 쉽게 하기 위해 DVCS(Distributed Version Control System)를 사용하는 목적과 거의 동일합니다.
하지만 대부분의 많은 개발자가 (D)VCS를 사용하고 있음에도 불구하고, 제대로 된 커밋 메시지를 작성하지 않고 있습니다. 또는 난해하고 지저분한 커밋 메시지를 작성합니다.
예를 들어 다음과 같이 말이죠:
(짤은 https://xkcd.com/1296/ 에서 퍼왔습니다.)
제일 심각한 문제점은 대부분의 Git 프로젝트는 협동 프로젝트(collaborative)이며 최소 두 명 이상의 개발자가 진행하는 프로젝트가 많다는 점입니다. 이럼에도 불구하고 사람들은 커밋 메시지를 대충대충 작성하려 합니다.
이 글에서는 이에 대해 전반적으로 왜 위의 커밋 메시지가 잘못되었는지 그리고 어떻게 개선할 수 있는지에 대해 설명합니다.
초간단 요약 작성방법
50자 이내의 짧은 커밋 요약을 작성합니다.
더 구체적으로 설명할 게 있다면 subsequential lines인 이 곳에 작성합니다. 이 곳에 쓰이는 텍스트는 70자를
넘지 않아야 합니다. 어떤 맥락에서 보면 첫 줄은 이메일의 제목, 나머지 공간은 이메일의 본문과 같은 것이죠.
첫 줄의 내용과 나머지 내용은 나머지 내용을 아예 작성하지 않는한 무조건 띄워둬야 합니다.
- 이렇게 써도 됩니다. (Bullet points are okay, too)
- 보통 하이픈(hyphen)이나 별표(asterisk)가 사용되고 사이에는 빈 공간을 둡니다. 이는 컨벤션에 따라
달라질 수도 있습니다.
이렇게 쓰세요
1. 당신이 무엇을 끝냈는지에 대해 명령조로 작성하세요.
예를 들어 다음과 같이 말이죠:
- Clean your room
- Close the door
- Take out the trash
- Turn off the light
1-1. 커밋 메시지를 과거형으로 작성하지 마세요.
Fixed 대신 Fix, Added 대신 Add, Changed 대신 Change 로 작성하세요.
2. 첫 줄은 50자 내로, 나머지 줄은 70자 내로 작성하세요.
대부분의 에디터에서는 텍스트 라인 경고를 지원합니다. vim을 사용하는 경우 ~/.vimrc 파일을 열고 다음 줄을 넣으세요:
autocmd Filetype gitcommit setlocal spell textwidth=72
3. 두 번째 줄은 항상 비워둬야 합니다.
4. 나머지 줄은 항상 자세하게 적어두세요.
코드에 어떠한 문제가 있었고 왜 그 문제가 발생했고, 최종적으로 새로 작성하거나 수정한 코드는 어떤 코드인지 최대한 자세하게 적으세요. 이것은 다른 개발자가 무엇을 왜 수정했는지에 대해 쉽게 이해할 수 있도록 도와줍니다.
또한 GitHub 등을 이용해서 Issue를 닫거나 할 때는 Closing issues via commit messages 가이드라인에 맞춰 메시지를 작성하세요.
예를 들어 다음과 같이 커밋 메시지를 작성하면:
(주: 아무것도 모를 때 쓰던 커밋 메시지임.)
이렇게 이슈가 자동으로 닫히게 됩니다:
또한 커밋 메시지에 다음과 같이 입력할 경우 이슈를 참조(reference)할 수 있습니다:
* SHA: a630c56cdbc1858068995f9b7a515172189bf812
* User@SHA: ssut@a630c56cdbc1858068995f9b7a515172189bf812
* User/Repository@SHA: ssut/PushBank@a630c56cdbc1858068995f9b7a515172189bf812
* #Num: #1
* GH-Num: GH-1
* User#Num: ssut#1
* User/Repository#Num: ssut/PushBank#1
(전부 같은 링크니까 하나하나 안 눌러보셔도 됩니다... 쓰레기스러운 커밋이니 지적은 달게 안 받습니다...)
5. 커밋 메시지 제목의 첫 글자는 대문자로 적으세요.
말 그대로 간단합니다. 모든 제목 줄의 첫 글자는 반드시 대문자로 적으세요.
단편적인 예로 어떤 메시지가 더 깔끔해 보이고 읽기 편한지 확인해보세요:
(사실 둘 다 막 휘갈겨 써서 읽기 편하지가 않..)
6. 제목 줄에 무엇을 추가했는지 적었고 더 이상 설명할 필요가 없어도 해당 커밋이 무엇을 의미하는지, 어떤 역할을 할 수 있는지에 대해 추가로 적으세요.
또한 왜 이 커밋을 작성했는지에 대해서도 추가로 작성하면 더 좋습니다: 예시
7. 가능한 간결하게, 문법에 맞게 작성하세요.
저도 자주 하는 실수입니다. 아직 영어로 커밋 메시지를 작성하는 것이 익숙하지가 않고 간혹 다른 사람의 코드를 보면서 "Fix ~ feature"라고 쓴 커밋들이 많이 보이기 때문에 이를 "Fixes"로 써야 하는지에 대한 해답을 얻지 못할 때가 상당히 많습니다. (다른 사람의 코드를 보면 실력이 늘어난다지만 커밋 메시지 작성 방법은 개개인마다 차이가 크기 때문에 더욱 혼란스럽게 하는 것 같습니다. 게다가 영어도 못해서.. 영어권 사람들이 이렇게 쓰면 더 헷갈린다는.. ㅠㅠ)
가능한 간결하게, 문법에 맞게, 마치 Documentation을 작성하듯 작성하세요. 오타를 최대한 줄이고 올바른 구두점을 사용하면 더 좋습니다.
이렇게는 쓰지 마세요
1. 마침표로 첫 줄을 끝내지 마세요.
마침표는 제목 줄에는 전혀 필요하지 않습니다. 또한 제목 줄을 50자 내로 작성하기 위해서는 더더욱이 말이죠.
이는 보통의 영문 이메일에서 다음과 같이 제목에 마침표를 쓰지 않는 것과 유사합니다:
(애증의 뉴에그)
정리
위에서 말한 모든 것을 지키기란 참 어렵습니다. 오히려 위에 나와있는 커밋 메시지 룰을 지키다가 코드를 작성/수정한 시간보다 커밋 메시지를 쓰는 시간이 더 길어질 수도 있습니다. 하지만, 위 과정을 통해 한 단계 더 성장할 수 있고 다른 사람들이 당신의 커밋 로그를 볼 때 더 쉽게 이해할 수 있게 됩니다.
물론 위 사항은 모두 public repository에 기여를 할 때에만 해당하는 내용입니다. (단 회사 내에, 또는 특정 레포 내에 커밋 메시지 컨벤션이 따로 정해져 있다면 그 룰을 우선으로 지키는 것이 맞습니다.)
혼자서 쓰는 repository라면 굳이 격식에 맞춰 쓸 필요 없이 간단한 게 작성해도 되겠죠. 하지만 좋은 메시지를 쓰는 방법을 꾸준히 이용한다면 그 습관이 몸에 배어 앞으로도 계속 좋은 메시지를 쓸 수 있는 좋은 발판이 됩니다.
시간이 있다면 그동안 썼던 커밋을 모두 되돌아보고 과연 내가 좋은 커밋 메시지를 작성했는지에 대해 다시 한 번 생각해보고, 커밋 메시지를 다시 작성해보시는 건 어떨까요?