commitlint 설정하기

최근 새로운 프로젝트 본격 진행에 앞서 커밋 린트(commit lint)를 설정하는 작업을 진행했다. 처음에는 간단히 끝날 줄 알았지만, 예상치 못한 문제들이 발생하며 생각보다 많은 시간을 소모하게 되었다. 하지만 배운 점들도 많아 기록해두려 한다.

커밋 린트의 필요성

 

커밋 린트는 커밋 메시지의 형식을 검증하여 일관성을 유지하는 도구다. 이번 프로젝트에서는 하나의 레포에 프론트엔드와 백엔드 코드를 공유하면서 사용하기로 했는데, 이에 따라 커밋 메시지에 (front)와 같은 구분을 추가해야 했다. 그런데 이 규칙을 자주 잊어버리는 일이 발생했다. 이런 문제를 해결하기 위해 커밋 메시지의 형식을 강제할 필요성을 느끼고, commitlint를 도입하기로 결정했다.

패키지 설치 및 초기 설정

프로젝트의 package.json 파일에 commitlint와 husky 패키지를 추가하고, 린트 규칙을 설정하기 위해 commitlint.config.js 파일을 생성했다. 이 파일에서는 커밋 메시지의 규칙을 정의했다. 예를 들어, 커밋 타입으로는 feat, fix, style, refactor, chore를 설정했다.

 

// commitlint.config.js

export default {
  rules: {
    'type-enum': [2, 'always', ['feat', 'fix', 'style', 'refactor', 'chore']],
    'scope-enum': [2, 'always', ['front']],
    'type-empty': [2, 'never'],
    'scope-empty': [2, 'never'],
  },
};

 

커밋 훅 스크립트 헤더

커밋 훅 스크립트의 시작 부분에는 #!/bin/sh 또는 #!/usr/bin/env sh와 같은 해더가 필요하다. 이 해더는 해당 스크립트를 실행할 때 사용할 쉘을 지정하는 역할을 하며, 올바르게 설정되지 않으면 스크립트가 실행되지 않을 수 있다. 처음 이 부분을 제대로 이해하지 못해 몇 번의 시행착오를 겪기도 했다.

git config 강제하기

그런데 아무리 커밋을 해도 린팅 기능이 작동을 하지 않는 문제가 있었다. 문제를 살펴보니 커밋을 할 때마다 프로젝트 루트 디렉토리에서 commitlint.config.js를 찾으려 하며, 원하는 경로에서 설정 파일을 읽지 못하는 것이 원인인 것 같았다. 훅 경로는 git config의 설정을 참조한다. 따라서 깃훅 경로를 제대로 불러오지 못할 경우에는 " git config core.hooksPath <경로명>" 명령어를 통해 git config의 core.hooksPath를 변경해주면 된다.

그런데 이렇게 해도 pnpm install을 새로 하면 hooksPath가 초기화되는 문제가 있었다. 또, 팀원들이 모두 같은 커밋 컨벤션을 따르도록 하기 위해서 린팅 룰을 만든 것인데 일일히 git config 설정을 변경하는 명령어를 쳐야 한다고 안내해 주기도 비효율적인 상황이었다. 이 문제를 해결하는 데는 prepare 스크립트를 사용해 install과 동시에 git config core.hooksPath를 프로젝트에 맞게 설정해주도록 했다.

//pacakge.json

"scripts": {
  "prepare": "husky install && git config core.hooksPath .husky"
}

commitlint config도 못 읽는다고?

그렇게 깃훅의 commit-msg를 읽어오는 데는 성공했으나 이번에는 commitlint.config.js 경로를 찾지 못해 또다시 오류가 났다. 이 부분은 공식 문서를 확인해 --config 옵션으로 설정 파일의 경로를 명시적으로 지정할 수 있다는 것을 알게 되었다. 이 설정을 통해, 프로젝트의 구조에 맞게 commitlint가 올바른 규칙을 적용하도록 할 수 있었다. 최종적으로 다음 명령어를 통해 커밋 메시지를 린팅하도록 했다.

commit-msg

#!/usr/bin/env sh
npx --no-install commitlint --config ./frontend/commitlint.config.js --edit "$1"

 

배운 점

이번 경험을 통해 다음과 같은 점들을 배웠다.

• 커밋 메시지 규칙의 필요성: 프론트엔드와 백엔드 코드가 같은 레포지토리에 존재하면서, 각 커밋 메시지에 (front)와 같은 스코프를 명시해야 한다는 점을 잊지 않도록 강제할 필요성이 커졌다. 커밋 메시지의 일관성을 유지하기 위해 commitlint를 사용하여 이러한 규칙을 자동화할 수 있었다.
• 경로 설정 문제 해결: 프로젝트 구조의 특성상 commitlint.config.js 파일의 경로를 명시적으로 지정해야 했다. --config ./frontend/commitlint.config.js와 같은 설정을 통해, 서로 다른 디렉터리에 있는 설정 파일을 올바르게 참조할 수 있는 방법을 배웠다.
• Hooks 설정과 준비 스크립트: core.hooksPath를 설정하고 prepare 스크립트를 사용하는 것이 왜 중요한지 깨달았다. 이를 통해 Git 훅이 프로젝트 전반에 걸쳐 일관되게 작동하도록 설정할 수 있었다.
• 명령어 이해: npx --no-install commitlint --config ./frontend/commitlint.config.js --edit "$1"와 같은 명령어의 구조를 이해하게 되었다. 이를 통해 특정 경로에 있는 설정 파일을 지정하여 필요할 때마다 쉽게 커밋 메시지를 검사할 수 있었다.

결론적으로, 커밋 린트를 설정하는 과정은 단순해 보였지만, 여러 문제를 통해 많은 것을 배우고, 팀의 코드 품질을 높이는 데 기여할 수 있었다. 앞으로도 이런 경험을 바탕으로 더욱 나은 개발 환경을 만들어 가고자 한다.