Original article: How to Write Good Commit Messages: A Practical Git Guide
쓸모 있는 개정 이력을 생성하기 위해 조직과 팀은 가장 먼저, 사용할 커밋 메세지 규칙에 동의해야 합니다. 이것은 개인 프로젝트도 마찬가지죠.
최근에 저는 Hashnode에 **"직장에서 어떤 커밋 메세지 규칙을 사용하고 있는지"**라는 질문을 해봤는데, 몇몇 커뮤니티 유저들로부터 그들이 직장에서 또는 개인 프로젝트를 위해 사용하는 규칙에 관한 훌륭한 답변을 받았습니다.
이 글을 통해 저는 좋은 커밋 메세지 작성하는 법과 우리가 왜 이 작성법을 따라야 하는지에 대해 설명하겠습니다.
이 글은 다른 글들과 함께 제 블로그에도 게시되었습니다.
깃으로 버전 컨트롤하기
버전 컨트롤 소프트웨어는 현대 사회 소프트웨어 개발자 실무에 중요한 부분입니다.
여태껏 깃은 세계에서 가장 광범위하게 사용되는 버전 컨트롤 시스템입니다. 깃은 리눅스 운영 시스템 커널의 유명 개발자인 리누스 토르발스가 2005년 최초로 개발한 오픈 소스 프로젝트이며, 배포된 이후 활발히 유지돼 왔습니다.
깃이 처음이신가요? 공식 가이드 문서 시작하기 또는 지난 대화에서 제가 드린 슬라이드를 확인해보세요.
커밋 메세지란?
커밋 명령어는 깃 안에 staging(번역자 주: 커밋으로 저장소에 기록할 수정사항을 대기상태로 만들기)을 한 이후 로컬 리포지토리(repository)에 발생한 변화를 저장하는 데 사용됩니다. 그러나 깃에서 변경점들을 저장하기 이전에 깃에게 사용자가 만든 수 많은 수정사항 중 어떤 변경점을 저장하고 싶은 것인지 말해야 합니다. 변경점들을 구분하기 위해 굉장히 좋은 방법은 바로 커밋 메세지를 추가하는 것입니다.
커밋 옵션들
- -m
해당 옵션은 커밋 메세지를 설정합니다.
git add static/admin/config.yml
git commit -m "Setup multiple roles for netlify-cms git gateway"
- -a 또는 -all
해당 옵션은 (새로운 걸 포함한) 모든 tracked, modified, 또는 deleted 상태의 파일들을 자동으로 커밋합니다.
git commit -a -m "Add a new role for netlify-cms git gateway"
- --amend
해당 옵션은 현재 staged된 변경 사항 또는 새 커밋 메세지로 마지막 커밋을 다시 작성하며 아직 원격 저장소에 푸시되지 않은 커밋에서만 실행해야 합니다.
git add .
git commit --amend -m "Update roles for netlify-cms git gateway"
좋은 커밋 메세지를 써야 하는 이유
어쩌면 당신은 "이건 그냥 개인 프로젝트일 뿐"이라 말할지도 몰라요. 그렇죠, 지금은 혼자 일하니까요. 하지만 어떤 팀과 함께 일할 때나 오픈 소스에 기여할 때는 어떻게 될까요?
잘 작성된 깃 커밋 메세지는 해당 프로젝트에서 작업하는 다른 개발자들에게 새로운 내용이나 수정사항에 대한 배경을 소통하는 최고의 방법이며 실제로 미래의 당신 스스로에게도 남겨두는 방법입니다.
오래된 프로젝트 중 하나에 git log를 실행해보고 프로젝트 초기부터 사용한 "이상한" 커밋 메세지를 발견한 적 있나요? 과거에 어떠한 작업을 왜 했는지 이해하기 어려울 수도 있고, 이 글을 좀 더 일찍 읽었길 바랄 것입니다 $:)$.
커밋 메세지는 어떤 변화가 왜 만들어졌는지 적절히 소통할 수 있고, 커밋 메세지의 중요성을 깨닫게 되면 개발 및 협업 작업을 더 효율적이게 할 수 있습니다.
깃으로 커밋 메세지 작성하는 법
이전에 저는 제 개인 프로젝트에서 git commit -m "Fix X to allow Y to use Z"으로 어떤 제목만 적고 추가 설명은 없는 방식만 사용하였습니다. 이 방식은 git commit -m "Fix typo in README.md"와 같은 작고 명확한 수정사항들을 커밋할 때 적합합니다. 하지만 좀 더 큰 규모의 작업 같은 경우에는 부연설명을 추가할 필요가 있을 것입니다.
에디터를 활용한 방법
아무런 메세지나 옵션 없이 git commit을 실행하면 커밋 메세지를 작성할 수 있는 기본 텍스트 에디터가 열릴 것입니다.
기본 에디터를 설정하려면 다음과 같은 명령어를 실행합니다.
git config --global core.editor nano
명령어를 실행하면 깃에 기본 에디터를 nano로 설정하는 것입니다. "nano"를 "emacs", "vim", 또는 무엇이든 선호하는 에디터로 변경하세요.
열린 에디터 안의 첫번째 줄은 제목(및 짧은 설명)이 되고, 빈 줄 하나를 띄운 후 그 외 모든 것들이 본문 및 부연 설명으로 저장됩니다.
<Summarize change(s) in around 50 characters or less>
<More detailed explanatory description of the change wrapped into about 72
characters>
커맨드라인(Command Line)을 활용한 방법
git commit -m "Subject" -m "Description..."
첫번째 -m 옵션은 제목 및 짧은 설명을 가르키고 다음 -m 옵션은 본문 및 부연 설명을 가르킵니다.
좋은 커밋 메세지 작성하는 법
다양한 팀과 개발자들이 좋은 커밋 메세지를 작성하기 위해 따르는 몇 가지 규칙이 있습니다. 저는 커밋 메세지를 작성하기 위한 몇 가지 일반적인 규칙과 팁에 대해서만 간략히 설명할테니 여러분이 따르고 싶은 관습을 스스로 결정하시면 됩니다. 그리고 만약 어떤 회사에서 일하거나 오픈 소스에 기여한다면 그 기관이나 프로젝트의 커밋 메세지 작성 방식을 따라 적용해야 합니다 $:)$.
일관성을 위해 직장 업무 볼 때는 하나의 커밋 메세지 작성법을, 개인 프로젝트일 때는 다른 방식을 사용할 수 있으며, 또한 방식 자체가 때에 따라 바뀔 수도 있습니다.
이곳에서 몇 가지 굉장한 커밋 메세지 작성법을 꼭 확인해보세요. 누군가 결정을 내리는데 도움이 될지도 모르니 본인만의 작성 규칙에 대해 적어놓아도 좋습니다.
여기에는 팀 포프(Tim Pope)가 작성한 매우 좋은 커밋 메세지 양식이 있습니다.
(영어의 경우 대문자로) 50자 이내 짧은 요약
만약에 필요하다면 보다 자세한 설명을 여기에 쓴다. 내용은 72자 내외에서 마무리하는 것을 권장한다. 어떤 맥락에서는 첫번째 줄은 이메일의 제목처럼 취급되고 나머지가 본문으로 간주된다. 빈 칸 한 줄은 본문과 요약문 및 제목을 구분하기 위한 것으로 본문 전체를 생략하지 않은 이상 필수로 있어야 한다; rebase같은 도구들은 이 본문과 요약문 사이에 빈 칸 한 줄이 없으면 혼란스러워하는 경우도 있다.
커밋 메세지는 명령형으로 적자: 예를 들어 "Fix bug"로 적어야지 "Fixed bug"나 "Fixes bug"가 아니다. 이러한 관습은 git merge나 git revert와 같은 명령어에 의해 생성된 커밋 메세지와 일치하게 된다.
추가 문장들은 빈 칸 한 줄 뒤에 따라온다.
- 글머리 기호가 있어도 괜찮다
- 글머리는 통상적으로 하이픈(-)이나 별(*) 기호 뒤에 한 칸 띄우는 것으로 사용되고 문단과 문단 사이에는 빈 칸 한 줄을 띄우는 것으로 사용되지만 그 외 다양한 법이 존재한다
- 들여쓰기를 사용하자
이슈 트래커를 사용한다면 가장 마지막에 레퍼런스 번호를 이런 식으로 적자.
Resolves: #123
정말 보기 좋지 않나요? 여기 여러분의 메세지도 좋게 만들 수 있는 방법입니다.
- 커밋의 종류를 명시하라.
- feat: 어떤 특정 어플리케이션에 더할 새로운 feature
- fix: 어떤 오류 해결(fix)
- style: 스타일과 연관된 feature나 업데이트들
- refactor: 코드 베이스의 특정 부분을 재정렬(refactoring)
- test: 테스트와 관련된 모든 것
- docs: 문서화에 관한 모든 것
- chore: 정규 코드 유지보수.
또한 커밋 종류를 표현하기 위해 이모티콘을 사용할 수도 있습니다.
- 제목을 본문으로부터 빈 칸 한 줄 띄워 구분하라
- 커밋 메세지는 어떠한 공백오류(whitespace errors)를 포함하지 않아야 한다
- 불필요한 구두점을 삭제하라
- 제목 행을 마침표(.)로 끝맺지 마라
- (영어일 경우) 제목 행과 매 문단의 시작을 대문자로 하라
- 제목 행에는 명령어를 사용하라
- 본문 영역은 적용한 변경 사항과 그것을 만든 이유에 대해 설명하기 위해 활용하라
- 검토자들이 본래 문제가 무엇이었는지 이해하고 있을 것이라 가정하지 말고 그것을 더해 적어라
- 본인의 코드가 설명 없이도 괜찮다고 생각하지 마라
- 소속되어 있는 팀의 정해진 커밋 규칙을 따르라
마치며
커밋 메세지에서 가장 중요한 것은 반드시 명확하고 의미가 있어야 한다는 것입니다. 장기적으로 좋은 커밋 메세지를 작성하는 것은 커밋 메세지 작성자가 얼마나 좋은 협력자인지를 보여줍니다. 좋은 커밋 메세지를 작성하여 얻는 이점들은 팀 내에서만 국한되는 것이 아니라 개발자 본인, 또한 미래의 컨트리뷰터(contributors)에게까지 영향을 끼칩니다.
깃에 대해 더 배우고 전문적인 "버전 관리자"가 되고 싶나요? 여기 참고자료들을 확인해보세요: