나중에 git log로 검색할 수 있는 커밋 메시지 쓰는 법

오래된 버그를 추적하다 보면 결국 git log를 뒤지게 된다. 그때 커밋 메시지가 "fix", "update", "wip" 같은 것들로 가득하면 하나하나 diff를 열어봐야 한다. 반대로 메시지가 잘 써져 있으면 git log --grep으로 바로 좁혀진다.

나중에 찾기 쉬운 메시지 구조

Conventional Commits 형식이 검색에 유리하다.

<type>(<scope>): <what>

<why — 선택>

fix(auth): 토큰 만료 후 리다이렉트가 로그인 페이지로 가지 않던 문제 수정

refreshToken 요청 실패 시 401 응답을 catch하지 않아서
/dashboard로 계속 리다이렉트됐음. 에러 핸들러에서 /login으로 이동하도록 변경.

fix, feat, refactor, chore, docs, perf 정도면 충분하다. scope는 모듈이나 파일명 수준으로 적으면 된다.

본문에 "왜"를 적는 게 핵심이다

제목에는 "무엇을" 했는지, 본문에는 "왜" 했는지를 쓴다. 코드를 보면 무엇을 바꿨는지는 알 수 있다. 그런데 왜 그렇게 바꿨는지는 코드만으로는 알 수 없는 경우가 많다.

# 별로 안 좋은 예
fix: 캐시 문제 수정

# 나중에 찾기 좋은 예
fix(api): 동일 요청이 연속될 때 stale 응답이 반환되던 문제 수정

SWR의 dedupingInterval이 기본값(2초)으로 설정돼 있어서
빠른 연속 요청 시 첫 번째 응답을 재사용했음.
dedupingInterval을 0으로 조정해 항상 최신 데이터를 가져오도록 변경.

git log로 검색하는 예시

# 특정 키워드가 포함된 커밋 찾기
git log --grep='토큰' --oneline

# 특정 파일에 영향을 준 커밋만 보기
git log --oneline -- src/lib/auth.ts

# 특정 문자열이 추가/삭제된 커밋 찾기 (pickaxe)
git log -S 'refreshToken' --oneline

# 날짜 범위로 좁히기
git log --after='2025-01-01' --before='2025-03-01' --oneline

-S 옵션(pickaxe)은 특정 문자열이 코드에 처음 등장하거나 사라진 커밋을 찾아준다. 함수나 변수명이 언제 추가됐는지 찾을 때 유용하다.

팀 없이 혼자 쓸 때도 형식이 필요한 이유

혼자 개발하면 나만 볼 거라서 대충 써도 되지 않냐고 생각하기 쉽다. 그런데 3개월 후의 나는 지금의 나와 다른 사람이나 마찬가지다. 그때 git log를 열어봤을 때 맥락이 남아있으면 훨씬 빠르게 작업을 재개할 수 있다.

커밋 메시지를 잘 쓰는 건 미래의 나에게 메모를 남기는 일이다.