일관된 Git 커밋 메시지의 중요성

소프트웨어 개발 과정에서 일관된 Git 커밋 메시지는 프로젝트의 유지보수성과 협업 효율성을 크게 향상시킵니다. 커밋 히스토리를 통해 변경 사항을 쉽게 추적하고, 릴리스 노트를 자동 생성하는 등의 이점을 얻을 수 있기 때문입니다. 그러나 팀원 간에 메시지 작성 규칙이 다르면 이러한 장점들이 퇴색될 수 있습니다. 이러한 문제를 해결하기 위해 '약속된 커밋(Conventional Commits)' 규약을 따르도록 돕는 도구가 바로 commitlint입니다.

commitlint 설치 및 초기 설정

프로젝트에 commitlint를 도입하려면 다음 두 가지 주요 패키지를 설치해야 합니다. @commitlint/cli는 커맨드라인 인터페이스를 제공하며, @commitlint/config-conventional은 약속된 커밋 규약을 따르는 기본적인 규칙 집합을 포함합니다.

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

설치 후에는 프로젝트 루트에 commitlint.config.js 파일을 생성하여 commitlint의 동작 방식을 정의합니다. 여기서는 config-conventional 규칙 세트를 상속받아 사용하도록 설정합니다.

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional']
};

Git 훅과 Husky를 이용한 자동 검증 연동

커밋 메시지를 자동으로 검증하려면 Git의 commit-msg 훅을 활용해야 합니다. 이를 위해 husky 라이브러리를 사용합니다. husky를 설치한 후, commit-msg 훅에 commitlint 실행 스크립트를 추가합니다.

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

위 명령어를 실행하면 .husky/commit-msg 파일이 생성되며, 앞으로 Git 커밋이 발생할 때마다 해당 스크립트가 실행되어 커밋 메시지를 검사하게 됩니다.

commitlint 동작 테스트

이제 설정이 올바르게 되었는지 확인하기 위해 커밋을 시도해 볼 수 있습니다. 약속된 커밋 규약을 따르는 메시지로 커밋하면 성공적으로 완료됩니다.

git commit -m "feat: 새로운 사용자 인증 기능 추가"

만약 규약에 맞지 않는 메시지로 커밋을 시도하면, commitlint는 오류를 발생시키고 커밋을 차단합니다.

git commit -m "잘못된 커밋 메시지"

이 경우, 다음과 유사한 오류 메시지를 볼 수 있습니다:

✖   type may not be empty [type-enum]
✖   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]
✖   subject may not be empty [subject-empty]

이는 커밋 메시지의 타입과 제목이 약속된 규약을 따르지 않았음을 의미합니다.

모범 사례 및 활용 전략

commitlint는 단순히 약속된 커밋 규약을 적용하는 것을 넘어, 팀의 특정 요구사항에 맞춰 유연하게 활용될 수 있습니다.

규칙 사용자 정의

기본 config-conventional 규칙 외에도 팀의 특성에 맞는 커스텀 규칙을 추가하거나 기존 규칙을 수정할 수 있습니다. 예를 들어, 특정 접두사만 허용하거나, 제목 길이에 제한을 두는 등의 설정을 commitlint.config.js 파일에서 정의할 수 있습니다.

// commitlint.config.js 예시 (커스텀 규칙 추가)
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'header-max-length': [2, 'always', 72], // 커밋 메시지 헤더 최대 길이 72자로 제한
    'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'build', 'ci', 'perf']] // 허용되는 타입 명시
  }
};

CI/CD 파이프라인 통합

지속적 통합/지속적 배포(CI/CD) 파이프라인에 commitlint 검증 단계를 추가하여, 모든 커밋이 푸시되기 전 또는 빌드 전에 자동으로 검사되도록 할 수 있습니다. 이는 코드 베이스의 일관성을 유지하고, 잠재적인 문제를 조기에 발견하는 데 기여합니다.

팀 교육 및 문서화

commitlint의 도입 효과를 극대화하려면, 모든 팀원이 약속된 커밋 규약의 중요성을 이해하고 올바른 메시지 작성 방법을 숙지하는 것이 중요합니다. 관련 가이드를 문서화하고 정기적인 교육을 통해 팀 전체의 참여를 유도해야 합니다.

관련 생태계 도구

commitlint는 Git 커밋 메시지 관리를 위한 강력한 도구이지만, 이와 함께 사용하면 개발 워크플로우를 더욱 효율적으로 만들 수 있는 도구들이 있습니다.

Commitizen

Commitizen은 개발자가 약속된 커밋 규약에 맞춰 인터랙티브하게 커밋 메시지를 작성할 수 있도록 돕는 CLI 도구입니다. commitizen을 사용하면 커밋 메시지 작성 시 타입, 스코프, 제목, 본문 등을 단계별로 안내받을 수 있어, 수동으로 규칙을 기억할 필요 없이 손쉽게 표준화된 메시지를 생성할 수 있습니다. 이는 commitlint와 함께 사용될 때 강력한 시너지를 발휘합니다.

Conventional Changelog

Conventional Changelog는 약속된 커밋 규약을 기반으로 프로젝트의 변경 로그(changelog)를 자동으로 생성해주는 도구입니다. 커밋 히스토리를 분석하여 새로운 기능(feat), 버그 수정(fix), 성능 개선(perf) 등 주요 변경 사항들을 추출하고, 이를 구조화된 형태로 보여줍니다. 이 도구를 활용하면 수동으로 릴리스 노트를 작성하는 번거로움을 줄이고, 항상 최신 상태의 변경 로그를 유지할 수 있습니다.

이러한 도구들을 함께 사용함으로써, 커밋 메시지 작성부터 검증, 그리고 최종 변경 로그 생성에 이르는 전 과정을 자동화하고 표준화하여 프로젝트의 전반적인 품질과 생산성을 높일 수 있습니다.