03-04 Git 훅과 자동화

커밋·푸시 시점에 검사·작업을 자동 실행하는 Git 훅 — 품질을 코드로 강제한다.

---

커밋·푸시 시점에 검사·작업을 자동 실행하는 Git 훅 — 품질을 코드로 강제한다.

목표: 잘못된 커밋이 들어오기 전에 자동으로 막기

---

🪝 Git 훅이란

특정 Git 이벤트(커밋, 푸시 등)에 자동 실행되는 스크립트. .git/hooks/에 위치하며 실행 권한이 있으면 동작한다.

ls .git/hooks/        # 샘플들(*.sample) 확인

[!warning] 훅은 기본적으로 공유 안 됨 .git/hooks/는 클론에 포함되지 않는다. 팀 공유는 pre-commit/husky 같은 도구 또는 core.hooksPath로 해결한다.

---

📋 주요 훅 종류

훅	시점	용도	실패 시
pre-commit	커밋 직전	린트·포맷·테스트	커밋 중단
commit-msg	메시지 작성 후	메시지 규칙 검사(commitlint)	커밋 중단
prepare-commit-msg	메시지 편집 전	템플릿·이슈번호 자동 삽입	-
pre-push	푸시 직전	테스트·빌드	푸시 중단
post-merge	머지 후	의존성 재설치 등	-
pre-receive/post-receive	서버 수신	서버측 정책·배포	거부 가능

graph LR
    EDIT["편집"] --> PC["pre-commit<br/>(린트/테스트)"]
    PC --> CM["commit-msg<br/>(메시지 검사)"]
    CM --> COMMIT["커밋"]
    COMMIT --> PP["pre-push<br/>(테스트)"]
    PP --> PUSH["푸시"]

---

✍️ 기본 훅 작성 예

.git/hooks/pre-commit (실행 권한 필요: chmod +x):

#!/bin/sh
# 스테이징된 JS 파일 린트
files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.js$')
[ -z "$files" ] && exit 0
npx eslint $files || {
  echo "❌ ESLint 실패 — 커밋 중단"
  exit 1
}

exit code가 0이 아니면 해당 동작(커밋/푸시)이 중단된다.

---

🤝 팀 공유: pre-commit / husky

pre-commit (프레임워크, 언어 무관)

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-added-large-files

pip install pre-commit
pre-commit install        # .git/hooks에 연결
pre-commit run --all-files

husky + lint-staged (JS 생태계)

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

npx husky init
echo "npx lint-staged" > .husky/pre-commit

lint-staged는 스테이징된 파일만 검사해 빠르다.

core.hooksPath (도구 없이 공유)

git config core.hooksPath .githooks   # 저장소에 커밋된 .githooks 사용

---

🔗 훅 ↔ CI 역할 분담

	로컬 훅	CI
속도	빠른 피드백	느리지만 강제
신뢰	우회 가능(--no-verify)	우회 불가
역할	1차 방어(편의)	최종 게이트

[!tip] 훅은 우회 가능하다 git commit --no-verify로 훅을 건너뛸 수 있다. 따라서 진짜 품질 게이트는 CI(브랜치 보호 + 상태 체크)에 둬야 한다. 훅은 빠른 1차 피드백용. → 02-02-PR과-코드-리뷰

---

📋 체크리스트

• 훅 종류와 시점 파악
• pre-commit/commit-msg/pre-push 용도
• 직접 훅 작성(exit code로 중단)
• pre-commit/husky로 팀 공유
• lint-staged로 스테이징 파일만 검사
• --no-verify 우회와 CI 보완
• core.hooksPath

---

🔗 관련 노트

• 03-03-모노레포와-대용량-관리 — 이전
• 03-05-트러블슈팅과-재해-복구 — 다음
• 02-03-커밋-컨벤션과-시맨틱-버저닝 — commitlint
• 02-02-GitHub-Actions — CI 게이트

---

마지막 업데이트: 2026-06-02