카테고리 없음

pre-commit으로 Python 코드 자동 정리하기

zmo 2025. 6. 9. 19:12

매번 코드를 스타일에 맞추어 작성하기는 번거로울수 있다. 각자의 습관 때문에, 혹은 검토를 한다는 번거로움은 코드를 작성하기도 전에 막막하고 하기 싫다는 느낌을 받을수도 있다. 

협업 중 코드를 작성하고 커밋하려는 순간, 팀원이 이런 말을 할수도 있다.
“이거 black 돌렸어?”, “import 순서 좀 맞춰줄래?”, “탭이 이상한데?”

매번 수동으로 포매터를 돌리는 것도 번거롭고, 스타일 이슈로 리뷰가 지연되기도 한다.
이럴 때 필요한 게 바로 pre-commit 도구다. 커밋 전에 자동으로 코드를 검사하고 정리해주는 훅(Hook) 시스템이다.

 

오늘은 pre-commit 도구는 우리에게 어떤 편안함을 주고 어떻게 세팅하면 될지 알아보자

 

 

 

 

1. 왜 pre-commit이 필요할까?

  • 협업 시 코드 스타일을 맞추는 건 중요하다.
  • black, flake8, isort 등을 수동으로 돌리는 건 번거롭다.
  • 사람이 까먹지 않도록 Git 커밋 전에 자동 실행되면 실수를 줄일 수 있다.
  • 코드 리뷰를 스타일 문제보다 로직 중심으로 진행할 수 있다.

 

2. Git Hook이란?

Git은 커밋, 푸시, 병합 등 이벤트 전에 특정 스크립트를 실행할 수 있는 Hook 기능을 제공한다.

대표적인 Hook:

  • pre-commit: 커밋 전 실행
  • pre-push: 푸시 전 실행
  • commit-msg: 커밋 메시지 검사

Hook은 .git/hooks/ 폴더에 존재하지만, 직접 작성하면 관리가 번거롭다.
이를 대신해서 Hook을 편하게 관리해주는 도구가 바로 pre-commit이다.

 

3. pre-commit이란?

pre-commit은 Git Hook을 관리하는 Python 기반 도구다.
설정 파일에 원하는 검사 도구(예: black, flake8, isort 등)를 지정해두면,
커밋 전에 자동으로 실행해준다.

 

4. 설치 및 기본 설정

 

▶️ 1) 설치

pip install pre-commit

▶️ 2) 설정 파일 작성 (.pre-commit-config.yaml)

repos:
  - repo: https://github.com/psf/black
    rev: 24.3.0
    hooks:
      - id: black

  - repo: https://github.com/pycqa/flake8
    rev: 6.1.0
    hooks:
      - id: flake8

  - repo: https://github.com/pre-commit/mirrors-isort
    rev: v5.12.0
    hooks:
      - id: isort

▶️ 3) Git Hook에 등록

pre-commit install

이제부터는 git commit을 할 때마다 위에 정의한 도구들이 자동 실행된다.
문제가 있으면 커밋이 실패하고, 수정 후 다시 시도할 수 있다.

 

5. 사용 예시

예를 들어 아래처럼 포맷이 틀린 코드를 작성해 보자:

import sys, os

def test():print("hello")

이 상태에서 커밋하려고 하면 black, flake8, isort가 실행되고,
다음과 같은 메시지를 출력한 후 커밋을 막는다.

black....................................Failed
- file.py: reformatted

flake8...................................Failed
- file.py: line 1: multiple imports on one line

isort....................................Failed
- file.py: Imports are not sorted correctly

이후 자동 수정되거나, 직접 수정 후 재커밋하면 된다.

 

6. 협업에서의 장점

  • 팀 전체 코드 스타일을 통일할 수 있다.
  • 수동 실행을 피할 수 있어 시간 절약된다.
  • 포맷 문제로 코드 리뷰 시간을 낭비하지 않는다.
  • 설정 파일을 프로젝트에 공유하면, 팀원이 동일한 검사 기준을 갖게 된다.

추가로

.pre-commit-config.yaml 예시는 기본적으로 잘 작동하지만.
완전히 "그대로 따라만 해서" 쓸 수 있으려면 아래 그대로 따라 해도 되는 전제 조건을 확인해보자

 

그대로 따라 해도 되는 전제 조건

 

1. Python 프로젝트가 Git 저장소로 초기화돼 있어야 한다

git init

이 명령어가 먼저 실행되어야 pre-commit install이 작동한다.
그렇지 않으면 .git 폴더가 없어서 Hook이 걸리지 않는다.

 

2. Python 3.7 이상 환경에서 작동 보장

black 같은 도구는 Python 3.7 이상을 권장하거나 요구한다.
Anaconda, pyenv, Poetry 등의 가상환경 안에서 작업하면 충돌을 줄일 수 있다.

 

3. 설치 후 꼭 실행해야 할 명령어

pre-commit install

이 명령어를 실행해야 Git의 pre-commit Hook에 연결된다.
설정만 해놓고 이걸 안 하면 자동 실행이 안 된다.

 

4. 첫 실행 시 자동으로 다운로드됨

pre-commit은 .pre-commit-config.yaml에 있는 repo: URL을 통해
각 린터 도구를 설치한다. 처음 실행하면 약간의 시간이 걸릴 수 있다.

pre-commit run --all-files

이 명령어로 전체 파일에 대해 한 번 실행해보면 잘 설정되었는지 확인할 수 있다.

 

5. : rev: 버전은 꼭 고정하자

예시에 나온 설정은 안정적인 버전 기준이다:

- repo: https://github.com/psf/black
  rev: 24.3.0

여기서 rev:는 반드시 GitHub 릴리스에 있는 태그명 또는 커밋 해시여야 한다.
버전을 생략하면 pre-commit이 설치를 거부한다.

 

결론


Python 프로젝트 내에서 코드 스타일 통일이 어렵다면 혹은 개인적으로도 코드 스타일을 일관성 있게 유지하고 싶을때

pre-commit install 후 사용해보자.

더보기