Git commit 메시지 작성하기: 변경 목적과 검증 결과 남기기

커밋 목록에 ‘수정’, ‘완료’, ‘최종’만 남아 있으면 몇 주 뒤에 같은 문제를 만났을 때 어느 변경을 찾아야 할지 알기 어렵습니다. 코드의 차이는 무엇을 바꿨는지 보여주지만, 그 선택을 한 이유와 확인하지 못한 범위까지 자동으로 설명해 주지는 않습니다. 커밋 메시지는 미래의 자신과 동료가 변경을 이해하도록 남기는 짧은 설명서입니다. 이 글에서는 작은 버그 수정 하나를 예로 들어 제목, 본문, 검증 기록을 구성하는 방법을 살펴봅니다.

1. 먼저 한 커밋에서 설명할 질문을 정한다

메시지를 잘 쓰려면 변경 묶음이 설명 가능한 크기여야 합니다. 예를 들어 검색 결과에서 빈 문자열을 처리하는 코드와 로그인 화면 색상 변경을 동시에 넣었다면 ‘검색 결과 오류 수정’이라는 제목으로는 전체 변경을 설명할 수 없습니다. 두 작업의 목적과 되돌릴 이유가 독립적이라면 별도 커밋으로 나누는 편이 기록을 찾기 쉽습니다. 파일 수가 많다는 이유만으로 반드시 나눌 필요는 없습니다. 같은 문제를 해결하기 위해 코드, 테스트, 설명 문서를 함께 바꿨다면 하나의 목적을 가질 수 있습니다.

작업을 마친 뒤 제목부터 억지로 붙이지 말고, ‘어떤 상황에서 문제가 발생했는가’, ‘이번 변경은 그 상황을 어떻게 처리하는가’를 한 문장씩 적어 보세요. 이 두 문장을 연결할 수 없다면 작업의 범위가 아직 불분명할 수 있습니다. 임시 디버깅 출력이나 관계없는 포맷 변경이 섞여 있는지도 확인합니다. 커밋 메시지로 변경의 혼합을 감추는 것보다 실제 묶음을 정리하는 것이 먼저입니다.

2. 제목은 변경을 식별하고 본문은 이유를 설명한다

Git 공식 문서는 짧은 제목 다음에 빈 줄을 두고 자세한 설명을 이어 쓰는 구성을 안내합니다. 약 50자 이내 제목은 가독성을 위한 권장 방식이며 모든 프로젝트에 적용되는 저장 제한은 아닙니다. 한국어 제목을 영어 기준에 기계적으로 맞추기보다 팀의 규칙을 확인하고, 목록에서 핵심 의미를 읽을 수 있게 작성하세요. 제목만 읽어도 변경 대상과 행동을 알 수 있으면 좋습니다.

예를 들어 ‘버그 수정’ 대신 ‘검색어가 공백일 때 결과 요청 생략’이라고 쓰면 조건과 동작이 함께 드러납니다. ‘검색 성능 대폭 개선’처럼 측정이 필요한 표현은 실제 근거가 없으면 피합니다. ‘전체 오류 해결’도 확인 범위를 넘어설 수 있습니다. 제목에는 이번 커밋이 한 일을 쓰고, 앞으로 하려는 작업이나 아직 해결하지 못한 문제는 본문에 따로 남깁니다.

항목	담을 내용	설명용 예시
제목	대상과 변경 행동	검색어가 공백일 때 결과 요청 생략
문제	변경 전의 구체적 조건	공백만 입력해도 검색 요청을 생성함
이유	이 방식을 선택한 까닭	요청 전에 정규화해 불필요한 호출을 줄임
검증	실제로 확인한 항목과 결과	빈 입력·공백 입력·일반 입력 사례 확인
남은 범위	확인하지 못했거나 별도로 처리할 부분	실제 서버 응답과 모바일 화면은 미확인

3. 실제 사용하지 않은 검증 결과는 적지 않는다

다음은 작성 형식을 보여주는 가상의 메시지입니다. 여기에 적힌 동작 확인은 실제 프로젝트 시험 결과가 아닙니다. 사용할 때는 자신의 작업에서 수행한 항목으로 바꾸세요. 특히 AI가 초안을 만들었다면 실행하지 않은 테스트 명령이나 ‘모든 테스트 통과’ 문구가 들어가 있지 않은지 확인해야 합니다. 작성자가 예상한 동작과 실제 실행으로 확인한 동작은 구분해서 기록합니다.

검색어가 공백일 때 결과 요청 생략

문제: 공백만 입력해도 검색 요청이 생성된다.
변경: 입력을 정리한 뒤 길이가 0이면 요청을 생략한다.
이유: 결과 처리 단계보다 요청 생성 단계에서 조건을 판단한다.

검증: 이 줄에는 실제 수행한 확인 항목과 결과를 적는다.
미확인: 실제 서버 연동과 모바일 화면은 별도 확인이 필요하다.

검증 기록에는 ‘확인 완료’만 적기보다 조건과 결과를 짝지어 쓰는 것이 좋습니다. 예를 들어 일반 검색어에서는 기존 호출이 유지됐는지, 공백에서는 호출이 생략됐는지, 오류 상황에서는 기존 오류 표시가 유지됐는지를 나누면 나중에 회귀 문제를 찾기 쉽습니다. 실패한 테스트를 기록하는 경우에는 실패 이유를 추정이라고 표시하고, 통과한 것처럼 바꾸지 않습니다.

아직 실행하지 못한 경우에도 유용한 메시지는 쓸 수 있습니다. ‘검증: 코드 차이 확인. 실행 시험 미수행’처럼 현재 수준을 밝히고, 실행할 항목을 별도 목록에 남기세요. 테스트 코드를 추가했다는 사실과 그 테스트를 실행했다는 사실도 다릅니다. 첫 번째는 변경 내용이고 두 번째는 검증 기록입니다. 이 구분은 동료가 다음에 해야 할 일을 정하는 데 직접 도움이 됩니다.

4. 저장 전에 스테이징 범위와 설명을 대조한다

기본적인 커밋은 스테이징 영역에 준비된 내용을 기록합니다. 편집기에서 파일을 저장한 것만으로 그 파일의 모든 최신 변경이 이번 커밋에 들어간다고 생각하면 메시지와 실제 코드가 어긋날 수 있습니다. 부분적으로 준비한 변경이 있다면 같은 파일 안에서도 포함되는 줄과 남아 있는 줄이 다를 수 있습니다. 사용하는 Git 화면에서 이번 커밋에 포함될 차이를 읽고, 메시지에 설명한 변경이 그 범위 안에 있는지 확인하세요.

메시지 검토는 세 번의 대조로 진행하면 간단합니다. 첫째, 제목에 쓴 동작이 실제 차이에서 보이는지 확인합니다. 둘째, 본문에서 설명한 이유가 코드의 조건이나 주석과 모순되지 않는지 확인합니다. 셋째, 변경한 공개 인터페이스나 문서가 있다면 설명에서 빠지지 않았는지 확인합니다. 비밀번호, 토큰, 실제 고객 자료처럼 기록에 남기면 안 되는 내용을 예시나 로그에서 제거하는 작업도 이 단계에 포함합니다.

다만 커밋 메시지를 완벽하게 꾸미려고 관계없는 코드를 추가로 고칠 필요는 없습니다. 발견한 별도 문제는 다음 작업으로 남기고 현재 목적을 분명히 합니다. ‘검색 요청 조건 수정’에 포함된 문서 변경이 그 조건을 설명하기 위한 것이라면 함께 설명할 수 있지만, 문서 전체 문체 개편은 다른 목적입니다. 되돌릴 때 함께 되돌려야 하는 변경인지 생각하면 묶음을 판단하기 쉽습니다.

5. 긴 메시지는 편집기나 파일로 작성한다

짧은 메시지는 git commit -m "검색어가 공백일 때 결과 요청 생략"처럼 전달할 수 있습니다. 여러 문단이 필요하면 기본 편집기를 쓰거나, UTF-8 텍스트 파일에 메시지를 작성한 뒤 git commit -F commit-message.txt로 읽어 들이는 방식이 편합니다. 이 명령들은 현재 저장소에 실제 커밋을 생성하므로, 이 글의 예시를 실행하기 전에 준비된 변경 범위를 확인해야 합니다.

메시지 파일은 첫 줄에 제목, 다음 줄에 빈 줄, 그 뒤에 설명을 넣습니다. 파일에 포함된 문구를 그대로 기록할 의도인지 확인하세요. 편집기용 템플릿의 안내 문장이 파일에도 남아 있다면 원하지 않는 설명이 기록될 수 있습니다. 긴 메시지를 쉘의 한 줄 문자열로 옮기다가 줄바꿈이나 따옴표를 잃는 경우에는 파일 방식이 읽고 검토하기 쉽습니다. 팀이 정한 템플릿이 있다면 그 틀을 우선 사용합니다.

메시지를 매번 같은 항목으로 쓰고 싶다면 ‘문제·변경·검증·미확인’ 네 줄짜리 틀부터 시작하세요. 모든 항목을 의무적으로 장문으로 채울 필요는 없습니다. 단순 오탈자 수정은 한 줄 제목으로 충분할 수 있고, 외부 API 동작이나 데이터 형식이 바뀌는 작업은 적용 조건과 호환성 설명이 필요할 수 있습니다. 기록의 길이는 변경의 위험과 설명에 필요한 정보에 맞추는 것이 좋습니다.

6. 목록과 상세 화면에서 읽히는지 확인한다

git log -5 --oneline은 최근 커밋을 짧은 식별자와 제목 중심으로 보여주는 읽기 명령입니다. 이 화면에서 ‘수정’, ‘추가’, ‘완료’라는 제목이 연속해서 나오면 검색하기 어려운 기록이 됩니다. 본문이 길어도 목록에는 제목만 보이는 상황이 많으므로 제목에 대상과 행동을 담는 이유가 여기에 있습니다. 상세 설명이 필요한 경우에는 일반 git log -1에서 최근 커밋의 메시지를 읽을 수 있습니다.

목록에서 다음 세 질문을 해 보세요. 검색 입력 문제를 찾는 사람이 이 제목을 선택할 수 있는가, UI 색상 변경과 구별되는가, 이번 변경이 추가인지 수정인지 제거인지 이해할 수 있는가. 제목을 읽기 위해 본문을 열어야 하는 일이 줄어들면 기록의 효용이 높아집니다. 커밋 해시는 변경을 식별하지만 문제의 의미까지 설명하지 않으므로 사람이 읽을 제목이 함께 필요합니다.

7. 접두사와 이슈 번호는 프로젝트 규칙에 맞춘다

fix:, feat:, docs: 같은 접두사는 팀이나 도구가 정한 규칙일 수 있으며 Git이 모든 저장소에 강제하는 문법은 아닙니다. 자동 릴리스 도구가 메시지를 읽는 프로젝트라면 그 도구의 규칙을 먼저 확인하세요. 개인 저장소에서는 접두사를 많이 늘리기보다 일관되게 쓰는 몇 가지 분류를 정하는 것으로 충분할 수 있습니다. 접두사가 정확해도 제목이 ‘기타 수정’이면 내용 찾기가 어렵습니다.

이슈 번호를 붙일 때도 번호만 남기지 말고 핵심 문제를 문장으로 설명합니다. 나중에 이슈 시스템에 접근할 수 없거나 저장소를 따로 보관해도 변경을 이해할 수 있기 때문입니다. 실제 문제의 세부 기록은 이슈에, 이번 커밋의 선택과 검증 범위는 메시지에 두면 역할이 명확합니다. 이슈 자동 종료 문법은 서비스마다 다를 수 있으므로 확인하지 않은 키워드를 관성적으로 넣지 않습니다.

8. 바로 사용할 수 있는 최종 점검표

• 제목에 변경 대상과 행동이 있는가?
• 제목 다음에 빈 줄을 두어 본문을 구분했는가?
• 변경 전 문제가 발생한 조건을 구체적으로 적었는가?
• 코드 차이만으로 알기 어려운 선택 이유를 설명했는가?
• 검증 기록은 실제 수행한 항목과 일치하는가?
• 실행하지 못한 범위를 통과로 표현하지 않았는가?
• 준비된 변경과 메시지의 범위가 같은가?
• 팀 규칙과 이슈 연결 방식에 맞는가?

좋은 기록은 거창한 문체보다 검색할 수 있는 조건과 믿을 수 있는 확인 범위에서 나옵니다. 오늘의 메시지를 미래에 오류를 분석할 사람이 읽는다고 생각해 보세요. ‘왜 이 조건이 추가됐는지’와 ‘어디까지 확인했는지’가 남아 있으면 코드의 변화가 판단 근거가 됩니다. 처음에는 짧은 제목과 두세 문장짜리 본문으로 시작하고, 설명이 필요한 변경에서만 내용을 확장하는 방법이 실용적입니다.

공식 출처와 작성 기준

• Git 공식 문서: git commit
• Git 공식 문서: git log

자료 확인일: 2026-10-10. 실제로 연 공식 자료를 바탕으로 AI가 작성한 설명입니다. 별도 표시한 계산·코드·점검 사례는 설명용이며 사용자 환경을 직접 시험하거나 실측한 결과가 아닙니다. 발행일에는 기능과 자료의 변경 여부를 다시 확인합니다.

커밋 기록을 만드는 순서

1. 문제 조건과 변경 목적 정리

→

2. 커밋에 포함할 차이 확인

→

3. 제목 → 빈 줄 → 이유 작성

→

4. 실제 검증과 미확인 범위 기록

→

5. 저장 후 목록과 상세 메시지 확인

본문 내용의 설명용 도해이며 실제 제품 화면·측정 자료가 아닙니다.