코드로 쓰는 편지, 동료의 마음을 여는 커밋 메시지
그때 그 커밋, 왜 그렇게 바꿨는지 기억나시나요?
오래된 프로젝트 폴더를 열어본 적 있으신가요? 저는 가끔 몇 년 전 제가 썼던 코드를 마주할 때가 있습니다. 마치 낯선 타임캡슐을 여는 기분이죠. 코드는 어찌어찌 이해하겠는데, 정작 저를 혼란에 빠뜨리는 것은 다름 아닌 커밋 로그였습니다.
“bug fix”
,
“update”
,
“수정”
과거의 저는 미래의 저에게 너무나 불친절했습니다. 그 코드를 왜 바꿨는지, 어떤 고민 끝에 나온 해결책이었는지, 로그만 봐서는 도무지 알 길이 없었죠.
그 막막했던 경험 이후로, 저는 커밋 메시지를 다르게 보기 시작했습니다. 그것은 단순한 변경 기록이 아니라, 미래의 나와 동료에게 보내는 한 통의 편지라는 것을요. 잘 쓴 커밋 메시지는 흩어진 코드 조각들을 하나의 이야기로 엮어주는 힘을 가집니다. 오늘은 제가 동료들과 함께 일하며 깨닫게 된, 코드로 다정한 편지를 쓰는 법에 대해 이야기해볼까 합니다.
좋은 메시지는 오늘의 나를 도와줄 뿐 아니라, 내일의 나와 동료들에게 선물이 됩니다.
왜 우리가 이토록 커밋 메시지에 마음을 쏟아야 할까요? 저는 그 이유를 세 가지로 정리하고 싶습니다. 첫째, 코드의 역사를 한눈에 보여주는 멋진 연대표가 됩니다. 둘째, 코드 리뷰 과정에서 동료가 나의 의도를 쉽게 파악할 수 있어 협업이 즐거워집니다. 마지막으로, 먼 훗날 코드를 다시 손봐야 할 때 빠르고 정확한 유지보수를 가능하게 합니다. 결국, 정성 들여 쓴 메시지는 우리 모두를 위한 일이었습니다.
우리의 코드를 위한 여덟 가지 약속
효율적인 협업을 위해, 특히 영어로 커밋 메시지를 작성할 때 제가 동료들과 함께 지키려고 노력하는 몇 가지 약속이 있습니다. 거창하진 않지만, 꾸준히 실천했을 때 가장 큰 힘을 발휘했던 약속들입니다.
1. 제목과 본문 사이에 숨 쉴 공간을 주세요
커밋 메시지는 '제목'과 '본문'으로 이루어진 한 편의 짧은 글입니다. 이 둘을 한 줄의 공백으로 분리하는 것만으로도 가독성은 놀랍게 달라집니다. 많은 Git 도구들이 제목만 따로 뽑아서 보여주기 때문에, 이 작은 공백 하나가 로그를 훑어보는 동료의 시간을 아껴줍니다.
2. 제목은 50자 이내의 짧은 울림으로
모든 내용을 제목에 담으려 애쓰지 않아도 괜찮습니다. 제목은 이 커밋이 무엇을 하는지 알려주는 가장 핵심적인 한 문장이면 충분합니다. 50자 이내로 짧게 요약하는 습관은 커밋의 핵심을 명확히 하는 훈련이 되기도 합니다.
3. 문장의 시작은 대문자로, 정중하게
"Refactor code"가 "refactor code"보다 훨씬 정돈되어 보이지 않나요? 영문법의 기본 규칙에 따라 제목의 첫 글자를 대문자로 시작하는 것만으로도 메시지 전체에 신뢰감을 더해줍니다.
4. 제목의 끝에는 마침표를 찍지 않아요
제목은 문장의 완결이 아니라, 커밋을 대표하는 표제어와 같습니다. “Fix bug.”처럼 끝에 마침표를 붙이면 어색하게 느껴질 수 있습니다. 간결하게 핵심만 남겨두는 편이 좋습니다.
5. 제목은 ‘무엇을 하는지’ 명령형으로
"Add new feature", "Update documentation"처럼 동사원형을 사용한 명령형으로 문장을 시작해보세요. Git이 자동으로 만들어주는 메시지도 이 형식을 따릅니다. 혹시 헷갈린다면, 마음속으로 “만약 이 커밋이 적용된다면, 이 커밋은...(If applied, this commit will...)” 뒤에 제목을 붙여보세요. 문장이 자연스럽게 이어진다면 아주 잘 쓰신 겁니다.
6. 이슈 번호로 길을 잃지 않게
GitHub 이슈 트래킹을 사용한다면, 커밋 메시지에 이슈 번호를 남기는 것은 정말 중요한 약속입니다. “Fix #23 - login bug”처럼 제목이나 본문에 이슈 번호를 적어두면, 클릭 한 번으로 해당 이슈 페이지로 이동할 수 있어 논의의 흐름을 놓치지 않게 도와줍니다.
7. 본문은 72자마다 잠시 쉬어가세요
때로는 제목만으로 설명이 부족해 본문을 길게 작성해야 할 때가 있습니다. 이때 72자가 넘어갈 때마다 줄을 바꿔주면, 어떤 환경에서 로그를 보더라도 글이 화면 밖으로 잘려나가지 않고 깔끔하게 보입니다.
8. 본문에는 ‘어떻게’보다 ‘무엇을, 왜’를 담아
코드는 ‘어떻게’ 구현했는지를 이미 보여주고 있습니다. 우리는 본문을 통해 이 변화가 **‘무엇’**이며, ‘왜’ 필요했는지에 대한 이야기를 들려주어야 합니다. 이 배경 스토리가 동료의 이해를 돕고, 더 나은 코드 리뷰로 이어지게 합니다.
실무의 마법, 깃허브와 교감하는 작은 팁
이슈를 자동으로 닫는 마법의 키워드
혹시 커밋 메시지 하나로 깃허브 이슈까지 자동으로 닫을 수 있다는 사실, 알고 계셨나요? close, fix, resolve 같은 키워드와 함께 이슈 번호를 적으면, 해당 커밋이 메인 브랜치에 병합될 때 마법처럼 이슈가 종료됩니다.
Close #31 - refactoring wrap-up
이 작은 자동화 하나가 프로젝트 관리의 번거로움을 크게 줄여주더군요. 여러 이슈를 한 번에 닫고 싶다면 본문에 아래처럼 적어주면 됩니다.
Update policy settings
This closes #128 and fixes #78.
내 터미널을 아름답게, git lg
기본 git log 명령어는 때로 너무 많은 정보를 한꺼번에 보여줘서 오히려 혼란스러울 때가 있습니다. 저는 git lg라는 별칭(alias)을 만들어 사용하는데요, 아래 명령어를 터미널에 한 번만 입력해두면 앞으로는 git lg만으로 훨씬 아름답고 구조화된 로그를 만날 수 있습니다.
git config --global alias.lg "log --graph --abbrev-commit --decorate --date=relative --format=format:'%C(bold red)%h%C(reset) : %C(bold green)(%ar)%C(reset) - %C(cyan)<%an>%C(reset)%C(bold yellow)%d%C(reset)%n%n%w(90,1,2)%C(white)%B%C(reset)%n'"
색깔과 그래프로 표현된 커밋의 흐름을 보고 있으면, 복잡했던 프로젝트의 역사가 한눈에 들어오는 기분 좋은 경험을 하게 될 겁니다.
이제, 당신의 코드가 이야기를 시작할 시간입니다
커밋 메시지는 더 이상 귀찮은 의무가 아닙니다. 동료와 소통하고, 미래의 나를 돕는 가장 확실하고 효율적인 방법입니다. 오늘 제가 소개해드린 약속과 팁들을 하나씩 실천해보세요. 당신의 커밋 로그가 동료들에게는 친절한 안내서가, 당신에게는 든든한 성장 기록이 되어줄 겁니다.
이제 당신의 코드가 어떤 이야기를 품고 있는지, 세상에 들려줄 차례입니다.
