فروع العمل المتوازية (Worktrees): عزل المهام لتمكين Codex من العمل بالتوازي
📚 التنقل في السلسلة: المقال السابق [24 · القواعد والخطافات (Hooks)] علمك كيفية إضافة "البوابات الأمنية ومفاتيح التشغيل" لـ Codex لأتمتة المهام المتكررة. يناقش هذا المقال بعداً آخر للعمل - بدلاً من إجبار مساعد واحد على معالجة المهام بالتتابع، سنتعلم كيفية تشغيل مهام متعددة بالتوازي ودون تداخل التعديلات. وتمثل شجرة العمل (Worktree) أداة العزل الأساسية التي يعتمد عليها Codex لإنجاز ذلك: كيفية بنائها، استخدامها، لماذا يمنع فحص نفس الفرع في موقعين، وكيف تعمل ميزة التسليم (Handoff) لنقل المهام بين الواجهة والخلفية. المقال التالي [26 · التكامل مع Git و GitHub] سيتحدث عن كيفية كتابة رسائل commit والرفع وفتح PRs بعد انتهاء التعديلات.
أشارككم أولاً خطأً فادحاً وقعت فيه في مارس الماضي.
كنت أحاول اختصار الوقت، وقمت بـ فتح محادثتين محليتين (Local) في نفس الوقت لتعديل نفس المستودع البرمجي داخل تطبيق Codex، وطلبت من الأولى إعادة هيكلة منطق قاعدة البيانات، ومن الثانية تعديل خريطة التوجيه. وكنت سعيداً بظني أنني قمت بمضاعفة الإنتاجية. ولكن تعارض عمل المحادثتين على نفس ملف الإعدادات config.ts، وقامت المحادثة الثانية برفع تعديلاتها لتكتب فوق نصف التعديلات التي أنجزتها المحادثة الأولى. وقضيت عدة دقائق مذهولاً أمام مخرجات git diff المعقدة الممتلئة بالتعديلات المتضاربة، حتى أدركت الحقيقة: لم يكن العيب في Codex، بل العيب في محاولتي تشغيل كاتبين يكتبان في نفس الصفحة وفي نفس اللحظة.
ومنذ ذلك اليوم تخليت عن هذا الأسلوب العشوائي وبدأت في الاستعانة بالأداة المخصصة للعمل بالتوازي - Git Worktrees. فإذا أردت تسيير عدة مهام معاً في نفس المستودع، فالمسار هو عزل كل مهمة في مجلد عمل مستقل (Worktree) ليتلقى كل وكيل نسخة معزولة ومستقلة من الأكواد، وتفادي مشاكل تداخل التعديلات نهائياً.
أشرنا لميزة فروع العمل المتوازية (Worktrees) باختصار في المقال 07 عند مناقشة خيارات الجلسات في تطبيق سطح المكتب (المحلي Local، شجرة العمل Worktree، والسحابي Cloud)، وكيفية استخدام ميزة التسليم والتسلم (Handoff) للتبديل بينها (ونحيل تفاصيل الخيار السحابي Cloud للمقال [10 · بيئة العمل السحابية (Codex Cloud)]). ونتناول في هذا المقال الجوانب العميقة للميزة: كيف يتم عزل الملفات تقنياً، لماذا يمنع فحص نفس الفرع في موقعين، كيفية نقل المهام بالاتجاهين، وكيف يتم التخلص من مجلدات العمل الزائدة وتوفير مساحة القرص. وهي تفاصيل فنية هامة يجب فهمها لتجنب المشاكل أثناء العمل.
بقراءة هذا المقال، ستحصل على:
- مفهوم فروع العمل المتوازية (Worktrees) والفوائد من ورائها، والفرق الجوهري بينها وبين تشغيل محادثتين محليتين معاً
- خطوات إنشاء جلسة عمل مستقلة (Worktree thread) في تطبيق سطح المكتب، وفهم وضع "مؤشر HEAD المنفصل (detached HEAD)" الافتراضي غير المعتاد
- قاعدة Git الصارمة - حظر فحص ومطابقة نفس الفرع البرمجي في موقعين في نفس الوقت، ورسالة الخطأ الناتجة وطريقة تجاوزها
- استخدام ميزة التسليم والتسلم (Handoff) لنقل المهام بالاتجاهين بين بيئة العمل المحلية (Local) ومجلد العمل المستقل (Worktree)، وحالات استخدام كل منهما
- استخدام سكربتات التهيئة للبيئة المحلية (Local environment) لضمان تثبيت كل التبعيات وإعدادات العمل تلقائياً بمجرد بناء مجلد العمل الجديد
- كيفية تنظيف المجلدات الزائدة لتوفير المساحة: عدد المجلدات المحفوظة افتراضياً، المجلدات المستثناة من الحذف، وإمكانية استعادة المجلدات المحذوفة من لقطات الحفظ
⚠️ تذكر أن ميزات فروع العمل المتوازية (Worktrees) والتسليم (Handoff) وتهيئة البيئة المحلية تتوفر حصرياً داخل تطبيق سطح المكتب (desktop app) لـ Codex، ولا توجد خيارات مطابقة مثل
--worktreeفي واجهة سطر الأوامر CLI. وجميع الخيارات والواجهات المذكورة أدناه تستند للوثائق الرسمية لـ Codex وقد تتغير الواجهة الرسومية مع التحديثات.
01 الفوائد والمشاكل التي تعالجها فروع العمل المتوازية (Worktrees)
نبدأ بالخلاصة: تعالج فروع العمل المتوازية (Worktrees) مشكلة الرغبة في تسيير عدة مهام مستقلة في نفس المستودع بالتوازي ودون تداخل التعديلات بينها. ويشترط لنجاحها - منع تداخل تعديلات المهام على نفس الملفات.
تذكر أن كل المهام البرمجية السابقة كانت تتم داخل محادثة واحدة: حيث ترسل الطلب ويقوم المساعد بالتعديل تدريجياً. ويفي هذا الأسلوب بمعظم الاحتياجات اليومية. ولكنك ستواجه عائقين رئيسيين يحدان من سرعة العمل:
العائق الأول: المهام المستقلة التي يمكن تسييرها بالتوازي. مثل "تعديل تنسيقات الواجهة"، "إصلاح خطأ برمجي في الخلفية"، و"كتابة اختبارات جديدة"، وهي مهام لا تعتمد على بعضها ولكنك تضطر لتسييرها بالتتابع - إنجاز التنسيق أولاً ثم البدء في إصلاح الخطأ. بينما يفضل تشغيلها معاً لاختصار الوقت.
العائق الثاني: الرغبة في تجربة فكرة جديدة دون التأثير على التعديلات الحالية غير المكتملة. فمستودعك الحالي يحتوي على ملفات قيد التعديل ولم ترفع بعد، وتود اختبار فكرة جانبية سريعة. وإجراء التجربة في نفس المجلد يعرض ملفاتك الحالية للتلف والتداخل.
قد تظن أن الحل هو تشغيل محادثتين محليتين معاً - وهنا مكمن الخطر. فتشغيل محادثتين محليتين على نفس مجلد العمل يعني عمل المساعدين على نفس الملفات الفيزيائية، وتكون النتيجة كتابة أحدهما فوق تعديلات الآخر (كما حدث معي).
تشبيه: ورقة التشخيص الطبي للمريض. يملك المريض ورقة تشخيص واحدة أصلية، وإذا حاول أطباء من ثلاثة تخصصات مختلفة كتابة ملاحظاتهم الطبية على نفس الورقة وفي نفس اللحظة، فستتداخل السطور وتضيع البيانات. والحل الصحيح هو - تصوير نسخة مستقلة من ورقة التشخيص لكل طبيب ليكتب ملاحظاته عليها بشكل منفصل، وعند انتهاء الجميع يتم دمج وتدوين النتائج في الورقة الأصلية. شجرة العمل (Worktree) تقوم بهذه الوظيفة: حيث ترجع لجذر مستودع Git الرئيسي وتنشئ منه مجلدات عمل فرعية معزولة ومستقلة، تضم كل منها نسخة كاملة من ملفات المشروع، ولكنها تتشارك نفس سجلات Git وتاريخ الفروع (مجلد .git الرئيسي). وأي تعديل يتم في مجلد مستقل لا يؤثر على بقية المجلدات نهائياً.
توضح الوثائق الرسمية الفائدة بوضوح:
يحتوي كل مجلد عمل (worktree) على نسخة مستقلة لجميع ملفات مستودعك، ولكنه يتشارك مع المجلدات الأخرى نفس ملفات التوثيق وسجلات الفروع وتاريخ الرفع (مجلد
.git). ويسمح لك ذلك بفتح وفحص والعمل على عدة فروع برمجية بالتوازي.
أهم الحالات التي تتطلب استخدام فروع العمل المتوازية (Worktrees):
- "إصلاح عطل برمجي في الخلفية مع الاستمرار في تطوير ميزات جديدة بالتوازي" - حجز مجلد عمل مستقل لكل مهمة لحماية الملفات.
- "الرغبة في اختبار فكرة برمجية سريعة دون مساس بالتعديلات الحالية غير المرفوعة" - بناء مجلد عمل مستقل للتجربة، وحذفه بأمان عند الفشل دون تأثر الكود الأساسي.
- "إسناد عملية إعادة هيكلة برمجية كبيرة لـ Codex ليعمل عليها في الخلفية، بينما تتابع عملك المعتاد في الواجهة" - نقل الجلسة للخلفية وحجز مجلد مستقل لها (كما سنوضح في القسم 04).
💡 ملخص في جملة واحدة: تمثل فروع العمل المتوازية (Worktrees) آلية لعزل وتسيير مهام برمجية متعددة ومستقلة في نفس المستودع بالتوازي ودون تداخل التعديلات (بمثابة توزيع نسخ مستقلة من الملفات لكل مهمة)، بشرط عدم عمل المساعدين على نفس الملفات الحساسة لمنع تضارب التعديلات.
توضح الرسمة الفكرة: يتم اشتقاق ثلاثة مجلدات عمل معزولة ومستقلة من مستودع Git الرئيسي، ليتولى كل وكيل Codex معالجة مهمة محددة في مجلده المستقل ودون التأثير على بقية الملفات.
02 خطوات إنشاء جلسة عمل مستقلة (Worktree Thread)
تتم عملية إنشاء الجلسة وإعداد مجلد العمل بالكامل من الواجهة الرسومية لتطبيق سطح المكتب دون حاجة لكتابة أوامر برمجية.
تشترط الميزة أن يكون المشروع مهيأً كمستودع Git - نظراً لاعتمادها على إمكانيات git worktree الأساسية. وإذا لم يكن المجلد مستودع Git فلن تظهر خيارات شجرة العمل.
خطوات الإنشاء الأربع:
الخطوة الأولى: تحديد وضع الجلسة كـ Worktree. عند فتح محادثة جديدة، توجه للخيارات المتاحة أسفل رسالة الطلب وحول وضع المحادثة من المحلي (Local) إلى Worktree. (ويمكنك اختيار البيئة المحلية المناسبة لتشغيل سكربتات التهيئة كما سنبين في القسم 05).
الخطوة الثانية: اختيار فرع البدء. حدد الفرع الذي تريد اشتقاق مجلد العمل الجديد منه - ويمكنك اختيار الفروع الأساسية مثل main أو master أو الفروع الفرعية، كما يوفر التطبيق خياراً متميزاً: اشتقاق مجلد العمل من الفرع الحالي مع تضمين التعديلات المحلية الحالية غير المرفوعة بعد، مما يتيح نقل العمل قيد التنفيذ لمجلد مستقل للمتابعة.
الخطوة الثالثة: كتابة الطلب وإرساله. اكتب إرشادات المهمة وأرسلها، ليتولى Codex إنشاء مجلد عمل مستقل (git worktree) بناءً على خياراتك والبدء في تنفيذ المهمة.
الخطوة الرابعة: تحديد الإجراء التالي بعد انتهاء المهمة. بعد إنجاز المهمة، يمكنك الاستمرار في العمل على مجلد العمل الحالي (لتوثيق التعديلات، رفعها، وفتح PR)، أو استخدام ميزة التسليم والتسلم (Handoff) لنقل التعديلات للمجلد المحلي الرئيسي (القسم 04).
وضع مؤشر HEAD المنفصل (detached HEAD) الافتراضي
نتناول هنا تفصيلاً تقنياً هاماً للمطورين يكثر التساؤل حوله.
يعمل Codex داخل مجلد العمل الجديد افتراضياً في وضع "مؤشر HEAD المنفصل (detached HEAD)" - ويعني ذلك أن سجلات العمل تشير لـ hash رمز التعديل مباشرة دون الارتباط باسم فرع محدد. تنص الوثائق على ذلك:
يعمل Codex افتراضياً في وضع مؤشر HEAD المنفصل (detached HEAD) عند تشغيل مجلدات العمل المستقلة.
لماذا يتبع هذا التصميم؟ لتسهيل تشغيل عدة مجلدات عمل معاً دون أن تمتلئ قائمة الفروع بأسماء عشوائية ومؤقتة. فتجنب تسمية الفروع يحافظ على ترتيب مستودعك.
وعند رغبتك في تثبيت التعديلات الحالية في فرع رسمي محدد لمشاركتها: توجه لأعلى واجهة المحادثة وانقر على زر Create branch here (إنشاء فرع هنا)، لتسمية الفرع البرمجي الحالي والبدء في كتابة رسائل commit والرفع وفتح PR بشكل معتاد.
💡 ملخص في جملة واحدة: خطوات الإعداد هي: تحويل وضع الجلسة لـ Worktree ← اختيار فرع الاشتقاق ← إرسال الطلب لبدء العمل ← وتحديد التثبيت أو النقل؛ وتعمل الجلسة افتراضياً في وضع مؤشر HEAD المنفصل، ويتطلب تثبيت التعديلات النقر على زر Create branch here لتسمية الفرع البرمجي.
03 قاعدة Git الصارمة: حظر فتح نفس الفرع في موقعين
نتناول هنا القاعدة التقنية الأهم لـ Git، والتي يسبب الجهل بها توقف العمليات وظهور الأخطاء.
تفرض Git قاعدة صارمة: يمنع فحص ومطابقة نفس الفرع البرمجي في أكثر من مجلد عمل (worktree) نشط في نفس الوقت. فإذا كان الفرع feature/a مفتوحاً في مجلد العمل المستقل، فيحظر فتحه أو الانتقال إليه في المجلد المحلي الرئيسي (Local)، ويطبق العكس أيضاً.
تشبيه: استعارة كتاب وحيد من المكتبة العامة. يملك الكتاب نسخة فيزيائية واحدة فقط، وإذا قام المستعير A بأخذ الكتاب، فلن يتمكن المستعير B من الحصول عليه حتى يقوم A بإرجاعه للمكتبة - لضمان بقاء سجل استعارة الكتاب صحيحاً وتجنب فقد النسخة. وتماثل فروع Git هذه الفكرة: فالفرع (المسار refs/heads/<branch_name>) يشير لحالة الكود الحالية، والسماح بتعديله ورفع التغييرات عليه من موقعين في نفس الوقت يسبب تعارض السجلات وتضارب البيانات. لذا تمنع Git هذا الإجراء تماماً.
ماذا يحدث عند مخالفة هذه القاعدة؟ إذا حاول المساعد العمل على فرع باسم feature/a في مجلد مستقل، وقمت أنت بمحاولة الانتقال لنفس الفرع feature/a في مجلدك المحلي الرئيسي، فستعرض Git رسالة الخطأ التالية وتوقف العملية:
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'وتعني الرسالة أن الفرع البرمجي مستخدم حالياً ومفتوح في مجلد عمل آخر، ويمنع فتحه هنا.
كيف تحل المشكلة؟ الحل ليس بمحاولة تجاوز رسائل الخطأ، بل بالاعتماد على ميزة التسليم (Handoff). وتوفر الوثائق الخيارين التاليين:
- تغيير الفرع المفتوح في مجلد العمل المستقل المذكور لفرع آخر لتحرير الفرع المطلق.
- استخدام ميزة التسليم والتسلم (Handoff) لنقل الجلسة والتعديلات للمجلد المحلي الرئيسي بالكامل (القسم 04) وتجنب تشتيت الفرع بين موقعين.
💡 ملخص في جملة واحدة: تمنع قواعد Git فتح وتعديل نفس الفرع البرمجي في موقعين في نفس الوقت وتوقف العملية برسالة تعذر الفتح؛ ولحل المشكلة استخدم ميزة التسليم والتسلم Handoff لنقل المهام بدلاً من تعارض الفروع.
04 ميزة التسليم والتسلم (Handoff): نقل المهام بين الواجهة والخلفية
أشرنا لميزة التسليم والتسلم (Handoff) سابقاً كأداة لحل مشاكل تعارض الفروع، ونوضح هنا دورها وكيفية توظيفها في تنظيم العمل اليومي.
نعتمد أولاً على المفهوم التالي لتنظيم العمل: المجلد المحلي (Local) يمثل الواجهة، ومجلد العمل المستقل (Worktree) يمثل الخلفية. يمثل المجلد المحلي (Local) بيئة عملك الأساسية التي تفتح فيها محرر الأكواد المعتاد وتتابع فيها تشغيل خوادم التجربة؛ ويمثل مجلد العمل المستقل (Worktree) المساحة الجانبية المعزولة التي ينفذ فيها الوكيل مهامه. وتتولى ميزة Handoff نقل جلسة التفكير الحالية وتعديلاتها البرمجية بين هاتين البيئتين بالاتجاهين.
تشبيه: المطبخ المفتوح وغرفة التحضير الجانبية في المطاعم. يمثل المطبخ المفتوح (المحلي Local) المساحة التي يقف فيها الطباخ الرئيسي أمام الزبائن ويقوم بلمسات الطهي الأخيرة وإخراج الأطباق؛ وتمثل غرفة التحضير الجانبية (Worktree) المساحة المعزولة التي يتم فيها غسل الخضار وتجهيز المكونات الطويلة. ويتم نقل الوجبة بين المساحتين بحسب الحاجة: فنقلها لغرفة التحضير لإتمام طهيها الطويل بهدوء، وإحضارها للمطبخ المفتوح للمراجعة والتقديم. ميزة Handoff تمثل هذا النقل - ليقوم Codex بمعالجة سجلات Git ونقل التعديلات بأمان بالنيابة عنك وتجنب كتابة أوامر النقل يدوياً.
وتشير الوثائق لأهمية الميزة كحل تقني لقاعدة Git الصارمة:
تكمن قيمة ميزة التسليم (Handoff) في حل قيود Git التي تمنع فتح نفس الفرع في موقعين معاً.
وتسير عمليات النقل في الاتجاهين كالتالي:
الاتجاه الأول: من مجلد العمل المستقل للمجلد المحلي الرئيسي (Worktree → Local) - نقل المهمة للواجهة. انقر على زر Hand off أعلى المحادثة واختر Local. متى نستخدم هذا الخيار؟ عند رغبتك في فحص ومراجعة النتائج ببيئة عملك المعتادة - كفتح محرر الأكواد المألوف لديك لقراءة سجلات التعديلات (diff)، أو تشغيل خوادم التجربة المحلية التي يمنع تكرار فتحها في المجلدات الفرعية. ونعتمد على هذا المسار بكثرة: إسناد كتابة الميزات لـ Codex في الخلفية، ونقل الجلسة للواجهة المحلية عند الانتهاء لمراجعة وتدقيق الكود يدوياً قبل الاعتماد.
الاتجاه الثاني: من المجلد المحلي لمجلد العمل المستقل (Local → Worktree) - إرسال المهمة للخلفية. ويستخدم عند انشغالك في المجلد المحلي بعمليات فحص أو كتابة أكواد وتريد إرسال جلسة Codex الحالية للخلفية ليتابع المساعد العمل بشكل مستقل ومعزول، مع إبقاء مجلدك المحلي نظيفاً لمتابعة بقية مهامك.
إليك تفصيلاً فنياً هاماً ومريحاً: ترتبط كل جلسة تفكير بمجلد العمل المستقل (worktree) الخاص بها بشكل دائم. فنقل الجلسة للمجلد المحلي يتبعه إمكانية إعادتها للخلفية لاحقاً ليقوم Codex بإعادتها لنفس مجلد العمل الفرعي الأول واستكمال العمل من حيث توقفت، ودون بناء مجلد عمل جديد.
وتذكر القاعدة الهامة التالية والمتعلقة بملفات الخصوصية والتجاهل:
نظراً لاعتماد ميزة Handoff على عمليات Git البرمجية، يحظر نقل أي ملفات مسجلة في ملف تجاهل التعديلات
.gitignoreبين المجلدات.
ويعني ذلك - أن ملفات الإعدادات الحساسة مثل .env ومجلدات التبعيات الكبيرة لن تنتقل مع الجلسة. ونوضح في القسم التالي كيفية حل هذا النقص وتثبيت التبعيات تلقائياً.
| وجه المقارنة | من المجلد المستقل للمحلي (Worktree → Local) | من المجلد المحلي للمستقل (Local → Worktree) |
|---|---|---|
| مسار النقل | نقل المهمة من الخلفية لواجهة العمل | إرسال المهمة من الواجهة لتستمر في الخلفية مع عزل الكود |
| الاستخدام الأنسب | مراجعة الكود بمحرر الأكواد المعتاد وتشغيل خادم التجربة | تفريغ الواجهة لمتابعة العمل يدوياً وإبقاء المجلد المحلي نظيفاً |
| إدارة سجلات Git | يتم معالجتها تلقائياً بواسطة Codex | يتم معالجتها تلقائياً |
الملفات في .gitignore | لا تنتقل مع التعديلات | لا تنتقل مع التعديلات |
💡 ملخص في جملة واحدة: تتولى ميزة Handoff نقل التعديلات والجلسات بين المحلي Local (الواجهة) والمستقل Worktree (الخلفية) بالاتجاهين، مع تولي Codex إدارة السجلات تلقائياً؛ ولا يتم نقل الملفات المكتوبة في ملف التجاهل
.gitignore.
05 تهيئة البيئة المحلية لمجلد العمل الجديد (setup script)
نستكمل حل مشكلة الملفات غير المنقولة. نظراً لأن مجلد العمل المستقل يمثل نسخة جديدة ونظيفة من المشروع، فلن تتوفر بداخله الملفات والتبعيات غير المرفوعة في Git. مما يسبب توقف تشغيل الأكواد لغياب مجلد المكتبات node_modules أو ملف التكوين .env.
واجهت هذه المشكلة سابقاً عندما طلبت من Codex تعديل كود برمجي في مجلد مستقل، وفشلت العملية لغياب ملف تكوين قاعدة البيانات .env الحساس والمكتوب في ملف التجاهل. وحل المشكلة يكمن في كتابة سكربت تهيئة البيئة المحلية.
تشبيه: قائمة التجهيزات الأساسية لافتتاح فرع جديد للمطعم. يملك الفرع الرئيسي (المجلد المحلي) كل المعدات والمكونات؛ وعند افتتاح فرع جديد (مجلد عمل مستقل) فستجد الجدران فارغة. ويقوم الطاهي الرئيسي بإعداد قائمة تجهيزات افتتاحية تضم: جلب الأجهزة، توفير المواد الأساسية، وترتيب الصالة، لتصبح صالحة للعمل بمجرد تشغيلها. يمثل سكربت التهيئة (setup script) هذه القائمة لـ Codex - حيث يقوم بتشغيله تلقائياً بمجرد بناء مجلد العمل الجديد لتثبيت التبعيات وتوفير الإعدادات الأساسية قبل بدء المهام.
كيف يتم التهيئة وكتابة السكربت؟
- تدار إعدادات البيئة المحلية عبر قائمة خيارات الإعدادات (settings) في تطبيق Codex، ويتم حفظ ملف التكوين الناتج في مجلد إعدادات المشروع الرئيسي
.codex. - ويمكنك رفع ملف التكوين هذا في Git لمشاركته مع الفريق - ليحصل كل مطور على نفس التهيئة التلقائية لمجلدات العمل الخاصة به بمجرد سحب المشروع.
إليك مثالاً مبسطاً لكتابة سكربت التهيئة لمشروع TypeScript:
npm install
npm run buildبمجرد بناء مجلد العمل المستقل، يتم تشغيل هذين الأمرين لتثبيت المكتبات البرمجية وإجراء عملية البناء الأولية، ليصبح المجلد جاهزاً لبدء العمل البرمجي مباشرة ودون انقطاع.
توافق الأنظمة: إذا كان فريق العمل يستخدم أنظمة مختلفة (macOS / Windows / Linux)، فيمكنك كتابة سكربتات تهيئة مخصصة لكل نظام مستقل لتجاوز مشاكل توافق الأوامر.
وإلى جانب سكربت التهيئة، تتيح إعدادات البيئة المحلية تهيئة الأفعال (Actions) - وهي عبارة عن أزرار سريعة تظهر أعلى المحادثة لتشغيل مهام متكررة مثل "بدء خادم التجربة" أو "تشغيل الاختبارات" بضغطة زر داخل الطرفية المدمجة للجلسة (أشرنا إليها في المقال 07).
💡 ملخص في جملة واحدة: يفتقر مجلد العمل الجديد للملفات غير المرفوعة في Git؛ ويستخدم سكربت التهيئة (setup script) (المحفوظ في مجلد
.codexللمشروع) لتثبيت المكتبات والتبعيات تلقائياً بمجرد بناء المجلد وتأمين متطلبات تشغيل الأكواد.
06 تنظيف مجلدات العمل الزائدة وتوفير مساحة القرص
مع كثرة تشغيل المهام بالتوازي، ستتراكم مجلدات العمل المستقلة وتستهلك مساحة تخزين كبيرة من القرص الصلب لاحتواء كل منها على ملفات المشروع والمكتبات المثبتة. لذا يوفر Codex آلية ذكية لإدارة وتنظيف هذه المجلدات تلقائياً.
ونوضح الحقيقتين التاليتين لإدارة ملفات العمل:
- يتم حفظ وبناء مجلدات العمل تحت مسار رئيسي موحد هو
$CODEX_HOME/worktrees(ويكون المجلد الافتراضي هو~/.codexكما بيّنا في المقال 18). - يقوم Codex تلقائياً بالاحتفاظ بآخر 15 مجلد عمل نشط؛ ويمكنك تعديل هذا الحد أو إيقاف ميزة الحذف التلقائي بالكامل من الإعدادات لإدارة مساحة القرص يدوياً.
وتخضع عملية التنظيف والحذف التلقائي للشروط التالية:
المجلدات المستثناة من الحذف التلقائي وتظل محفوظة دائماً:
- مجلدات العمل المرتبطة بمحادثات قمت بـ "تثبيتها (pinned)" في القائمة.
- مجلدات العمل المرتبطة بمحادثات لا تزال قيد التنفيذ والعمل حالياً.
- مجلدات العمل المعرفة كـ "مجلدات عمل دائمة (permanent worktrees)" كما سنوضح أدناه.
المجلدات التي يتم حذفها تلقائياً لتوفير المساحة:
- مجلدات العمل التابعة لمحادثات قمت بـ "أرشفتها (archive)".
- مجلدات العمل القديمة التي يتم حذفها تلقائياً لإفساح المجال للمجلدات الجديدة عند تجاوز الحد الأقصى المسموح به.
ونشير لـ صمام أمان متميز لحماية البيانات:
قبل حذف مجلد العمل التلقائي، يقوم Codex بأخذ لقطة حفظ (snapshot) سريعة للتعديلات المنجزة بداخلها. وإذا قمت بفتح المحادثة المؤرشفة أو القديمة لاحقاً، ستظهر واجهة تعرض استعادة الملفات والتعديلات بنجاح.
مما يضمن عدم ضياع التعديلات البرمجية حتى بعد حذف المجلد الفيزيائي من القرص.
ونبين الفارق بين المجلد المؤقت التلقائي و المجلد الدائم:
| وجه المقارنة | مجلد العمل التلقائي المدار (الافتراضي) | مجلد العمل الدائم (Permanent Worktree) |
|---|---|---|
| طريقة الإنشاء | يتم إنشاؤه تلقائياً بواسطة Codex عند تشغيل جلسة Worktree | يتم إنشاؤه يدوياً من قائمة خيارات المشروع الفرعية |
| الارتباط بالمحادثات | يقتصر على مهمة ومحادثة واحدة عادة | يمكن ربطه وتسيير عدة محادثات مستقلة منه |
| شروط الحذف | يحذف تلقائياً عند الأرشفة أو تجاوز الحد الأقصى | يستثنى من الحذف التلقائي نهائياً ويظل محفوظاً على القرص |
| الاستخدام الأنسب | للمهام والمراجعات السريعة والمؤقتة | لحجز بيئة عمل ثابتة ومستقرة للعودة إليها بانتظام |
💡 ملخص في جملة واحدة: تحفظ مجلدات العمل في المسار
$CODEX_HOME/worktreesويتم الاحتفاظ بآخر 15 مجلد عمل نشط تلقائياً (مع حفظ لقطة أمان للاستعادة قبل الحذف)؛ وتظل المجلدات المثبتة أو المعرفة كدائمة محفوظة دائماً لحماية البيانات.
07 تدريب عملي: تشغيل دورة عمل متكاملة لمجلد عمل مستقل
نطبق معاً تدريباً عملياً متكاملاً داخل تطبيق سطح المكتب لـ Codex: إنشاء مجلد عمل مستقل ← الاستعلام عن ملفات المشروع ← التحقق من عزل المجلد ← نقل المهمة للمجلد المحلي عبر Handoff ← ثم أرشفتها لتنظيف الملفات.
يتطلب التدريب توفر مستودع Git (يمكنك تهيئة مجلد فارغ بكتابة
git initوتثبيت ملف عشوائي فيه). ويقتصر تطبيق الخطوات على واجهة تطبيق سطح المكتب.
الخطوة الأولى: فتح محادثة جديدة وتفعيل وضع Worktree
أنشأ محادثة جديدة في تطبيق Codex، وتوجه للأسفل وحول خيار التشغيل من المحلي (Local) إلى Worktree، وحدد فرع البدء كفرع main الرئيسي.
المتوقع: تحول رمز المحادثة ليعبر عن جلسة عمل مستقلة مع ظهور اسم فرع البدء المختار.
الخطوة الثانية: إرسال طلب استكشاف بسيط
اكتب طلباً لا يترتب عليه تعديل ملفات حساسة، مثل: "اعرض لي قائمة بأسماء الملفات المكتوبة بتنسيق markdown في هذا المشروع."
المتوقع: سيقوم Codex ببناء مجلد عمل فرعي جديد مشتق من الفرع المختار داخل مسار المجلدات الرئيسي $CODEX_HOME/worktrees ويبدأ في قراءة الملفات وعرض الأسماء، دون مساس بمجلدك المحلي الرئيسي.
الخطوة الثالثة: التحقق من استقلالية المجلد من الطرفية المدمجة
افتح نافذة الطرفية المدمجة للمحادثة (باستخدام الاختصار Cmd + J لأنظمة Mac أو الاختصار المقابل لنظامك)، واكتب الأمر التالي:
git worktree listالمتوقع: ظهور سطرين في المخرجات: الأول يشير لمجلد المشروع الرئيسي (Local)، والثاني يشير لمجلد العمل الفرعي المؤقت التابع لـ Codex تحت مسار .../.codex/worktrees/.... مما يثبت نجاح عزل الملفات.
الخطوة الرابعة: نقل الجلسة للمجلد المحلي عبر Handoff
توجه لأعلى واجهة المحادثة، وانقر على زر Hand off واختر Local.
المتوقع: انتقال الجلسة والتعديلات بنجاح للمجلد المحلي الرئيسي لتصبح متاحة للمراجعة بمحرر أكوادك المعتاد، مع تولي Codex إدارة السجلات البرمجية في الخلفية تلقائياً ودون تدخل منك.
الخطوة الخامسة: أرشفة المحادثة لتنظيف الملفات
بعد انتهاء التجربة، توجه لقائمة المحادثات الجانبية وانقر على خيار أرشفة (Archive) للمحادثة الحالية.
المتوقع: اختفاء المحادثة من قائمة العمليات النشطة وبدء حذف وتطهير مجلد العمل المؤقت من القرص تلقائياً لتوفير المساحة، مع بقاء لقطة أمان محفوظة للرجوع إليها عند الحاجة.
بإتمام هذه الخطوات الخمس، تكون قد أتقنت عملياً دورة عمل فروع العمل المتوازية: البناء ← التحقق من العزل ← النقل بالـ Handoff ← والتطهير التلقائي بعد الانتهاء.
💡 ملخص في جملة واحدة: خطوات التدريب العملي هي: تفعيل وضع Worktree لجلسة جديدة ← طلب سرد ملفات المشروع لتأسيس المجلد ← التحقق من المجلد بأمر git worktree list ← استخدام Handoff لنقل الجلسة للمحلي ← وأرشفة المحادثة للتنظيف وتوفير مساحة القرص.
08 ملخص
شرحنا في هذا المقال نظام فروع العمل المتوازية (Worktrees) في Codex - وكيفية عزل وتسيير عدة مهام معاً بالتوازي ودون تداخل التعديلات، وقواعد نقل المهام بالـ Handoff وتهيئة البيئات المحلية وتنظيف الملفات.
دعنا نلخص النقاط الأساسية معاً بشكل سريع:
| الجانب | المفهوم الأساسي | نقاط هامة |
|---|---|---|
| وظيفة الميزة | عزل وتسيير مهام برمجية متعددة ومستقلة بالتوازي | تمنع تداخل التعديلات وتفادي استهلاك وكلاء متعددين لنفس الملفات الفيزيائية |
| خطوات البدء | تفعيل وضع Worktree في تطبيق سطح المكتب | اشتقاق المجلد من فرع محدد؛ وتعمل الجلسة في وضع detached HEAD ويشترط النقر على Create branch here للتسمية |
| قاعدة Git الصارمة | حظر فتح نفس الفرع في موقعين معاً | تمنع Git فتح الفرع النشط في مجلد آخر لتجنب تضارب السجلات، والحل عبر Handoff |
| ميزة Handoff | نقل الجلسات بين الواجهة (Local) والخلفية (Worktree) | نقل متكامل وبالاتجاهين يديره Codex تلقائياً، وتستثنى الملفات المكتوبة في .gitignore |
| تهيئة البيئة | سكربت التهيئة (setup script) | يكتب في مجلد .codex للمشروع ويشغل تلقائياً لتثبيت التبعيات والكتب البرمجية للمجلد الجديد |
| إدارة مساحة القرص | تنظيف وحذف مجلدات العمل القديمة تلقائياً | يحفظ آخر 15 مجلد عمل تلقائياً مع أخذ لقطات أمان للاستعادة؛ وتستثنى الجلسات المثبتة أو الدائمة |
يجب أن تكون الآن قادراً على: تقييم المهام وتحديد ما يناسب عزلها في مجلد عمل مستقل؛ وتشغيل فروع عمل متوازية وإدارتها في تطبيق سطح المكتب وتسمية الفروع عند الحاجة؛ وتجنب أخطاء تعارض فتح الفروع بالاستعانة بميزة Handoff؛ وتهيئة سكربتات البيئة المحلية لتأمين متطلبات التشغيل تلقائياً؛ وإدارة وتنظيف مساحة التخزين وحفظ المجلدات الدائمة. هذه القدرة على عزل وتنسيق العمليات تتيح لك إدارة وتطوير مهام برمجية متعددة بالتوازي وبكامل الأمان والسرعة.
وتذكر دائماً التنبيهات الفنية - واحفظ قواعد "تجنب العمل على نفس الفرع في موقعين، وتفعيل Handoff لنقل المهام، وكتابة سكربت التهيئة لتوفير التبعيات، وأرشفة المحادثات المؤقتة لتنظيف القرص" لتأمين وتسريع دورة عملك.
المقال التالي [26 · التكامل مع Git و GitHub] - ساعدتنا فروع العمل المتوازية (Worktrees) على عزل وتسيير المهام بالتوازي، ونقلها بالـ Handoff للواجهة المحلية بنجاح. ولكن بعد انتهاء التعديلات البرمجية، كيف نقوم بدمج هذه الفروع وتثبيت التعديلات ورفعها وفتح PRs بشكل مؤتمت وذكي بالاستعانة بالمساعد؟ سنتحدث في المقال القادم بالتفصيل عن أدوات التكامل مع Git و GitHub: وكيفية صياغة رسائل commit معبرة وإدارة التعديلات وفتح PRs وتنسيق المراجعات بالتكامل مع منصة GitHub لإتمام دورة التطوير البرمجي بنجاح.