GITMODULES(5)                     Git Manual                     GITMODULES(5)

نام (NAME)
       gitmodules - تعریف ویژگی‌های زیرپروژه‌ها (submodules) در گیت

خلاصه دستور (SYNOPSIS)
       $GIT_WORK_TREE/.gitmodules

توضیحات (DESCRIPTION)
       فایل .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 تنظیم شود، کلون این زیرپروژه به صورت یک کلون
           کم‌عمق (با عمق تاریخچه ۱) انجام می‌شود مگر اینکه کاربر صراحتاً درخواست
           کلون غیرکم‌عمق داشته باشد.

نکات (NOTES)
       گیت اجازه نمی‌دهد فایل .gitmodules درون یک درخت کاری یک پیوند نمادین
       (symbolic link) باشد و از استخراج (checkout) چنین مدخلی در درخت خودداری
       می‌کند. این امر رفتار سیستم را هنگام دسترسی به فایل از ایندکس یا درخت در
       مقایسه با فایل‌سیستم یکدست نگه می‌دارد و به گیت کمک می‌کند تا بررسی‌های
       امنیتی محتوای فایل را به طور قابل‌اعتماد اعمال کند.

مثال‌ها (EXAMPLES)
       فایل .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) مشخص شده است که
       می‌تواند برای کلون کردن زیرپروژه‌ها استفاده شود.

همچنین ببینید (SEE ALSO)
       git-submodule(1), gitsubmodules(7), git-config(1)

گیت (GIT)
       بخشی از مجموعه git(1)

Git 2.55.0                        2026-06-29                     GITMODULES(5)