gitmodules - تعریف
ویژگی‌های
زیرپروژه‌ها
(submodules) در گیت
$GIT_WORK_TREE/.gitmodules
فایل .gitmodules،
واقع در
بالاترین
سطح
دایرکتوری
درخت کاری
گیت، یک
فایل متنی
با ساختار
نحوی منطبق
بر الزامات
git-config(1) است.
این فایل
شامل یک
زیربخش به
ازای هر
زیرپروژه (submodule)
است و مقدار
این
زیربخش،
نام آن
زیرپروژه
است. این نام
به صورت
پیش‌فرض
همان مسیری
است که
زیرپروژه
در آن اضافه
شده است،
مگر آنکه با
گزینه --name در
دستور git submodule add
سفارشی‌سازی
شده باشد. هر
بخش
زیرپروژه
شامل
کلیدهای
اجباری زیر
نیز هست:
submodule.<name>.path
مسیری را
مشخص
می‌کند
(نسبت به
دایرکتوری
ریشه درخت
کاری گیت) که
انتظار
می‌رود
زیرپروژه
در آن
استخراج (checkout)
شود. نام
مسیر نباید
به / ختم شود.
تمام
مسیرهای
زیرپروژه
در فایل .gitmodules
باید یکتا
باشند.
submodule.<name>.url
نشانی
اینترنتی (URL)
را که مخزن
زیرپروژه
می‌تواند
از آن کلون
شود مشخص
می‌کند. این
می‌تواند
یک نشانی
کامل و
آماده برای
ارسال به
git-clone(1)
باشد یا (اگر
با
./ یا
../
آغاز شود)
مکانی نسبی
نسبت به
مخزن مبدا (origin)
پروژه اصلی
باشد.
علاوه بر
این،
تعدادی
کلید
اختیاری
نیز وجود
دارد:
submodule.<name>.update
روال
پیش‌فرض
به‌روزرسانی
زیرپروژه
مشخص‌شده
را تعیین
می‌کند؛
یعنی نحوه
به‌روزرسانی
زیرپروژه
توسط دستور
git submodule update در
پروژه اصلی.
این مقدار
فقط توسط
دستور
git submodule
init برای
مقداردهی
اولیه
متغیر
پیکربندی
هم‌نام
استفاده
می‌شود.
مقادیر
مجاز در
اینجا
عبارتند از:
checkout،
rebase،
merge یا
none، اما نه
!command
(به دلایل
امنیتی).
برای
جزئیات
بیشتر به
توضیحات
دستور
update در
git-submodule(1) مراجعه
کنید.
submodule.<name>.branch
نام یک
شاخه راه
دور برای
ردیابی
به‌روزرسانی‌ها
در
زیرپروژه
بالادست.
اگر این
گزینه مشخص
نشود، به
صورت
پیش‌فرض به
HEAD شاخه راه
دور ارجاع
داده
می‌شود.
مقدار ویژه .
نشان
می‌دهد که
نام شاخه در
زیرپروژه
باید با نام
شاخه جاری
در مخزن
فعلی یکسان
باشد. برای
جزئیات به
مستندات
--remote
در
git-submodule(1)
مراجعه
کنید.
submodule.<name>.fetchRecurseSubmodules
این
گزینه
می‌تواند
برای کنترل
دریافت
بازگشتی (recursive fetching)
این
زیرپروژه
استفاده
شود. اگر این
گزینه در
مدخل
زیرپروژه
در فایل .git/config
پروژه اصلی
نیز وجود
داشته
باشد،
تنظیمات
موجود در
آنجا بر
تنظیمات
یافت‌شده
در .gitmodules
اولویت
خواهد داشت.
هر دو تنظیم
را می‌توان
در خط فرمان
با استفاده
از گزینه
--[no-]recurse-submodules در
دستورهای git
fetch و git pull
بازنویسی
کرد.
submodule.<name>.ignore
تعیین
می‌کند که
تحت چه
شرایطی
دستور
git status و
خانواده
دستورهای diff
زیرپروژه
را به عنوان
تغییریافته
(modified) نشان دهند.
مقادیر زیر
پشتیبانی
می‌شوند:
all
زیرپروژه
هرگز
تغییریافته
در نظر
گرفته
نخواهد شد
(اما در
صورتی که
مرحله‌بندی
شده باشد،
در خروجی status و
commit ظاهر
می‌شود).
افزودن یک
زیرپروژه
با (new commits) را
می‌توان با
دستور git add --force
<submodule.path>
بازنویسی
کرد. این
تنظیم بر
دستورهای
status، update-index، diff و
log (به دلیل
استفاده از
diff درونی)
تاثیر
می‌گذارد.
dirty
تمام
تغییرات
اعمال‌شده
در درخت
کاری
زیرپروژه
نادیده
گرفته
می‌شوند؛
فقط
تفاوت‌های
کامیت‌شده
بین HEAD
زیرپروژه و
وضعیت
ثبت‌شده آن
در پروژه
اصلی در نظر
گرفته
می‌شوند.
untracked
فقط
فایل‌های
ردیابی‌نشده
در
زیرپروژه‌ها
نادیده
گرفته
می‌شوند.
تفاوت‌های
کامیت‌شده
و تغییرات
فایل‌های
ردیابی‌شده
نمایش داده
خواهند شد.
none
هیچ
تغییری در
زیرپروژه‌ها
نادیده
گرفته
نمی‌شود؛
تمام
تفاوت‌های
کامیت‌شده
و تغییرات
فایل‌های
ردیابی‌شده
و
ردیابی‌نشده
نشان داده
می‌شوند.
این گزینه
پیش‌فرض
است.
اگر این
گزینه در
مدخل
زیرپروژه
در فایل .git/config
پروژه اصلی
نیز وجود
داشته
باشد،
مقدار آنجا
بر تنظیم
موجود در .gitmodules
اولویت
خواهد
داشت.
هر دو
تنظیم را
می‌توان در
خط فرمان با
استفاده از
گزینه --ignore-submodules
بازنویسی
کرد.
دستورهای git
submodule تحت
تاثیر این
تنظیم قرار
نمی‌گیرند.
submodule.<name>.shallow
هنگامی
که روی true
تنظیم شود،
کلون این
زیرپروژه
به صورت یک
کلون
کم‌عمق (با
عمق
تاریخچه ۱)
انجام
می‌شود مگر
اینکه
کاربر
صراحتاً
درخواست
کلون
غیرکم‌عمق
داشته
باشد.
گیت اجازه
نمی‌دهد
فایل .gitmodules
درون یک
درخت کاری
یک پیوند
نمادین (symbolic link)
باشد و از
استخراج (checkout)
چنین مدخلی
در درخت
خودداری
می‌کند. این
امر رفتار
سیستم را
هنگام
دسترسی به
فایل از
ایندکس یا
درخت در
مقایسه با
فایل‌سیستم
یکدست نگه
می‌دارد و
به گیت کمک
می‌کند تا
بررسی‌های
امنیتی
محتوای
فایل را به
طور
قابل‌اعتماد
اعمال کند.
فایل .gitmodules
زیر را در
نظر
بگیرید:
[submodule "libfoo"]
path = include/foo
url = git://foo.com/git/lib.git
[submodule "libbar"]
path = include/bar
url = git://bar.com/git/lib.git
این
پیکربندی
دو
زیرپروژه
با نام‌های
libfoo و libbar را
تعریف
می‌کند.
انتظار
می‌رود این
زیرپروژه‌ها
در مسیرهای
include/foo و include/bar
استخراج
شوند، و
برای هر دو
زیرپروژه
یک نشانی (URL)
مشخص شده
است که
می‌تواند
برای کلون
کردن
زیرپروژه‌ها
استفاده
شود.
