اگر می‌خواهید کدی که کامیت می‌کنید همیشه تمیز، فرمت‌شده و بدون خطای سرسری باشد، pre-commit دقیقاً همان ابزاری است که باید بشناسید. این ابزار به‌جای تکیه بر حافظه‌ی شما، یک فایل پیکربندی واحد را می‌خواند و پیش از هر git commit، لینتر، فرمت‌کننده و تست‌های سبک پروژه را خودکار اجرا می‌کند. در این آموزش از نصب تا نوشتن اولین .pre-commit-config.yaml و افزودن Ruff و Pytest قدم‌به‌قدم جلو می‌رویم؛ پس جای درستی آمده‌اید.

آموزش pre-commit در پایتون و اجرای خودکار چک‌ها قبل از هر کامیت

pre-commit یک مدیر هوک چندزبانه است که با یک بار نصب، اسکریپت‌های Git شما را مدیریت می‌کند. کافی است با pip install pre-commit نصبش کنید، فایل .pre-commit-config.yaml را بسازید و pre-commit install بزنید؛ از آن به بعد هر کامیت به‌طور خودکار بررسی می‌شود. ادامه‌ی مطلب مراحل دقیق، پیکربندی آماده و خطاهای رایج را پوشش می‌دهد.

فهرست مطالب

pre-commit چیست و چرا جلوی کامیت خراب را می‌گیرد؟
پیش‌نیازها و نصب pre-commit
ساخت اولین فایل .pre-commit-config.yaml
نصب هوک گیت و اجرای اولین کامیت
افزودن Ruff و Pytest به‌صورت هوک
دستورات روزمره pre-commit
کاربرد واقعی: pre-commit در تیم و CI
نکات امنیتی و پایداری
اشتباهات و خطاهای رایج
سوالات متداول
جمع‌بندی

pre-commit چیست و چرا جلوی کامیت خراب را می‌گیرد؟

Git هوک‌های داخلی دارد، اما مدیریت دستی آن‌ها سخت و شکننده است: هر توسعه‌دهنده باید اسکریپت را جدا کپی کند، نسخه‌ی ابزار را خودش نصب کند و روی سیستم‌عامل‌های مختلف با آن کشتی بگیرد. pre-commit این لایه را استاندارد می‌کند. شما فقط مشخص می‌کنید «چه ابزارهایی و با چه نسخه‌ای» باید اجرا شوند؛ pre-commit خودش مخزن هر هوک را می‌گیرد، محیط ایزوله‌اش را می‌سازد، کش می‌کند و روی فایل‌های استیج‌شده اجرا می‌کند.

نکته‌ی کلیدی این است که pre-commit فقط روی محتوای استیج‌شده کار می‌کند و تغییرهای استیج‌نشده را موقتاً کنار می‌گذارد. یعنی همان چیزی که واقعاً کامیت می‌شود بررسی می‌شود، نه وضعیت نیم‌کاره‌ی پوشه‌ی کاری.

پیش‌نیازها و نصب pre-commit

برای شروع به Git (نسخه‌ی ۲.۲۴ به بالا برای هوک‌های merge) و Python 3.9 یا بالاتر نیاز دارید. خود pre-commit یک پکیج پایتونی است، اما برای اجرای هوک‌های زبان‌های دیگر (مثل Node یا Go) بقیه‌ی پیش‌نیازها را خودش می‌سازد.

pip install pre-commit
# یا با ابزار مدیریت محیط:
uv tool install pre-commit
# یا:
pipx install pre-commit

pre-commit --version

خروجی دستور آخر نسخه را نشان می‌دهد؛ در زمان نوشتن این آموزش، آخرین نسخه‌ی پایدار 4.7.0 است. برای اینکه هم‌تیمی‌هایتان هم همان نسخه را داشته باشند، pre-commit را به فایل وابستگی‌های توسعه اضافه کنید:

# requirements-dev.txt
pre-commit

ساخت اولین فایل .pre-commit-config.yaml

فایل پیکربندی باید در ریشه‌ی مخزن Git قرار بگیرد. معتبرترین راه، خودداری از نمونه‌های قدیمی اینترنتی و استفاده از دستور رسمی نمونه‌سازی است:

pre-commit sample-config

اما یک پیکربندی آماده و به‌روز برای پروژه‌ی پایتون این است. نسخه‌ها را عمداً دقیق پین کرده‌ام تا رفتار همه‌جا یکسان باشد:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-merge-conflict
      - id: check-added-large-files
      - id: detect-private-key

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.17.0
    hooks:
      - id: ruff-check
        args: [--fix]
      - id: ruff-format

توضیح خط‌به‌خط پیکربندی

repo: نشانی مخزن Git هوک، یا مقدار ویژه‌ی local برای هوک‌های خودتان.
rev: تگ یا هش کامیت همان مخزن؛ این مهم‌ترین خط برای تکرارپذیری است.
hooks: فهرست شناسه‌های هوک (id). هر id دقیقاً همان چیزی است که مخزن هوک تعریف کرده است.
args: آرگومان‌های اضافی مثل --fix که Ruff را در حالت اصلاح خودکار اجرا می‌کند.

یک ظرافت مهم: در ruff-pre-commit نسخه‌ی ۰.۱۷، شناسه‌ی ruff فقط یک نام مستعار قدیمی برای ruff-check است. اگر در آموزش‌های قدیمی id: ruff دیدید بدانید همچنان کار می‌کند، اما شناسه‌ی رسمی و آینده‌دار ruff-check است.

نصب هوک گیت و اجرای اولین کامیت

حالا نصبش کنید تا git در هر کامیت آن را صدا بزند:

pre-commit install
# pre-commit installed at .git/hooks/pre-commit

قبل از کامیت بعدی، یک بار روی کل فایل‌ها اجرا کنید تا محیط هوک‌ها ساخته شود. اولین اجرا ممکن است کمی طول بکشد، چون pre-commit مخزن‌ها را clone و محیطشان را نصب می‌کند:

pre-commit run --all-files

خروجی چیزی شبیه این است و برای هر هوک وضعیت Passed یا Failed را می‌بینید:

trim trailing whitespace.................................................Passed
fix end of files.........................................................Failed
- hook id: end-of-file-fixer
- files were modified by this hook
check yaml...............................................................Passed
ruff check...............................................................Passed
ruff format..............................................................Passed

اگر هوکی مثل end-of-file-fixer فایل را تغییر دهد، کامیت متوقف می‌شود تا تغییرها را ببینید. کافی است دوباره git add کنید و کامیت را تکرار کنید؛ این طبیعی‌ترین رفتار pre-commit است.

افزودن Ruff و Pytest به‌صورت هوک

Ruff همان ابزار سریع لینت و فرمت است که در آموزش جداگانه‌ی آموزش Ruff در پایتون کامل توضیح داده‌ایم؛ pre-commit فقط اجرای خودکارش را روی هر کامیت سوار می‌کند. برای تست‌ها هم می‌توانید همان ایده‌ی آموزش Pytest در پایتون را به‌صورت یک هوک محلی اضافه کنید:

repos:
  - repo: local
    hooks:
      - id: pytest
        name: pytest (fast tests)
        entry: pytest -q
        language: unsupported
        pass_filenames: false
        always_run: true
        stages: [pre-push]

چند نکته‌ی مهم در این هوک: repo: local یعنی هوکی که خودتان تعریف کرده‌اید؛ pass_filenames: false مانع می‌شود pytest نام فایل‌های استیج‌شده را به‌جای مسیر پروژه بگیرد؛ و always_run: true باعث می‌شود حتی وقتی فایل پایتونی تغییر نکرده هم اجرا شود. مقدار language: unsupported از نسخه‌ی 4.4.0 جایگزین system شده و به pre-commit می‌گوید از ابزار نصب‌شده در محیط فعلی استفاده کند، پس مطمئن شوید pytest در همان محیط virtualenv نصب است.

دستورات روزمره pre-commit

pre-commit run --all-files        # اجرا روی همه‌ی فایل‌ها (مناسب CI)
pre-commit run ruff-check         # فقط یک هوک مشخص
pre-commit autoupdate             # به‌روزرسانی rev هوک‌ها به آخرین تگ
pre-commit autoupdate --freeze    # پین کردن rev به هش (پایدارتر)
pre-commit validate-config        # اعتبارسنجی فایل پیکربندی
pre-commit clean                  # پاک‌کردن کش هوک‌ها

اگر خواستید موقتاً یک هوک را رد کنید، کل کامیت را با --no-verify نزنید؛ بهتر است فقط همان هوک را skip کنید:

# لینوکس و مک
SKIP=ruff-check git commit -m "docs: update readme"

# ویندوز (PowerShell)
$env:SKIP="ruff-check"; git commit -m "docs: update readme"

اجرای مرحله‌ای: pre-commit در برابر pre-push

از نسخه‌ی 3.2.0، مقادیر stages هم‌نام خود هوک‌های گیت هستند: pre-commit، pre-push، commit-msg، manual و غیره. پیشنهاد می‌کنم چک‌های سریع را در pre-commit و تست‌های کندتر را در pre-push بگذارید تا هر کامیت کوچک شما را معطل نکند. برای نصب چند نوع هوک با هم:

pre-commit install --hook-type pre-commit --hook-type pre-push

یا آن را در بالای پیکربندی کلی کنید تا با یک pre-commit install همه نصب شوند:

default_install_hook_types: [pre-commit, pre-push]

کاربرد واقعی: pre-commit در تیم و CI

ارزش اصلی pre-commit وقتی دیده می‌شود که یک تیم از آن استفاده کند. چون rev پین است، همه دقیقاً یک نسخه از Ruff و همان مجموعه هوک را اجرا می‌کنند؛ دیگر بحث «روی سیستم من پاس می‌شود» پیش نمی‌آید. همان دستور pre-commit run --all-files را در CI هم بگذارید تا حتی اگر کسی هوک را نصب نکرده باشد، خط لوله شکست بخورد.

روش	سرعت	هزینه‌ی نگهداری	مناسب برای
اسکریپت دستی در .git/hooks	سریع	بالا (کپی دستی، شکننده)	پروژه‌ی تک‌نفره و کوچک
pre-commit	سریع تا متوسط	پایین (یک فایل پیکربندی)	تیم‌ها و پروژه‌های چندزبانه
فقط CI	کند (بازخورد دیرهنگام)	متوسط	به‌عنوان لایه‌ی دوم حفاظتی

نکات امنیتی و پایداری

هوک‌ها کدِ اشخاص ثالث از GitHub هستند که روی ماشین شما اجرا می‌شود؛ پس rev را پین کنید و ترجیحاً با pre-commit autoupdate --freeze به هش کامیت قفل کنید تا تغییر ناخواسته‌ی تگ مشکلی ایجاد نکند.
قبل از merge هر به‌روزرسانی هوک، دیف آن نسخه را مرور کنید؛ به‌روزرسانی کورکورانه‌ی خودکار ریسک دارد.
عادت نکنید هر کامیت را با --no-verify رد کنید، وگرنه کل مزیت ابزار از بین می‌رود.
هوک‌های detect-private-key و check-added-large-files را همیشه در فهرست داشته باشید تا کلید و فایل سنگین اشتباهی وارد مخزن نشود.
pre-commit برای ساخت محیط هوک‌ها به دسترسی شبکه نیاز دارد؛ در شبکه‌های محدود باید پروکسی را برای Git تنظیم کنید، وگرنه اولین اجرا در clone مخزن‌ها گیر می‌کند.

اشتباهات و خطاهای رایج

pre-commit: command not found: ابزار در PATH نیست. با pipx یا uv tool install نصب کنید و ترمینال را دوباره باز کنید.
Permission denied روی اسکریپت هوک در لینوکس/مک: فایل اجرایی نیست. یک بار pre-commit install --overwrite بزنید یا مجوز اجرا بدهید.
اجرا نشدن هوک با وجود نصب: اگر git config core.hooksPath تنظیم شده باشد، Git پوشه‌ی .git/hooks را نادیده می‌گیرد؛ آن را با git config --unset core.hooksPath حذف کنید.
Repository does not contain hook بعد از تغییر نام یک هوک (مثلاً ruff به ruff-check): pre-commit autoupdate بزنید و شناسه را در فایل پیکربندی اصلاح کنید.
گیر کردن اولین اجرا: معمولاً به‌خاطر clone نشدن مخزن‌ها از GitHub است؛ اتصال و پروکسی را بررسی کنید.
هوک فایل را تغییر داد ولی کامیت رد شد: تغییرها را با git add دوباره استیج کنید و کامیت را تکرار کنید.

سوالات متداول

pre-commit چه فرقی با گیت هوک دستی دارد؟

هوک دستی را باید در هر مخزن کپی و به‌روز نگه دارید و به نصب‌بودن ابزار روی سیستم هر نفر وابسته است. pre-commit خودش مخزن هوک، نسخه و محیط ایزوله را مدیریت می‌کند و فقط با یک فایل YAML قابل اشتراک است.

چطور فقط یک هوک را موقتاً رد کنم؟

از متغیر محیطی SKIP استفاده کنید: SKIP=ruff-check git commit -m "...". این روش از --no-verify امن‌تر است، چون فقط یک هوک را نادیده می‌گیرد نه همه‌ی بررسی‌ها.

آیا pre-commit تست‌ها را هم اجرا می‌کند؟

خودِ pre-commit فقط هوک‌ها را اجرا می‌کند، اما با یک هوک repo: local می‌توانید pytest را هم سوار کنید. برای اینکه هر کامیت کند نشود، آن را در مرحله‌ی pre-push قرار دهید.

آیا روی ویندوز هم کار می‌کند؟

بله. با pip، pipx یا uv نصب می‌شود و هوک‌ها به‌طور بومی روی ویندوز اجرا می‌شوند؛ فقط برای تنظیم متغیر SKIP از سینتکس PowerShell استفاده کنید.

چرا اجرای اول این‌قدر طول می‌کشد؟

چون pre-commit برای هر هوک مخزنش را clone و محیط ایزوله‌اش را نصب می‌کند. این کار فقط یک بار انجام می‌شود و نتیجه در کش محلی ذخیره می‌ماند؛ اجراهای بعدی سریع هستند.

تفاوت pre-commit با ابزارهای جاوااسکریپتی مثل Husky چیست؟

Husky و lint-staged عمدتاً در اکوسیستم Node کار می‌کنند، اما pre-commit چندزبانه است و می‌تواند هم‌زمان هوک پایتون، Node، Go و هر زبان دیگری را در یک فایل مدیریت کند.

جمع‌بندی

در این آموزش دیدیم که pre-commit چطور یک عادت کوچک را به یک گاردریل خودکار تبدیل می‌کند. برای شروع، همین چک‌لیست را انجام دهید:

pip install pre-commit و افزودن آن به فایل وابستگی‌های توسعه.
ساخت .pre-commit-config.yaml با هوک‌های pre-commit-hooks نسخه‌ی v6.0.0.
افزودن ruff-check و ruff-format از ruff-pre-commit نسخه‌ی v0.17.0.
نصب هوک با pre-commit install و یک بار اجرای pre-commit run --all-files.
افزودن هوک محلی pytest در مرحله‌ی pre-push برای تست‌ها.
ثبت همان pre-commit run --all-files در CI و پین کردن نسخه‌ها با autoupdate --freeze.

با این شش قدم، کد شما قبل از رسیدن به مرحله‌ی بازبینی تمیز می‌شود و بازبین می‌تواند به‌جای ایرادهای نگارشی، روی منطق و معماری تمرکز کند. برای تعمیق مهارت‌های پایتون، پیشنهاد می‌کنیم سراغ آموزش Ruff و آموزش Pytest بروید.

آموزش pre-commit در پایتون؛ چک خودکار قبل از کامیت