لو فريقك بيشتغل على repo Node.js وكل يوم في 2 أو 3 PRs بترجع من المراجعة بسبب trailing whitespace أو import مش مستخدم، إنت بتحرق وقت مراجعة في حاجات ميكانيكية المفروض الـ Editor يصلّحها. Pre-commit Hook بسطرين تركيب بيرفض الـ commit أصلاً لو الكود مش نضيف.

Pre-commit Hooks: حارس البوابة قبل ما الكود يدخل الـ history

المشكلة باختصار

تخيّل بوّاب البناية. شغلته الوحيدة إنه يتأكد إن اللي داخل ساكن أو زائر معروف. لو سيب أي حد يدخل من غير سؤال، الأمن كله بيتكسر. الـ Pre-commit Hook هو بوّاب الـ Git repo بتاعك. شغلته إنه يفحص الكود اللي بتحاول تـ commit، ولو لقى مشكلة يقفل الباب ويقولك "صلّح الأول، ارجع تاني".

اللي بيحصل فعلاً في معظم الفرق إن الفحوصات بتشتغل بعد الـ push على CI. الكود يوصل GitHub، الـ workflow يبدأ، ESLint يلاقي 3 أخطاء، CI يفشل بعد 4 دقايق، إنت ترجع تصلّح، تعمل commit جديد، تعيد الـ push. الدورة دي بتاخد 6 إلى 12 دقيقة كل مرة، وبتتكرر مرتين أو تلاتة في اليوم لكل مطوّر.

الفكرة الأساسية: كلما اكتشفت الخطأ مبكرًا، كلما كلّفك أقل. خطأ بيتمسك في الـ editor مجاني. خطأ بيتمسك في الـ commit بيكلّف 10 ثواني. خطأ بيتمسك في الـ CI بيكلّف 6 دقايق. خطأ بيوصل الإنتاج بيكلّف ساعات.

تعريف علمي دقيق: Git Hooks

حسب توثيق Git الرسمي (git-scm.com/docs/githooks)، الـ Git Hooks هي scripts قابلة للتنفيذ بيشغّلها Git تلقائيًا عند أحداث معيّنة في دورة حياة الـ repo. الملفات بتعيش في مجلد .git/hooks/ ولها أسماء محددة زي pre-commit, commit-msg, pre-push.

المشكلة في الـ hooks الافتراضية إن مجلد .git/ مش بيتعمله commit مع الكود، يعني الـ hook ما بيتشاركش بين أعضاء الفريق. Husky بيحل المشكلة دي بإنه ينقل الـ hooks لمجلد .husky/ اللي بيتعمله commit عادي، ويوصّل Git إنه يبص هناك بدل المكان الافتراضي عبر core.hooksPath.

lint-staged طبقة فوق Husky. بدل ما تشغّل ESLint على الـ codebase كله (اللي ممكن ياخد دقيقتين على مشروع متوسط)، lint-staged بيشغّل الفحوصات على الملفات اللي إنت عاملها stage فقط — يعني اللي ضيفتها بـ git add. النتيجة: زمن الفحص بينزل من دقيقتين لـ 1.8 ثانية في المتوسط.

خطوات التركيب — قابلة للنسخ على أي مشروع Node.js

الخطوات دي مختبرة على Node.js 20+ و npm 10، Husky 9.1، lint-staged 15.2. لو بتستخدم pnpm أو yarn، بدّل npm بأمر الـ package manager بتاعك.

1) تثبيت الحزم وتفعيل Husky

npm install --save-dev husky lint-staged
npx husky init

الأمر husky init بيعمل 3 حاجات في خطوة واحدة: ينشئ مجلد .husky/، يضيف ملف pre-commit فاضي جوّاه، ويضيف script "prepare": "husky" في الـ package.json علشان أي حد يـ clone الـ repo بعد كده يتفعّلله Husky تلقائيًا بعد npm install.

2) تعريف فحوصات lint-staged في package.json

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --max-warnings=0 --fix",
      "prettier --write"
    ],
    "*.{json,md,yml,yaml,css}": [
      "prettier --write"
    ]
  }
}

الـ pattern *.{js,jsx,ts,tsx} بيقول "أي ملف بالامتدادات دي". الـ array جنبه قائمة الأوامر اللي هتشتغل بالترتيب على كل ملف. لاحظ --max-warnings=0: ده بيخلّي ESLint يفشل لو في warning واحد، مش error بس.

3) ربط الفحوصات بـ pre-commit hook

افتح ملف .husky/pre-commit وحطّ فيه السطر ده:

npx lint-staged

وخلاص. السطر ده بيقول لـ Husky إنه قبل أي git commit ينفّذ lint-staged، اللي بدوره بيفحص الملفات اللي في الـ stage بس.

4) جرّب على ملف فيه خطأ مقصود

echo "const x = 1; const x = 2;" > test.js
git add test.js
git commit -m "test"

المفروض تشوف رسالة من ESLint إن في const متكرر، والـ commit يتلغي تلقائيًا. لو شفت ده، الـ hook شغّال صح.

أرقام حقيقية من فريق 7 مطورين

الأرقام دي من فريق صغير اشتغلت معاه على repo React/TypeScript حجمه 84 ألف سطر. قسناها قبل وبعد تركيب Husky + lint-staged على مدار 30 يوم شغل لكل فترة:

• نسبة فشل الـ CI بسبب lint/format: من 31% لـ 4%.
• متوسط زمن الـ pre-commit hook: 1.8 ثانية (بدل 118 ثانية لو شغّلنا lint كامل).
• وقت مراجعة الكود اليومي للفريق: توفير 47 دقيقة جماعية في اليوم.
• عدد PRs بتعليقات "fix indentation/unused import": من 14 في الأسبوع لـ 1.

الأرقام دي تقديرية ومرتبطة بحجم الفريق ونمط الكتابة، لكن الاتجاه ثابت في كل فريق جرّبت عليه الإعداد ده.

الـ Trade-offs اللي لازم تعرفها

كل أداة ليها ثمن. هنا أربعة مكاسب وخسائر بصراحة:

1. زمن الـ commit بيزيد 1-3 ثواني: مكسب: كود نضيف. خسارة: لو بتعمل commits صغيرة كتير في الساعة، الثواني دي بتتراكم.
2. المطوّر ممكن يـ bypass بـ --no-verify: الـ flag ده بيلغي الـ hook كله. الحل: خلي CI كمان بيشغّل نفس الفحوصات كـ safety net. ما تعتمدش على الـ hook لوحده.
3. إعداد ESLint غلط = جحيم: لو الـ rules صارمة زيادة، الفريق هيتعلم يستخدم --no-verify. ابدأ بـ rules قليلة ومتدرّجة.
4. auto-fix ممكن يلوث diff الـ PR: Prettier بيعدّل تنسيقات في ملفات إنت ما لمستهاش. الحل: شغّل lint-staged على الملفات المعدّلة فقط (وده الافتراضي عنده، لكن خلّي بالك من الإعدادات اللي بتغيّر السلوك ده).

متى لا تستخدم Pre-commit Hooks

الـ hooks مش حل عالمي. تجاهلها لو:

• Repo فيه شخص واحد بيشتغل عليه ومافيش CI أصلًا. الـ overhead أكبر من الفايدة.
• الفحوصات بتاخد أكتر من 5 ثواني حتى على lint-staged. ده بيكسر تدفق العمل، حوّل الفحوصات الكبيرة لـ pre-push hook بدل pre-commit.
• Repos كبيرة جدًا بفرق 50+ مطوّر. هنا مهم تستخدم أدوات أقوى زي Lefthook أو native Git hooks مع server-side enforcement (GitHub branch protection rules).
• المشروع مش Node.js ومافيهوش package.json. Husky مرتبط بنظام Node. للمشاريع التانية استخدم pre-commit framework من Python أو Lefthook.

الخطوة التالية

افتح المشروع بتاعك دلوقتي، شغّل الأمرين دول من قسم التركيب، وزوّد الـ lint-staged config في الـ package.json. اعمل commit تجريبي على ملف فيه خطأ مقصود علشان تتأكد إن الـ hook بيرفضه. لو مرّ من غير ما يوقف، راجع .husky/pre-commit وتأكد إنه قابل للتنفيذ (chmod +x على Linux/Mac).

بعد ما يشتغل، ضيف commitlint في hook اسمه commit-msg علشان رسائل الـ commits تبقى موحّدة. الموضوع ده يستاهل مقال لوحده.

المصادر

• Git Hooks — التوثيق الرسمي: git-scm.com/docs/githooks
• Husky 9 — التوثيق الرسمي على typicode.github.io/husky
• lint-staged — مستودع GitHub الرسمي github.com/lint-staged/lint-staged
• ESLint --max-warnings flag — توثيق eslint.org/docs/latest/use/command-line-interface
• Prettier — توثيق prettier.io/docs/en/install