🐶 Husky로 커밋 실수 줄이기

Husky는 Git hook을 쉽게 설정할 수 있도록 도와주는 도구예요.

보통 pre-commit, commit-msg, pre-push 등 Git의 특정 시점에 자동으로 스크립트를 실행하게 해줘요.

예를 들어:

• 커밋 전에 Lint 검사를 강제하거나
• 커밋 메시지를 검사(commitlint)
• 테스트가 실패하면 커밋/푸시를 막는 식의 흐름 제어가 가능해요

Husky 설치

npm install --save-dev husky

Husky 초기화

npx husky init

설치하면 package.json의 prepare 스크립트에 "husky"가 추가돼요:

"scripts": {
  "prepare": "husky"
},

.husky 폴더가 생기고, .husky/pre-commit 파일도 함께 생겨요 (npm test 실행 코드 포함).

.husky/pre-commit 파일에 실행 권한을 줘요.

Husky 훅 파일은 실제로 '실행되는 스크립트'이기 때문에, 운영체제에서 "실행 가능한 파일"로 인식시키는 권한 설정이 필요해요.

chmod +x .husky/pre-commit

lint-staged

Prettier, Stylelint 관련 생태계에도 기여하고 있는 개발자가 만들었어요.
Git staging 영역(= 커밋할 파일로 선택된 상태)에 올라간 파일만 대상으로 lint나 포맷을 적용할 수 있어요.
전체 프로젝트를 검사하지 않아서 속도도 빠르고, 꼭 커밋할 파일만 검사하니 효율적이기 때문에 Husky의 pre-commit 훅과 함께 사용해요.

lint-staged 설치

npm install --save-dev lint-staged

.husky/pre-commit에 lint-staged 실행 코드를 넣어줘요.

echo 'npx lint-staged' > .husky/pre-commit

package.json에 설정도 추가해줘요.

"lint-staged": {
  "**/*.{js,ts,tsx}": [
    "prettier --write",
    "eslint --fix"
  ]
}

commitlint

semantic-release, standard-version 같은 릴리즈 자동화 도구도 함께 관리하는 Conventional Changelog 팀에서 만든 커밋 메시지 검사 도구 패키지에요.

커밋 메시지를 검사해서 정해진 규칙에 맞지 않으면 커밋을 막기 때문에 팀 프로젝트에서 커밋 메시지 규칙을 통일하기 위해 사용해요.

husky의 commit-msg 훅과 함께 연결해서 사용해요.

commitlint 설치

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

commitlint 설정 파일을 만들기

.commitlintrc.json 파일을 생성하여 "@commitlint/config-conventional" 규칙을 불러와서 적용해요.

echo '{ "extends": ["@commitlint/config-conventional"] }' > .commitlintrc.json

commit-msg 훅 만들기

echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg

.husky/commit-msg에 실행 권한을 줘요.

chmod +x .husky/commit-msg

커밋 메시지 가이드 출력 (prepare-commit-msg)

커밋 메시지를 입력할 때마다, 터미널에 메시지 가이드를 출력해줘요.
매번 헷갈리지 않도록 도와주는 초보자 전용 안전장치예요.

#!/bin/sh

GREEN=$(tput setaf 2)
BLUE=$(tput setaf 4)
RED=$(tput setaf 1)
BOLD=$(tput bold)
RESET=$(tput sgr0)

echo "
${BOLD}${BLUE}📝 커밋 메시지 가이드${RESET}

${GREEN}형식${RESET}: <type>: <message> [#이슈번호]

${GREEN}예시${RESET}:
  ${BLUE}feat${RESET}: 회원가입 기능 추가
  ${BLUE}fix${RESET}: 로그인 오류 수정 #123
  ${BLUE}docs${RESET}: README 업데이트

  ${BOLD}✅ commitlint 검사 규칙 요약:${RESET}
  - ${BOLD}<type>${RESET}은 반드시 있어야 하고, ${BLUE}feat, fix, docs${RESET} 등으로 시작해야 해요.
  - ${BOLD}<message(subject)>${RESET}는 소문자로 시작해야 하고, 마침표(.)로 끝나면 안 돼요.
  - 예시 비교:
    ${GREEN}fix: login 오류 수정${RESET} ← ✅
    ${RED}Fix: Login 오류 수정.${RESET} ← ❌

사용 가능한 type 목록:
  ${BLUE}feat${RESET}      새로운 기능
  ${BLUE}fix${RESET}       버그 수정
  ${BLUE}docs${RESET}      문서 관련 변경
  ${BLUE}style${RESET}     코드 포맷팅 (세미콜론, 들여쓰기 등)
  ${BLUE}refactor${RESET}  리팩토링 (기능 변화 없음)
  ${BLUE}test${RESET}      테스트 추가/수정
  ${BLUE}chore${RESET}     기타 설정, 패키지 변경
  ${BLUE}WIP${RESET}       작업 중인 커밋 (Work in Progress)

${GREEN}TIP:${RESET} 관련된 이슈가 있다면 메시지 끝에 ${BOLD}#123${RESET}처럼 적어주세요.
"

prepare-commit-msg 실행 권한을 줘요.

chmod +x .husky/prepare-commit-msg