GIT-SUBMODULE(1) Git Manual GIT-SUBMODULE(1)

git-submodule - مقداردهی اولیه، به‌روزرسانی یا بررسی زیرماژول‌ها

git submodule [--quiet] [--cached]
git submodule [--quiet] add [<options>] [--] <repository> [<path>]
git submodule [--quiet] status [--cached] [--recursive] [--] [<path>...]
git submodule [--quiet] init [--] [<path>...]
git submodule [--quiet] deinit [-f|--force] (--all|[--] <path>...)
git submodule [--quiet] update [<options>] [--] [<path>...]
git submodule [--quiet] set-branch [<options>] [--] <path>
git submodule [--quiet] set-url [--] <path> <newurl>
git submodule [--quiet] summary [<options>] [--] [<path>...]
git submodule [--quiet] foreach [--recursive] <command>
git submodule [--quiet] sync [--recursive] [--] [<path>...]
git submodule [--quiet] absorbgitdirs [--] [<path>...]

زیرماژول‌ها را بررسی، به‌روزرسانی و مدیریت می‌کند.

برای اطلاعات بیشتر درباره زیرماژول‌ها، به gitsubmodules(7) مراجعه کنید.

بدون هیچ آرگومانی، وضعیت زیرماژول‌های موجود را نمایش می‌دهد. چندین زیردستور برای انجام عملیات روی زیرماژول‌ها در دسترس است.

add [-b <branch>] [-f | --force] [--name <name>] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--] <repository> [<path>]

مخزن داده‌شده را به عنوان یک زیرماژول در مسیر مشخص‌شده به مجموعه تغییراتی که قرار است در کامیت بعدی پروژه فعلی ثبت شود، اضافه می‌کند: پروژه فعلی «پروژه والد» (سوپرپروژه) نامیده می‌شود.

<repository> نشانی URL مربوط به مخزن origin زیرماژول جدید است. این نشانی می‌تواند یک URL مطلق باشد، یا (اگر با ./ یا ../ شروع شود) مکانی نسبی نسبت به مخزن ریموت پیش‌فرض پروژه والد باشد (لطفاً توجه داشته باشید برای مشخص کردن مخزن foo.git که دقیقاً در کنار پروژه والد bar.git قرار دارد، باید از ../foo.git به‌جای ./foo.git استفاده کنید - همان‌طور که ممکن است هنگام پیروی از قواعد URLهای نسبی انتظار برود - زیرا ارزیابی URLهای نسبی در Git مشابه دایرکتوری‌های نسبی است).

ریموت پیش‌فرض، همان ریموتِ شاخه ردیابی ریموت برای شاخه فعلی است. اگر چنین شاخه ردیابی ریموتی وجود نداشته باشد یا HEAD جدا شده (detached) باشد، origin به عنوان ریموت پیش‌فرض در نظر گرفته می‌شود. اگر پروژه والد ریموت پیش‌فرضی پیکربندی نکرده باشد، پروژه والد مرجع بالادست خود خواهد بود و در عوض از دایرکتوری کاری فعلی استفاده می‌شود.

آرگومان اختیاری <path> مکان نسبی برای قرارگیری زیرماژول کلون‌شده در پروژه والد است. اگر <path> داده نشود، بخش کانونیکال مخزن مبدا استفاده می‌شود (repo برای /path/to/repo.git و foo برای host.xz:foo/.git). اگر <path> وجود داشته باشد و از قبل یک مخزن معتبر Git باشد، بدون کلون کردن برای کامیت آماده‌سازی (stage) می‌شود. همچنین <path> به عنوان نام منطقی زیرماژول در مدخل‌های پیکربندی آن استفاده می‌شود، مگر اینکه از --name <name> برای مشخص کردن نام منطقی استفاده شود.

نشانی URL داده‌شده در .gitmodules ثبت می‌شود تا توسط کاربران بعدی که پروژه والد را کلون می‌کنند مورد استفاده قرار گیرد. اگر URL به صورت نسبی نسبت به مخزن پروژه والد داده شده باشد، فرض بر این است که مخازن پروژه والد و زیرماژول در همان موقعیت نسبی در کنار هم نگه داشته می‌شوند و فقط ارائه URL پروژه والد کافی است. دستور git-submodule با استفاده از URL نسبی موجود در .gitmodules زیرماژول را به درستی پیدا خواهد کرد.

اگر --ref-format <format> مشخص شده باشد، فرمت ذخیره‌سازی ارجاعات (ref) زیرماژول‌های تازه‌کلون‌شده بر اساس آن تنظیم می‌شود.

status [--cached] [--recursive] [--] [<path>...]

وضعیت زیرماژول‌ها را نمایش می‌دهد. این دستور شناسه SHA-1 کامیتی را که در حال حاضر در هر زیرماژول چک‌اوت شده است، به همراه مسیر زیرماژول و خروجی git-describe(1) برای آن SHA-1 چاپ می‌کند. ممکن است پیشوند هر SHA-1 یکی از موارد زیر باشد: - اگر زیرماژول مقداردهی اولیه نشده باشد، + اگر کامیت فعلیِ چک‌اوت‌شده در زیرماژول با SHA-1 یافت‌شده در ایندکس مخزن حاوی آن مطابقت نداشته باشد، و U اگر زیرماژول دارای تعارض‌های ادغام (merge conflicts) باشد.

اگر --cached مشخص شده باشد، این دستور در عوض SHA-1 ثبت‌شده در پروژه والد را برای هر زیرماژول چاپ می‌کند.

اگر --recursive مشخص شده باشد، این دستور به صورت بازگشتی وارد زیرماژول‌های تو در تو می‌شود و وضعیت آن‌ها را نیز نمایش می‌دهد.

اگر تنها به تغییرات زیرماژول‌های مقداردهی‌شده فعلی نسبت به کامیت ثبت‌شده در ایندکس یا HEAD علاقه‌مندید، دستورات git-status(1) و git-diff(1) نیز این اطلاعات را ارائه می‌دهند (و همچنین می‌توانند تغییرات در درخت کاری زیرماژول را گزارش کنند).

init [--] [<path>...]

زیرماژول‌های ثبت‌شده در ایندکس (که در جای دیگری اضافه و کامیت شده‌اند) را با تنظیم submodule.$name.url در .git/config، با استفاده از همان تنظیم در .gitmodules به عنوان الگو، مقداردهی اولیه می‌کند. اگر URL نسبی باشد، با استفاده از ریموت پیش‌فرض حل‌وفصل می‌شود. اگر ریموت پیش‌فرضی وجود نداشته باشد، فرض می‌شود که مخزن فعلی همان بالادست (upstream) است.

آرگومان‌های اختیاری <path> مشخص می‌کنند کدام زیرماژول‌ها مقداردهی اولیه شوند. اگر هیچ مسیری مشخص نشده باشد و submodule.active پیکربندی شده باشد، زیرماژول‌هایی که برای فعال بودن پیکربندی شده‌اند مقداردهی اولیه می‌شوند؛ در غیر این صورت تمام زیرماژول‌ها مقداردهی اولیه خواهند شد.

همچنین مقدار submodule.$name.update را، در صورت وجود در فایل .gitmodules، در .git/config کپی می‌کند؛ اما (۱) این دستور اطلاعات موجود در .git/config را تغییر نمی‌دهد، و (۲) مقدار submodule.$name.update که روی یک دستور سفارشی تنظیم شده باشد، به دلایل امنیتی کپی نمی‌شود.

سپس می‌توانید نشانی‌های URL کلون زیرماژول را در .git/config برای پیکربندی محلی خود سفارشی کرده و با git submodule update ادامه دهید؛ همچنین اگر قصد سفارشی‌سازی مکان هیچ‌یک از زیرماژول‌ها را ندارید، می‌توانید صرفاً از git submodule update --init بدون گام صریح init استفاده کنید.

برای تعریف ریموت پیش‌فرض، به زیردستور add مراجعه کنید.

deinit [-f | --force] (--all|[--] <path>...)

لغو ثبت (unregister) زیرماژول‌های داده‌شده؛ یعنی حذف کامل بخش submodule.$name از .git/config به همراه درخت کاری آن‌ها. فراخوانی‌های بعدی git submodule update، git submodule foreach و git submodule sync هر زیرماژول ثبت‌نشده را تا زمانی که دوباره مقداردهی اولیه شود نادیده می‌گیرند؛ بنابراین اگر دیگر نمی‌خواهید نسخه محلی از زیرماژول را در درخت کاری خود داشته باشید، از این دستور استفاده کنید.

هنگامی که این دستور بدون مشخص کردن مسیر (pathspec) اجرا شود، برای جلوگیری از اشتباه، به جای لغو ثبت همه چیز، با خطا خارج می‌شود.

اگر --force مشخص شده باشد، درخت کاری زیرماژول حتی در صورت داشتن تغییرات محلی حذف خواهد شد.

اگر واقعاً می‌خواهید یک زیرماژول را از مخزن حذف کرده و آن را کامیت کنید، به جای آن از git-rm(1) استفاده کنید. برای گزینه‌های حذف به gitsubmodules(7) مراجعه کنید.

update [--init] [--remote] [-N | --no-fetch] [--[no-]recommend-shallow] [-f | --force] [--checkout | --rebase | --merge] [--reference=<repository>] [--ref-format=<format>] [--depth=<depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter=<filter-spec>] [--] [<path>...]

زیرماژول‌های ثبت‌شده را با کلون کردن زیرماژول‌های مفقود، واکشی (fetch) کامیت‌های مفقود در زیرماژول‌ها و به‌روزرسانی درخت کاری آن‌ها، مطابق با آنچه پروژه والد انتظار دارد به‌روزرسانی می‌کند. «به‌روزرسانی» می‌تواند بسته به گزینه‌های خط فرمان و مقدار متغیر پیکربندی submodule.<name>.update به روش‌های مختلفی انجام شود. گزینه خط فرمان نسبت به متغیر پیکربندی اولویت دارد. اگر هیچ‌کدام داده نشود، عملیات checkout انجام می‌شود. (توجه: آنچه در فایل .gitmodules است در این مرحله اهمیتی ندارد؛ برای نحوه استفاده از .gitmodules به git submodule init در بالا مراجعه کنید). روش‌های update که هم از طریق خط فرمان و هم از طریق پیکربندی submodule.<name>.update پشتیبانی می‌شوند عبارتند از:

checkout

کامیتی که در پروژه والد ثبت شده است، در زیرماژول روی یک HEAD جدا شده (detached) چک‌اوت می‌شود.

اگر --force مشخص شده باشد، زیرماژول چک‌اوت خواهد شد (با استفاده از git checkout --force)، حتی اگر کامیت مشخص‌شده در ایندکس مخزن حاوی آن با کامیت چک‌اوت‌شده در زیرماژول مطابقت داشته باشد.

rebase

شاخه فعلی زیرماژول بر روی کامیت ثبت‌شده در پروژه والد بازپایه‌ریزی (rebase) می‌شود.

merge

کامیت ثبت‌شده در پروژه والد با شاخه فعلی در زیرماژول ادغام (merge) می‌شود.

روش‌های به‌روزرسانی زیر دارای محدودیت‌های اضافی هستند:

!<custom-command>

سازوکاری برای اجرای دستورات دلخواه با شناسه کامیت به عنوان آرگومان. به طور مشخص، اگر متغیر پیکربندی submodule.<name>.update روی !<custom-command> تنظیم شده باشد، نام شیءِ کامیت ثبت‌شده در پروژه والد برای زیرماژول به انتهای رشته <custom-command> پیوست شده و اجرا می‌شود. توجه داشته باشید که این سازوکار در فایل .gitmodules یا در خط فرمان پشتیبانی نمی‌شود.

none

زیرماژول به‌روزرسانی نمی‌شود. این روش به‌روزرسانی در خط فرمان مجاز نیست.

اگر زیرماژول هنوز مقداردهی اولیه نشده است، و صرفاً می‌خواهید از تنظیمات ذخیره‌شده در .gitmodules استفاده کنید، می‌توانید زیرماژول را به طور خودکار با گزینه --init مقداردهی اولیه کنید.

اگر --recursive مشخص شده باشد، این دستور به صورت بازگشتی وارد زیرماژول‌های ثبت‌شده می‌شود و هر زیرماژول تو در تویی را در آن‌ها به‌روزرسانی می‌کند.

اگر --ref-format <format> مشخص شده باشد، فرمت ذخیره‌سازی ارجاعات زیرماژول‌های تازه‌کلون‌شده بر اساس آن تنظیم می‌شود.

اگر --filter <filter-spec> مشخص شده باشد، فیلتر کلون جزئی ارائه‌شده روی زیرماژول اعمال خواهد شد. برای جزئیات مربوط به مشخصات فیلتر به git-rev-list(1) مراجعه کنید.

set-branch (-b|--branch) <branch> [--] <path>, set-branch (-d|--default) [--] <path>

شاخه ردیابی ریموت پیش‌فرض را برای زیرماژول تنظیم می‌کند. گزینه --branch امکان تعیین شاخه ریموت را فراهم می‌کند. گزینه --default کلید پیکربندی submodule.<name>.branch را حذف می‌کند، که باعث می‌شود شاخه ردیابی به طور پیش‌فرض به HEAD ریموت بازگردد.

set-url [--] <path> <newurl>

نشانی URL زیرماژول مشخص‌شده را به <newurl> تنظیم می‌کند. سپس، به طور خودکار پیکربندی URL جدید ریموت زیرماژول را همگام‌سازی می‌کند.

summary [--cached | --files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]

خلاصه کامیت‌ها را بین کامیت داده‌شده (به طور پیش‌فرض HEAD) و درخت کاری/ایندکس نمایش می‌دهد. برای زیرماژول مورد نظر، مجموعه‌ای از کامیت‌ها در زیرماژول بین کامیت پروژه والد داده‌شده و ایندکس یا درخت کاری (تغییر با --cached) نمایش داده می‌شوند. اگر گزینه --files داده شود، مجموعه‌ای از کامیت‌ها در زیرماژول بین ایندکس پروژه والد و درخت کاری زیرماژول نمایش داده می‌شود (این گزینه اجازه استفاده از گزینه --cached یا ارائه یک کامیت صریح را نمی‌دهد).

استفاده از گزینه --submodule=log همراه با git-diff(1) نیز این اطلاعات را ارائه می‌دهد.

foreach [--recursive] <command>

یک دستور شل دلخواه <command> را در هر زیرماژول چک‌اوت‌شده اجرا می‌کند. این دستور به متغیرهای $name، $sm_path، $displaypath، $sha1 و $toplevel دسترسی دارد:

$name

نام بخش مربوط به زیرماژول در .gitmodules

$sm_path

مسیر زیرماژول همان‌گونه که در پروژه والد بلاواسطه ثبت شده است

$displaypath

مسیر نسبی از دایرکتوری کاری فعلی به دایرکتوری ریشه زیرماژول

$sha1

کامیت ثبت‌شده در پروژه والد بلاواسطه

$toplevel

مسیر مطلق به سطح بالای پروژه والد بلاواسطه.

توجه داشته باشید که برای جلوگیری از تعارض با $PATH در ویندوز، متغیر $path اکنون یک نام مترادف منسوخ‌شده برای متغیر $sm_path است. هر زیرماژولی که در پروژه والد تعریف شده اما چک‌اوت نشده باشد توسط این دستور نادیده گرفته می‌شود. دستور foreach مگر در صورت دادن --quiet، نام هر زیرماژول را قبل از اجرای دستور چاپ می‌کند. اگر --recursive داده شده باشد، زیرماژول‌ها به صورت بازگشتی پیمایش می‌شوند (یعنی دستور شل داده‌شده در زیرماژول‌های تو در تو نیز اجرا می‌شود). بازگشت کد وضعیت غیرصفر از دستور در هر زیرماژول باعث پایان یافتن پردازش می‌شود. این رفتار را می‌توان با افزودن ||: به انتهای دستور نادیده گرفت.

به عنوان مثال، دستور زیر مسیر و کامیت فعلیِ چک‌اوت‌شده را برای هر زیرماژول نشان می‌دهد:

git submodule foreach 'echo $sm_path `git rev-parse HEAD`'

sync [--recursive] [--] [<path>...]

تنظیمات پیکربندی URL ریموت زیرماژول‌ها را با مقدار مشخص‌شده در .gitmodules همگام‌سازی می‌کند. این دستور تنها بر زیرماژول‌هایی تأثیر می‌گذارد که از قبل دارای مدخل URL در .git/config هستند (این حالت زمانی رخ می‌دهد که آن‌ها مقداردهی اولیه شده یا تازه اضافه شده باشند). این قابلیت زمانی مفید است که URLهای زیرماژول در بالادست تغییر کرده باشند و نیاز داشته باشید مخازن محلی خود را متناسب با آن به‌روزرسانی کنید.

دستور git submodule sync تمام زیرماژول‌ها را همگام‌سازی می‌کند در حالی که git submodule sync -- A تنها زیرماژول A را همگام‌سازی می‌کند.

اگر --recursive مشخص شده باشد، این دستور به صورت بازگشتی وارد زیرماژول‌های ثبت‌شده می‌شود و هر زیرماژول تو در تویی را در آن‌ها همگام‌سازی می‌کند.

absorbgitdirs

اگر دایرکتوری git یک زیرماژول درون خود زیرماژول باشد، دایرکتوری git زیرماژول را به مسیر $GIT_DIR/modules پروژه والد منتقل می‌کند و سپس دایرکتوری git و دایرکتوری کاری آن را با تنظیم core.worktree و افزودن یک فایل .git که به دایرکتوری git تعبیه‌شده در دایرکتوری git پروژه والد اشاره دارد متصل می‌کند.

مخزنی که به طور مستقل کلون شده و بعداً به عنوان زیرماژول اضافه شده است، یا در پیکربندی‌های قدیمی، دایرکتوری git زیرماژول را به جای تعبیه در دایرکتوری git پروژه والد، درون خود زیرماژول نگه می‌دارند.

این دستور به طور پیش‌فرض بازگشتی است.

-q, --quiet

فقط پیام‌های خطا را چاپ می‌کند.

--progress

وضعیت پیشرفت را به طور پیش‌فرض در صورتی که جریان خطای استاندارد به یک ترمینال متصل باشد روی آن گزارش می‌دهد، مگر اینکه -q مشخص شده باشد. این فلگ نمایش وضعیت پیشرفت را حتی اگر جریان خطای استاندارد به ترمینال هدایت نشده باشد اجباری می‌کند. این گزینه فقط برای دستورات add و update معتبر است.

--all

لغو ثبت تمام زیرماژول‌ها در درخت کاری. این گزینه فقط برای دستور deinit معتبر است.

-b<branch>, --branch=<branch>

شاخه مخزن برای اضافه شدن به عنوان زیرماژول. نام شاخه به عنوان submodule.<name>.branch در .gitmodules برای update --remote ثبت می‌شود. مقدار ویژه . برای نشان دادن این است که نام شاخه در زیرماژول باید هم‌نام با شاخه فعلی در مخزن فعلی باشد. اگر این گزینه مشخص نشود، پیش‌فرض آن HEAD ریموت خواهد بود.

-f, --force

دستور را مجبور به ادامه می‌کند، حتی اگر در غیر این صورت با شکست مواجه شود. این گزینه فقط برای دستورات add، deinit و update معتبر است.

add

اجازه افزودن مسیر زیرماژولی را که در حالت عادی نادیده گرفته شده است می‌دهد. همچنین از این گزینه برای دور زدن بررسی عدم استفاده قبلی از نام زیرماژول استفاده می‌شود. به طور پیش‌فرض، git submodule add در صورتی که نام پیشنهادی (که از مسیر مشتق شده است) از قبل برای زیرماژول دیگری در مخزن ثبت شده باشد با شکست مواجه می‌شود. استفاده از --force اجازه می‌دهد دستور با تولید خودکار یک نام منحصربه‌فرد از طریق افزودن یک عدد به نام دارای تعارض (برای مثال، اگر زیرماژولی به نام child وجود داشته باشد، child1 و به همین ترتیب را امتحان می‌کند) ادامه یابد.

deinit

درخت‌های کاری زیرماژول حذف خواهند شد حتی اگر حاوی تغییرات محلی باشند.

update

(فقط در روش چک‌اوت موثر است)، هنگام جابجایی به یک کامیت متفاوت، تغییرات محلی در زیرماژول‌ها را دور می‌ریزد؛ و همیشه یک عملیات چک‌اوت را در زیرماژول اجرا می‌کند، حتی اگر کامیت فهرست‌شده در ایندکس مخزن حاوی آن با کامیت چک‌اوت‌شده در زیرماژول مطابقت داشته باشد.

--cached

به جای HEAD، از ایندکس برای تعیین کامیت استفاده می‌کند. این گزینه فقط برای دستورات status و summary معتبر است.

--files

دستور summary را وادار می‌کند تا کامیت موجود در ایندکس را با کامیت موجود در HEAD زیرماژول مقایسه کند.

-n<n>, --summary-limit=<n>

اندازه summary (تعداد کل کامیت‌های نمایش‌داده‌شده) را به <n> محدود می‌کند. دادن مقدار 0 خلاصه را غیرفعال می‌کند؛ عدد منفی به معنای نامحدود است (پیش‌فرض). این محدودیت فقط برای زیرماژول‌های تغییریافته اعمال می‌شود. اندازه برای زیرماژول‌های اضافه‌شده/حذف‌شده/تغییر‌نوع‌یافته همیشه به 1 محدود است.

--remote

به جای استفاده از SHA-1 ثبت‌شده در پروژه والد برای به‌روزرسانی زیرماژول، از وضعیت شاخه ردیابی ریموت زیرماژول استفاده می‌کند. این گزینه فقط برای دستور update معتبر است. ریموت مورد استفاده، ریموتِ شاخه است (branch.<name>.remote)، که به طور پیش‌فرض origin است. شاخه ریموت مورد استفاده به طور پیش‌فرض HEAD ریموت است، اما نام شاخه را می‌توان با تنظیم گزینه submodule.<name>.branch در یکی از فایل‌های .gitmodules یا .git/config (با اولویت .git/config) تغییر داد.

این گزینه برای هر یک از روش‌های به‌روزرسانی پشتیبانی‌شده (--checkout، --rebase و غیره) کار می‌کند. تنها تفاوت، منبعِ SHA-1 هدف است. به عنوان مثال، submodule update --remote --merge تغییرات زیرماژول بالادست را در زیرماژول‌ها ادغام می‌کند، در حالی که submodule update --merge تغییرات gitlink پروژه والد را در زیرماژول‌ها ادغام می‌کند.

به منظور اطمینان از وضعیت جاری شاخه ردیابی، update --remote قبل از محاسبه SHA-1، مخزن ریموت زیرماژول را واکشی می‌کند. اگر نمی‌خواهید واکشی انجام شود، باید از submodule update --remote --no-fetch استفاده کنید.

از این گزینه برای ادغام تغییرات حاصل از زیرپروژه بالادست با HEAD فعلی زیرماژول خود استفاده کنید. متناوباً، می‌توانید git pull را از داخل زیرماژول اجرا کنید، که به جز نام شاخه ریموت، معادل آن است: update --remote از مخزن بالادست پیش‌فرض و submodule.<name>.branch استفاده می‌کند، در حالی که git pull از branch.<name>.merge زیرماژول استفاده می‌کند. اگر می‌خواهید شاخه پیش‌فرض بالادست را به همراه پروژه والد توزیع کنید از submodule.<name>.branch استفاده کنید، و اگر می‌خواهید هنگام کار در خود زیرماژول احساس طبیعی‌تری داشته باشید از branch.<name>.merge استفاده کنید.

-N, --no-fetch

اشیاء جدید را از سایت ریموت واکشی نمی‌کند. این گزینه فقط برای دستور update معتبر است.

--checkout

کامیتی را که در پروژه والد ثبت شده است، روی یک HEAD جدا شده در زیرماژول چک‌اوت می‌کند. این گزینه فقط برای دستور update معتبر است. این رفتار پیش‌فرض است، و کاربرد اصلی این گزینه برای لغو اثر submodule.<name>.update هنگامی است که روی مقداری غیر از checkout تنظیم شده باشد. اگر کلید submodule.<name>.update یا صریحاً تنظیم نشده باشد یا روی checkout تنظیم شده باشد، این گزینه به صورت ضمنی فعال است.

--merge

کامیتی را که در پروژه والد ثبت شده است، در شاخه فعلی زیرماژول ادغام می‌کند. این گزینه فقط برای دستور update معتبر است. اگر این گزینه داده شود، HEAD زیرماژول جدا نخواهد شد. اگر شکست در ادغام مانع از این فرآیند شود، باید تعارض‌های حاصل را با استفاده از ابزارهای معمول حل تعارض در داخل زیرماژول حل کنید. اگر کلید submodule.<name>.update روی merge تنظیم شده باشد، این گزینه ضمنی است.

--rebase

شاخه فعلی را روی کامیتی که در پروژه والد ثبت شده است بازپایه‌ریزی (rebase) می‌کند. این گزینه فقط برای دستور update معتبر است. در این حالت HEAD زیرماژول جدا نخواهد شد. اگر شکست بازپایه‌ریزی مانع از این فرآیند شود، باید این خطاها را با git-rebase(1) حل کنید. اگر کلید submodule.<name>.update روی rebase تنظیم شده باشد، این گزینه ضمنی است.

--init

تمام زیرماژول‌هایی را که پیش از به‌روزرسانی تاکنون git submodule init برای آن‌ها فراخوانی نشده است، مقداردهی اولیه می‌کند. این گزینه فقط برای دستور update معتبر است.

--name=<name>

نام زیرماژول را به جای پیش‌فرض گرفتن از مسیر آن، به رشته داده‌شده تنظیم می‌کند. <name> باید به عنوان نام دایرکتوری معتبر باشد و نباید با / پایان یابد.

--reference=<repository>

مخزن محلی <repository> را به عنوان مرجع هنگام کلون کردن زیرماژول ارسال می‌کند. این گزینه فقط برای دستورات add و update معتبر است. این دستورات گاهی اوقات نیاز به کلون کردن یک مخزن ریموت دارند. در این حالت، این گزینه به دستور git-clone(1) ارسال خواهد شد.

یادداشت (Note)
از این گزینه استفاده نکنید مگر اینکه یادداشت مربوط به گزینه‌های --reference، --shared و --dissociate در git-clone(1) را با دقت مطالعه کرده باشید.

--dissociate

پس از استفاده از یک مخزن مرجع برای کلون کردن، دیگر به آن وابسته نباشد. این گزینه فقط برای دستورات add و update معتبر است. این دستورات گاهی اوقات نیاز به کلون کردن یک مخزن ریموت دارند. در این حالت، این گزینه به دستور git-clone(1) ارسال خواهد شد.

یادداشت (Note)
یادداشت بالا برای گزینه --reference را ببینید.

--recursive

پیمایش بازگشتی در زیرماژول‌ها. این گزینه فقط برای دستورات foreach، update، status و sync معتبر است. عملیات نه تنها در زیرماژول‌های مخزن فعلی، بلکه در هر زیرماژول تو در تو در داخل آن زیرماژول‌ها (و به همین ترتیب) انجام می‌شود.

--depth=<depth>

یک کلون کم‌عمق (shallow) با تاریخچه‌ای کوتاه‌شده به <depth> بازبینی ایجاد می‌کند. این گزینه برای دستورات add و update معتبر است. به git-clone(1) مراجعه کنید.

--recommend-shallow, --no-recommend-shallow

کلون کم‌عمق زیرماژول‌ها را توصیه می‌کند یا نمی‌کند. این گزینه فقط برای دستور update معتبر است. کلون اولیه زیرماژول به طور پیش‌فرض از تنظیم پیشنهادی submodule.<name>.shallow ارائه‌شده توسط فایل .gitmodules استفاده می‌کند. برای نادیده گرفتن این پیشنهادها از --no-recommend-shallow استفاده کنید.

-j<n>, --jobs=<n>

کلون کردن زیرماژول‌های جدید به صورت موازی با <n> پردازش همزمان. این گزینه فقط برای دستور update معتبر است. مقدار پیش‌فرض آن از گزینه submodule.fetchJobs گرفته می‌شود.

--single-branch, --no-single-branch

در حین به‌روزرسانی تنها یک شاخه کلون شود: HEAD یا شاخه‌ای که توسط --branch مشخص شده است. این گزینه فقط برای دستور update معتبر است.

<path>...

مسیر(های) زیرماژول‌ها. در صورت تعیین، این آرگومان اجرای دستور را تنها به زیرماژول‌های موجود در مسیرهای مشخص‌شده محدود می‌کند. (این آرگومان برای add الزامی است).

هنگام مقداردهی اولیه زیرماژول‌ها، از یک فایل .gitmodules در دایرکتوری سطح بالای مخزن حاوی آن برای یافتن URL هر زیرماژول استفاده می‌شود. ساختار این فایل باید مشابه با $GIT_DIR/config باشد. کلید مربوط به URL هر زیرماژول عبارت است از submodule.<name>.url. برای جزئیات به gitmodules(5) مراجعه کنید.

gitsubmodules(7), gitmodules(5).

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

2026-06-29 Git 2.55.0