팀 커밋 메시지 제각각? 깃 컨벤션 통일 설정 가이드

팀 프로젝트를 진행하면서 깃 커밋 히스토리를 볼 때, 팀원마다 다른 커밋 메시지 형식 때문에 변경 내용을 한눈에 파악하기 어려웠던 경험이 있으신가요? 어떤 커밋이 새로운 기능을 추가한 건지, 버그를 수정한 건지 파악하는 데 불필요한 시간이 소모되곤 합니다.

이런 문제는 팀 내에 명확한 커밋 메시지 컨벤션이 없거나, 있어도 수동으로 관리되면서 잘 지켜지지 않을 때 주로 발생합니다.

이 글에서는 효과적인 깃 커밋 메시지 컨벤션의 중요성을 설명하고, 이를 팀에 성공적으로 적용하기 위한 구체적인 가이드와 Git Hooks를 활용한 자동화된 설정 방법을 단계별로 제시합니다.

왜 깃 커밋 메시지 컨벤션이 필요한가?

협업하는 프로젝트에서 일관성 없는 커밋 메시지는 혼란을 가중시키고 생산성을 저하시키는 주범 중 하나입니다. 각자의 스타일대로 작성된 메시지는 타인이 변경 내역을 이해하는 데 불필요한 시간을 소모하게 만들며, 결국 코드 리뷰나 문제 해결 과정에서 비효율을 초래합니다.

명확한 커밋 메시지 컨벤션은 단순히 메시지를 예쁘게 꾸미는 것을 넘어, 프로젝트의 유지보수성과 개발 생산성을 획기적으로 향상시키는 강력한 도구입니다. 약속된 규칙을 통해 모든 팀원이 변경 내역을 최소 3초 안에 파악할 수 있게 되며, 이는 전체 개발 프로세스에서 상당한 시간 절약으로 이어집니다.

효과적인 깃 커밋 메시지 컨벤션 형식 (Conventional Commits)

수많은 커밋 컨벤션 중 가장 널리 사용되며 효과적이라고 평가받는 것은 바로 Conventional Commits 표준입니다. 이는 Git 커밋 메시지에 의미론적인 구조를 부여하여, 사람이 읽고 이해하기 쉬울 뿐만 아니라, 기계적으로 파싱하여 릴리즈 노트를 생성하거나 버전을 관리하는 데도 유용합니다.

Conventional Commits는 주로 다음과 같은 형식을 따릅니다.

type(scope): subject

body (optional)

footer (optional)

각 부분의 의미는 다음과 같습니다.

• type: 커밋의 종류를 나타냅니다. (필수)
• scope: 변경 사항이 영향을 미치는 범위 (예: auth, users, payment)를 명시합니다. (선택)
• subject: 변경 사항을 간결하게 요약합니다. 명령형으로 작성하며, 마침표를 찍지 않습니다. (필수)
• body: 변경 사항에 대한 상세한 설명입니다. 여러 줄로 작성할 수 있습니다. (선택)
• footer: Breaking Change, 참조하는 이슈 번호 (예: Closes #123) 등을 포함합니다. (선택)

Git Hooks로 커밋 메시지 컨벤션 자동 강제하기 (husky + commitlint)

아무리 좋은 컨벤션이라도 팀원들이 꾸준히 지키지 않으면 무용지물이 됩니다. 이 문제를 해결하기 위해 Git Hooks를 활용할 수 있습니다. Git Hooks는 특정 Git 이벤트가 발생했을 때 자동으로 스크립트를 실행할 수 있게 해주는 기능입니다. 특히, ‘commit-msg’ 훅을 사용하면 커밋 메시지가 저장되기 전에 컨벤션 준수 여부를 검사하고, 규칙에 맞지 않으면 커밋을 거부할 수 있습니다.

여기서는 Git Hooks를 쉽게 관리해주는 husky와 커밋 메시지 규칙을 검증해주는 commitlint를 사용하여 3단계로 컨벤션 강제 시스템을 구축하는 방법을 소개합니다.

1. husky 설치 및 설정 — 프로젝트 루트에서 다음 명령어를 실행하여 husky를 설치하고 Git Hooks를 활성화합니다.

   npm install husky --save-dev
   npx husky install
   npx husky add .husky/commit-msg "npx --no-install commitlint --edit \$1"

   세 번째 명령어는 `commit-msg` 훅을 생성하고, 이 훅이 `commitlint`를 실행하도록 설정합니다.

2. commitlint 설치 및 설정 — 커밋 메시지를 검증할 commitlint와 Conventional Commits 규칙을 위한 설정을 설치합니다.

   npm install @commitlint/cli @commitlint/config-conventional --save-dev

   루트 디렉토리에 `commitlint.config.js` 파일을 생성하고 다음 내용을 추가합니다.

   module.exports = {
     extends: ['@commitlint/config-conventional'],
     rules: {
       // 여기에 커스텀 규칙을 추가하거나 기존 규칙을 수정할 수 있습니다.
       'type-enum': [
         2,
         'always',
         ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'build', 'ci', 'perf']
       ],
       'subject-empty': [2, 'never'],
       'subject-full-stop': [2, 'never', '.'],
       'header-max-length': [2, 'always', 72]
     }
   };

3. commitlint 규칙 커스터마이징 — `commitlint.config.js` 파일의 `rules` 객체에서 팀의 필요에 따라 규칙을 수정하거나 추가할 수 있습니다. 예를 들어, 특정 `scope`를 강제하거나, 메시지 길이를 조절하는 등의 설정을 할 수 있습니다. 깃 커밋 메시지 컨벤션의 80% 이상은 이 `commitlint` 설정을 통해 통제할 수 있습니다.

팀에 컨벤션 안착을 위한 실용 팁과 예시

자동화된 강제 시스템을 구축했다고 해도, 팀원들이 새로운 컨벤션에 익숙해지는 시간이 필요합니다. 초기에는 가이드라인을 명확히 제시하고, 코드 리뷰 시 피드백을 통해 올바른 커밋 문화를 정착시키는 것이 중요합니다.

IDE (통합 개발 환경)의 플러그인(예: VS Code의 GitLens, Commitizen 등)을 활용하면 커밋 메시지 작성 과정을 더욱 편리하게 만들 수 있습니다. 이러한 도구들은 커밋 타입을 선택하고 메시지를 구조화하는 데 도움을 주어, 컨벤션 준수를 한층 더 쉽게 만들어줍니다.