훌륭한 Git 커밋 메시지 작성하기: 명확한 히스토리를 위한 모범 사례

Git 커밋 메시지는 코드가 깨지거나, 동작이 변경되거나, 릴리스를 설명해야 할 때 팀이 의존하는 노트입니다. 명확한 메시지는 diff를 역공학하지 않고도 무엇이 변경되었고 왜 변경되었는지 알려줍니다.

좋은 커밋 메시지는 화려할 필요가 없습니다. 유용한 제목 줄, 사소하지 않은 변경 사항에 대한 충분한 컨텍스트, 그리고 몇 달 후에도 팀이 읽을 수 있는 일관된 스타일이 필요합니다.

좋은 커밋 메시지가 중요한 이유는 무엇인가요?

좋은 커밋 메시지는 여러 실용적인 측면에서 도움이 됩니다:

• 변경 사항 이해: 특정 커밋이 도입하거나 수정하는 내용에 대한 즉각적인 컨텍스트를 제공하여 코드 검토나 과거 결정을 기억할 때 시간을 절약합니다.
• 디버깅: 버그를 추적할 때 명확한 커밋 히스토리를 통해 문제가 있는 변경 사항이 언제, 왜 도입되었는지 정확히 파악할 수 있습니다.
• 협업: 프로젝트에 새로 합류하거나 오래된 코드를 다시 방문하는 팀원들에게 잘 작성된 메시지는 프로젝트 개발 궤적을 이해하기 쉽게 만듭니다.
• 코드 리뷰: 리뷰어에게 변경 사항 뒤에 숨은 의도에 대한 통찰력을 제공하여 더 생산적이고 집중된 피드백을 가능하게 합니다.
• 자동화 도구: 변경 로그 생성기 및 릴리스 노트 작성기와 같은 많은 Git 도구는 효과적으로 기능하기 위해 커밋 메시지에 의존합니다.
• 역사 기록: 코드베이스의 진화를 시간이 지남에 따라 보존하는 문서의 한 형태로 사용됩니다.

훌륭한 Git 커밋 메시지의 구성 요소

보편적으로 인정받는 Git 커밋 메시지 구조는 간단하면서도 강력한 패턴을 따릅니다: 간결한 제목 줄 뒤에 선택적인 더 자세한 본문입니다.

제목 줄

제목 줄은 커밋 메시지의 첫 번째 줄입니다. 변경 사항에 대한 간결하고 명령형 요약이어야 합니다. 커밋의 제목이라고 생각하세요.

제목 줄에 대한 주요 지침:

• 간결하게 유지하세요: 약 50자가 유용한 목표이지 엄격한 제한은 아닙니다. git log --oneline에서 훑어볼 수 있을 만큼 제목을 짧게 유지하세요.
• 명령형 분위기를 사용하세요: 마치 명령을 내리는 것처럼 동작을 설명하는 동사로 시작하세요. 예: Fix, Add, Refactor, Update, Remove, Style.
• 첫 단어를 대문자로 시작하세요: 표준 관례는 제목 줄의 첫 글자를 대문자로 하는 것입니다.
• 마침표로 끝내지 마세요: 제목 줄은 문장이 아니라 제목입니다.
• 긴 메시지에 git commit -m "message" 사용을 피하세요: 짧은 메모에는 편리하지만 덜 구조화된 메시지로 이어질 수 있습니다. 더 복잡한 메시지를 위해 인수 없이 git commit을 사용하여 편집기를 여세요.

좋은 제목 줄의 예:

• feat: 사용자 인증 모듈 추가
• fix: 데이터 처리 중 무한 루프 해결
• docs: README 설치 단계 업데이트
• refactor: 이미지 로딩 단순화
• chore: 개발 종속성 업데이트

본문

커밋 메시지의 본문은 더 많은 컨텍스트와 세부 정보를 제공하는 곳입니다. 빈 줄로 제목 줄과 구분됩니다. 이 섹션은 선택 사항이지만 사소한 변경 이상의 경우에는 적극 권장됩니다.

본문에 대한 주요 지침:

• '이유'와 '방법'을 설명하세요: 무엇이 변경되었는지 설명하는 것에 그치지 말고, 변경이 왜 필요했는지, 어떻게 구현되었는지 설명하세요. 이 커밋은 어떤 문제를 해결합니까? 이전 동작은 무엇이었습니까? 새로운 동작은 무엇입니까?
• 줄을 72자로 감싸세요: 이것은 많은 Git 도구와 터미널에서 가독성을 향상시키는 오랜 관례입니다.
• 목록에는 글머리 기호를 사용하세요: 여러 변경 사항이나 요점을 열거해야 하는 경우 명확성을 위해 글머리 기호를 사용하세요.
• 이슈 또는 티켓을 참조하세요: 커밋이 이슈 트래커(예: GitHub Issues, Jira)와 관련된 경우 추적 가능성을 위해 티켓 번호를 포함하세요.

좋은 커밋 메시지의 예 (제목 + 본문):

feat: 사용자 프로필 페이지 구현

이 커밋은 사용자가 개인 정보를 보고 편집할 수 있도록
사용자 프로필 페이지를 도입합니다.

이전에는 사용자가 프로필 세부 정보에 접근하거나 수정할 수 없었습니다.
이 변경 사항은 새 라우트(`/profile`)와 API에서 사용자 데이터를 가져오고
이름, 이메일, 약력과 같은 필드를 업데이트하기 위한 양식을 제공하는
해당 컴포넌트를 추가합니다.

관련 이슈 #123.

일반적인 커밋 메시지 유형 (Conventional Commits)

커밋 메시지 유형에 대한 규칙을 따르면 명확성을 더욱 높이고 자동화 도구를 활성화할 수 있습니다. Conventional Commits 사양은 구조화된 접근 방식을 촉진하는 널리 사용되는 표준입니다.

Conventional Commits는 변경 유형을 나타내기 위해 접두사를 사용합니다:

• feat (기능): 코드베이스에 새로운 기능이 도입되었습니다.
• fix (버그 수정): 버그가 해결되었습니다.
• docs (문서): 문서만 변경되었습니다.
• style (서식): 코드의 의미에 영향을 주지 않는 변경 사항 (공백, 서식, 누락된 세미콜론 등).
• refactor (리팩토링): 버그를 수정하거나 기능을 추가하지 않는 코드 변경.
• perf (성능): 성능을 개선하는 코드 변경.
• test (테스트 추가 또는 수정): 테스트 추가 또는 수정.
• build (빌드 시스템 또는 외부 종속성에 영향을 미치는 변경): npm 스크립트, webpack 등의 예.
• ci (CI 설정 파일 및 스크립트 변경): Travis, Circle, BrowserStack, SauceLabs 등의 예.
• chore (유지 관리 작업): 저장소 관리와 같이 다른 유형에 맞지 않는 작업.

범위 (선택 사항): 영향을 받는 코드베이스 부분을 나타내기 위해 접두사에 범위를 추가할 수 있습니다. 예: feat(auth): JWT 인증 추가.

바닥글 (선택 사항): 이슈를 참조하거나, 호환되지 않는 변경 사항을 표시하거나, 다른 메타데이터를 추가하려면 바닥글을 사용하세요. Conventional Commits는 호환되지 않는 변경 사항에 BREAKING CHANGE:를 사용합니다.

Conventional Commits를 사용한 예:

fix(api): 사용자 데이터 검색을 위한 엔드포인트 수정

이전에는 `/users/:id/data` 엔드포인트가 오래된 정보를 반환했습니다.
이 커밋은 가장 최신 사용자 프로필 데이터를 가져오는
`/users/:id/profile`로 엔드포인트를 업데이트합니다.

종료 #456

훌륭한 커밋 메시지 작성을 위한 팁

• 자주, 그러나 논리적으로 커밋하세요: 단일 논리적 변경을 나타내는 작고 원자적인 커밋을 만드세요. 이렇게 하면 메시지를 더 쉽게 작성하고 이해할 수 있습니다.
• 프로젝트의 미래 관점에서 메시지를 작성하세요: 6개월 후에 이 커밋을 다시 본다고 상상해보세요. 변경 사항을 빨리 이해하기 위해 어떤 정보가 필요할까요?
• 구체적으로 작성하세요: "코드 업데이트" 또는 "버그 수정"과 같은 모호한 메시지는 피하세요. 정확히 무엇이 업데이트되거나 수정되었는지 설명하세요.
• 코드 참조에는 백틱을 사용하세요: 파일 이름, 함수 또는 변수 이름을 언급하는 경우 백틱(`)으로 묶으세요.
• 메시지를 검토하세요: 커밋하기 전에 잠시 시간을 내어 메시지를 읽어보세요. 이해가 되나요? 명확한가요?

핵심 요약

리뷰, 롤백 또는 장애 상황에서 읽게 될 사람을 위해 각 커밋 메시지를 작성하세요. 짧은 명령형 제목을 사용하고, 이유가 명확하지 않을 때는 본문을 추가하며, 각 커밋을 하나의 논리적 변경에 집중하세요.