Husky 완벽 가이드 | Git Hooks·Pre-commit·Lint-staged·실전 활용

2026년 4월 7일 · 11분 읽기 · 수정 2026년 4월 7일 초급

이 글의 핵심

Husky로 Git Hooks를 관리하는 완벽 가이드입니다. Pre-commit, Pre-push, Lint-staged, Commitlint까지 실전 예제로 정리했습니다.

실무 경험 공유: Husky를 도입하면서, 린트 에러가 있는 코드가 커밋되는 일이 사라지고 코드 품질이 크게 향상된 경험을 공유합니다.

들어가며: “나쁜 코드가 커밋돼요”

실무 문제 시나리오

시나리오 1: 린트 에러가 있는 코드가 푸시돼요
수동 확인은 놓치기 쉽습니다. Husky로 자동 검사합니다.

시나리오 2: 커밋 메시지가 일관적이지 않아요
규칙이 없습니다. Commitlint로 강제합니다.

시나리오 3: 테스트를 건너뛰고 푸시해요
실수로 빠뜨립니다. Pre-push Hook으로 방지합니다.

1. Husky란?

핵심 특징

Husky는 Git Hooks 관리 도구입니다.

주요 장점:

쉬운 설정: 간단한 명령어
Git Hooks: Pre-commit, Pre-push
Lint-staged: 변경된 파일만
팀 공유: package.json으로 관리
크로스플랫폼: Windows, macOS, Linux

2. 설치 및 기본 설정

설치

npm install -D husky
npx husky init

자동으로 .husky/ 폴더와 pre-commit 파일이 생성됩니다.

.husky/pre-commit

npm test

3. Pre-commit Hook

ESLint + Prettier

# .husky/pre-commit
npm run lint
npm run format:check

전체 파일 검사

# .husky/pre-commit
npm run lint
npm run test

4. Lint-staged

설치

npm install -D lint-staged

.husky/pre-commit

npx lint-staged

package.json

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,css,md}": [
      "prettier --write"
    ]
  }
}

5. Pre-push Hook

# .husky/pre-push
npm run test
npm run build

6. Commitlint

설치

npm install -D @commitlint/cli @commitlint/config-conventional

commitlint.config.js

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',
        'fix',
        'docs',
        'style',
        'refactor',
        'test',
        'chore',
      ],
    ],
  },
};

.husky/commit-msg

npx --no -- commitlint --edit $1

커밋 메시지 형식

feat: add user authentication
fix: resolve login bug
docs: update README
style: format code
refactor: simplify API logic
test: add unit tests
chore: update dependencies

7. 실전 예제: 풀 설정

package.json

{
  "scripts": {
    "lint": "eslint src",
    "lint:fix": "eslint src --fix",
    "format": "prettier --write \"src/**/*.{js,jsx,ts,tsx,json,css,md}\"",
    "format:check": "prettier --check \"src/**/*.{js,jsx,ts,tsx,json,css,md}\"",
    "test": "jest",
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write",
      "jest --bail --findRelatedTests"
    ],
    "*.{json,css,md}": [
      "prettier --write"
    ]
  },
  "devDependencies": {
    "husky": "^9.0.0",
    "lint-staged": "^15.0.0",
    "@commitlint/cli": "^18.0.0",
    "@commitlint/config-conventional": "^18.0.0"
  }
}

.husky/pre-commit

npx lint-staged

.husky/pre-push

npm run test
npm run build

.husky/commit-msg

npx --no -- commitlint --edit $1

8. 특정 Hook 비활성화

# 일시적으로 비활성화
git commit --no-verify -m "WIP: work in progress"

9. CI/CD 통합

GitHub Actions

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run lint
      - run: npm run format:check
      - run: npm test

정리 및 체크리스트

핵심 요약

Husky: Git Hooks 관리
Pre-commit: 커밋 전 검사
Lint-staged: 변경된 파일만
Commitlint: 커밋 메시지 규칙
Pre-push: 푸시 전 검사
팀 공유: package.json

구현 체크리스트

같이 보면 좋은 글

ESLint 완벽 가이드
Prettier 완벽 가이드
Git 완벽 가이드

이 글에서 다루는 키워드

Husky, Git Hooks, Pre-commit, Lint-staged, Code Quality, Git, Frontend

자주 묻는 질문 (FAQ)

Q. 팀원도 자동으로 설정되나요?

A. 네, npm install 시 자동으로 설정됩니다.

Q. Windows에서도 작동하나요?

A. 네, 크로스플랫폼으로 작동합니다.

Q. Hook을 건너뛸 수 있나요?

A. 네, —no-verify 플래그를 사용하면 됩니다.

Q. 프로덕션에서 사용해도 되나요?

A. 네, 거의 모든 JavaScript 프로젝트에서 사용하고 있습니다.