나의 가장 좋아하는 Git 커밋 (2019)

• GOV.UK 작업 중 나온 Dan Carley의 “Convert template to US-ASCII to fix error” 커밋은 작은 코드 변경도 상세한 커밋 메시지를 통해 코드베이스의 장기 문서가 될 수 있음을 보여줌
• 좋은 메시지는 무엇을 바꿨는지보다 왜 바꿨는지를 남기며, 이 사례는 bundle exec rake 실행 시 발생한 invalid byte sequence in US-ASCII 오류와 재현 조건을 구체적으로 기록함
• 오류 문자열과 조사 과정이 함께 남아 있어, 나중에 같은 문제를 만난 사람이 git log --grep이나 GitHub 커밋 검색으로 이전 해결 기록을 찾을 수 있음
• 메시지에는 find -exec, file --mime, iconv 같은 Unix 도구 사용 과정도 포함돼 리뷰어와 이후 독자가 문제 해결 흐름을 따라갈 수 있음
• 모든 커밋이 이 정도로 길 필요는 없지만, 맥락·조사 과정·감정까지 남긴 메시지는 팀의 공유된 코드베이스 이해와 신뢰를 쌓는 데 도움이 됨

---

작은 변경을 장기 문서로 만든 커밋

• Git 커밋 메시지는 잘 쓰면 코드베이스의 생애 동안 유지되는 강력한 문서화 도구가 될 수 있음
• 사례로 든 커밋은 Government Digital Service에서 GOV.UK를 작업하던 시기의 변경임
• 작성자는 Dan Carley이고, 제목은 “Convert template to US-ASCII to fix error”임
• GDS의 공개 개발 방식 덕분에 이런 조직 내부 사례도 외부에서 공유할 수 있음

길이보다 중요한 맥락

• 이 커밋은 코드 변경량에 비해 메시지가 길지만, 핵심 가치는 길이 자체가 아니라 유용한 맥락에 있음
• 같은 변경이 다른 곳에서는 change whitespace, fix bug처럼 짧게 남았을 수도 있음
• Dan은 주변 동료와 이후 독자가 문제의 원인과 해결 과정을 이해할 수 있도록 상세한 기록을 남김

바뀐 내용보다 왜 바뀌었는지

• 좋은 커밋 메시지는 바뀐 내용뿐 아니라 왜 바뀌었는지를 설명함
• 이 커밋은 feature branch에서 /etc/nginx/router_routes.conf 내용과 맞추는 테스트를 추가한 뒤, 실행 방식에 따라 결과가 달랐다는 점을 기록함
  • bundle exec rake spec 또는 bundle exec rspec modules/router/spec로 실행하면 정상 동작함
  • bundle exec rake로 실행하면 각 should 블록이 실패함
  • 오류는 ArgumentError: invalid byte sequence in US-ASCII임
• 이런 설명이 없었다면 어떤 도구에서 어떤 파싱 오류가 났는지 추측해야 했을 가능성이 큼
• 원래 작업 맥락은 사람이 잊거나, 팀을 옮기거나, 조직을 떠나면서 쉽게 사라질 수 있음

검색 가능한 오류 기록

• 커밋 메시지 초반에는 변경의 계기가 된 오류 메시지가 그대로 들어 있음
• 같은 오류를 만난 사람은 다음 방식으로 코드베이스에서 이전 기록을 찾을 수 있음
  • git log --grep "invalid byte sequence"
  • GitHub commit search
• 검색 결과상 여러 사람이 이 오류를 검색했고, 누가 먼저 문제를 만났는지와 어떤 조치를 했는지도 확인할 수 있었음

문제 해결 과정을 이야기로 남김

• 메시지는 문제가 어떻게 보였는지, 어떤 순서로 조사했는지, 결국 어떻게 고쳤는지를 따라갈 수 있게 구성됨
• 예시로 .with_content(//) matcher를 제거하면 오류가 사라졌고, spec 파일에는 이상한 문자가 없었으며, 같은 인터프리터에서 Puppet을 require하면 재현할 수 있었다는 내용이 포함됨
• 커밋 메시지는 특정 파일·함수·코드 한 줄이 아니라 변경 자체를 문서화하므로, 코드베이스가 거쳐 온 여정을 기록하기 좋은 위치임

팀 지식을 넓히는 부수 효과

• Dan은 조사 단계마다 실행한 명령을 기록했고, 이는 팀 안에서 지식을 가볍게 퍼뜨리는 방식이 될 수 있음
• 독자는 커밋 메시지만으로도 Unix 도구 사용법을 배울 수 있음
  • find에 -exec 인자를 전달해 찾은 각 파일에 명령을 실행할 수 있음
  • 명령 끝에 \+를 붙이면 파일마다 한 번씩 실행하는 대신 여러 파일명을 하나의 file 명령에 전달함
  • file --mime은 파일의 MIME 타입을 알려줌
  • iconv라는 도구가 존재함
• 변경을 리뷰하는 사람뿐 아니라 나중에 이 커밋을 찾는 사람도 같은 정보를 얻음
• 충분한 시간과 커밋이 쌓이면 이런 메시지는 팀의 지식 증폭 장치가 될 수 있음

공감과 신뢰를 쌓는 기록

• 커밋 마지막에는 “Now the tests work! One hour of my life I won't get back..”이라는 문장이 있음
• 이 문장은 한 시간 동안 교묘한 버그를 추적한 개발자의 좌절과 해결했을 때의 만족감을 전함
• 단기 해킹이나 프로토타입 코드가 프로덕션에 들어가 뿌리내린 경우에도, 이런 메시지는 모든 변경 뒤에 당시 정보 안에서 최선의 결정을 내린 사람이 있었다는 점을 떠올리게 함

모든 커밋이 길 필요는 없음

• 이 사례는 극단적인 예이며, 특히 이 정도 크기의 모든 커밋에 같은 수준의 상세함을 기대할 필요는 없음
• 그래도 변경 뒤의 맥락을 설명하고, 다른 사람이 배우게 하며, 팀의 코드베이스에 대한 공동 정신 모델에 기여하는 좋은 예임
• 좋은 커밋 메시지와 변경 구조화 도구에 관심이 있다면 다음 자료를 볼 수 있음
  • Telling stories through your commits by Joel Chippindale
  • A branch in time by Tekin Süleyman

[GN⁺]

Hacker News 의견들

• 좋든 나쁘든, GitHub 공동창업자이자 Pro Git 같은 Git 책을 쓴 입장에서 보면, Git 커밋 메시지는 코드 문서화의 독특한 경로지만 매우 비효율적임
  핵심 문제는 Git, GitHub 등 대부분의 도구가 보통 첫 줄만 보여준다는 것임. 예시 커밋도 “US-ASCII error” 같은 일반적인 한 줄만 보이고, 글에서 칭찬하는 나머지 내용은 현대 도구에서는 거의 아무도 보지 않음
  Git은 커밋 메시지를 프로젝트 모두가 읽는 이메일 본문으로 설계했지만, 오늘날에는 대체로 그런 역할을 하지 않음. 메일링 리스트에서 패치 시리즈로 논의되지 않는 한, 제목의 첫 50자 말고는 거의 읽히지 않음
  git blame에서 -w -C -C -C인지 -C 두 개인지 찾아 관련 메시지를 추적해도 첫 줄만 보이고, 결국 SHA를 찾아 git show를 해야 긴 메시지를 볼 수 있음. 잘 써도 정보를 다시 찾기가 너무 어렵다는 게 Git에 대한 가장 큰 불만 중 하나임
  Git 프로젝트 기록을 보면 커밋 메시지는 거의 매번 훌륭하지만, 파일 하나에 blame을 돌려도 함수 구현의 맥락을 따라가기는 매우 어려움. Jeff King이 지난 10년간 남긴 문서화는 천재적인 수준인데 거의 아무도 감상하지 못한다는 점이 끔찍함
  정확한 해법은 모르겠지만, 대부분의 커뮤니티에서 커밋 메시지로 훌륭한 문서를 쓰는 일은 슬프게도 거의 시간 낭비에 가까움. 찾기가 너무 어렵기 때문임

  • GitHub가 있기 전부터 Git에 기여했고 레거시 코드를 유지보수해 온 입장에서는 전혀 동의할 수 없음. 터미널에서 git blame, git log, git show를 늘 쓰고, 파일 기록을 따라가는 건 쉽고 git log -G로 추가·삭제 시점을 찾는 데 몇 초면 충분함
    힘든 건 커밋을 찾아냈는데 메시지가 “bleh”나 “add a thing”뿐일 때임. 개발자가 60초만 들여 왜 그렇게 했는지 적었으면 됐을 텐데 말임
    반대로 어떤 변경이 왜 이루어졌는지 자세히 설명한 커밋 메시지를 찾으면 정말 기쁨. 좋은 커밋 메시지 하나가 몇 시간, 며칠의 일을 아껴줌
    GitHub도 나쁜 커밋 메시지 문제에 기여함. 운 좋으면 PR 설명에 세부 내용이 있지만 커밋 로그 바로 옆에 있지 않고, 대개 PR은 Jira 링크, Jira는 Slack 대화 링크, Slack은 Google 문서 링크로 이어짐
    업계는 문서화를 정말 못하지만 Jeff King 같은 사람들은 제대로 싸우고 있음. 결국 기술 문제가 아니라 사람 문제라고 봄. 문서 작성은 즉각 보상이 없어서 추가 업무처럼 느껴지고, 보상은 며칠·몇 주·몇 달 뒤에야 나타남
    제발 좋은 커밋 메시지를 쓰면 좋겠음. 왜 했는지만 1분 들여 적어도 모든 커밋이 빌어먹을 체스터턴의 울타리 풀이가 되지 않음. 쉽게 찾을 수 있는 커밋 메시지에 넣어두면 미래의 자신과 내가 고마워할 것임
    덧붙이면, 커밋 메시지를 찾기 어렵다는 주장에도 동의하지 않음. 코드 한 줄, 함수, 파일의 역사를 따라가는 데 거의 어려움을 느끼지 않으며, 커밋 메시지는 다시 읽히지 않더라도 작성 당시 가치가 있음. 좋은 메시지를 쓰면 내가 의도한 코드를 실제로 썼는지 확인하게 되고, 코드 리뷰어에게도 가치가 있음
  • “Git은 커밋 메시지를 프로젝트 모두가 읽는 이메일 본문으로 설계했다”는 말은 믿기 어려움. 실제로는 커밋 주제나 변경 파일에 관심 있는 사람이 본문을 읽는 것에 가깝지, 왜 다른 사람이 불변의 역사 문서를 읽어야 하는지 모르겠음
    git blame 옵션을 찾기 어렵다는 말도 농담처럼 들림. 좋은 IDE는 각 줄에 blame 정보를 붙이고 버튼 하나로 차이를 보여주며, 그런 차이에서 문맥 줄이나 삭제된 줄에 대해 재귀적으로 blame을 할 수 있어야 함. Tig 같은 도구는 정확히 그걸 해줌
    GitHub가 커밋 메시지를 보기 어렵게 만드는 건 인정함
    커밋에 붙은 문서는 재미로 쓴 게 아님. 나중에 없을 수도 있는 사람이 보낸 패치를 받아들이는 위험을 줄이고, 관련 생각을 드러내서 다른 사람이 그 위에 작업할 수 있게 하는 장치임. 생각을 숨기면 코드에 대한 배타적 소유권이 쌓이고, 대개 좋은 일이 아님. 커밋 메시지는 작업 증명 역할도 하며, 패치가 너무 많을 때 중요해질 수 있음. 상업 프로젝트에서는 일부 중요성이 낮을 수 있음
  • 터미널 Git은 잘 못하지만 IntelliJ나 Emacs의 Magit을 쓰면 파일을 바꾼 모든 커밋을 쉽게 찾고, 전체 커밋 메시지도 편하게 탐색할 수 있음. 적절한 도구를 쓰면 어렵지 않고, 거의 모두가 비슷한 도구를 갖고 있지 않나 싶음. 정말 Git CLI에만 매달려 수백 개 명령과 플래그를 외우려는 건가, 왜 그러는지 모르겠음
  • 이건 GitHub 등의 실패임. GitHub는 사용자가 커밋 기록을 추론하지 못한다고 보는지 단순화하려 하고, 그 결과 중 하나가 이것임. 특히 비공개 GitHub 저장소의 혼란은 때로 믿기 어려울 정도임
    이런 문서를 둘 곳은 사실 달리 없음. 코드 주석에는 맞지 않음. 그런데 이제는 Git이 곧 GitHub이고, Git의 유일한 목적은 GitHub에 변경사항을 올리는 것이라고 생각하는 개발자 세대가 생김
    Git은 별로지만 다른 것들보다는 훨씬 덜 별로임. 다시 기본으로 돌아가 버전 관리의 실제 목적을 이해해야 함
  • 그래도 역사 연구에는 훌륭함. 코드와 영원히 함께 살아남는 몇 안 되는 문서 중 하나임. GitHub나 다른 중앙화 형태는 사람들이 쉽게 백업·변환·이관하는 개방형 데이터 형식이 아니어서, 프로젝트를 옮기면 보통 데이터를 뒤에 두고 떠남
    그래서 현재 커뮤니티에는 크게 도움이 안 될 수도 있지만, 몇 년 뒤 디버깅하는 사람에게는 도움이 됨

• 전반적 취지에는 동의하지만, 더 구체적인 BLUF를 앞에 두면 좋겠음. 예를 들면 “Fix test issues caused by non-breaking space character \xa0”처럼 쓰는 것임
  문제가 무엇인지 바로 알 수 있고, 더 알고 싶으면 아래를 읽을 자유도 남아 있음

  • 이 메시지가 훨씬 낫다고 봄. GitHub에서 차이를 보면 무엇이 바뀌었는지도 꽤 분명함. 차이가 똑같아 보이는 변경 세트라면 보이지 않는 문자가 추가되거나 제거된 경우밖에 없기 때문임
    그래서 기록 검색용으로는 좋은 첫 줄 메시지만 있으면 충분함. 버그의 근본 원인을 찾으러 나니아까지 갔다 돌아온 짧은 이야기는 별로 관련 없다고 봄. 다만 PR 설명이나 커밋의 확장 메시지에 화풀이 겸 쓰는 것까지 반대하지는 않음
  • 이상적인 커밋 메시지도 저 정도임. 글에 나온 나머지 본문은 어떻게 발견했는지에 대한 이야기일 뿐임. 작업 과정을 설명하는 내용은 Git 커밋 메시지에 들어갈 필요가 없다고 봄. 저 메시지는 왜, 어떤 변경이 이루어졌는지 알려주고 그걸로 충분함
  • 이 개념이 마음에 듦. 항상 맨 위에는 가장 실행 가능하거나 중요한 내용을 두고, 그 뒤에는 맥락을 둠. 다른 사람의 시간을 존중하고 핵심을 묻어두지 말아야 함

• 훌륭한 커밋 메시지를 쓸 때의 자부심은 느껴봤지만, 다른 사람에게 주는 가치는 덜 확신함. 이상한 오류 메시지를 만났거나 새 기능을 추가할 때, 혹은 거의 어떤 경우에도 대부분은 커밋 메시지를 검색하지 않는다고 봄
  조금 슬프지만, 아름다운 커밋 메시지는 프로그래머의 허영에 가까운 면이 있다는 의심이 커짐. 주로 감탄하는 사람은 작성자 자신이고, 다른 사람들은 알아채지 못한 채 지나감
  때때로 그런 미적 장식이 들어갈 여지는 있지만 실용적 가치가 크다고는 확신하지 않음. 다른 사람이 “fix whitespace issue”라고 커밋해도 이제 크게 신경 쓰지 않게 됐고, 그 덕분에 더 나은 동료가 된 것 같음
  Git이나 Linux처럼 거대한 분산 팀과 수많은 커밋이 있는 프로젝트에서는 다를 수 있음. 익숙한 프로젝트들은 기여자가 1~100명이고 대부분 같은 조직에 속해 있음

  • 커밋 메시지는 평생 볼 사람이 자신뿐이어도 가치가 있음. 문제를 이분 탐색할 때 마침내 찾은 커밋의 메시지는 정말 유용함. “fixed thing”만 아니었다면 더 유용했을 것임. 비슷한 문제를 다시 만나도 찾아볼 수 있는 커밋 노트가 있다는 뜻이기도 함
  • 이상할지 모르지만, 적극적으로 참여하는 프로젝트라면 모든 커밋을 최소한 훑어보려고 함. 오픈소스 프로젝트라면 그 커밋 메시지는 영원히 남고, 코드 검색뿐 아니라 일반 검색엔진에도 색인될 수 있음. 다만 GitHub가 봇을 점점 더 막는 지금은 덜 그럴 수 있음
    Google이나 Stack Overflow에서 답이 안 나올 때는 GitHub에서 비슷한 내용이 PR이나 커밋 메시지에 있는지 찾기도 함. 접근 가능한 비공개 저장소까지 포함해서 수없이 도움을 받았음. 좋은 커밋 메시지는 허영을 넘어 확실히 가치가 있음. 많은 개발자가 보지 않는다면 그들의 손해이고, 경험이 쌓이면 언젠가 깨닫길 바람. 주니어 개발자에게 검색법을 가르치거나 원문 글을 보내도 좋음
  • 너무 짧은 커밋 메시지에 몇 번 당한 적이 있음. 누가 “왜 이렇게 했죠?”라고 물으면 Git 기록을 확인하고, 3년 전 내가 남긴 “it should be done this way”라는 메시지를 발견하는 식임
    그 뒤로는 적어도 미래의 내가 변경이 필요했던 이유를 떠올릴 수 있게 커밋 메시지를 쓰려고 함
  • 코드 한 줄을 바꾸기 전에 git blame을 하지 않는다면 잘못하고 있는 것임
    명백한 버그를 고치려다 커밋 직전에 이전 커밋을 보니, 그 “버그”가 의도적으로 들어간 것이고 연결된 JIRA 작업에는 왜 내 명백한 변경이 2년 전 버그를 다시 만들게 되는지 잘 설명되어 있었던 일이 여러 번 있음
  • IDE의 git blame 기능으로 무슨 일이 있었는지 자주 파악함. 좋은 커밋 메시지를 발견하면 고맙게 느껴짐

• 커밋 메시지의 첫 줄은 git log가 체스터턴의 울타리를 다룰 수 있게 하므로 가장 중요함. 이 경우 작성자는 헛스윙했다고 봄
  첫 줄에는 무엇을 했는지가 아니라 왜 했는지를 넣는 게 핵심임. 무엇이 바뀌었는지는 관심 있는 사람이 코드나 차이를 보면 됨
  예를 들면 “nginx .conf files must be in us-ascii”라고 쓰고, 그다음 “changed blahblah.erb to remove nonbreaking space character”를 둔 뒤, 꽤 좋은 나머지 커밋 메시지를 이어가면 됨
  뉴스 기사처럼 생각해야 함. 독자가 어느 지점에서 읽기를 멈춰도 된다고 가정하고, 중요도는 내려가고 세부사항은 늘어나는 순서로 써야 함

  • 첫 줄은 먼저 문제 커밋을 찾을 수 있도록 무엇을 바꿨는지 요약해야 함
    뉴스 기사도 제목에서 왜가 아니라 무엇을 설명함
    이 경우 원문의 첫 줄은 딱 맞음. git log를 훑다 보면 이 커밋이 테스트의 기능적 동작을 바꾼 게 아닐 가능성이 크다고 보고 넘어갈 수 있음
  • 임의 프로젝트의 커밋 메시지는 누군가에게 nginx 규칙을 가르치는 곳이 아님
    “nginx .conf files must be in us-ascii”는 버그나 PR 제목으로는 좋을 수 있지만, 여러 커밋이 서로 다른 일을 하는 데 대응될 수도 있고 실제로 무슨 일이 일어나는지는 알려주지 않음. 파일을 US-ASCII로 변환하는 건지, 변환 도구를 만드는 건지, 문서를 갱신하는 건지, 테스트를 만드는 건지, 혹은 조합인지 알 수 없음. 왜가 아니라 무엇으로 시작해야 그 혼란을 줄일 수 있음
  • 핵심은 첫 줄만 출력되는 경우가 있으니 첫 줄에 말이 되는 내용을 넣는 것이라고 하면 되지 않나 싶음
    “The files must be in us-ascii”든 “Changed the files to us-ascii”든 크게 상관없음. 둘 다 파일이 US-ASCII로 바뀌었다는 걸 분명히 알려줌

• 이런 문서화 방식의 단점은 한 번 쓴 커밋 메시지를 사실상 바꿀 수 없다는 것임
  물론 rebase로 가능은 하지만, 1년 전에 쓰였고 이미 main에 병합된 내용을 정말 바꿔서 모두의 기능 브랜치에 고통을 줄 건가 싶음
  .md 파일, Wiki, Confluence에 저장된 문서와 비교하면 동료가 쓴 내용을 내가 개선하고, 다른 동료도 내가 쓴 내용을 개선할 수 있음
  이 사례에서는 버그가 고쳐져 다시 나오지 않을지도 모름. 하지만 특정 컴포넌트를 커밋할 때 그 설계를 설명하고 싶은 유혹이 있는데, 이제는 피함. 비즈니스 요구사항 변경 등으로 나중에 그 컴포넌트가 바뀌면 어떻게 될까. 커밋 문서는 차이만 설명하게 될까. 그러면 새 팀원이 시스템을 이해하려면 여러 커밋 메시지를 읽고 머릿속에서 병합해야 함

  • 그건 단점이 아님. 커밋은 역사 기록이므로 3년 뒤 돌아왔을 때 당시 맥락에서 그 목적이 무엇이었는지 알고 싶지, 세탁된 역사를 보고 싶지는 않음
    .md 파일이나 Wiki, Confluence와 비교하는 건 자전거와 거위를 비교하는 것과 같음
    컴포넌트 생성 당시의 고려사항이나 절충, 혹은 그런 게 없었다는 사실은 원본 결함, 이후 진화, 사용 사례 변화에서 생긴 결함을 이해하는 데 자주 유용함
    새 팀원이 시스템을 이해하려면 별도의 “현재” 문서를 유지하면 됨. 그 문서는 구현상의 절충이나 초안이 시간 압박 속에서 작성됐다는 사실까지 다룰 필요는 없음
  • 커밋 메시지가 편집 불가능하다는 점이 오히려 이점이라고 봄. 사후 수정은 어렵지만, 코드베이스의 역사를 단계별로 따라가는 일은 정말 많은 걸 드러내줌
  • 커밋 메시지는 시간이 지나며 갱신되어야 하는 문서가 아니라 단일 변경의 역사 기록임. 나중에 중요한 세부사항을 빼먹었다는 걸 깨닫는 건 아쉽지만, 전체적으로는 절대 바뀌지 않는 것이 중요하다고 봄
  • Git은 무엇이 바뀌었는지에 대한 불변 로그와, 무엇이 병합됐는지에 대한 ideally 가변적인 이야기를 섞어버린 점이 실수였다고 봄. 그래서 커밋 압축, 재배치, 병합을 두고 논쟁이 생김
    커밋을 압축하면 기능 추가의 이야기로서 기록이 좋아지고, 병합은 실제 코드 변경의 불변 로그를 보존하며, 재배치는 둘 다 조금씩 함
    둘 다 가질 수 없는 이유는 없음. 컴퓨터를 프로그래밍하는 사람들이니 원하는 대로 만들 수 있음
    내가 Git을 새로 쓴다면 커밋을 두 부분으로 나누겠음. 변경 이력은 Git처럼 Merkle DAG 같은 구조로 불변으로 두고, 별도의 연관 데이터 저장소에 커밋 메시지를 보관해 작업 흐름을 설명하는 합리적이고 편집 가능한 로그로 만들겠음. 기능 태그 중심으로 커밋을 묶고, 오타를 고치고, 메시지를 원하는 대로 바꿀 수 있게 하되, 아래의 차이 로그, 즉 “코드에서 실제로 바뀐 것”은 그대로 보존하면 됨
  • git notes로 덧붙일 수는 있음. 다만 메시지가 저렇게 길면 누가 알아볼 가능성은 낮아 보임

• 동의하지 않는 부분이 하나 있음. “모든 커밋, 특히 이 정도 크기의 커밋에 이런 수준의 세부사항을 기대하지는 않는다”는 대목임
  경험상 오히려 작고 무해해 보이는 것들이 상대적으로 더 긴 설명을 필요로 하는 경우가 많음
  어제 gh pr list에 --limit=999를 추가한 이유를 세 문단으로 썼음. 헷갈리기 때문임. --jq 인자 안에도 이미 limit(가 있고, 전체 PR이 무한히 있다고 치면 값이 높을수록 최종 결과는 실제로 더 낮아짐
  코드 주석도 썼고, 아마 글을 쓰는 시간보다 생각하고 다듬는 데 더 오래 썼을 것임. 누군가 이 일이 코드를 마구 찍어내는 일이라고 암시할 때 다음 예시로 기억하길 바람

  • 작고 무해해 보이는 것들이 더 긴 설명을 필요로 한다는 데는 동의하지만, 링크된 커밋 메시지는 너무 길다고 봄. 독자의 시간을 낭비하거나, 텍스트 벽 때문에 눈이 흐려지게 만듦. 발견한 내용과 이유를 문서화하려고 전체 여정을 기록할 필요는 없음
    “This was a non-ascii whitespace character that caused ArgumentError: invalid byte sequence in US-ASCII when running bundle exec rake” 정도면 충분함. 나중에 비슷한 문제를 검색할 키워드가 있고, 근본 원인을 담고 있으며, 너무 길지 않아 사람들이 흘려보낼 가능성도 낮음
  • 언어 바인딩을 추가하는 커밋이라면 추가·삭제가 100줄이 넘더라도 “Add X function” 정도만 쓸 수 있음. 이미 확립된 패턴을 따르는 것뿐이기 때문임. 하지만 링크된 종류의 변경이라면 여러 문단 설명이 확실히 유용함
  • 코드 주석도 비슷한 패턴으로 쓰게 됨. “흥미로운” 코드의 작은 핵심 부분에는 코드 대비 주석 비율이 1:1 이상 붙고, 그 덕분에 나머지 코드베이스는 굳이 주석이 많이 필요 없는 지루하고 자기 설명적인 상용구 코드로 유지될 수 있음

• 훌륭한 Git 커밋은 아니라고 봄
  저 많은 텍스트에 비해 첫 줄 “Convert template to US-ASCII to fix error”는 더 나을 수 있음. 어떤 공백 문자가 오류를 일으켰고 오류가 무엇이었는지 몇 단어만 더 넣으면 됨. 그 설명과 차이만 있으면 필요한 맥락은 충분함
  솔직히 나머지는 거의 쓸모없음. 해가 되지는 않지만 가치도 크지 않음. 작성자가 이 버그를 추적한 여정을 문서화했는데, 누가 신경 쓰겠나 싶음

  • 배우고 더 나은 프로그래머가 되고 싶은 사람은 신경 씀. 실제로 글은 그 추가 내용의 가치를 설명하고 있고, 그건 신경 쓰는 사람이 있다는 뜻임
    글에는 그 수정에서 배운 사람들이 남긴 여러 커밋을 보여주는 검색 결과 링크도 있음
    그 커밋 메시지는 지식의 보고임

• 훌륭한 커밋 메시지를 보려면 Linux 커널의 Git 기록을 보면 됨. 거기서는 이게 표준임
  첫 줄은 항상 변경 영향을 받는 하위 시스템을 언급하고, 이어서 명령형 한 줄 요약을 둠. 그 뒤에는 세 질문에 최대한 자세히 답함

  1. 현재 동작은 무엇인가
  2. 무엇이 이 변경으로 이어졌는가
  3. 변경 적용 뒤 새 동작은 무엇인가
     예시는 “현재 코드는 X를 한다. 테스트 케이스 T를 실행하면 예상치 못한 동작 U가 관찰됐다. 이는 이유 R 때문이다. F를 해서 고친다”처럼 쓸 수 있음

• 최근 기여자에게 내 Git 메시지 접근법, 즉 요구사항이 “독특하다”는 말을 들었음. Linux 커널 배경이 드러난 모양이지만, 내 커밋 메시지는 모두 여기 나온 것처럼 생겼음
  기존 코드에 관한 내용이면 주석은 코드와 함께 있어야 함. 프로세스 관련 내용, 예를 들어 제거된 코드나 동작하지 않았던 코드는 커밋에 있어야 함
  가장 중요한 건 커밋 메시지가 편의상 이슈를 참조할 수는 있지만 핵심 세부사항을 반드시 재현해야 한다는 점임. GitHub는 일시적이지만 Git 메시지는 그렇지 않음

• 맥락이 가득한 커밋 메시지는 여기 있음[1]
  이런 일이 너무 흔해서 유지보수자가 이 글을 썼음[2]
  [1] https://github.com/git/git/commit/d70f554cdf38b0b05cfaa8e8eb...
  [2] https://lore.kernel.org/git/xmqqedevo8ps.fsf@gitster.g/