본문 바로가기

기록

효율적인 커밋 메세지 관리를 위한 Conventional Commits 적용하기

개발을 진행하다 보면 항상 고민이 많이 되는 부분이 커밋 메세지인 것 같습니다. 내가 쓸 때에도 잘 쓰지 않으면 문제가 되지만, 여러 명이 함께 건드리게 되는 프로젝트의 경우엔 더더욱 커밋 메세지가 명확하지 않으면 히스토리 파악이 쉽지 않을 때가 왕왕 있습니다. 이런 커밋 메세지 관리를 위해 나온 것이 Conventional Commits입니다.

Conventional Commits

Conventional Commits은 말 그대로 커밋 메세지를 위한 규칙입니다. 명확한 커밋 히스토리를 위한 간단한 규칙을 제공하고, 이를 사용하여 자동화된 도구를 만들기 쉽게 합니다. 이 규칙은 커밋 메세지에 기능, 수정 사항 및 변경 사항을 설명함으로써 SemVer(Semantic Versioning)와 일치합니다.

커밋 메세지는 아래와 같은 유형이어야 합니다:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

실제 예시는 아래와 같습니다:

chore: run tests on travis ci
fix(server): send cors headers
feat(blog): add comment section
# 타입에 !가 붙으면 BREAKING CHANGE
refactor!: drop support for Node 6

BREAKING CHANGE: refactor to use JavaScript features not available in Node 6.

위와 같은 규칙을 알아두면 좋습니다. Conventional Commits 공식 홈페이지에서 더 자세히 알아보세요.

Conventional Commits 적용하기

Conventional Commits를 따르기 위해 git hooks를 사용하여 적용해보겠습니다. 이번엔 Node.js 프로젝트에 적용해볼 에정이므로, husky 패키지를 사용하겠습니다.

프로젝트에 husky 적용하기

husky는 Node.js 프로젝트에서 git hooks를 쉽게 관리하기 위한 도구입니다. husky나 git hooks에 대한 상세한 정보는 아래 깃허브 레포지토리와 문서 링크를 통해 확인하실 수 있습니다.

husky를 사용하기 위해 프로젝트 경로에서 아래와 같이 입력해 줍니다.

# npm을 사용하는 경우
npm install husky --save-dev
npx husky install

# yarn을를 사용하는 경우
yarn add husky --dev
yarn husky install

commitlint 적용하기

이제 commitlint를 적용해봅시다.

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

위처럼 터미널에서 입력해도 되고, 직접 프로젝트 루트에 있는 .husky 디렉토리 밑에 commit-msg라는 파일을 만들고 아래 내용을 입력해도 됩니다.

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx --no-install commitlint --edit "$1"

위 방식은 따로 패키지를 설치하지 않고 실행하는 방식입니다. 위와 같은 방식 뿐만 아니라 직접 패키지를 설치하는 방향으로 진행할 수도 있습니다.

# npm을 사용하는 경우
npm install --dev @commitlint/config-conventional @commitlint/cli

# yarn을 사용하는 경우
yarn add --dev @commitlint/config-conventional @commitlint/cli

패키지를 설치하신 후, 프로젝트 루트 디렉토리에 commitlint.config.js 파일을 만들고 아래와 같이 작성해 줍니다.

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

마지막으로 프로젝트 루트 디렉토리에 있는 .husky 디렉토리 밑에 commit-msg라는 파일을 만들고 아래와 같이 작성해 줍니다.

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

# npm을 사용하는 경우
npm commitlint --edit $1

# yarn을 사용하는 경우
yarn commitlint --edit $1

테스트

이제 commitlint가 잘 적용이 되었는지 테스트 해봅시다.

# 실패 케이스
$ git add .
$ git commit -m "테스트입니다"

⧗   input: 테스트입니다
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

error Command failed with exit code 1.

# 성공 케이스
$ git commit -m "build: commitlint 적용" 

Done in 0.21s.
[main 7cefd09] build: commitlint 적용

커밋 메세지는 위에서 설명한 Conventional Commits 규칙을 따르면 됩니다. 기본적으로 허용되는 type은 아래와 같습니다.

  • build
  • ci
  • chore
  • docs
  • feat
  • fix
  • perf
  • refactor
  • revert
  • style
  • test

만약 규칙을 수정하고 싶다면 commitlint.config.js 파일을 수정해서 적용할 수 있습니다. 상세한 사항은 commitlint 문서를 참고하시면 좋습니다. 커밋 메세지 길이 뿐 아니라 다양한 설정을 상세하게 할 수 있으니 참고하시면 좋습니다.

마치며

커밋 메세지의 규칙은 여러 명이 참여하는 프로젝트를 진행할 때 아주 좋습니다. 타입과 설명을 통해 빠르게 어떤 이유로 해당 커밋이 이루어졌는지 알 수 있기 때문이죠. commitlint와 같은 도구는 이런 규칙을 잘 적용할 수 있도록 도와주기 때문에 작업의 능률이 올라갈 수 있습니다. 다음에는 이렇게 적용한 규칙을 가지고 자동으로 CHANGELOG를 작성하는 방법을 알아보도록 해야겠습니다. 긴 글 읽어주셔서 감사합니다.