'\" t
.\"     Title: gitmodules
.\"    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: English
.\"
.TH "GITMODULES" "5" "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)"
gitmodules \- تعریف ویژگی‌های زیرپروژه‌ها (submodules) در گیت
.SH "خلاصه دستور (SYNOPSIS)"
.sp
$GIT_WORK_TREE/\&.gitmodules
.SH "توضیحات (DESCRIPTION)"
.sp
فایل \fB\&.gitmodules\fR، واقع در بالاترین سطح دایرکتوری درخت کاری گیت، یک فایل متنی با ساختار نحوی منطبق بر الزامات \fBgit-config\fR(1) است\&.
.sp
این فایل شامل یک زیربخش به ازای هر زیرپروژه (submodule) است و مقدار این زیربخش، نام آن زیرپروژه است\&. این نام به صورت پیش‌فرض همان مسیری است که زیرپروژه در آن اضافه شده است، مگر آنکه با گزینه \fB\-\-name\fR در دستور \fIgit submodule add\fR سفارشی‌سازی شده باشد\&. هر بخش زیرپروژه شامل کلیدهای اجباری زیر نیز هست:
.PP
submodule\&.<name>\&.path
.RS 4
مسیری را مشخص می‌کند (نسبت به دایرکتوری ریشه درخت کاری گیت) که انتظار می‌رود زیرپروژه در آن استخراج (checkout) شود\&. نام مسیر نباید به
\fB/\fR
ختم شود\&. تمام مسیرهای زیرپروژه در فایل
\fB\&.gitmodules\fR
باید یکتا باشند\&.
.RE
.PP
submodule\&.<name>\&.url
.RS 4
نشانی اینترنتی (URL) را که مخزن زیرپروژه می‌تواند از آن کلون شود مشخص می‌کند\&. این می‌تواند یک نشانی کامل و آماده برای ارسال به
\fBgit-clone\fR(1)
باشد یا (اگر با
\fB\&./\fR
یا
\fB\&.\&.\fR\fB/\fR
آغاز شود) مکانی نسبی نسبت به مخزن مبدا (origin) پروژه اصلی باشد\&.
.RE
.sp
علاوه بر این، تعدادی کلید اختیاری نیز وجود دارد:
.PP
submodule\&.<name>\&.update
.RS 4
روال پیش‌فرض به‌روزرسانی زیرپروژه مشخص‌شده را تعیین می‌کند؛ یعنی نحوه به‌روزرسانی زیرپروژه توسط دستور
\fBgit\fR
\fBsubmodule\fR
\fBupdate\fR
در پروژه اصلی\&. این مقدار فقط توسط دستور
\fBgit\fR
\fBsubmodule\fR
\fBinit\fR
برای مقداردهی اولیه متغیر پیکربندی هم‌نام استفاده می‌شود\&. مقادیر مجاز در اینجا عبارتند از:
\fIcheckout\fR،
\fIrebase\fR،
\fImerge\fR
یا
\fInone\fR، اما نه
\fI!command\fR
(به دلایل امنیتی)\&. برای جزئیات بیشتر به توضیحات دستور
\fIupdate\fR
در
\fBgit-submodule\fR(1)
مراجعه کنید\&.
.RE
.PP
submodule\&.<name>\&.branch
.RS 4
نام یک شاخه راه دور برای ردیابی به‌روزرسانی‌ها در زیرپروژه بالادست\&. اگر این گزینه مشخص نشود، به صورت پیش‌فرض به
\fBHEAD\fR
شاخه راه دور ارجاع داده می‌شود\&. مقدار ویژه \&. نشان می‌دهد که نام شاخه در زیرپروژه باید با نام شاخه جاری در مخزن فعلی یکسان باشد\&. برای جزئیات به مستندات
\fB\-\-remote\fR
در
\fBgit-submodule\fR(1)
مراجعه کنید\&.
.RE
.PP
submodule\&.<name>\&.fetchRecurseSubmodules
.RS 4
این گزینه می‌تواند برای کنترل دریافت بازگشتی (recursive fetching) این زیرپروژه استفاده شود\&. اگر این گزینه در مدخل زیرپروژه در فایل
\fB\&.git/config\fR
پروژه اصلی نیز وجود داشته باشد، تنظیمات موجود در آنجا بر تنظیمات یافت‌شده در
\fB\&.gitmodules\fR
اولویت خواهد داشت\&. هر دو تنظیم را می‌توان در خط فرمان با استفاده از گزینه
\fB\-\-\fR[\fBno\-\fR]\fBrecurse\-submodules\fR
در دستورهای
\fBgit\fR
\fBfetch\fR
و
\fBgit\fR
\fBpull\fR
بازنویسی کرد\&.
.RE
.PP
submodule\&.<name>\&.ignore
.RS 4
تعیین می‌کند که تحت چه شرایطی دستور
\fBgit\fR
\fBstatus\fR
و خانواده دستورهای diff زیرپروژه را به عنوان تغییریافته (modified) نشان دهند\&. مقادیر زیر پشتیبانی می‌شوند:
.PP
all
.RS 4
زیرپروژه هرگز تغییریافته در نظر گرفته نخواهد شد (اما در صورتی که مرحله‌بندی شده باشد، در خروجی status و commit ظاهر می‌شود)\&. افزودن یک زیرپروژه با (\fBnew\fR
\fBcommits\fR) را می‌توان با دستور
\fBgit\fR
\fBadd\fR
\fB\-\-force\fR
\fI<submodule\&.path>\fR
بازنویسی کرد\&. این تنظیم بر دستورهای
\fBstatus\fR،
\fBupdate\-index\fR،
\fBdiff\fR
و
\fBlog\fR
(به دلیل استفاده از
\fBdiff\fR
درونی) تاثیر می‌گذارد\&.
.RE
.PP
dirty
.RS 4
تمام تغییرات اعمال‌شده در درخت کاری زیرپروژه نادیده گرفته می‌شوند؛ فقط تفاوت‌های کامیت‌شده بین
\fBHEAD\fR
زیرپروژه و وضعیت ثبت‌شده آن در پروژه اصلی در نظر گرفته می‌شوند\&.
.RE
.PP
untracked
.RS 4
فقط فایل‌های ردیابی‌نشده در زیرپروژه‌ها نادیده گرفته می‌شوند\&. تفاوت‌های کامیت‌شده و تغییرات فایل‌های ردیابی‌شده نمایش داده خواهند شد\&.
.RE
.PP
none
.RS 4
هیچ تغییری در زیرپروژه‌ها نادیده گرفته نمی‌شود؛ تمام تفاوت‌های کامیت‌شده و تغییرات فایل‌های ردیابی‌شده و ردیابی‌نشده نشان داده می‌شوند\&. این گزینه پیش‌فرض است\&.
.RE
.sp
اگر این گزینه در مدخل زیرپروژه در فایل
\fB\&.git/config\fR
پروژه اصلی نیز وجود داشته باشد، مقدار آنجا بر تنظیم موجود در
\fB\&.gitmodules\fR
اولویت خواهد داشت\&.
.sp
هر دو تنظیم را می‌توان در خط فرمان با استفاده از گزینه
\fB\-\-ignore\-submodules\fR
بازنویسی کرد\&. دستورهای
\fBgit\fR
\fBsubmodule\fR
تحت تاثیر این تنظیم قرار نمی‌گیرند\&.
.RE
.PP
submodule\&.<name>\&.shallow
.RS 4
هنگامی که روی true تنظیم شود، کلون این زیرپروژه به صورت یک کلون کم‌عمق (با عمق تاریخچه ۱) انجام می‌شود مگر اینکه کاربر صراحتاً درخواست کلون غیرکم‌عمق داشته باشد\&.
.RE
.SH "نکات (NOTES)"
.sp
گیت اجازه نمی‌دهد فایل \fB\&.gitmodules\fR درون یک درخت کاری یک پیوند نمادین (symbolic link) باشد و از استخراج (checkout) چنین مدخلی در درخت خودداری می‌کند\&. این امر رفتار سیستم را هنگام دسترسی به فایل از ایندکس یا درخت در مقایسه با فایل‌سیستم یکدست نگه می‌دارد و به گیت کمک می‌کند تا بررسی‌های امنیتی محتوای فایل را به طور قابل‌اعتماد اعمال کند\&.
.SH "مثال‌ها (EXAMPLES)"
.sp
فایل \fB\&.gitmodules\fR زیر را در نظر بگیرید:
.sp
.if n \{\
.RS 4
.\}
.nf
[submodule "libfoo"]
        path = include/foo
        url = git://foo\&.com/git/lib\&.git

[submodule "libbar"]
        path = include/bar
        url = git://bar\&.com/git/lib\&.git
.fi
.if n \{\
.RE
.\}
.sp
.sp
این پیکربندی دو زیرپروژه با نام‌های \fBlibfoo\fR و \fBlibbar\fR را تعریف می‌کند\&. انتظار می‌رود این زیرپروژه‌ها در مسیرهای \fBinclude/foo\fR و \fBinclude/bar\fR استخراج شوند، و برای هر دو زیرپروژه یک نشانی (URL) مشخص شده است که می‌تواند برای کلون کردن زیرپروژه‌ها استفاده شود\&.
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBgit-submodule\fR(1), \fBgitsubmodules\fR(7), \fBgit-config\fR(1)
.SH "گیت (GIT)"
.sp
بخشی از مجموعه \fBgit\fR(1)