استخدم خطافات Git لفحص عملك قبل أن يغادر جهازك
خطاف Git سكربت يشغّله Git تلقائيًا في لحظة محددة، مثل ما قبل الإيداع أو الدفع مباشرة. في التفضيلات › خطافات Git يعرض GitTree ما يعمل ومتى، ويتيح لك إضافة خطافات من قوالب جاهزة، وتعديلها وتشغيلها تجريبيًا، وإيقافها وتشغيلها، ومشاركتها مع فريقك عبر المستودع.
يعمل في GitTree المجاني: كل ميزات Git المحلية دون حاجة إلى حساب.
في هذه الصفحة
قبل أن تبدأ
- هناك مستودع مفتوح: الخطافات تخص مستودعًا واحدًا.
- المستودع موثوق. في الوضع المقيَّد لا يشغّل Git أيًّا من خطافاته، لكن يمكنك قراءتها وتعديلها (الثقة بالمستودع).
- الخطافات سكربتات shell. تستخدم القوالب
shالعادي الموجود في macOS وWindows (ضمن Git for Windows) وLinux.
أين تجده
- مربع الإيداع: تحت زر الإيداع يسرد السطر May run: … الخطافات التي يشغّلها الإيداع، وإدارة الخطافات يفتح الصفحة.
- الأدوات في شريط الأدوات، أو قسم TOOLS في اللوحة اليسرى: خطافات Git.
- قائمة لسان المستودع أو لوحة الأوامر: إدارة خطافات Git…، أو
Alt+Shift+H. - التفضيلات (
Mod+,) › خطافات Git. ويجدها البحث في التفضيلات عن «خطافات» أو «pre-commit» أو «husky» أيضًا.
| الإجراء | macOS | Windows وLinux |
|---|---|---|
| إدارة خطافات Git | ⌥⇧H | Alt+Shift+H |
| فتح التفضيلات | ⌘, | Ctrl+, |
الخطوات
افتح صفحة الخطافات
استخدم إدارة الخطافات تحت زر الإيداع أو
Alt+Shift+H. إذا كانت عدة مستودعات مفتوحة، فاختر واحدًا في المستودع.اقرأ ما يعمل ومتى
يعرض ما الذي يعمل ومتى مسار الإيداع (pre-commit وprepare-commit-msg وcommit-msg وpost-commit) ومسار الدفع (pre-push). كل خطوة تقول يعمل أو متوقف أو غير قابل للتنفيذ أو لا يوجد خطاف، وهل يمكنه إيقاف الإجراء أم للإبلاغ فقط.
تسمّي الصفحة الخطافات التي قد يشغّلها Git عند الإيداع وعند الدفع، وتعرض المشاركة عبر .githooks.واجهة GitTree مع مستودع للعرض. أضف خطافًا
اضغط إضافة خطاف…. في متى يعمل اختر الخطاف، وفي البدء من اختر قالبًا أو مثال Git أو سكربت فارغ. تعرض معاينة السكربت بالضبط ما سيُكتب. إنشاء الخطاف يكتب الملف جاهزًا للتشغيل ويفتحه في المحرر.
عدّل السكربت
تعديل يفتح السكربت بأرقام الأسطر. غيّره واضغط حفظ (أو
Mod+S). إذا تغيّر الملف على القرص منذ فتحته، يرفض GitTree الكتابة فوقه ويحتفظ بنصك لتعيد فتحه وتقارن.جرّبه
تشغيل تجريبي يشغّل الخطاف الآن كما يشغّله Git، دون إنشاء إيداع أو دفع. في commit-msg وprepare-commit-msg اكتب رسالة لفحصها. تظهر المخرجات أولًا بأول، وتقول النتيجة ما كان Git سيفعله: نجح برمز الخروج 0: سيتابع Git. أو فشل برمز الخروج 1: سيتوقف Git هنا. وإيقاف يُنهي التشغيل الطويل.
أوقف خطافًا أو شارك الخطافات
المفتاح بجانب الخطاف يوقفه بإعادة تسميته إلى
<name>.disabled، ويشغّله مجددًا؛ لا يُحذف شيء. المشاركة عبر .githooks تضع الخطافات في المستودع لفريقك (انظر أدناه).
النتيجة المتوقعة
من الإيداع أو الدفع التالي يشغّل Git الخطافات المعلَّمة بـ يعمل. يذكرها سطر May run: … في مربع الإيداع، وتظهر مخرجات الخطاف تحت مخرجات الخطاف عندما يطبع شيئًا أو يوقف الإيداع.
ما الخطافات، ولماذا تستخدمها
يبحث Git عن ملفات قابلة للتنفيذ بأسماء ثابتة في مجلد الخطافات (.git/hooks ما لم يحدد core.hooksPath غيره) ويشغّلها في اللحظات المقابلة. الخطاف الذي يعمل قبل إجراء، مثل pre-commit أو pre-push، يستطيع إيقافه بالخروج برمز غير الصفر. أما الخطاف الذي يعمل بعده، مثل post-commit أو post-merge، فيستطيع الإبلاغ فقط.
- اكتشف الأخطاء قبل أن تغادر جهازك: الاختبارات الفاشلة وأخطاء الفحص وعلامات التعارض المتبقية والملفات الضخمة.
- حافظ على اتساق رسائل الإيداع، مثل Conventional Commits أو رقم المهمة في كل رسالة.
- احصل على النتيجة خلال ثوانٍ بدلًا من انتظار فشل تشغيل CI.
- امنح الفريق كله الفحوص نفسها بحفظ الخطافات داخل المستودع.
الخطافات الأكثر استخدامًا
| الخطاف | متى يشغّله Git | الاستخدام المعتاد |
|---|---|---|
| pre-commit | قبل إنشاء الإيداع | فحص الكود والاختبارات السريعة على المجهَّز، ومنع الإيداع على main |
| prepare-commit-msg | قبل كتابة الرسالة | وضع رقم المهمة من اسم الفرع في الرسالة |
| commit-msg | بعد كتابة الرسالة | فحص صيغة الرسالة، مثل Conventional Commits |
| post-commit | بعد إنشاء الإيداع | التنبيه أو التسجيل؛ لا يمكنه التراجع عن الإيداع |
| pre-push | قبل إرسال أي شيء إلى المستودع البعيد | تشغيل الاختبارات كاملة، ورفض الدفع إلى الفروع المحمية |
| post-merge | بعد الدمج أو السحب | التنبيه عند تغيّر ملف قفل لإعادة تثبيت الاعتماديات |
| post-checkout | بعد التبديل بين الفروع | تنظيف ملفات البناء أو تحديث الملفات المولَّدة |
خطافات الخادم مثل pre-receive وupdate تعمل فقط على خادم يستقبل الدفع. يسردها GitTree إن وُجدت، لكنه لا يشغّلها تجريبيًا أبدًا.
قوالب جاهزة
| القالب | الخطاف | ما يفعله |
|---|---|---|
| حماية الفروع الرئيسية | pre-commit | يمنع الإيداع مباشرة على main أو master |
| اكتشاف علامات التعارض والمسافات | pre-commit | يمنع إيداعًا يضيف علامات تعارض متبقية أو مسافات زائدة في نهاية الأسطر (git diff --cached --check) |
| منع الملفات الكبيرة | pre-commit | يمنع إيداعًا يضيف ملفًا أكبر من 5 ميغابايت |
| إضافة رقم المهمة | prepare-commit-msg | يبدأ كل رسالة برقم المهمة الموجود في اسم الفرع، مثل ABC-123 |
| Conventional Commits | commit-msg | يشترط ملخصًا مثل feat(parser): accept empty lines |
| تشغيل الاختبارات قبل الدفع | pre-push | يشغّل npm test أو cargo test أو go test أو pytest أو make test، ويوقف الدفع إذا فشلت |
| حماية الفروع البعيدة | pre-push | يمنع الدفع مباشرة إلى main أو master على المستودع البعيد |
| تذكير بالاعتماديات | post-merge | ينبّهك إذا تغيّر ملف قفل بعد سحب أو دمج |
كل قالب سكربت عادي إعداداته في أعلاه، مثل PROTECTED="main master" أو TEST_COMMAND="". غيّرها في المحرر لتناسب مشروعك.
ما الذي يفعله التشغيل التجريبي
يشغّل GitTree الخطاف عبر git hook run، فيجده Git ويبدؤه كما يفعل أثناء الإجراء الحقيقي تمامًا، بما في ذلك core.hooksPath. ويتلقى الخطاف مدخلات تجريبية:
- pre-commit وpre-merge-commit وpost-commit وpre-auto-gc: دون وسائط.
- commit-msg وprepare-commit-msg: ملف مؤقت فيه الرسالة التي كتبتها، ويُحذف بعد ذلك.
- pre-push: اسم مستودع الدفع البعيد وعنوانه، دون أي فروع في مدخلاته.
- post-merge:
0، كما بعد دمج عادي.
شارك الخطافات مع فريقك
الخطافات في .git/hooks لا تُودَع أبدًا، فلكل نسخة خطافاتها. المشاركة عبر .githooks تنسخها إلى مجلد .githooks داخل المستودع وتضبط core.hooksPath عليه في إعدادات هذا المستودع. أودِع المجلد، ثم يشغّل كل زميل هذا الأمر مرة واحدة بعد الاستنساخ:
git config core.hooksPath .githooksاستخدام خطافات هذه النسخة يزيل ذلك الإعداد مجددًا. يبقى مجلد .githooks وخطافاتك في .git/hooks في مكانهما.
تخطي الخطافات في إيداع واحد
افتح خيارات الإيداع في مربع الإيداع وفعّل تخطي الخطافات (--no-verify). عندها يتخطى Git pre-commit وcommit-msg في ذلك الإيداع، بينما يبقى prepare-commit-msg وpost-commit يعملان، ويذكر السطر تحت زر الإيداع ذلك. ولإيقاف خطاف مدة أطول، أوقفه في صفحة الخطافات.
إن لم يسر الأمر كما توقعت
يظهر خطاف بحالة غير قابل للتنفيذ ولا يعمل أبدًا.
على macOS وLinux يتخطى Git ملف خطاف ليست له صلاحية التنفيذ. اضغط جعله قابلًا للتنفيذ؛ يضيفها GitTree فقط حيث يكون الملف قابلًا للقراءة.
«تغيّر الخطاف على القرص منذ فتحه؛ أعد فتحه لرؤية المحتوى الجديد.»
برنامج آخر أو أداة لإدارة الخطافات أعاد كتابة الملف. أغلق المحرر وافتحه مجددًا، ثم طبّق تعديلك على المحتوى الجديد.
«هذا الخطاف رابط. لا يكتب GitTree عبر رابط أبدًا؛ عدّل الملف الذي يشير إليه.»
الخطاف رابط رمزي، تنشئه غالبًا أداة لإدارة الخطافات. عدّل الملف الذي يشير إليه، أو إعدادات تلك الأداة.
يعمل السكربت على macOS لكنه يفشل على Linux بخطأ «bad interpreter» أو أخطاء \r.
في الملف نهايات أسطر Windows (CRLF). ينبّهك المحرر إليها؛ احفظ السكربت بنهايات أسطر LF.
زر تشغيل تجريبي معطَّل.
سببه مكتوب بجانب الزر: امنح المستودع الثقة، أو شغّل الخطاف، أو اجعله قابلًا للتنفيذ، أو لاحظ أن هذا الخطاف لا يتلقى مدخلاته إلا أثناء عملية Git الحقيقية.
أسئلة
هل الخطافات ضمن الخطة المجانية؟
نعم. إدارة الخطافات وتعديلها وتشغيلها تجريبيًا ومشاركتها عمل Git محلي ولا تحتاج إلى حساب استضافة.
هل يحذف GitTree الخطاف عندما أوقفه؟
لا. الإيقاف يعيد تسمية الملف إلى <name>.disabled، والتشغيل يعيد اسمه. لا يحذف GitTree أي خطاف أبدًا.
هل سيُودَع الخطاف الذي أنشئه؟
ليس ما دام في .git/hooks. استخدم المشاركة عبر .githooks لحفظ الخطافات في المستودع، حيث تُودَع مثل أي ملف آخر.
هل يمكن كتابة خطاف بـ Node.js أو Python؟
نعم. يشغّل Git الملف بالبرنامج المذكور في سطره الأول، مثل #!/usr/bin/env node، ويعرض المحرر ذلك البرنامج بصيغة يعمل باستخدام node. يجب أن يكون البرنامج مثبتًا على كل جهاز يشغّل الخطاف.