Pre‐commit 사용법 가이드 (UV 기준) - glasslego/getting-started-with-python GitHub Wiki

🚀 설치 및 설정

1. UV와 함께 Pre-commit 설치

# UV로 프로젝트 초기화
uv init my-project
cd my-project

# Pre-commit을 개발 의존성으로 추가
uv add --dev pre-commit

# 또는 pyproject.toml에 직접 추가 후
uv sync

pyproject.toml 예시:

[project]
name = "my-project"
dependencies = []

[dependency-groups]
dev = [
    "pre-commit",
    "ruff",
    "black",
    "pytest",
]

2. Git 훅 설치

# UV 환경에서 pre-commit 실행
uv run pre-commit install

# 또는 UV shell에서 실행
uv shell
pre-commit install
exit

✅ 이제 git commit 할 때마다 자동으로 실행됩니다!

3. .pre-commit-config.yaml 설정

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.12.3
    hooks:
      - id: ruff-check
        args: [ --fix ]
      - id: ruff-format
  
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-toml

---

📝 실행 방법 (UV 환경)

자동 실행 (권장)

# UV 프로젝트에서 평소처럼 커밋
git add .
git commit -m "your commit message"
# → UV 환경에서 pre-commit 자동 실행

수동 실행

모든 파일에 대해 실행

# UV run으로 실행
uv run pre-commit run --all-files

# 또는 UV shell에서 실행
uv shell
pre-commit run --all-files
exit

특정 훅만 실행

# ruff만 실행
uv run pre-commit run ruff-check

# 여러 훅 실행
uv run pre-commit run ruff-check ruff-format

UV 프로젝트 초기 설정

# 새 프로젝트 생성
uv init my-project
cd my-project

# 개발 의존성 추가
uv add --dev pre-commit ruff black pytest

# Pre-commit 설치 및 초기 실행
uv run pre-commit install
uv run pre-commit run --all-files

# 초기 설정 커밋
git add .
git commit -m "initial project setup with pre-commit"

---

🔄 UV 기반 워크플로우

1. 새 프로젝트 시작

# 1. UV로 프로젝트 생성
uv init my-awesome-project
cd my-awesome-project

# 2. 개발 도구 설치
uv add --dev pre-commit ruff pytest mypy

# 3. Pre-commit 설정
uv run pre-commit install

# 4. 전체 코드베이스에 적용
uv run pre-commit run --all-files

2. 기존 프로젝트에 추가

# 1. 현재 프로젝트에 pre-commit 추가
uv add --dev pre-commit

# 2. 설정 파일 생성
cat > .pre-commit-config.yaml << EOF
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.12.3
    hooks:
      - id: ruff-check
        args: [--fix]
      - id: ruff-format
EOF

# 3. 설치 및 실행
uv run pre-commit install
uv run pre-commit run --all-files

3. 일상적인 개발 워크플로우

# 코드 작성
vim src/main.py

# 테스트 실행 (선택적)
uv run pytest

# 커밋 (pre-commit 자동 실행)
git add .
git commit -m "feat: add new feature"

---

🛠️ UV 환경에서 유용한 명령어들

설정 관리

# pre-commit 설정 업데이트
uv run pre-commit autoupdate

# 캐시 클리어
uv run pre-commit clean

# Git 훅 제거
uv run pre-commit uninstall

# UV 의존성 업데이트
uv sync --upgrade

개발 도구 통합

# pyproject.toml에 스크립트 추가
[project.scripts]
lint = "pre-commit run --all-files"
format = "ruff format ."
check = "ruff check ."

# 스크립트 실행
uv run lint
uv run format
uv run check

팀 협업을 위한 Makefile

# Makefile
.PHONY: install lint format test

install:
	uv sync
	uv run pre-commit install

lint:
	uv run pre-commit run --all-files

format:
	uv run ruff format .

test:
	uv run pytest

setup: install lint
	@echo "Project setup complete!"

UV Lock 파일과 함께 관리

# 의존성 고정
uv lock

# 팀원들이 동일한 환경 구성
uv sync

# pre-commit도 동일한 버전으로 실행
uv run pre-commit install

---

📊 실행 결과 해석

✅ 성공 케이스

black....................................Passed
ruff.....................................Passed
flake8...................................Passed

→ 모든 검사 통과, 커밋 진행

❌ 실패 케이스

black....................................Failed
- hook id: black
- files were modified by this hook

To see the diff of what changed, try: git diff

→ Black이 파일을 수정함, 다시 add 후 커밋 필요

⚠️ 오류 케이스

flake8...................................Failed
- hook id: flake8
- exit code: 1

src/main.py:10:80: E501 line too long (89 > 88 characters)
src/main.py:15:1: F401 'os' imported but unused

→ 직접 수정 후 다시 커밋 필요

---

🎯 UV 기반 팀 워크플로우

프로젝트 초기 설정 (팀 리더)

# 1. UV 프로젝트 생성
uv init awesome-project
cd awesome-project

# 2. pyproject.toml 설정
cat >> pyproject.toml << EOF

[dependency-groups]
dev = [
    "pre-commit>=3.0.0",
    "ruff>=0.1.0",
    "pytest>=7.0.0",
    "mypy>=1.0.0",
]

[project.scripts]
lint = "pre-commit run --all-files"
format = "ruff format ."
test = "pytest"
EOF

# 3. Pre-commit 설정 파일 생성
cat > .pre-commit-config.yaml << EOF
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.12.3
    hooks:
      - id: ruff-check
        args: [--fix]
      - id: ruff-format
  
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-toml
EOF

# 4. 환경 설정 및 커밋
uv sync
uv run pre-commit install
uv run pre-commit run --all-files
git add .
git commit -m "chore: setup project with UV and pre-commit"

팀원 환경 설정

# 1. 프로젝트 클론
git clone <repository-url>
cd awesome-project

# 2. UV 환경 설정 (자동으로 pyproject.toml 읽음)
uv sync

# 3. Pre-commit 설치
uv run pre-commit install

# 4. 테스트 실행
uv run lint
uv run test

일상적인 개발 워크플로우

# 개발자 워크플로우
uv run test          # 테스트 실행
git add .
git commit -m "feat: add user service"  # pre-commit 자동 실행

# 코드 품질 체크
uv run lint          # 전체 린트 실행
uv run format        # 코드 포맷팅

GitHub Actions 통합 (.github/workflows/ci.yml)

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install UV
        uses: astral-sh/setup-uv@v1
        
      - name: Set up Python
        run: uv python install 3.12
        
      - name: Install dependencies
        run: uv sync
        
      - name: Run pre-commit
        run: uv run pre-commit run --all-files
        
      - name: Run tests
        run: uv run pytest