يا جماعة الخير، السلام عليكم ورحمة الله.
خلوني أحكيلكم قصة صارت معي قبل كم سنة. كنا شغالين على مشروع كبير ومهم، فريق من المبرمجين الشاطرين، كل واحد فيهم “أزقرت” من الثاني. لكن كان عنا مشكلة، مشكلة صغيرة بس كانت بتسحب روحنا سحب: مراجعات الكود أو الـ Code Reviews.
كنت أفتح الـ Pull Request وأنا حاط إيدي على قلبي. مش خوفًا من خطأ منطقي في الكود، لا والله. الخوف كان من التعليقات اللي ما بتخلص على التنسيق. “أبو عمر، نسيت مسافة بعد الفاصلة في السطر 53”. “في ملف ناقص سطر فاضي بآخره”. “ليش مستخدم علامات تنصيص فردية هان ومزدوجة هان؟ وحدّ الله يا زلمة!”. كانت مراجعات الكود عبارة عن حفلة تعليقات على أشياء ما إلها أي علاقة بمنطق البرنامج نفسه.
وصلت فينا المرحلة إنه النقاشات التقنية العميقة صارت تضيع وسط بحر من الملاحظات السطحية. وبصراحة، صرنا نكره عملية المراجعة اللي المفروض إنها لرفع جودة الكود، مش لرفع الضغط. لحد ما في يوم، واحد من الشباب صرخ بنص المكتب: “يا عمي خلص! لازم نلاقي حل لهالقصة!”. وهان كانت بداية رحلتنا مع المنقذ: الـ Pre-commit Hooks.
ما هي “خطافات Git” (Git Hooks) أصلاً؟
قبل ما نغوص في الحل، خلينا نفهم أصل المشكلة والأداة الأساسية. نظام Git، اللي كلنا بنستخدمه وبنحبه، ذكي جدًا. بيوفرلنا إشي اسمه “الخطافات” أو الـ Hooks. ببساطة، هي عبارة عن سكربتات (ملفات برمجية صغيرة) بتشتغل تلقائيًا عند نقاط معينة في دورة حياة Git.
تخيلها زي حارس أمن على بوابات مختلفة. في حارس عند بوابة الـ “commit”، وحارس عند بوابة الـ “push”، وحارس عند بوابة الـ “merge”، وهكذا. بتقدر تطلب من هالحارس إنه يعمل فحص معين قبل ما يسمح للعملية تكمل.
هاي السكربتات موجودة داخل كل مستودع (repository) عندك في مجلد مخفي اسمه .git/hooks. لو فتحته، رح تلاقي ملفات بأسماء زي pre-commit.sample و pre-push.sample. كل ما عليك هو إنك تشيل كلمة .sample من آخر الملف وتكتب الكود اللي بدك ياه يتنفذ.
الدخول إلى عالم ‘خطافات ما قبل الإيداع’ (Pre-commit Hooks)
من بين كل الخطافات، في واحد هو بطل قصتنا اليوم: pre-commit. من اسمه، هاد الخطاف بيشتغل قبل ما عملية الـ commit تتم بنجاح. يعني، بعد ما تكتب git commit -m "رسالتي" وتضغط Enter، وقبل ما Git يسجل التغييرات بشكل نهائي، بيشتغل هاد السكربت.
شو الفائدة؟ الفائدة عظيمة!
- منع الأخطاء قبل وقوعها: بدل ما ترفع كود فيه مشاكل تنسيق أو أخطاء بسيطة على المستودع المشترك، ويشوفها كل الفريق ويعلق عليها، أنت بتكتشفها وبتصلحها على جهازك فورًا.
- توحيد المعايير: بتضمن إنه كل الكود اللي بيدخل على المستودع بتبع نفس قواعد التنسيق والجودة، بغض النظر مين اللي كتبه.
- توفير الوقت والجهد: بتحوّل النقاشات في مراجعات الكود من “وين الفاصلة المنقوطة؟” إلى “هل هذا هو أفضل حل منطقي للمشكلة؟”. وهذا هو الهدف الحقيقي من مراجعة الكود.
المشكلة الحقيقية: إدارة الخطافات يدويًا “شغلة بتغلب”
لهان الحكي حلو وجميل. لكن لو حاولت تستخدم الـ Git Hooks بالطريقة التقليدية (تعديل الملفات في .git/hooks)، رح تكتشف بسرعة إنها “شغلة بتغلب” (مهمة متعبة وغير عملية)، خصوصًا في الفرق:
- غير قابلة للمشاركة: مجلد
.gitلا يتم رفعه مع المشروع على GitHub أو GitLab. هذا يعني إن كل مبرمج في الفريق لازم يجهز هاي السكربتات يدويًا على جهازه. ولو حدثت السكربت، لازم تبلغ كل الفريق عشان يحدثوه. فوضى! - صعبة الإدارة: كل أداة (زي مدقق التنسيق أو مدقق الأخطاء) بتحتاج إعدادات خاصة. إدارتها كلها في سكربت واحد بصير معقد بسرعة.
- تعتمد على لغة واحدة: غالبًا بتنكتب بـ Shell script، وإذا مشروعك فيه أكثر من لغة (Python, JavaScript, etc)، بتصير القصة أعقد وأعقد.
وهان بيجي دور البطل الحقيقي…
الحل السحري: إطار عمل pre-commit
لا تخلط بينه وبين الخطاف نفسه. pre-commit هو اسم أداة وإطار عمل (framework) مكتوب بلغة بايثون، ولكنه يعمل مع أي لغة برمجة. مهمته هي إدارة “خطافات ما قبل الإيداع” بطريقة سهلة، مركزية، وقابلة للمشاركة.
لماذا هو أفضل؟
ببساطة، لأنه بيحل كل مشاكل الإدارة اليدوية. هو عبارة عن مدير حزم (package manager) للخطافات.
- ملف إعدادات مركزي: كل الإعدادات بتنحط في ملف واحد اسمه
.pre-commit-config.yaml. هاد الملف بتضيفه للمستودع زي أي ملف كود آخر. أي حدا بنزل المشروع، بنزل معه الإعدادات. - سهولة الإعداد: أي مبرمج جديد بنضم للفريق، كل اللي عليه يعمله هو كتابة أمرين في الطرفية، وكل شي بكون جاهز.
- دعم لغات متعددة: بتقدر تضيف خطافات لـ Python, JavaScript, TypeScript, Go, Rust, JSON, YAML, Markdown… أي شي بخطر على بالك.
- السرعة والكفاءة: الأداة ذكية. هي بتدير بيئات معزولة لكل خطاف، والأهم، إنها بتشغل الفحص فقط على الملفات اللي أنت غيرتها، مش على المشروع كله. هذا بخليها سريعة جدًا.
يلا نطبق عملي: إعداد pre-commit في مشروعك
هالحكي النظري ما بطعمي خبز. خلينا نشوف كيف بنطبق هاد الكلام خطوة بخطوة.
الخطوة 1: التثبيت (Installation)
أول شي، لازم تثبت الأداة على جهازك. لو عندك بايثون و pip، الأمر بسيط:
pip install pre-commitالخطوة 2: إنشاء ملف الإعدادات (.pre-commit-config.yaml)
في المجلد الرئيسي لمشروعك، أنشئ ملف جديد بهذا الاسم بالضبط: .pre-commit-config.yaml. هاد الملف هو قلب النظام. خلينا نحط فيه شوية خطافات مفيدة كمثال لمشروع بايثون و ويب:
# .pre-commit-config.yaml
repos:
- 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 # بفحص ملفات الـ YAML للتأكد من صحتها
- id: check-added-large-files # بمنع إضافة ملفات كبيرة بالخطأ
- repo: https://github.com/psf/black
rev: 24.4.2
hooks:
- id: black # فورماتر قياسي لكود البايثون
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.4.4
hooks:
- id: ruff # أداة فحص (linter) سريعة جدًا للبايثون
args: [--fix] # منخليها تحاول تصلح الأخطاء تلقائيًا
- repo: https://github.com/prettier/prettier
rev: 3.2.5
hooks:
- id: prettier # فورماتر للملفات الأمامية (JS, CSS, JSON, MD)
لاحظ كيف كل خطاف معرف من خلال مستودع (repo) ورقم إصدار (rev). هذا بضمن إنه كل الفريق بيستخدم نفس نسخة الأداة بالضبط.
الخطوة 3: تفعيل الخطافات (Activation)
بعد ما حفظت الملف، ارجع للطرفية واكتب الأمر التالي في مجلد مشروعك:
pre-commit installهذا الأمر رح يقرأ ملف الإعدادات تبعك، وينشئ سكربت صغير في .git/hooks/pre-commit. هيك بتكون ربطت الأداة بمستودع Git تبعك. خلص، هاي الخطوة بتعملها مرة واحدة بس.
الخطوة 4: التجربة والمشاهدة
الآن، جرب تعمل شوية “تخبيص” في الكود. مثلا، افتح ملف بايثون وضيف مسافات زيادة، أو اكتب كود تنسيقه سيء. بعدها، جرب تعمل commit كالمعتاد:
git add .
git commit -m "تجربة الكود السيء"
رح تشوف السحر بعينك! قبل ما يكتمل الـ commit، رح تشتغل الخطافات واحد ورا التاني، ورح تظهرلك رسائل زي هيك:
Trim Trailing Whitespace.................................................Failed
- hook id: trailing-whitespace
- exit code: 1
- files were modified by this hook
Fix End of Files.........................................................Passed
Check Yaml...............................................................Passed
Black....................................................................Failed
- hook id: black
- files were modified by this hook
- re-formatted my_bad_code.py
Ruff.....................................................................Failed
- hook id: ruff
- files were modified by this hook
لاحظ كلمة Failed. هذا يعني إن الـ commit فشل ولم يتم. والأجمل من هيك، لاحظ جملة files were modified by this hook. هذا يعني إن أدوات مثل black و prettier و trailing-whitespace قامت بتصليح الملفات تلقائيًا!
كل اللي عليك تعمله الآن هو إضافة الملفات اللي تم تعديلها مرة ثانية، والمحاولة مرة أخرى:
git add .
git commit -m "إضافة الكود بعد التصليح التلقائي"
هالمرة، رح تشتغل الخطافات مرة ثانية، وبما إنه كل شي نظيف، رح تمر كلها بنجاح (Passed)، ورح يتم الـ commit بنجاح. مبروك! لقد منعت كودًا سيئًا من دخول المستودع بدون أي مجهود يذكر.
نصائح من خبرة أبو عمر
- ابدأ بالبسيط: لا تتحمس وتضيف 20 خطاف من أول يوم. ابدأ بخطافات التنسيق الأساسية (formatting & linting). مع الوقت، ممكن تضيف خطافات أكثر تعقيدًا، مثل فحص الـ security أو أنواع الـ types.
- السرعة هي الأهم: لو كانت الخطافات بطيئة، المبرمجين رح يتضايقوا وممكن يتجاوزوها. استخدم أدوات سريعة. مثلا، أداة
ruffفي عالم البايثون أسرع بعشرات المرات من الأدوات القديمة زيflake8وisort. - لا تنسى التشغيل اليدوي: علم فريقك إنه ممكن يشغل كل الخطافات على كل الملفات في المشروع باستخدام الأمر
pre-commit run --all-files. هذا مفيد جدًا لما تضيف الأداة لأول مرة على مشروع قديم، أو لما تضيف خطاف جديد. - خط الدفاع الثاني (CI/CD): بعض المبرمجين “الحركيين” ممكن يتجاوزوا الخطافات باستخدام
git commit --no-verify. عشان هيك، دائمًا شغل نفس الفحص في الـ CI/CD pipeline تبعك (مثل GitHub Actions). ضيف خطوة بتشغلpre-commit run --all-files. إذا حدا تجاوز الفحص المحلي، الـ CI رح يمسكه.
الخلاصة: استثمر في الأتمتة، واربح وقتك وسلامك النفسي ✅
في النهاية، تبني أدوات مثل pre-commit هو استثمار صغير جدًا مقابل عائد ضخم. نعم، رح ياخذ منك ومن فريقك ساعة أو ساعتين للإعداد والفهم في البداية، لكنه رح يوفر عليكم مئات الساعات من النقاشات التافهة، والإحباط، والوقت الضائع في مراجعات الكود.
لقد حولت هذه الأداة مراجعات الكود عندنا من ساحة جدل إلى ورشة عمل بناءة. صرنا نركز على جودة المنطق، وجمال الحلول، وبناء منتجات أفضل. الكود صار أنظف، والفريق صار أسعد، وأنا، أبو عمر، صرت أفتح الـ Pull Requests وأنا مرتاح البال.
نصيحتي الأخيرة: لا تخلوا النقاشات السطحية تسرق منكم متعة بناء الأشياء العظيمة. أتمتوا كل ما هو قابل للأتمتة، وركزوا طاقتكم الذهنية في الإبداع وحل المشاكل الحقيقية.
