Git에서 커밋은 단순히 파일을 저장하는 작업이 아니다.
프로젝트가 어떤 과정을 거쳐 변경되었는지를 기록하는 하나의 버전이다.
커밋에는 다음과 같은 정보가 포함된다.
- 커밋을 작성한 사용자
- 커밋한 날짜와 시간
- 변경된 파일과 내용
- 커밋 메시지
사용자와 시간은 Git이 자동으로 기록하지만, 커밋 메시지는 직접 작성해야 한다.
따라서 프로젝트의 변경 이력을 쉽게 파악하려면 커밋 메시지를 구체적이고 일관된 방식으로 작성하는 것이 중요하다.
커밋 메시지가 중요한 이유
개인 프로젝트에서는 간단하게 작성해도 큰 문제가 없을 수 있다.
하지만 시간이 지난 뒤 코드를 다시 확인하거나 여러 명이 함께 작업할 때는 커밋 메시지가 중요한 역할을 한다.
좋은 커밋 메시지는 다음과 같은 질문에 답할 수 있어야 한다.
- 어떤 내용을 변경했는가?
- 왜 변경했는가?
- 어떤 문제를 해결했는가?
- 다른 기능에 미치는 영향은 무엇인가?
예를 들어 다음과 같은 메시지는 변경 내용을 파악하기 어렵다.
수정작업 완료코드 변경반면 다음과 같이 작성하면 커밋의 목적을 쉽게 알 수 있다.
로그인 실패 시 오류 메시지 표시사용자 조회 쿼리의 중복 조건 제거README에 프로젝트 실행 방법 추가커밋 메시지의 기본 구조
커밋 메시지는 일반적으로 다음과 같이 구성한다.
제목
상세 설명제목에는 무엇을 변경했는지 간단히 작성하고, 상세 설명에는 변경 이유와 구현 내용을 적는다.
사용자 로그인 오류 메시지 추가
로그인에 실패해도 사용자에게 원인이 표시되지 않는 문제가 있었다.
입력값 오류와 서버 오류를 구분하여 안내 메시지를 표시하도록 수정했다.간단한 변경이라면 제목만 작성해도 된다.
git commit -m "README에 설치 방법 추가"변경 이유를 자세히 설명해야 한다면 git commit만 입력하여 텍스트 에디터에서 여러 줄로 작성할 수 있다.
git commit커밋 메시지 작성 가이드라인
1. 제목과 상세 설명 사이에 한 줄을 비운다
Git은 첫 번째 줄을 제목으로 인식하고, 빈 줄 이후의 내용을 상세 설명으로 구분한다.
회원가입 입력값 검증 추가
이메일 형식과 비밀번호 길이를 확인하는 검증 로직을 추가했다.
잘못된 입력값이 서버로 전송되지 않도록 처리했다.제목과 본문을 붙여 작성하면 가독성이 떨어진다.
회원가입 입력값 검증 추가
이메일 형식과 비밀번호 길이를 확인한다.2. 제목은 변경 내용을 구체적으로 작성한다
수정, 변경, 업데이트처럼 범위가 넓은 표현만 사용하면 어떤 작업인지 알기 어렵다.
좋지 않은 예시는 다음과 같다.
파일 수정기능 업데이트에러 해결변경 대상을 포함하면 더 명확해진다.
로그인 페이지의 입력값 검증 수정상품 목록 정렬 기능 추가빈 검색어 입력 시 발생하는 오류 해결3. 제목 끝에는 마침표를 붙이지 않는다
커밋 메시지의 제목은 문장이라기보다 변경 내용을 나타내는 표제에 가깝다.
로그인 기능 추가다음처럼 마침표를 붙이지 않는 것이 일반적이다.
로그인 기능 추가.절대적인 규칙은 아니지만, 팀 내 메시지 형식을 통일하는 데 도움이 된다.
4. 영문 제목은 명령형으로 작성한다
영어로 커밋 메시지를 작성한다면 보통 동사의 원형으로 시작한다.
Add login validationFix user search errorUpdate installation guide다음과 같은 과거형이나 진행형보다는 명령형을 주로 사용한다.
Added login validationFixing user search error커밋 메시지 앞에 다음 문장을 붙였을 때 자연스럽게 읽히는지 확인하면 된다.
If applied, this commit will...예를 들어 다음 메시지는 자연스럽게 이어진다.
If applied, this commit will add login validation.5. 상세 설명에는 변경 이유를 작성한다
코드만 보면 무엇을 변경했는지는 알 수 있지만, 왜 변경했는지는 알기 어려울 수 있다.
따라서 본문에는 단순한 작업 내용보다 문제 상황과 변경 목적을 작성하는 것이 좋다.
검색 결과가 없을 때 안내 문구 표시
검색 결과가 없는 경우 빈 화면만 표시되어 사용자가 오류로 오해할 수 있었다.
결과가 없다는 안내 문구와 검색어 재입력 버튼을 추가했다.상세 설명에는 다음 내용을 포함할 수 있다.
- 기존에 어떤 문제가 있었는지
- 변경이 필요했던 이유
- 어떤 방식으로 해결했는지
- 변경으로 인해 어떤 효과가 생기는지
- 주의해야 할 부작용이나 제한 사항이 있는지
6. 하나의 커밋에는 하나의 작업만 담는다
서로 관련 없는 작업을 하나의 커밋에 모두 넣으면 나중에 변경 이력을 이해하기 어렵다.
예를 들어 다음 작업을 한 번에 커밋하는 것은 피하는 것이 좋다.
- 로그인 오류 수정
- README 내용 변경
- 불필요한 이미지 삭제
- 상품 검색 기능 추가
가능하면 작업 단위로 나누어 커밋한다.
로그인 실패 오류 수정README에 실행 방법 추가사용하지 않는 이미지 파일 삭제상품명 검색 기능 추가커밋을 작게 나누면 문제가 발생했을 때 어떤 변경에서 오류가 생겼는지 찾기 쉽고, 특정 변경만 되돌리기도 편하다.
7. 정상적으로 실행되는 상태에서 커밋한다
커밋은 언제든 다시 사용할 수 있는 하나의 버전이다. 따라서 가능하면 프로그램이 정상적으로 실행되고 기본적인 테스트를 통과한 상태에서 커밋해야 한다.
커밋하기 전에는 다음 내용을 확인하는 것이 좋다.
git status- 커밋에 포함할 파일이 맞는지
- 불필요한 파일이 포함되지 않았는지
- 작업 중인 코드가 함께 추가되지 않았는지
변경 내용을 확인하려면 다음 명령어를 사용할 수 있다.
git diff스테이징된 변경 내용을 확인하려면 다음 명령어를 사용한다.
git diff --staged확인한 뒤 커밋한다.
git commit -m "회원가입 입력값 검증 추가"커밋 메시지에 자주 사용하는 표현
프로젝트에서 정해진 규칙이 없다면 변경 목적에 따라 간단한 접두어를 사용할 수도 있다.
| feat | 새로운 기능 추가 |
| fix | 오류 수정 |
| docs | 문서 수정 |
| style | 코드 동작에 영향이 없는 형식 수정 |
| refactor | 기능 변경 없이 코드 구조 개선 |
| test | 테스트 코드 추가 또는 수정 |
| chore | 설정, 패키지, 빌드 등 기타 작업 |
예시는 다음과 같다.
feat: 회원가입 기능 추가fix: 빈 검색어 입력 시 오류 수정docs: README에 설치 방법 추가refactor: 사용자 조회 로직 분리이러한 형식을 Conventional Commits 방식이라고 부르기도 한다. 반드시 사용해야 하는 규칙은 아니며, 개인 또는 팀에서 정한 방식이 있다면 그 규칙을 우선하면 된다.
좋은 커밋과 좋지 않은 커밋 비교
변경 내용을 알기 어려운 메시지
수정최종 수정진짜 최종에러 해결변경 내용이 드러나는 메시지
로그인 실패 시 안내 메시지 추가중복된 사용자 조회 조건 제거모바일 화면에서 버튼이 겹치는 문제 수정README에 로컬 실행 방법 추가커밋 메시지만 읽어도 변경 목적을 짐작할 수 있어야 한다.
커밋 메시지 수정하기
가장 최근 커밋의 메시지를 잘못 작성했다면 --amend 옵션으로 수정할 수 있다.
git commit --amend -m "수정한 커밋 메시지"텍스트 에디터에서 메시지를 수정하려면 다음 명령어를 사용한다.
git commit --amend--amend를 실행하면 기존 커밋을 직접 고치는 것이 아니라 새로운 커밋으로 교체되기 때문에 커밋 ID가 변경된다.
아직 원격 저장소에 올리지 않은 커밋은 비교적 안전하게 수정할 수 있지만, 이미 다른 사람과 공유한 커밋을 수정하면 협업 과정에서 충돌이 생길 수 있으므로 주의해야 한다.
커밋 전 확인하면 좋은 명령어
git status현재 수정된 파일과 스테이징된 파일을 확인한다.
git diff아직 스테이징하지 않은 변경 내용을 확인한다.
git diff --staged다음 커밋에 포함될 변경 내용을 확인한다.
git log --oneline기존 커밋 메시지와 히스토리를 한 줄씩 확인한다.
핵심 정리
좋은 커밋 메시지는 단순히 작업했다는 사실만 남기는 것이 아니라, 무엇을 왜 변경했는지 설명하는 기록이다.
커밋할 때는 다음 기준을 기억하면 된다.
- 제목에는 변경 내용을 구체적으로 작성한다.
- 제목과 상세 설명 사이에는 한 줄을 비운다.
- 본문에는 변경 이유와 해결 방법을 작성한다.
- 하나의 커밋에는 하나의 작업만 담는다.
- 커밋 전 변경 파일과 실행 상태를 확인한다.
- 팀에서 정한 커밋 규칙이 있다면 해당 규칙을 우선한다.
커밋을 작고 명확하게 남기는 습관을 들이면 프로젝트 이력을 파악하거나 오류의 원인을 찾고, 다른 사람과 협업하는 과정이 훨씬 수월해진다.
'AI & 개발 > 개발' 카테고리의 다른 글
| [Git] HEAD와 reset, checkout, merge 동작 원리 정리 (0) | 2026.07.06 |
|---|---|
| [Git] 브랜치 기본 명령어와 Merge Conflict 해결 방법 정리 (0) | 2026.07.06 |
| [Git] 기본 브랜치가 master에서 main으로 바뀐 이유 (0) | 2026.07.03 |
| [Git] Git 기본 개념과 명령어 총정리: add, commit, push, reset까지 (0) | 2026.07.03 |
| [Markdown] 문법 총정리 | GitHub에서 가장 많이 사용하는 마크다운 문법 (0) | 2026.07.02 |