개발자라면 누구나 "Fix typo"나 "Apply linter" 같은 부끄러운 커밋 로그를 남긴 경험이 있을 것입니다. 이런 사소한 실수는 단순한 부끄러움을 넘어, PR(Pull Request) 리뷰 시간을 잡아먹고 CI 파이프라인의 리소스를 낭비하게 만드는 주범입니다. 동료가 변수명 오타를 지적하느라 비즈니스 로직을 검토할 에너지를 뺏겨서는 안 됩니다. 이 글에서는 git hook을 활용한 pre-commit 프레임워크로, 커밋 버튼을 누르는 순간 코드 품질을 강제로 교정하는 프로덕션 레벨의 워크플로우를 구축해 봅니다.
Deep Dive: 왜 쉘 스크립트 대신 프레임워크인가?
Git은 기본적으로 .git/hooks 디렉토리에 쉘 스크립트를 배치하여 특정 이벤트(commit, push 등) 발생 시 스크립트를 실행할 수 있는 기능을 제공합니다. 하지만 이 방식에는 치명적인 단점이 있습니다. .git 디렉토리는 버전 관리 대상이 아니기 때문에, 팀원들에게 스크립트를 배포하고 동기화하는 것이 매우 번거롭다는 점입니다. "김 대리님, 어제 슬랙으로 보낸 스크립트 chmod +x 하셨나요?" 같은 대화가 오가는 순간 자동화는 실패한 것입니다.
팀 단위 프로젝트에서는 개별 쉘 스크립트 대신
pre-commit 프레임워크를 사용하여 훅 설정(config) 자체를 버전 관리해야 합니다. 이를 통해 신규 입사자도 git clone 후 명령어 한 번이면 동일한 검사 환경을 갖출 수 있습니다.
이러한 문제를 해결하기 위해 등장한 것이 Python으로 작성된 pre-commit 프레임워크입니다. 이는 .pre-commit-config.yaml 파일 하나로 여러 언어의 린터(Linter)와 포맷터(Formatter)를 관리하며, 실행 환경을 격리하여 로컬 라이브러리 버전 충돌 문제까지 해결합니다.
The Solution: 설정 파일 구성 및 적용
가장 범용적인 Python 및 공통 파일 검사 구성을 적용해 보겠습니다. 이 설정은 거대한 requirements.txt 설치 없이도 독립된 가상 환경에서 훅을 실행합니다.
1. 설치 및 Config 작성
프로젝트 루트에 아래와 같이 설정 파일을 생성합니다. Black(포맷터)과 Flake8(린터), 그리고 대용량 파일 커밋 방지 훅을 포함합니다.
# .pre-commit-config.yaml
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.4.0
hooks:
- id: trailing-whitespace # 줄 끝 공백 제거
- id: end-of-file-fixer # 파일 끝 개행 문자 보장
- id: check-yaml # YAML 문법 검사
- id: check-added-large-files # 500KB 이상 파일 차단
args: ['--maxkb=500']
- repo: https://github.com/psf/black
rev: 23.3.0
hooks:
- id: black
language_version: python3.10 # 특정 파이썬 버전 강제
- repo: https://github.com/pycqa/flake8
rev: 6.0.0
hooks:
- id: flake8
# E501: 라인 길이 제한 무시 (Black과 충돌 방지)
args: ['--ignore=E501,W503'] 2. 훅 설치 및 실행
설정 파일을 작성했다면, 실제로 git hooks 경로에 스크립트를 설치해야 작동합니다. 아래 명령어를 실행합니다.
# 1. 프레임워크 설치 (로컬 환경)
pip install pre-commit
# 2. .git/hooks에 스크립트 설치 (최초 1회 필수)
pre-commit install
# 3. (선택) 모든 파일에 대해 수동 실행해보기
pre-commit run --all-files급한 핫픽스 상황에서는
git commit --no-verify 옵션으로 훅 실행을 건너뛸 수 있습니다. 하지만 이 옵션을 상습적으로 사용하는 팀원은 코드 품질을 저해하는 주범이 되므로, CI 파이프라인에서 2차 검증을 반드시 수행해야 합니다.
Performance Verification
실제 사내 MSA 전환 프로젝트에서 pre-commit을 도입하기 전과 후의 지표 변화입니다. 단순한 포맷팅 리뷰가 사라지면서 리뷰의 질이 달라졌습니다.
| 지표 (Metric) | 도입 전 (Legacy) | 도입 후 (Pre-commit) | 개선율 |
|---|---|---|---|
| 평균 코드 리뷰 시간 | 45분 | 15분 | 66% 단축 |
| CI 린트 실패율 | 35% | 2% | 94% 감소 |
| "Fix typo" 커밋 비율 | 15% | 0.5% | 거의 소멸 |
Conclusion
Pre-commit은 선택이 아닌 필수 개발 환경 설정입니다. 인간은 반복적이고 사소한 규칙 검사에 취약하지만, 기계는 이를 완벽하게 수행합니다. 지금 당장 팀의 레포지토리에 .pre-commit-config.yaml을 추가하세요. 코드 리뷰 시간에는 오직 '설계'와 '로직'에만 집중할 수 있는 쾌적한 환경이 열릴 것입니다. 더 자세한 훅 목록은 공식 지원 Hooks 목록에서 확인할 수 있습니다.
Post a Comment