Husky

🧩 Reference

• Husky: Git hooks를 쉽게 관리할 수 있게 해주는 도구
• Git hooks: Git 이벤트(커밋, 푸시 등) 발생 시 자동으로 실행되는 스크립트
• pre-commit: 커밋 전에 실행되는 Git hook

왜 Husky가 필요할까?

팀 프로젝트를 하다 보면 이런 상황이 생긴다:

• 커밋 후에 ESLint 에러를 발견하고 다시 커밋
• 포맷이 맞지 않는 코드가 올라와서 리뷰 시간 낭비
• 타입 오류가 있는 코드가 머지되어 빌드 실패

이런 문제를 커밋 전에 자동으로 검사하면 불필요한 커밋과 리뷰 시간을 줄일 수 있다.
Husky는 Git hooks를 프로젝트 코드로 관리할 수 있게 해주는 도구다. 이를 통해 팀 전체가 동일한 커밋 규칙을 공유할 수 있다.

🧩 프로젝트에 적용하면서 깨달은 점

• Git hooks를 직접 관리하는 것보다 Husky를 쓰는 게 훨씬 편하다.
• 커밋 전 자동 검사로 커밋 후 수정 → 다시 커밋 사이클을 줄일 수 있다.
• 팀원 간 코드 품질 기준을 자동으로 강제할 수 있다.

Git hooks란?

Git hooks는 Git 이벤트가 발생할 때 자동으로 실행되는 스크립트다.

주요 Git hooks:

• pre-commit: 커밋 전에 실행
• commit-msg: 커밋 메시지 작성 후 실행
• pre-push: 푸시 전에 실행

이 프로젝트에서는 pre-commit hook을 사용하여 커밋 전에 ESLint, Prettier, Type Check를 자동으로 실행한다.

Husky vs 직접 Git hooks 관리

직접 Git hooks 관리의 문제점

Git hooks는 .git/hooks/ 디렉터리에 직접 스크립트를 작성해야 한다.

# .git/hooks/pre-commit (Git에 포함되지 않음)
#!/bin/sh
npm run lint
npm run type-check

문제점:

• .git 폴더는 Git에 포함되지 않아 팀원과 공유 불가
• 각 팀원이 수동으로 설정해야 함
• 스크립트 수정 시 모든 팀원에게 공지 필요

Husky의 장점

Husky는 Git hooks 설정을 프로젝트 파일로 관리할 수 있게 해준다.

• .husky/ 폴더가 Git에 포함되어 팀원과 자동 공유
• npm install 시 자동으로 Git hooks 설정
• 수정 사항이 자동으로 모든 팀원에게 적용

설치 및 설정

1. Husky 설치

npm install -D husky

2. Husky 초기화

npx husky init

실행 시 다음과 같은 변화가 생긴다:

• .husky/ 폴더 생성
• package.json에 prepare 스크립트 추가
• .husky/pre-commit 파일 생성 (기본 예시)

// package.json
{
  "scripts": {
    "prepare": "husky"
  }
}

prepare 스크립트란?

prepare는 npm에서 정의한 특수 스크립트로, npm install 실행 시 자동으로 실행된다.

이를 통해 팀원이 프로젝트를 클론하고 npm install을 실행하면 Husky가 자동으로 Git hooks를 설정하게 된다.

3. pre-commit hook 설정

.husky/pre-commit 파일을 수정하여 커밋 전에 실행할 명령어를 설정한다.

# .husky/pre-commit
npx lint-staged

이제 git commit 실행 시 자동으로 lint-staged가 실행된다.

lint-staged와의 관계

Husky는 언제 실행할지(커밋 전)를 담당하고,
lint-staged는 무엇을 실행할지(ESLint, Prettier, Type Check)를 담당한다.

자세한 내용은 lint-staged 문서를 참고.

실행 흐름

개발자가 git commit 실행
     ↓
Husky의 pre-commit hook 실행
     ↓
lint-staged 실행
     ↓
변경된 파일에 대해 ESLint, Prettier, Type Check 실행
     ↓
모두 통과하면 커밋 완료
실패하면 커밋 중단

Husky 우회하기 (긴급 상황)

특별한 경우 Husky를 일시적으로 건너뛸 수 있다.

git commit --no-verify -m "urgent fix"

🚨 주의

--no-verify는 긴급한 상황에서만 사용해야 한다.
남발하면 Husky를 설정한 의미가 없어진다!

---

💡 정리

• Husky는 Git hooks를 쉽게 관리할 수 있게 해주는 도구다.
• .husky/ 폴더를 통해 Git hooks 설정을 팀원과 공유할 수 있다.
• prepare 스크립트로 npm install 시 자동으로 Git hooks를 설정한다.
• 새로운 프로젝트에서는:
  • pre-commit → lint-staged 실행
  • lint-staged → ESLint + Prettier 실행
    구조로 커밋 품질을 자동 관리했다.