إذا قمت باستنساخ مستودع Git على جهاز Mac وكانت مجلدات الوحدات الفرعية فارغة، فافتح تطبيق Terminal، وانتقل إلى المستودع، وقم بتشغيل git submodule update --init --recursive. يؤدي هذا إلى تهيئة الوحدات الفرعية المسجلة بواسطة المشروع، واستخراج (check out) الإيداعات (commits) التي يحددها المستودع الأصل، بالإضافة إلى التعامل مع الوحدات الفرعية المتداخلة. يلزم تثبيت Git والوصول إلى المستودع البعيد لكل وحدة فرعية.

تشغيل أمر التهيئة في المستودع المستنسخ

افتح تطبيق Terminal واستخدم الأمر cd للدخول إلى الدليل الذي تم إنشاؤه بواسطة git clone. إذا كان اسم الدليل يحتوي على مسافات، فضعه بين علامتي اقتباس، على سبيل المثال:

cd "$HOME/Projects/My Project"
git submodule update --init --recursive

استبدل المسار النموذجي بالمسار الفعلي للمستودع المستنسخ لديك. يمكنك أيضاً كتابة cd ، ثم سحب مجلد المستودع من Finder إلى نافذة Terminal لإدراج مساره، ثم الضغط على Return. توثق شركة Apple تطبيق Terminal كواجهة لسطر الأوامر في macOS وتحدد zsh كغلاف افتراضي له؛ وتستخدم الأوامر أعلاه بنية shell عادية تعمل في zsh. Open or quit Terminal on Mac، Change the default shell in Terminal on Mac

توضح وثائق Git الرسمية أن خيار --init يقوم بتهيئة الوحدات الفرعية التي لم تتم تهيئتها، بينما يقوم --recursive أيضاً بتحديث الوحدات الفرعية المتداخلة. ويقوم update بجلب الإيداعات المفقودة واستخراج المراجعة التي يتوقعها المستودع الأصل. git-submodule documentation

التحقق من تهيئة الوحدات الفرعية

لمعرفة ما يسجله المستودع الأصل، قم بتشغيل:

git submodule status --recursive

يعرض سطر حالة الوحدة الفرعية عادةً معرف الإيداع (commit ID) والمسار. وتعني علامة الطرح (-) البادئة أن تلك الوحدة الفرعية لم تتم تهيئتها؛ بينما تعني علامة الجمع (+) أن الإيداع المستخرج يختلف عن الإيداع المسجل بواسطة المستودع الأصل؛ ويشير الحرف U إلى وجود تعارض. كما يُظهر خيار الحالة التكراري (recursive) الوحدات الفرعية المتداخلة أيضاً. git-submodule documentation

إذا أظهرت النتيجة مسارات مسبوقة بعلامات طرح، فقم بتشغيل أمر التهيئة مرة أخرى من الدليل الرئيسي للمستودع. وإذا لم تظهر أي وحدات فرعية، فتحقق مما إذا كان المستودع المستنسخ الحالي يحتوي بالفعل على ملف .gitmodules وما إذا كنت في المستودع المطلوب. فقد لا يحتوي المستودع على أي وحدات فرعية، أو قد لا يسجل الإيداع الذي استنسخته أيّاً منها.

فهم المراجعة التي يتم استخراجها

تُعد الوحدة الفرعية مستودع Git خاصاً بها، ويسجل المستودع الأصل إيداعاً محدداً لها. يقوم سلوك update العادي باستخراج ذلك الإيداع المسجل، مما يترك الوحدة الفرعية عادةً في حالة HEAD منفصلة (detached HEAD). وهذا أمر متوقع عند إعداد المشروع الأصل: فهو يعيد إنتاج الإصدار الذي حدده الأصل. Git - Submodules، git-submodule documentation

لهذا السبب، لا تقم بإضافة --remote عندما يكون هدفك ببساطة هو تهيئة النسخة المستنسخة. حيث يستخدم هذا الخيار فرع التتبع عن بُعد للوحدة الفرعية بدلاً من الإيداع المسجل بواسطة الأصل، مما قد ينتج عنه إصدار مختلف. وإذا كنت تنوي التطوير داخل وحدة فرعية، فتعرف أولاً على سير عمل المشروع؛ فالتبديل إلى فرع أو إنشاء إيداعات بداخلها أمر منفصل عن تهيئتها.

في حالة فشل الأمر

تحتاج تحديثات الوحدات الفرعية إلى الاتصال بالمستودعات البعيدة المدرجة في تهيئة المشروع، لذلك قد يؤدي انقطاع الشبكة أو فقدان إمكانية الوصول إلى منع الاستخراج. قد تتطلب منك الوحدات الفرعية الخاصة المصادقة مع خدمة الاستضافة أو الحصول على إذن وصول إلى المستودع. إذا أبلغ Git بأنه لا يمكنه العثور على مستودع أو حل اسم المضيف، فتأكد من اتصالك بالشبكة ومن إمكانية الوصول، ثم أعد المحاولة.

إذا غيّر مشروع ما عنوان URL الخاص بوحدة فرعية مؤخراً، فيمكن لأمر git submodule sync --recursive مزامنة إعدادات URL المحلية من .gitmodules؛ وأتبعه بأمر git submodule update --init --recursive. يوثق Git استخدام sync لتحديث تكوين عنوان URL للوحدات الفرعية التي تمت تهيئتها بالفعل أو المضافة حديثاً. git-submodule documentation

إذا كان لديك بالفعل عمل محلي داخل وحدة فرعية، فافحصه قبل فرض أي تحديث أو تبديل المراجعات. لا يطلب أمر التهيئة القياسي من Git فرض الاستخراج فوق التغييرات المحلية؛ قم بحل هذا العمل أو الحفاظ عليه بعناية بدلاً من حذف الدليل كحل مختصر للمشاكل.

بمجرد أن يُظهر أمر git submodule status --recursive معرفات الإيداع المتوقعة دون علامات طرح بادئة، تكون مراجعات الوحدات الفرعية المسجلة في المستودع قد تم استخراجها. واصل العمل من المستودع الأصل ما لم تتطلب تعليمات المشروع عملاً منفصلاً داخل وحدة فرعية.

المصادر