'\" t
.\"     Title: git-submodule
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net>
.\"      Date: 2026-06-29
.\"    Manual: Git Manual
.\"    Source: Git 2.55.0
.\"  Language: Persian
.\"
.TH "GIT\-SUBMODULE" "1" "2026\-06\-29" "Git 2\&.55\&.0" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "نام (NAME)"
git-submodule \- مقداردهی اولیه، به‌روزرسانی یا بررسی زیرماژول‌ها
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
\fBgit\fR \fBsubmodule\fR [\fB\-\-quiet\fR] [\fB\-\-cached\fR]
\fBgit\fR \fBsubmodule\fR [\fB\-\-quiet\fR] \fBadd\fR [\fI<options>\fR] [\fB\-\-\fR] \fI<repository>\fR [\fI<path>\fR]
\fBgit\fR \fBsubmodule\fR [\fB\-\-quiet\fR] \fBstatus\fR [\fB\-\-cached\fR] [\fB\-\-recursive\fR] [\fB\-\-\fR] [\fI<path>\fR\&...]
\fBgit\fR \fBsubmodule\fR [\fB\-\-quiet\fR] \fBinit\fR [\fB\-\-\fR] [\fI<path>\fR\&...]
\fBgit\fR \fBsubmodule\fR [\fB\-\-quiet\fR] \fBdeinit\fR [\fB\-f\fR|\fB\-\-force\fR] (\fB\-\-all\fR|[\fB\-\-\fR] \fI<path>\fR\fB\&...\fR)
\fBgit\fR \fBsubmodule\fR [\fB\-\-quiet\fR] \fBupdate\fR [\fI<options>\fR] [\fB\-\-\fR] [\fI<path>\fR\&...]
\fBgit\fR \fBsubmodule\fR [\fB\-\-quiet\fR] \fBset\-branch\fR [\fI<options>\fR] [\fB\-\-\fR] \fI<path>\fR
\fBgit\fR \fBsubmodule\fR [\fB\-\-quiet\fR] \fBset\-url\fR [\fB\-\-\fR] \fI<path>\fR \fI<newurl>\fR
\fBgit\fR \fBsubmodule\fR [\fB\-\-quiet\fR] \fBsummary\fR [\fI<options>\fR] [\fB\-\-\fR] [\fI<path>\fR\&...]
\fBgit\fR \fBsubmodule\fR [\fB\-\-quiet\fR] \fBforeach\fR [\fB\-\-recursive\fR] \fI<command>\fR
\fBgit\fR \fBsubmodule\fR [\fB\-\-quiet\fR] \fBsync\fR [\fB\-\-recursive\fR] [\fB\-\-\fR] [\fI<path>\fR\&...]
\fBgit\fR \fBsubmodule\fR [\fB\-\-quiet\fR] \fBabsorbgitdirs\fR [\fB\-\-\fR] [\fI<path>\fR\&...]
.fi
.sp
.SH "توضیحات (DESCRIPTION)"
.sp
زیرماژول‌ها را بررسی، به‌روزرسانی و مدیریت می‌کند\&.
.sp
برای اطلاعات بیشتر درباره زیرماژول‌ها، به \fBgitsubmodules\fR(7) مراجعه کنید\&.
.SH "دستورات (COMMANDS)"
.sp
بدون هیچ آرگومانی، وضعیت زیرماژول‌های موجود را نمایش می‌دهد\&. چندین زیردستور برای انجام عملیات روی زیرماژول‌ها در دسترس است\&.
.PP
\fBadd\fR [\fB\-b\fR \fI<branch>\fR] [\fB\-f\fR | \fB\-\-force\fR] [\fB\-\-name\fR \fI<name>\fR] [\fB\-\-reference\fR \fI<repository>\fR] [\fB\-\-ref\-format\fR \fI<format>\fR] [\fB\-\-depth\fR \fI<depth>\fR] [\fB\-\-\fR] \fI<repository>\fR [\fI<path>\fR]
.RS 4
مخزن داده‌شده را به عنوان یک زیرماژول در مسیر مشخص‌شده به مجموعه تغییراتی که قرار است در کامیت بعدی پروژه فعلی ثبت شود، اضافه می‌کند: پروژه فعلی «پروژه والد» (سوپرپروژه) نامیده می‌شود\&.
.sp
\fI<repository>\fR
نشانی URL مربوط به مخزن
\fBorigin\fR
زیرماژول جدید است\&. این نشانی می‌تواند یک URL مطلق باشد، یا (اگر با
\fB\&./\fR
یا
\fB\&.\&.\fR\fB/\fR
شروع شود) مکانی نسبی نسبت به مخزن ریموت پیش‌فرض پروژه والد باشد (لطفاً توجه داشته باشید برای مشخص کردن مخزن
\fBfoo\&.git\fR
که دقیقاً در کنار پروژه والد
\fBbar\&.git\fR
قرار دارد، باید از
\fB\&.\&.\fR\fB/foo\&.git\fR
به‌جای
\fB\&./foo\&.git\fR
استفاده کنید \- همان‌طور که ممکن است هنگام پیروی از قواعد URLهای نسبی انتظار برود \- زیرا ارزیابی URLهای نسبی در Git مشابه دایرکتوری‌های نسبی است)\&.
.sp
ریموت پیش‌فرض، همان ریموتِ شاخه ردیابی ریموت برای شاخه فعلی است\&. اگر چنین شاخه ردیابی ریموتی وجود نداشته باشد یا
\fBHEAD\fR
جدا شده (detached) باشد،
\fBorigin\fR
به عنوان ریموت پیش‌فرض در نظر گرفته می‌شود\&. اگر پروژه والد ریموت پیش‌فرضی پیکربندی نکرده باشد، پروژه والد مرجع بالادست خود خواهد بود و در عوض از دایرکتوری کاری فعلی استفاده می‌شود\&.
.sp
آرگومان اختیاری
\fI<path>\fR
مکان نسبی برای قرارگیری زیرماژول کلون‌شده در پروژه والد است\&. اگر
\fI<path>\fR
داده نشود، بخش کانونیکال مخزن مبدا استفاده می‌شود (\fBrepo\fR
برای
\fB/path/to/repo\&.git\fR
و
\fBfoo\fR
برای
\fBhost\&.xz:foo/\&.git\fR)\&. اگر
\fI<path>\fR
وجود داشته باشد و از قبل یک مخزن معتبر Git باشد، بدون کلون کردن برای کامیت آماده‌سازی (stage) می‌شود\&. همچنین
\fI<path>\fR
به عنوان نام منطقی زیرماژول در مدخل‌های پیکربندی آن استفاده می‌شود، مگر اینکه از
\fB\-\-name\fR
\fI<name>\fR
برای مشخص کردن نام منطقی استفاده شود\&.
.sp
نشانی URL داده‌شده در
\fB\&.gitmodules\fR
ثبت می‌شود تا توسط کاربران بعدی که پروژه والد را کلون می‌کنند مورد استفاده قرار گیرد\&. اگر URL به صورت نسبی نسبت به مخزن پروژه والد داده شده باشد، فرض بر این است که مخازن پروژه والد و زیرماژول در همان موقعیت نسبی در کنار هم نگه داشته می‌شوند و فقط ارائه URL پروژه والد کافی است\&. دستور git\-submodule با استفاده از URL نسبی موجود در
\fB\&.gitmodules\fR
زیرماژول را به درستی پیدا خواهد کرد\&.
.sp
اگر
\fB\-\-ref\-format\fR
\fI<format>\fR
مشخص شده باشد، فرمت ذخیره‌سازی ارجاعات (ref) زیرماژول‌های تازه‌کلون‌شده بر اساس آن تنظیم می‌شود\&.
.RE
.PP
\fBstatus\fR [\fB\-\-cached\fR] [\fB\-\-recursive\fR] [\fB\-\-\fR] [\fI<path>\fR\&.\&.\&.]
.RS 4
وضعیت زیرماژول‌ها را نمایش می‌دهد\&. این دستور شناسه SHA\-1 کامیتی را که در حال حاضر در هر زیرماژول چک‌اوت شده است، به همراه مسیر زیرماژول و خروجی
\fBgit-describe\fR(1)
برای آن SHA\-1 چاپ می‌کند\&. ممکن است پیشوند هر SHA\-1 یکی از موارد زیر باشد:
\fB\-\fR
اگر زیرماژول مقداردهی اولیه نشده باشد،
\fB+\fR
اگر کامیت فعلیِ چک‌اوت‌شده در زیرماژول با SHA\-1 یافت‌شده در ایندکس مخزن حاوی آن مطابقت نداشته باشد، و
\fBU\fR
اگر زیرماژول دارای تعارض‌های ادغام (merge conflicts) باشد\&.
.sp
اگر
\fB\-\-cached\fR
مشخص شده باشد، این دستور در عوض SHA\-1 ثبت‌شده در پروژه والد را برای هر زیرماژول چاپ می‌کند\&.
.sp
اگر
\fB\-\-recursive\fR
مشخص شده باشد، این دستور به صورت بازگشتی وارد زیرماژول‌های تو در تو می‌شود و وضعیت آن‌ها را نیز نمایش می‌دهد\&.
.sp
اگر تنها به تغییرات زیرماژول‌های مقداردهی‌شده فعلی نسبت به کامیت ثبت‌شده در ایندکس یا
\fBHEAD\fR
علاقه‌مندید، دستورات
\fBgit-status\fR(1)
و
\fBgit-diff\fR(1)
نیز این اطلاعات را ارائه می‌دهند (و همچنین می‌توانند تغییرات در درخت کاری زیرماژول را گزارش کنند)\&.
.RE
.PP
\fBinit\fR [\fB\-\-\fR] [\fI<path>\fR\&.\&.\&.]
.RS 4
زیرماژول‌های ثبت‌شده در ایندکس (که در جای دیگری اضافه و کامیت شده‌اند) را با تنظیم
\fBsubmodule\&.$name\&.url\fR
در
\fB\&.git/config\fR،
با استفاده از همان تنظیم در
\fB\&.gitmodules\fR
به عنوان الگو، مقداردهی اولیه می‌کند\&. اگر URL نسبی باشد، با استفاده از ریموت پیش‌فرض حل‌وفصل می‌شود\&. اگر ریموت پیش‌فرضی وجود نداشته باشد، فرض می‌شود که مخزن فعلی همان بالادست (upstream) است\&.
.sp
آرگومان‌های اختیاری
\fI<path>\fR
مشخص می‌کنند کدام زیرماژول‌ها مقداردهی اولیه شوند\&. اگر هیچ مسیری مشخص نشده باشد و submodule\&.active پیکربندی شده باشد، زیرماژول‌هایی که برای فعال بودن پیکربندی شده‌اند مقداردهی اولیه می‌شوند؛ در غیر این صورت تمام زیرماژول‌ها مقداردهی اولیه خواهند شد\&.
.sp
همچنین مقدار
\fBsubmodule\&.$name\&.update\fR
را، در صورت وجود در فایل
\fB\&.gitmodules\fR،
در
\fB\&.git/config\fR
کپی می‌کند؛ اما (۱) این دستور اطلاعات موجود در
\fB\&.git/config\fR
را تغییر نمی‌دهد، و (۲) مقدار
\fBsubmodule\&.$name\&.update\fR
که روی یک دستور سفارشی تنظیم شده باشد، به دلایل امنیتی کپی
\fBنمی‌شود\fR\&.
.sp
سپس می‌توانید نشانی‌های URL کلون زیرماژول را در
\fB\&.git/config\fR
برای پیکربندی محلی خود سفارشی کرده و با
\fBgit\fR
\fBsubmodule\fR
\fBupdate\fR
ادامه دهید؛ همچنین اگر قصد سفارشی‌سازی مکان هیچ‌یک از زیرماژول‌ها را ندارید، می‌توانید صرفاً از
\fBgit\fR
\fBsubmodule\fR
\fBupdate\fR
\fB\-\-init\fR
بدون گام صریح
\fBinit\fR
استفاده کنید\&.
.sp
برای تعریف ریموت پیش‌فرض، به زیردستور add مراجعه کنید\&.
.RE
.PP
\fBdeinit\fR [\fB\-f\fR | \fB\-\-force\fR] (\fB\-\-all\fR|[\fB\-\-\fR] \fI<path>\fR\fB\&.\&.\&.\fR)
.RS 4
لغو ثبت (unregister) زیرماژول‌های داده‌شده؛ یعنی حذف کامل بخش
\fBsubmodule\&.$name\fR
از \&.git/config به همراه درخت کاری آن‌ها\&. فراخوانی‌های بعدی
\fBgit\fR
\fBsubmodule\fR
\fBupdate\fR،
\fBgit\fR
\fBsubmodule\fR
\fBforeach\fR
و
\fBgit\fR
\fBsubmodule\fR
\fBsync\fR
هر زیرماژول ثبت‌نشده را تا زمانی که دوباره مقداردهی اولیه شود نادیده می‌گیرند؛ بنابراین اگر دیگر نمی‌خواهید نسخه محلی از زیرماژول را در درخت کاری خود داشته باشید، از این دستور استفاده کنید\&.
.sp
هنگامی که این دستور بدون مشخص کردن مسیر (pathspec) اجرا شود، برای جلوگیری از اشتباه، به جای لغو ثبت همه چیز، با خطا خارج می‌شود\&.
.sp
اگر
\fB\-\-force\fR
مشخص شده باشد، درخت کاری زیرماژول حتی در صورت داشتن تغییرات محلی حذف خواهد شد\&.
.sp
اگر واقعاً می‌خواهید یک زیرماژول را از مخزن حذف کرده و آن را کامیت کنید، به جای آن از
\fBgit-rm\fR(1)
استفاده کنید\&. برای گزینه‌های حذف به
\fBgitsubmodules\fR(7)
مراجعه کنید\&.
.RE
.PP
\fBupdate\fR [\fB\-\-init\fR] [\fB\-\-remote\fR] [\fB\-N\fR | \fB\-\-no\-fetch\fR] [\fB\-\-\fR[\fBno\-\fR]\fBrecommend\-shallow\fR] [\fB\-f\fR | \fB\-\-force\fR] [\fB\-\-checkout\fR | \fB\-\-rebase\fR | \fB\-\-merge\fR] [\fB\-\-reference=\fR\fI<repository>\fR] [\fB\-\-ref\-format=\fR\fI<format>\fR] [\fB\-\-depth=\fR\fI<depth>\fR] [\fB\-\-recursive\fR] [\fB\-\-jobs\fR \fI<n>\fR] [\fB\-\-\fR[\fBno\-\fR]\fBsingle\-branch\fR] [\fB\-\-filter=\fR\fI<filter\-spec>\fR] [\fB\-\-\fR] [\fI<path>\fR\&.\&.\&.]
.RS 4
زیرماژول‌های ثبت‌شده را با کلون کردن زیرماژول‌های مفقود، واکشی (fetch) کامیت‌های مفقود در زیرماژول‌ها و به‌روزرسانی درخت کاری آن‌ها، مطابق با آنچه پروژه والد انتظار دارد به‌روزرسانی می‌کند\&. «به‌روزرسانی» می‌تواند بسته به گزینه‌های خط فرمان و مقدار متغیر پیکربندی
\fBsubmodule\&.\fR\fI<name>\fR\fB\&.update\fR
به روش‌های مختلفی انجام شود\&. گزینه خط فرمان نسبت به متغیر پیکربندی اولویت دارد\&. اگر هیچ‌کدام داده نشود، عملیات
\fBcheckout\fR
انجام می‌شود\&. (توجه: آنچه در فایل
\fB\&.gitmodules\fR
است در این مرحله اهمیتی ندارد؛ برای نحوه استفاده از
\fB\&.gitmodules\fR
به
\fBgit\fR
\fBsubmodule\fR
\fBinit\fR
در بالا مراجعه کنید)\&. روش‌های
\fBupdate\fR
که هم از طریق خط فرمان و هم از طریق پیکربندی
\fBsubmodule\&.\fR\fI<name>\fR\fB\&.update\fR
پشتیبانی می‌شوند عبارتند از:
.PP
\fBcheckout\fR
.RS 4
کامیتی که در پروژه والد ثبت شده است، در زیرماژول روی یک
\fBHEAD\fR
جدا شده (detached) چک‌اوت می‌شود\&.
.sp
اگر
\fB\-\-force\fR
مشخص شده باشد، زیرماژول چک‌اوت خواهد شد (با استفاده از
\fBgit\fR
\fBcheckout\fR
\fB\-\-force\fR)،
حتی اگر کامیت مشخص‌شده در ایندکس مخزن حاوی آن با کامیت چک‌اوت‌شده در زیرماژول مطابقت داشته باشد\&.
.RE
.PP
\fBrebase\fR
.RS 4
شاخه فعلی زیرماژول بر روی کامیت ثبت‌شده در پروژه والد بازپایه‌ریزی (rebase) می‌شود\&.
.RE
.PP
\fBmerge\fR
.RS 4
کامیت ثبت‌شده در پروژه والد با شاخه فعلی در زیرماژول ادغام (merge) می‌شود\&.
.RE
.sp
روش‌های به‌روزرسانی زیر دارای محدودیت‌های اضافی هستند:
.PP
!\fI<custom\-command>\fR
.RS 4
سازوکاری برای اجرای دستورات دلخواه با شناسه کامیت به عنوان آرگومان\&. به طور مشخص، اگر متغیر پیکربندی
\fBsubmodule\&.\fR\fI<name>\fR\fB\&.update\fR
روی !\fI<custom\-command>\fR
تنظیم شده باشد، نام شیءِ کامیت ثبت‌شده در پروژه والد برای زیرماژول به انتهای رشته
\fI<custom\-command>\fR
پیوست شده و اجرا می‌شود\&. توجه داشته باشید که این سازوکار در فایل
\fB\&.gitmodules\fR
یا در خط فرمان پشتیبانی نمی‌شود\&.
.RE
.PP
\fBnone\fR
.RS 4
زیرماژول به‌روزرسانی نمی‌شود\&. این روش به‌روزرسانی در خط فرمان مجاز نیست\&.
.RE
.sp
اگر زیرماژول هنوز مقداردهی اولیه نشده است، و صرفاً می‌خواهید از تنظیمات ذخیره‌شده در
\fB\&.gitmodules\fR
استفاده کنید، می‌توانید زیرماژول را به طور خودکار با گزینه
\fB\-\-init\fR
مقداردهی اولیه کنید\&.
.sp
اگر
\fB\-\-recursive\fR
مشخص شده باشد، این دستور به صورت بازگشتی وارد زیرماژول‌های ثبت‌شده می‌شود و هر زیرماژول تو در تویی را در آن‌ها به‌روزرسانی می‌کند\&.
.sp
اگر
\fB\-\-ref\-format\fR
\fI<format>\fR
مشخص شده باشد، فرمت ذخیره‌سازی ارجاعات زیرماژول‌های تازه‌کلون‌شده بر اساس آن تنظیم می‌شود\&.
.sp
اگر
\fB\-\-filter\fR
\fI<filter\-spec>\fR
مشخص شده باشد، فیلتر کلون جزئی ارائه‌شده روی زیرماژول اعمال خواهد شد\&. برای جزئیات مربوط به مشخصات فیلتر به
\fBgit-rev-list\fR(1)
مراجعه کنید\&.
.RE
.PP
\fBset\-branch\fR (\fB\-b\fR|\fB\-\-branch\fR) \fI<branch>\fR [\fB\-\-\fR] \fI<path>\fR, \fBset\-branch\fR (\fB\-d\fR|\fB\-\-default\fR) [\fB\-\-\fR] \fI<path>\fR
.RS 4
شاخه ردیابی ریموت پیش‌فرض را برای زیرماژول تنظیم می‌کند\&. گزینه
\fB\-\-branch\fR
امکان تعیین شاخه ریموت را فراهم می‌کند\&. گزینه
\fB\-\-default\fR
کلید پیکربندی
\fBsubmodule\&.\fR\fI<name>\fR\fB\&.branch\fR
را حذف می‌کند، که باعث می‌شود شاخه ردیابی به طور پیش‌فرض به
\fBHEAD\fR
ریموت بازگردد\&.
.RE
.PP
\fBset\-url\fR [\fB\-\-\fR] \fI<path>\fR \fI<newurl>\fR
.RS 4
نشانی URL زیرماژول مشخص‌شده را به
\fI<newurl>\fR
تنظیم می‌کند\&. سپس، به طور خودکار پیکربندی URL جدید ریموت زیرماژول را همگام‌سازی می‌کند\&.
.RE
.PP
\fBsummary\fR [\fB\-\-cached\fR | \fB\-\-files\fR] [(\fB\-n\fR|\fB\-\-summary\-limit\fR) \fI<n>\fR] [\fBcommit\fR] [\fB\-\-\fR] [\fI<path>\fR\&.\&.\&.]
.RS 4
خلاصه کامیت‌ها را بین کامیت داده‌شده (به طور پیش‌فرض
\fBHEAD\fR)
و درخت کاری/ایندکس نمایش می‌دهد\&. برای زیرماژول مورد نظر، مجموعه‌ای از کامیت‌ها در زیرماژول بین کامیت پروژه والد داده‌شده و ایندکس یا درخت کاری (تغییر با
\fB\-\-cached\fR)
نمایش داده می‌شوند\&. اگر گزینه
\fB\-\-files\fR
داده شود، مجموعه‌ای از کامیت‌ها در زیرماژول بین ایندکس پروژه والد و درخت کاری زیرماژول نمایش داده می‌شود (این گزینه اجازه استفاده از گزینه
\fB\-\-cached\fR
یا ارائه یک کامیت صریح را نمی‌دهد)\&.
.sp
استفاده از گزینه
\fB\-\-submodule=log\fR
همراه با
\fBgit-diff\fR(1)
نیز این اطلاعات را ارائه می‌دهد\&.
.RE
.PP
\fBforeach\fR [\fB\-\-recursive\fR] \fI<command>\fR
.RS 4
یک دستور شل دلخواه
\fI<command>\fR
را در هر زیرماژول چک‌اوت‌شده اجرا می‌کند\&. این دستور به متغیرهای
\fB$name\fR،
\fB$sm_path\fR،
\fB$displaypath\fR،
\fB$sha1\fR
و
\fB$toplevel\fR
دسترسی دارد:
.PP
\fB$name\fR
.RS 4
نام بخش مربوط به زیرماژول در
\fB\&.gitmodules\fR
.RE
.PP
\fB$sm_path\fR
.RS 4
مسیر زیرماژول همان‌گونه که در پروژه والد بلاواسطه ثبت شده است
.RE
.PP
\fB$displaypath\fR
.RS 4
مسیر نسبی از دایرکتوری کاری فعلی به دایرکتوری ریشه زیرماژول
.RE
.PP
\fB$sha1\fR
.RS 4
کامیت ثبت‌شده در پروژه والد بلاواسطه
.RE
.PP
\fB$toplevel\fR
.RS 4
مسیر مطلق به سطح بالای پروژه والد بلاواسطه\&.
.RE
.sp
توجه داشته باشید که برای جلوگیری از تعارض با
\fB$PATH\fR
در ویندوز، متغیر
\fB$path\fR
اکنون یک نام مترادف منسوخ‌شده برای متغیر
\fB$sm_path\fR
است\&. هر زیرماژولی که در پروژه والد تعریف شده اما چک‌اوت نشده باشد توسط این دستور نادیده گرفته می‌شود\&. دستور foreach مگر در صورت دادن
\fB\-\-quiet\fR،
نام هر زیرماژول را قبل از اجرای دستور چاپ می‌کند\&. اگر
\fB\-\-recursive\fR
داده شده باشد، زیرماژول‌ها به صورت بازگشتی پیمایش می‌شوند (یعنی دستور شل داده‌شده در زیرماژول‌های تو در تو نیز اجرا می‌شود)\&. بازگشت کد وضعیت غیرصفر از دستور در هر زیرماژول باعث پایان یافتن پردازش می‌شود\&. این رفتار را می‌توان با افزودن
\fB||:\fR
به انتهای دستور نادیده گرفت\&.
.sp
به عنوان مثال، دستور زیر مسیر و کامیت فعلیِ چک‌اوت‌شده را برای هر زیرماژول نشان می‌دهد:
.sp
.if n \{\
.RS 4
.\}
.nf
git submodule foreach \*(Aqecho $sm_path `git rev\-parse HEAD`\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
\fBsync\fR [\fB\-\-recursive\fR] [\fB\-\-\fR] [\fI<path>\fR\&.\&.\&.]
.RS 4
تنظیمات پیکربندی URL ریموت زیرماژول‌ها را با مقدار مشخص‌شده در
\fB\&.gitmodules\fR
همگام‌سازی می‌کند\&. این دستور تنها بر زیرماژول‌هایی تأثیر می‌گذارد که از قبل دارای مدخل URL در
\fB\&.git/config\fR
هستند (این حالت زمانی رخ می‌دهد که آن‌ها مقداردهی اولیه شده یا تازه اضافه شده باشند)\&. این قابلیت زمانی مفید است که URLهای زیرماژول در بالادست تغییر کرده باشند و نیاز داشته باشید مخازن محلی خود را متناسب با آن به‌روزرسانی کنید\&.
.sp
دستور
\fBgit\fR
\fBsubmodule\fR
\fBsync\fR
تمام زیرماژول‌ها را همگام‌سازی می‌کند در حالی که
\fBgit\fR
\fBsubmodule\fR
\fBsync\fR
\fB\-\-\fR
\fBA\fR
تنها زیرماژول
\fBA\fR
را همگام‌سازی می‌کند\&.
.sp
اگر
\fB\-\-recursive\fR
مشخص شده باشد، این دستور به صورت بازگشتی وارد زیرماژول‌های ثبت‌شده می‌شود و هر زیرماژول تو در تویی را در آن‌ها همگام‌سازی می‌کند\&.
.RE
.PP
\fBabsorbgitdirs\fR
.RS 4
اگر دایرکتوری git یک زیرماژول درون خود زیرماژول باشد، دایرکتوری git زیرماژول را به مسیر
\fB$GIT_DIR/modules\fR
پروژه والد منتقل می‌کند و سپس دایرکتوری git و دایرکتوری کاری آن را با تنظیم
\fBcore\&.worktree\fR
و افزودن یک فایل
\fB\&.git\fR
که به دایرکتوری git تعبیه‌شده در دایرکتوری git پروژه والد اشاره دارد متصل می‌کند\&.
.sp
مخزنی که به طور مستقل کلون شده و بعداً به عنوان زیرماژول اضافه شده است، یا در پیکربندی‌های قدیمی، دایرکتوری git زیرماژول را به جای تعبیه در دایرکتوری git پروژه والد، درون خود زیرماژول نگه می‌دارند\&.
.sp
این دستور به طور پیش‌فرض بازگشتی است\&.
.RE
.SH "گزینه‌ها (OPTIONS)"
.PP
\fB\-q\fR, \fB\-\-quiet\fR
.RS 4
فقط پیام‌های خطا را چاپ می‌کند\&.
.RE
.PP
\fB\-\-progress\fR
.RS 4
وضعیت پیشرفت را به طور پیش‌فرض در صورتی که جریان خطای استاندارد به یک ترمینال متصل باشد روی آن گزارش می‌دهد، مگر اینکه
\fB\-q\fR
مشخص شده باشد\&. این فلگ نمایش وضعیت پیشرفت را حتی اگر جریان خطای استاندارد به ترمینال هدایت نشده باشد اجباری می‌کند\&. این گزینه فقط برای دستورات
\fBadd\fR
و
\fBupdate\fR
معتبر است\&.
.RE
.PP
\fB\-\-all\fR
.RS 4
لغو ثبت تمام زیرماژول‌ها در درخت کاری\&. این گزینه فقط برای دستور
\fBdeinit\fR
معتبر است\&.
.RE
.PP
\fB\-b\fR\fI<branch>\fR, \fB\-\-branch=\fR\fI<branch>\fR
.RS 4
شاخه مخزن برای اضافه شدن به عنوان زیرماژول\&. نام شاخه به عنوان
\fBsubmodule\&.\fR\fI<name>\fR\fB\&.branch\fR
در
\fB\&.gitmodules\fR
برای
\fBupdate\fR
\fB\-\-remote\fR
ثبت می‌شود\&. مقدار ویژه \&. برای نشان دادن این است که نام شاخه در زیرماژول باید هم‌نام با شاخه فعلی در مخزن فعلی باشد\&. اگر این گزینه مشخص نشود، پیش‌فرض آن
\fBHEAD\fR
ریموت خواهد بود\&.
.RE
.PP
\fB\-f\fR, \fB\-\-force\fR
.RS 4
دستور را مجبور به ادامه می‌کند، حتی اگر در غیر این صورت با شکست مواجه شود\&. این گزینه فقط برای دستورات
\fBadd\fR،
\fBdeinit\fR
و
\fBupdate\fR
معتبر است\&.
.PP
\fBadd\fR
.RS 4
اجازه افزودن مسیر زیرماژولی را که در حالت عادی نادیده گرفته شده است می‌دهد\&. همچنین از این گزینه برای دور زدن بررسی عدم استفاده قبلی از نام زیرماژول استفاده می‌شود\&. به طور پیش‌فرض،
\fBgit\fR
\fBsubmodule\fR
\fBadd\fR
در صورتی که نام پیشنهادی (که از مسیر مشتق شده است) از قبل برای زیرماژول دیگری در مخزن ثبت شده باشد با شکست مواجه می‌شود\&. استفاده از
\fB\-\-force\fR
اجازه می‌دهد دستور با تولید خودکار یک نام منحصربه‌فرد از طریق افزودن یک عدد به نام دارای تعارض (برای مثال، اگر زیرماژولی به نام
\fIchild\fR
وجود داشته باشد،
\fIchild1\fR
و به همین ترتیب را امتحان می‌کند) ادامه یابد\&.
.RE
.PP
\fBdeinit\fR
.RS 4
درخت‌های کاری زیرماژول حذف خواهند شد حتی اگر حاوی تغییرات محلی باشند\&.
.RE
.PP
\fBupdate\fR
.RS 4
(فقط در روش چک‌اوت موثر است)، هنگام جابجایی به یک کامیت متفاوت، تغییرات محلی در زیرماژول‌ها را دور می‌ریزد؛ و همیشه یک عملیات چک‌اوت را در زیرماژول اجرا می‌کند، حتی اگر کامیت فهرست‌شده در ایندکس مخزن حاوی آن با کامیت چک‌اوت‌شده در زیرماژول مطابقت داشته باشد\&.
.RE
.RE
.PP
\fB\-\-cached\fR
.RS 4
به جای
\fBHEAD\fR،
از ایندکس برای تعیین کامیت استفاده می‌کند\&. این گزینه فقط برای دستورات
\fBstatus\fR
و
\fBsummary\fR
معتبر است\&.
.RE
.PP
\fB\-\-files\fR
.RS 4
دستور
\fBsummary\fR
را وادار می‌کند تا کامیت موجود در ایندکس را با کامیت موجود در
\fBHEAD\fR
زیرماژول مقایسه کند\&.
.RE
.PP
\fB\-n\fR\fI<n>\fR, \fB\-\-summary\-limit=\fR\fI<n>\fR
.RS 4
اندازه
\fBsummary\fR
(تعداد کل کامیت‌های نمایش‌داده‌شده) را به
\fI<n>\fR
محدود می‌کند\&. دادن مقدار 0 خلاصه را غیرفعال می‌کند؛ عدد منفی به معنای نامحدود است (پیش‌فرض)\&. این محدودیت فقط برای زیرماژول‌های تغییریافته اعمال می‌شود\&. اندازه برای زیرماژول‌های اضافه‌شده/حذف‌شده/تغییر‌نوع‌یافته همیشه به 1 محدود است\&.
.RE
.PP
\fB\-\-remote\fR
.RS 4
به جای استفاده از SHA\-1 ثبت‌شده در پروژه والد برای به‌روزرسانی زیرماژول، از وضعیت شاخه ردیابی ریموت زیرماژول استفاده می‌کند\&. این گزینه فقط برای دستور
\fBupdate\fR
معتبر است\&. ریموت مورد استفاده، ریموتِ شاخه است (\fBbranch\&.\fR\fI<name>\fR\fB\&.remote\fR)، که به طور پیش‌فرض
\fBorigin\fR
است\&. شاخه ریموت مورد استفاده به طور پیش‌فرض
\fBHEAD\fR
ریموت است، اما نام شاخه را می‌توان با تنظیم گزینه
\fBsubmodule\&.\fR\fI<name>\fR\fB\&.branch\fR
در یکی از فایل‌های
\fB\&.gitmodules\fR
یا
\fB\&.git/config\fR
(با اولویت
\fB\&.git/config\fR)
تغییر داد\&.
.sp
این گزینه برای هر یک از روش‌های به‌روزرسانی پشتیبانی‌شده (\fB\-\-checkout\fR،
\fB\-\-rebase\fR
و غیره) کار می‌کند\&. تنها تفاوت، منبعِ SHA\-1 هدف است\&. به عنوان مثال،
\fBsubmodule\fR
\fBupdate\fR
\fB\-\-remote\fR
\fB\-\-merge\fR
تغییرات زیرماژول بالادست را در زیرماژول‌ها ادغام می‌کند، در حالی که
\fBsubmodule\fR
\fBupdate\fR
\fB\-\-merge\fR
تغییرات gitlink پروژه والد را در زیرماژول‌ها ادغام می‌کند\&.
.sp
به منظور اطمینان از وضعیت جاری شاخه ردیابی،
\fBupdate\fR
\fB\-\-remote\fR
قبل از محاسبه SHA\-1، مخزن ریموت زیرماژول را واکشی می‌کند\&. اگر نمی‌خواهید واکشی انجام شود، باید از
\fBsubmodule\fR
\fBupdate\fR
\fB\-\-remote\fR
\fB\-\-no\-fetch\fR
استفاده کنید\&.
.sp
از این گزینه برای ادغام تغییرات حاصل از زیرپروژه بالادست با
\fBHEAD\fR
فعلی زیرماژول خود استفاده کنید\&. متناوباً، می‌توانید
\fBgit\fR
\fBpull\fR
را از داخل زیرماژول اجرا کنید، که به جز نام شاخه ریموت، معادل آن است:
\fBupdate\fR
\fB\-\-remote\fR
از مخزن بالادست پیش‌فرض و
\fBsubmodule\&.\fR\fI<name>\fR\fB\&.branch\fR
استفاده می‌کند، در حالی که
\fBgit\fR
\fBpull\fR
از
\fBbranch\&.\fR\fI<name>\fR\fB\&.merge\fR
زیرماژول استفاده می‌کند\&. اگر می‌خواهید شاخه پیش‌فرض بالادست را به همراه پروژه والد توزیع کنید از
\fBsubmodule\&.\fR\fI<name>\fR\fB\&.branch\fR
استفاده کنید، و اگر می‌خواهید هنگام کار در خود زیرماژول احساس طبیعی‌تری داشته باشید از
\fBbranch\&.\fR\fI<name>\fR\fB\&.merge\fR
استفاده کنید\&.
.RE
.PP
\fB\-N\fR, \fB\-\-no\-fetch\fR
.RS 4
اشیاء جدید را از سایت ریموت واکشی نمی‌کند\&. این گزینه فقط برای دستور
\fBupdate\fR
معتبر است\&.
.RE
.PP
\fB\-\-checkout\fR
.RS 4
کامیتی را که در پروژه والد ثبت شده است، روی یک
\fBHEAD\fR
جدا شده در زیرماژول چک‌اوت می‌کند\&. این گزینه فقط برای دستور
\fBupdate\fR
معتبر است\&. این رفتار پیش‌فرض است، و کاربرد اصلی این گزینه برای لغو اثر
\fBsubmodule\&.\fR\fI<name>\fR\fB\&.update\fR
هنگامی است که روی مقداری غیر از
\fBcheckout\fR
تنظیم شده باشد\&. اگر کلید
\fBsubmodule\&.\fR\fI<name>\fR\fB\&.update\fR
یا صریحاً تنظیم نشده باشد یا روی
\fBcheckout\fR
تنظیم شده باشد، این گزینه به صورت ضمنی فعال است\&.
.RE
.PP
\fB\-\-merge\fR
.RS 4
کامیتی را که در پروژه والد ثبت شده است، در شاخه فعلی زیرماژول ادغام می‌کند\&. این گزینه فقط برای دستور
\fBupdate\fR
معتبر است\&. اگر این گزینه داده شود،
\fBHEAD\fR
زیرماژول جدا نخواهد شد\&. اگر شکست در ادغام مانع از این فرآیند شود، باید تعارض‌های حاصل را با استفاده از ابزارهای معمول حل تعارض در داخل زیرماژول حل کنید\&. اگر کلید
\fBsubmodule\&.\fR\fI<name>\fR\fB\&.update\fR
روی
\fBmerge\fR
تنظیم شده باشد، این گزینه ضمنی است\&.
.RE
.PP
\fB\-\-rebase\fR
.RS 4
شاخه فعلی را روی کامیتی که در پروژه والد ثبت شده است بازپایه‌ریزی (rebase) می‌کند\&. این گزینه فقط برای دستور
\fBupdate\fR
معتبر است\&. در این حالت
\fBHEAD\fR
زیرماژول جدا نخواهد شد\&. اگر شکست بازپایه‌ریزی مانع از این فرآیند شود، باید این خطاها را با
\fBgit-rebase\fR(1)
حل کنید\&. اگر کلید
\fBsubmodule\&.\fR\fI<name>\fR\fB\&.update\fR
روی
\fBrebase\fR
تنظیم شده باشد، این گزینه ضمنی است\&.
.RE
.PP
\fB\-\-init\fR
.RS 4
تمام زیرماژول‌هایی را که پیش از به‌روزرسانی تاکنون
\fBgit\fR
\fBsubmodule\fR
\fBinit\fR
برای آن‌ها فراخوانی نشده است، مقداردهی اولیه می‌کند\&. این گزینه فقط برای دستور
\fBupdate\fR
معتبر است\&.
.RE
.PP
\fB\-\-name=\fR\fI<name>\fR
.RS 4
نام زیرماژول را به جای پیش‌فرض گرفتن از مسیر آن، به رشته داده‌شده تنظیم می‌کند\&.
\fI<name>\fR
باید به عنوان نام دایرکتوری معتبر باشد و نباید با
\fB/\fR
پایان یابد\&.
.RE
.PP
\fB\-\-reference=\fR\fI<repository>\fR
.RS 4
مخزن محلی
\fI<repository>\fR
را به عنوان مرجع هنگام کلون کردن زیرماژول ارسال می‌کند\&. این گزینه فقط برای دستورات
\fBadd\fR
و
\fBupdate\fR
معتبر است\&. این دستورات گاهی اوقات نیاز به کلون کردن یک مخزن ریموت دارند\&. در این حالت، این گزینه به دستور
\fBgit-clone\fR(1)
ارسال خواهد شد\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBیادداشت (Note)\fR
.ps -1
.br
از این گزینه استفاده
\fBنکنید\fR
مگر اینکه یادداشت مربوط به گزینه‌های
\fB\-\-reference\fR،
\fB\-\-shared\fR
و
\fB\-\-dissociate\fR
در
\fBgit-clone\fR(1)
را با دقت مطالعه کرده باشید\&.
.sp .5v
.RE
.RE
.PP
\fB\-\-dissociate\fR
.RS 4
پس از استفاده از یک مخزن مرجع برای کلون کردن، دیگر به آن وابسته نباشد\&. این گزینه فقط برای دستورات
\fBadd\fR
و
\fBupdate\fR
معتبر است\&. این دستورات گاهی اوقات نیاز به کلون کردن یک مخزن ریموت دارند\&. در این حالت، این گزینه به دستور
\fBgit-clone\fR(1)
ارسال خواهد شد\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBیادداشت (Note)\fR
.ps -1
.br
یادداشت بالا برای گزینه
\fB\-\-reference\fR
را ببینید\&.
.sp .5v
.RE
.RE
.PP
\fB\-\-recursive\fR
.RS 4
پیمایش بازگشتی در زیرماژول‌ها\&. این گزینه فقط برای دستورات
\fBforeach\fR،
\fBupdate\fR،
\fBstatus\fR
و
\fBsync\fR
معتبر است\&. عملیات نه تنها در زیرماژول‌های مخزن فعلی، بلکه در هر زیرماژول تو در تو در داخل آن زیرماژول‌ها (و به همین ترتیب) انجام می‌شود\&.
.RE
.PP
\fB\-\-depth=\fR\fI<depth>\fR
.RS 4
یک کلون
\fIکم‌عمق\fR
(shallow) با تاریخچه‌ای کوتاه‌شده به
\fI<depth>\fR
بازبینی ایجاد می‌کند\&. این گزینه برای دستورات
\fBadd\fR
و
\fBupdate\fR
معتبر است\&. به
\fBgit-clone\fR(1)
مراجعه کنید\&.
.RE
.PP
\fB\-\-recommend\-shallow\fR, \fB\-\-no\-recommend\-shallow\fR
.RS 4
کلون کم‌عمق زیرماژول‌ها را توصیه می‌کند یا نمی‌کند\&. این گزینه فقط برای دستور
\fBupdate\fR
معتبر است\&. کلون اولیه زیرماژول به طور پیش‌فرض از تنظیم پیشنهادی
\fBsubmodule\&.\fR\fI<name>\fR\fB\&.shallow\fR
ارائه‌شده توسط فایل
\fB\&.gitmodules\fR
استفاده می‌کند\&. برای نادیده گرفتن این پیشنهادها از
\fB\-\-no\-recommend\-shallow\fR
استفاده کنید\&.
.RE
.PP
\fB\-j\fR\fI<n>\fR, \fB\-\-jobs=\fR\fI<n>\fR
.RS 4
کلون کردن زیرماژول‌های جدید به صورت موازی با
\fI<n>\fR
پردازش همزمان\&. این گزینه فقط برای دستور
\fBupdate\fR
معتبر است\&. مقدار پیش‌فرض آن از گزینه
\fBsubmodule\&.fetchJobs\fR
گرفته می‌شود\&.
.RE
.PP
\fB\-\-single\-branch\fR, \fB\-\-no\-single\-branch\fR
.RS 4
در حین به‌روزرسانی تنها یک شاخه کلون شود:
\fBHEAD\fR
یا شاخه‌ای که توسط
\fB\-\-branch\fR
مشخص شده است\&. این گزینه فقط برای دستور
\fBupdate\fR
معتبر است\&.
.RE
.PP
\fI<path>\fR\&.\&.\&.
.RS 4
مسیر(های) زیرماژول‌ها\&. در صورت تعیین، این آرگومان اجرای دستور را تنها به زیرماژول‌های موجود در مسیرهای مشخص‌شده محدود می‌کند\&. (این آرگومان برای
\fBadd\fR
الزامی است)\&.
.RE
.SH "فایل‌ها (FILES)"
.sp
هنگام مقداردهی اولیه زیرماژول‌ها، از یک فایل \fB\&.gitmodules\fR در دایرکتوری سطح بالای مخزن حاوی آن برای یافتن URL هر زیرماژول استفاده می‌شود\&. ساختار این فایل باید مشابه با \fB$GIT_DIR/config\fR باشد\&. کلید مربوط به URL هر زیرماژول عبارت است از \fBsubmodule\&.\fR\fI<name>\fR\fB\&.url\fR\&. برای جزئیات به \fBgitmodules\fR(5) مراجعه کنید\&.
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBgitsubmodules\fR(7), \fBgitmodules\fR(5)\&.
.SH "گیت (GIT)"
.sp
بخشی از مجموعه \fBgit\fR(1)