مدیریت Git Submodules

چیست؟

Submodule مکانیزمی در Git است که اجازه می‌دهد یک مخزن را داخل مخزن دیگر به‌عنوان یک dependency قرار دهید. Submodule خودش یک repository جداست و در parent فقط pointer به commit مشخصی نگهداری می‌شود.

مزایا و چالش‌ها

• منظم نگه داشتن وابستگی‌ها
• کنترل دقیق نسخه هر dependency
• نیاز به مدیریت دستی pointerها و commit کردن آنها در parent
• مواجه شدن با detached HEAD یا mismatch بین .gitmodules و .git/config

پاراگراف عملیاتی: شماری از سناریوها

افزودن submodule

git submodule add <repo_url> <path>
git submodule update --init --recursive
git add .gitmodules && git add <path>
git commit -m "Add submodule <path>"

بروزرسانی به جدیدترین commit در remote

git submodule update --remote --recursive
git add .
git commit -m "Update submodules"
git push

حذف کامل submodule

git submodule deinit -f <path>
git rm -f <path>
rm -rf .git/modules/<path>
git commit -m "Remove submodule <path>"

تفاوت Submodule و Subtree

Submodule یک reference است، Subtree یک copy که merge می‌شود — Submodule سبک‌تر ولی مدیریت آن پیچیده‌تر است.

بهترین روش‌ها (Best Practices)

• برای توسعه فعال از branch مشخصی استفاده کنید و آن را در README مستند کنید.
• هر تغییر در submodule را در parent با یک commit نقطه‌ای ثبت کنید.
• استفاده از CI برای آپدیت خودکار و چک کردن compatibility.

رفع کانفلیکت‌ها — نکات عمیق

1. URL mismatch: اصلاح .gitmodules سپس `git submodule sync`.
2. Pointer mismatch: داخل submodule commit/checkout درست را بزنید سپس parent را update کنید.
3. Detached HEAD: create a branch or move pointer to a stable commit.