Binyard

Appearance

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/ 디렉터리에 직접 스크립트를 작성해야 한다.

bash
# .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 설치 ​

bash
npm install -D husky

2. Husky 초기화 ​

bash
npx husky init

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

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

prepare 스크립트란?

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

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


3. pre-commit hook 설정 ​

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

bash
# .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를 일시적으로 건너뛸 수 있다.

bash
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 실행
      구조로 커밋 품질을 자동 관리했다.