초보자를 위한 품질 커맨드 5편: pre-commit으로 “커밋 전에 자동 품질 체크” 돌리기

1. 마지막 퍼즐 조각 – “이제는 자동이다”

1~4편까지 우리가 만들어 온 것들을 잠깐 정리해 보면

• 2편: quality_check.bat
  → 품질 커맨드를 한 번에 돌리는 대표 버튼
• 3편: py_compile_all.py
  → Python 파일들 문법(구문) 체크하는 구문 검진기
• 4편: requirements-dev.txt + setup.cfg
  → 품질 도구(black, isort, flake8, mypy, bandit, coverage…)를
  설치하고, 같은 규칙으로 쓰게 만드는 룰북

여기까지는 “내가 원할 때, 내가 명령을 실행”하는 방식이었죠.

이제 5편에서는 한 단계 더 나갑니다.

“내가 커밋 버튼만 눌러도,
자동으로 품질 커맨드가 먼저 돌고, 문제 있으면 커밋 자체를 막아버리는 구조”

를 만드는 게 목표예요.
그 주인공이 바로

• pre-commit
• .pre-commit-config.yaml

입니다.

2. pre-commit이 뭔데 이렇게 다들 좋아할까?

pre-commit은 간단히 말해서

“Git 커밋 직전에 자동으로 실행되는 작은 프로그램들의 집합을
쉽게 관리하게 해주는 프레임워크”

입니다.

원래 Git에는 hook이라는 개념이 있습니다.

• pre-commit, pre-push, post-commit 같은 hook들은
• 특정 시점(커밋 전, 푸시 전 등)에
• 자동으로 스크립트를 실행할 수 있게 해줍니다.

문제는 이걸 직접 관리하기가 꽤 귀찮다는 점이에요.

• 각자의 PC에서 hook 스크립트를 복사해 넣어야 하고
• 수정하면 또 배포해야 하고
• 팀원마다 설정이 달라지기 쉽고…

그래서 등장한 게 도구로서의 pre-commit입니다.

• .pre-commit-config.yaml라는 하나의 설정 파일만 레포에 두고,
• 팀원들은 pre-commit install만 한 번 실행하면,
• 앞으로 커밋할 때마다 동일한 품질 체크가 자동 실행됩니다.

초보자 입장에서 요약하면

“다른 거 몰라도,
한 번만 설치해 두면,
앞으로 커밋할 때마다 품질 커맨드가 자동으로 돌아간다”

이게 pre-commit의 매력입니다.

3. .pre-commit-config.yaml 안에는 뭐가 들어갈까?

질문에서 주신 내용처럼,
대표적인 설정은 이런 훅(hook)들을 포함합니다.

• black (코드 포맷터)
• isort (import 정렬)
• flake8 (스타일/간단 에러 체크)
• bandit (보안 패턴 검사)

구조를 개념적으로 보면 이런 느낌입니다.

repos:
  - repo: https://github.com/psf/black
    rev: 23.12.1          # 사용 버전
    hooks:
      - id: black
        # 여기에서 파일 타입, 옵션 등을 설정 가능

  - repo: https://github.com/PyCQA/isort
    rev: 5.13.2
    hooks:
      - id: isort

  - repo: https://github.com/PyCQA/flake8
    rev: 7.0.0
    hooks:
      - id: flake8

  - repo: https://github.com/PyCQA/bandit
    rev: 1.7.6
    hooks:
      - id: bandit
        args: ["-r", "."]

여기서 중요한 포인트는 두 가지입니다.

1. 어떤 도구를 쓸지
2. 그 도구를 어떤 옵션으로 돌릴지

이 두 가지를 .pre-commit-config.yaml 파일 하나로
통합 관리할 수 있다는 점이에요.

4. 초보자 기준 실행 흐름 – 실제로 써보면 이렇게 된다

이제 현실적인 사용 방식을 순서대로 볼게요.

4-1. pre-commit 설치

우선, requirements-dev.txt에 pre-commit이 들어있다고 가정하고

pip install -r requirements-dev.txt

까지 끝났다면,
이제 레포 안에서 단 한 번만

pre-commit install

을 실행하면 됩니다.

이 명령을 실행하면,

• .git/hooks/pre-commit에
• pre-commit이 관리하는 스크립트가 자동으로 설치됩니다.

(이제부터 이 레포에서는 커밋할 때마다 pre-commit이 자동 실행돼요.)

4-2. 첫 실행 – pre-commit run --all-files

초보자에게 꼭 권장하는 단계입니다.

pre-commit run --all-files

이 명령은

• 지금 레포에 있는 모든 파일에 대해서
• .pre-commit-config.yaml에 정의된 모든 훅(black, isort, flake8, bandit 등) 을
  한 번씩 돌려보는 명령이에요.

보통 첫 실행에서는

• black이 코드 스타일을 자동 정리하고
• isort가 import를 재정렬하고
• flake8이 경고를 쏟아내고(?)
• bandit이 보안 관련 경고를 몇 개 뱉을 수도 있습니다.

그럴 수밖에 없는 게,

“기존 코드에는 품질 도구 기준에서 봤을 때
손댈 곳이 꽤 많다”

는 뜻이거든요.

이때는

1. 도구가 자동으로 고쳐준 파일(black, isort)을 확인하고
2. flake8, bandit 경고 중
   • 지금 당장 꼭 고쳐야 할 것
   • 나중으로 미룰 수 있는 것
     을 구분해서 하나씩 정리해 나가면 됩니다.

4-3. 평소 개발 루틴 – 커밋할 때마다 자동 실행

이제부터는 아주 쉽습니다.

1. 코드를 수정하고
2. git add ...로 변경 파일을 스테이징한 뒤
3. git commit -m "메시지"만 입력하면,

Git이 커밋을 하기 전에

1. pre-commit이 자동 실행되고
2. black, isort, flake8, bandit이 스테이징된 파일을 점검하고
3. 문제가 있으면 커밋을 막고
4. 수정 후 다시 커밋을 시도하게 됩니다.

초보자 입장에서 느끼는 사용감은 이렇습니다.

“아, 커밋 누르면 먼저 코드 정리+점검이 돌고,
통과해야만 커밋되는구나.”

즉, 코드 품질이 기본적으로 항상 일정 수준 이상을 유지하게 됩니다.

5. 품질 커맨드와 pre-commit은 어떻게 연결될까?

이 시리즈의 키워드인 “품질 커맨드”와
이제 막 배운 pre-commit은
서로 대체 관계가 아니라, 보완 관계입니다.

5-1. 품질 커맨드 = 수동·전체 점검 버튼

• quality_check.bat
  • 전체 구문 체크
  • Django 시스템 체크
  • 마이그레이션 체크
  • (필요하면) 테스트 실행까지

→ “배포 전이나 큰 기능 합치기 전에
전체 프로젝트 상태를 한 번에 점검하는 버튼”

5-2. pre-commit = 일상적인 “커밋 게이트”

• .pre-commit-config.yaml + pre-commit install
  • 변경된 파일에 대해
    black, isort, flake8, bandit 실행
  • 커밋 전에 기본적인 코드 품질을 자동으로 체크

→ “매일매일, 커밋마다,
작은 단위로 품질을 관리해 주는 문지기”

5-3. 그래서 어떻게 같이 쓰면 좋을까?

추천 방식은 이렇습니다.

1. 개발하면서
   • 커밋할 때마다 pre-commit이 실행되도록 해 두고
   • 작은 단위의 품질을 유지한다.
2. 배포 전/큰 머지 전
   • quality_check.bat을 실행해서
   • 구문 + Django 시스템 + 마이그레이션 + 테스트까지
     풀세트 검사로 최종 확인한다.

한 줄로 정리하면

“pre-commit은 커밋 단위 품질 관리,
품질 커맨드는 프로젝트 전체 건강검진”

이라고 이해하시면 됩니다.

6. 초보자용 “실전 세팅 순서” 정리

이 시리즈를 전제로,
새 프로젝트에 품질 커맨드 + pre-commit을 세팅한다면
초보자에게는 이렇게 가이드해 줄 수 있어요.

1. 개발용 도구 설치 pip install -r requirements-dev.txt
2. pre-commit 설치 & Git hook 연결 pre-commit install
3. 최초 전체 검사 pre-commit run --all-files
4. 평소 개발 루틴 # 코드 수정 git add . git commit -m "메시지" # 여기서 pre-commit 자동 실행
5. 배포/중요 머지 직전 quality_check.bat → Python 구문 체크, Django 시스템 체크, 마이그레이션, 보안 권장사항, 테스트 등을 한 번에 돌려서 최종 확인.

이 흐름만 지켜도,
“코드가 점점 지저분해지고, 어디부터 고쳐야 할지 모르겠다”는
고전적인 문제에서 꽤 멀어질 수 있습니다.

7. 용어 정리

• pre-commit
  Git hook을 관리해 주는 도구.
  커밋 전에 자동으로 black, isort, flake8, bandit 같은 도구를 실행해
  커밋 품질을 일정 수준 이상으로 유지하게 도와줍니다.
• .pre-commit-config.yaml
  pre-commit이 어떤 도구를 어떤 버전과 옵션으로 실행할지 정의하는 설정 파일.
  레포에 함께 커밋되며, 팀 전체가 같은 기준으로 품질 체크를 할 수 있게 합니다.
• Git hook
  Git이 특정 타이밍(커밋 전, 푸시 전 등)에 자동으로 실행할 수 있는 스크립트.
  pre-commit은 이 hook을 편하게 다루도록 해주는 프레임워크입니다.
• 품질 커맨드
  quality_check.bat처럼, 여러 품질 관련 명령을 한 번에 실행해
  프로젝트 전체 상태를 점검하는 스크립트(버튼).
• 자동 포매터(black)
  코드 스타일을 자동으로 정리해 주는 도구.
  “어떻게 줄을 나눌까?” 고민을 줄여줍니다.
• 린터(flake8, pylint)
  잠재적인 에러, 스타일 위반, 의심스러운 코드를 찾아주는 정적 분석 도구.
• 보안 스캐너(bandit)
  위험한 코드 패턴(하드코딩된 비밀번호, 위험한 함수 사용 등)을
  미리 찾아주는 도구.