'\" t
.\"     Title: git-sparse-checkout
.\"    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: دستورات عمومی کاربر
.\"    Source: Git 2.55.0
.\"  Language: Persian
.\"
.TH "GIT\-SPARSE\-CHECKOUT" "1" "2026\-06\-29" "Git 2\&.55\&.0" "دستورات عمومی کاربر"
.\" -----------------------------------------------------------------
.\" * 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-sparse-checkout \- کاهش درخت کاری به زیرمجموعه‌ای از فایل‌های ردیابی‌شده
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
\fIgit sparse\-checkout\fR (init | list | set | add | reapply | disable | check\-rules | clean) [<options>]
.fi
.sp
.SH "توضیحات (DESCRIPTION)"
.sp
این دستور برای ایجاد چک‌اوت‌های تنک (sparse checkouts) استفاده می‌شود، که درخت کاری را از داشتن تمامی فایل‌های ردیابی‌شده به داشتن تنها زیرمجموعه‌ای از آن فایل‌ها تغییر می‌دهد\&. همچنین می‌تواند زیرمجموعه فایل‌های حاضر را تعویض کند، یا تغییرات را برگردانده و دوباره تمام فایل‌های ردیابی‌شده را در نسخه کاری حاضر سازد\&.
.sp
زیرمجموعه فایل‌ها با ارائه فهرستی از دایرکتوری‌ها در حالت مخروطی (cone mode، حالت پیش‌فرض)، یا با ارائه فهرستی از الگوها در حالت غیرمخروطی (non\-cone mode) انتخاب می‌شود\&.
.sp
هنگامی که در حالت چک‌اوت تنک هستید، سایر دستورات گیت کمی متفاوت رفتار می‌کنند\&. برای نمونه، تغییر شاخه باعث به‌روزرسانی مسیرهای خارج از دایرکتوری‌ها/الگوهای چک‌اوت تنک نمی‌شود، و دستور \fBgit\fR \fBcommit\fR \fB\-a\fR مسیرهای خارج از دایرکتوری‌ها/الگوهای چک‌اوت تنک را به عنوان حذف‌شده ثبت نخواهد کرد\&.
.sp
این دستور آزمایشی است\&. رفتار آن و رفتار سایر دستورات در حضور چک‌اوت‌های تنک، به احتمال زیاد در آینده تغییر خواهد کرد\&.
.SH "دستورات (COMMANDS)"
.PP
\fIlist\fR
.RS 4
توصیف دایرکتوری‌ها یا الگوهای موجود در فایل sparse\-checkout\&.
.RE
.PP
\fIset\fR
.RS 4
تنظیمات پیکربندی لازم برای چک‌اوت تنک (شامل
\fBcore\&.sparseCheckout\fR،
\fBcore\&.sparseCheckoutCone\fR
و
\fBindex\&.sparse\fR)
را در صورتی که پیش‌تر روی مقادیر مورد نظر تنظیم نشده باشند فعال می‌کند، فایل sparse\-checkout را از فهرست آرگومان‌های پس از زیردستور
\fIset\fR
پر می‌کند، و دایرکتوری کاری را برای مطابقت با آن به‌روزرسانی می‌نماید\&.
.sp
برای اطمینان از اینکه تنظیم گزینه‌های چک‌اوت تنک در یک درخت کاری (worktree) تنظیمات چک‌اوت تنک را در سایر درخت‌های کاری دگرگون نسازد، زیردستور
\fIset\fR
پیکربندی مخزن شما را به استفاده از پیکربندی مختص هر درخت کاری ارتقا می‌دهد، مگر اینکه از قبل فعال باشد\&. تُنکی (sparsity) تعریف‌شده با آرگومان‌های زیردستور
\fIset\fR
در فایل sparse\-checkout مختص همان درخت کاری ذخیره می‌شود\&. برای جزئیات بیشتر به
\fBgit-worktree\fR(1)
و مستندات
\fBextensions\&.worktreeConfig\fR
در
\fBgit-config\fR(1)
مراجعه کنید\&.
.sp
هنگامی که گزینه
\fB\-\-stdin\fR
ارائه شود، دایرکتوری‌ها یا الگوها به جای آرگومان‌ها، از ورودی استاندارد به صورت فهرستی که با خط جدید از هم جدا شده‌اند خوانده می‌شوند\&.
.sp
به‌طور پیش‌فرض، فهرست ورودی به عنوان فهرستی از دایرکتوری‌ها در نظر گرفته می‌شود، مطابق با خروجی
\fBgit\fR
\fBls\-tree\fR
\fB\-d\fR
\fB\-\-name\-only\fR\&.
این شامل تفسیر نام مسیرهایی است که با علامت نقل‌قول دوگانه (\") آغاز می‌شوند به عنوان رشته‌های نقل‌قول‌شده به سبک C\&. توجه داشته باشید که تمامی فایل‌های زیر دایرکتوری‌های مشخص‌شده (در هر عمقی)، و همچنین فایل‌هایی که هم‌سطح (هم‌نیای) دایرکتوری داده‌شده یا هر یک از نیاکان آن هستند در چک‌اوت تنک گنجانده خواهند شد (برای جزئیات بیشتر به
\fIمجموعه الگوهای مخروطی (CONE PATTERN SET)\fR
در ادامه مراجعه کنید)\&. در گذشته، این رفتار پیش‌فرض نبود و نیاز بود گزینه
\fB\-\-cone\fR
مشخص شود یا
\fBcore\&.sparseCheckoutCone\fR
فعال گردد\&.
.sp
هنگامی که
\fB\-\-no\-cone\fR
داده شود، فهرست ورودی به عنوان فهرستی از الگوها در نظر گرفته می‌شود\&. این حالت دارای چندین نقطه‌ضعف است، از جمله عدم کارکرد با برخی گزینه‌ها مانند
\fB\-\-sparse\-index\fR\&.
همان‌طور که در بخش «مشکلات حالت غیرمخروطی» در ادامه توضیح داده شده است، استفاده از آن را توصیه نمی‌کنیم\&.
.sp
از گزینه
\fB\-\-\fR[\fBno\-\fR]\fBsparse\-index\fR
برای استفاده از یک ایندکس تنک استفاده کنید (حالت پیش‌فرض عدم استفاده از آن است)\&. یک ایندکس تنک، اندازه ایندکس را کاهش می‌دهد تا با تعریف چک‌اوت تنک شما هماهنگ‌تر باشد\&. این امر می‌تواند مزایای عملکردی چشمگیری برای دستوراتی نظیر
\fBgit\fR
\fBstatus\fR
یا
\fBgit\fR
\fBadd\fR
داشته باشد\&. این ویژگی هنوز آزمایشی است\&. برخی از دستورات ممکن است تا زمانی که به طور مناسب با این ویژگی یکپارچه شوند، با ایندکس تنک کندتر کار کنند\&.
.sp
\fBهشدار:\fR
استفاده از ایندکس تنک مستلزم اصلاح ایندکس به گونه‌ای است که توسط ابزارهای خارجی کاملاً درک نمی‌شود\&. اگر با سازگاری مشکلی دارید، دستور
\fBgit\fR
\fBsparse\-checkout\fR
\fBinit\fR
\fB\-\-no\-sparse\-index\fR
را اجرا کنید تا ایندکس شما بازنویسی شده و غیرتنک شود\&. نگارش‌های قدیمی‌تر گیت افزونه ایندکس مدخل‌های دایرکتوری تنک را درک نمی‌کنند و ممکن است تا زمان غیرفعال شدن آن نتوانند با مخزن شما تعامل داشته باشند\&.
.RE
.PP
\fIadd\fR
.RS 4
به‌روزرسانی فایل sparse\-checkout برای افزودن دایرکتوری‌های بیشتر (در حالت مخروطی) یا الگوها (در حالت غیرمخروطی)\&. به‌طور پیش‌فرض، این دایرکتوری‌ها یا الگوها از آرگومان‌های خط فرمان خوانده می‌شوند، اما با استفاده از گزینه
\fB\-\-stdin\fR
می‌توان آن‌ها را از ورودی استاندارد خواند\&.
.RE
.PP
\fIreapply\fR
.RS 4
اعمال دوباره قواعد الگوی تنکی روی مسیرهای درخت کاری\&. دستوراتی مانند merge یا rebase می‌توانند برای انجام کار خود مسیرها را پدیدار کنند (برای مثال جهت نشان دادن یک تعارض به شما)، و سایر دستورات sparse\-checkout ممکن است در تنک‌سازی یک فایل منفرد شکست بخورند (مثلاً به دلیل داشتن تغییرات استیج‌نشده یا تعارض‌ها)\&. در چنین مواردی، منطقی است که بعداً پس از پاکسازی مسیرهای متأثر (مانند حل تعارض‌ها، بازگرداندن یا کامیت تغییرات و غیره)، دستور
\fBgit\fR
\fBsparse\-checkout\fR
\fBreapply\fR
را اجرا کنید\&.
.sp
دستور
\fBreapply\fR
همچنین می‌تواند فلگ‌های
\fB\-\-\fR[\fBno\-\fR]\fBcone\fR
و
\fB\-\-\fR[\fBno\-\fR]\fBsparse\-index\fR
را بپذیرد، با همان مفهومی که در دستور
\fBset\fR
دارند، تا بدون نیاز به مشخص کردن مجدد تمام مسیرهای تنکی، حالت تنکی مورد استفاده را تغییر دهد\&.
.RE
.PP
\fIclean\fR
.RS 4
حذف مقتضی و فرصت‌طلبانه فایل‌های خارج از تعریف sparse\-checkout\&. این دستور برای تعیین فایل‌هایی که باید حذف شوند به حالت مخروطی نیاز دارد تا از تطابق بازگشتی دایرکتوری‌ها استفاده کند\&. فایلی واجد شرایط حذف در نظر گرفته می‌شود که درون دایرکتوری ردیابی‌شده‌ای قرار داشته باشد که خارج از تعریف sparse\-checkout است\&.
.sp
برخی شرایط ویژه، مانند تعارض‌های ادغام (merge conflicts) یا فایل‌های تغییریافته خارج از تعریف sparse\-checkout، می‌توانند منجر به نگه‌داشتن فایل‌هایی شوند که در غیر این صورت حذف می‌شدند\&. تعارض‌ها را حل کنید، تغییرات را استیج کنید و از دستور
\fBgit\fR
\fBsparse\-checkout\fR
\fBreapply\fR
همراه با
\fBgit\fR
\fBsparse\-checkout\fR
\fBclean\fR
برای حل این موارد استفاده کنید\&.
.sp
از این دستور می‌توان برای اطمینان از کارکرد کارآمد ایندکس تنک استفاده کرد، هرچند که نیازی به فعال‌سازی ویژگی ایندکس تنک از طریق پیکربندی
\fBindex\&.sparse=true\fR
ندارد\&.
.sp
برای جلوگیری از حذف تصادفی فایل‌های درخت کاری، زیردستور
\fBclean\fR
هیچ فایلی را بدون گزینه
\fB\-f\fR
یا
\fB\-\-force\fR
حذف نخواهد کرد، مگر اینکه گزینه پیکربندی
\fBclean\&.requireForce\fR
روی
\fBfalse\fR
تنظیم شده باشد\&.
.sp
گزینه
\fB\-\-dry\-run\fR
دایرکتوری‌هایی را که بدون حذف واقعی پاک خواهند شد فهرست می‌کند\&. اجرا در این حالت می‌تواند برای پیش‌بینی رفتار دستور clean یا تعیین اینکه چه نوع فایل‌هایی در دایرکتوری‌های تنک باقی مانده‌اند مفید باشد\&.
.sp
گزینه
\fB\-\-verbose\fR
تک‌تک فایل‌های درون دایرکتوری‌های در نظر گرفته‌شده برای حذف را فهرست می‌کند\&. این گزینه برای تشخیص اینکه آیا آن فایل‌ها واقعاً مهم هستند یا شاید برای توضیح اینکه چرا دایرکتوری با وجود sparse\-checkout جاری همچنان حضور دارد مفید است\&.
.RE
.PP
\fIdisable\fR
.RS 4
تنظیم پیکربندی
\fBcore\&.sparseCheckout\fR
را غیرفعال کرده و دایرکتوری کاری را برای در بر گرفتن تمامی فایل‌ها بازیابی می‌کند\&.
.RE
.PP
\fIinit\fR
.RS 4
دستوری منسوخ‌شده که رفتاری مانند
\fBset\fR
بدون هیچ مسیر مشخص‌شده دارد\&. ممکن است در آینده حذف شود\&.
.sp
از نظر تاریخی، دستور
\fBset\fR
همه تنظیمات پیکربندی لازم را انجام نمی‌داد، به این معنی که هر دو دستور
\fBinit\fR
و
\fBset\fR
باید فراخوانی می‌شدند\&. فراخوانی هر دو به این معنی بود که گام
\fBinit\fR
ابتدا تقریباً تمام فایل‌های ردیابی‌شده (و در حالت مخروطی، فایل‌های نادیده‌گرفته‌شده را نیز) حذف می‌کرد، سپس گام
\fBset\fR
بسیاری از فایل‌های ردیابی‌شده (اما نه فایل‌های نادیده‌گرفته‌شده) را بازمی‌گرداند\&. افزون بر فایل‌های از دست رفته، کارایی و رابط کاربری این ترکیب ضعیف بود\&.
.sp
همچنین از نظر تاریخی،
\fBinit\fR
اگر فایل sparse\-checkout از قبل وجود داشت، در واقع آن را مقداردهی اولیه نمی‌کرد\&. این بدان معنا بود که بازگشت به یک چک‌اوت تنک بدون به‌خاطر سپردن مسیرهایی که باید به دستور بعدی
\fIset\fR
یا
\fIadd\fR
داده شوند امکان‌پذیر بود\&. با این حال، گزینه‌های
\fB\-\-cone\fR
و
\fB\-\-sparse\-index\fR
پس از دستور disable به خاطر سپرده نمی‌شدند، بنابراین کاربرد بازیابی آسان با فراخوانی یک
\fBinit\fR
ساده کاهش یافت\&.
.RE
.PP
\fIcheck\-rules\fR
.RS 4
بررسی اینکه آیا قواعد تنکی با یک یا چند مسیر مطابقت دارند یا خیر\&.
.sp
به‌طور پیش‌فرض،
\fBcheck\-rules\fR
فهرستی از مسیرها را از ورودی استاندارد می‌خواند و تنها آن‌هایی را که با قواعد تنکی جاری مطابقت دارند خروجی می‌دهد\&. انتظار می‌رود ورودی شامل یک مسیر در هر سطر باشد، مطابق با خروجی
\fBgit\fR
\fBls\-tree\fR
\fB\-\-name\-only\fR،
شامل اینکه نام مسیرهایی که با نقل‌قول دوگانه (\") آغاز می‌شوند به عنوان رشته‌های نقل‌قول‌شده به سبک C تفسیر شوند\&.
.sp
هنگامی که با فلگ
\fB\-\-rules\-file\fR
\fI<file>\fR
فراخوانی شود، فایل‌های ورودی با قواعد چک‌اوت تنک موجود در
\fI<file>\fR
به جای قواعد جاری مقایسه و تطبیق داده می‌شوند\&. انتظار می‌رود قواعد موجود در فایل‌ها به همان شکلی باشند که توسط
\fBgit\fR
\fBsparse\-checkout\fR
\fBset\fR
\fB\-\-stdin\fR
پذیرفته می‌شوند (به ویژه اینکه باید با خط جدید از یکدیگر جدا شده باشند)\&.
.sp
به‌طور پیش‌فرض، قواعد ارائه‌شده به گزینه
\fB\-\-rules\-file\fR
به عنوان دایرکتوری‌های حالت مخروطی تفسیر می‌شوند\&. برای ارسال الگوهای حالت غیرمخروطی با
\fB\-\-rules\-file\fR،
این گزینه را با گزینه
\fB\-\-no\-cone\fR
ترکیب کنید\&.
.sp
هنگامی که با فلگ
\fB\-z\fR
فراخوانی شود، قالب مسیرهای ورودی در ورودی استاندارد و همچنین مسیرهای خروجی با \e0 خاتمه یافته و نقل‌قول نمی‌شوند\&. توجه داشته باشید که این موضوع شامل قالب قواعد ارائه‌شده با گزینه
\fB\-\-rules\-file\fR
نمی‌شود\&.
.RE
.SH "مثال‌ها (EXAMPLES)"
.PP
\fBgit\fR \fBsparse\-checkout\fR \fBset\fR \fBMY/DIR1\fR \fBSUB/DIR2\fR
.RS 4
تغییر به یک چک‌اوت تنک که در آن تمامی فایل‌ها (در هر عمقی) زیر MY/DIR1/ و SUB/DIR2/ در نسخه کاری حضور دارند (به علاوه تمامی فایل‌های بلافاصله زیر MY/ و SUB/ و دایرکتوری سطح بالا)\&. اگر هم‌اکنون در یک چک‌اوت تنک هستید، فایل‌های حاضر در نسخه کاری را به این انتخاب جدید تغییر می‌دهد\&. توجه داشته باشید که این دستور همچنین تمام فایل‌های نادیده‌گرفته‌شده را در هر دایرکتوری که دیگر هیچ فایل ردیابی‌شده یا فایل ردیابی‌نشده‌ی نادیده‌نگرفته‌شده‌ای در آن حضور ندارد، حذف خواهد کرد\&.
.RE
.PP
\fBgit\fR \fBsparse\-checkout\fR \fBdisable\fR
.RS 4
پر کردن مجدد دایرکتوری کاری با تمام فایل‌ها و غیرفعال کردن چک‌اوت‌های تنک\&.
.RE
.PP
\fBgit\fR \fBsparse\-checkout\fR \fBadd\fR \fBSOME/DIR/ECTORY\fR
.RS 4
افزودن تمامی فایل‌های زیر SOME/DIR/ECTORY/ (در هر عمقی) به چک‌اوت تنک، و همچنین تمامی فایل‌های بلافاصله زیر SOME/DIR/ و بلافاصله زیر SOME/\&. پیش از استفاده از این دستور باید از قبل در یک چک‌اوت تنک باشید\&.
.RE
.PP
\fBgit\fR \fBsparse\-checkout\fR \fBreapply\fR
.RS 4
این امکان وجود دارد که دستورات درخت کاری را به گونه‌ای به‌روزرسانی کنند که دایرکتوری‌های تنکی انتخاب‌شده رعایت نشوند\&. این حالت می‌تواند ناشی از ابزارهای خارج از گیت باشد که فایل می‌نویسند، یا حتی دستورات گیت را تحت تأثیر قرار دهد؛ چه به دلیل حالت‌های خاص (مانند برخورد با تعارض‌ها هنگام ادغام/rebase)، یا به این دلیل که برخی دستورات به طور کامل از چک‌اوت‌های تنک پشتیبانی نمی‌کردند (برای نمونه، بک‌اند قدیمی ادغام
\fBrecursive\fR
تنها پشتیبانی محدودی داشت)\&. این دستور مشخصات دایرکتوری تنک موجود را مجدداً اعمال می‌کند تا دایرکتوری کاری با آن همخوان شود\&.
.RE
.SH "سازوکار داخلی \(em چک‌اوت تنک (INTERNALS \(em SPARSE CHECKOUT)"
.sp
«چک‌اوت تنک» (Sparse checkout) امکان پر کردن تنک و پراکنده دایرکتوری کاری را فراهم می‌آورد\&. این قابلیت از بیت skip\-worktree (نگاه کنید به \fBgit-update-index\fR(1)) استفاده می‌کند تا به گیت اعلام کند که آیا فایلی در دایرکتوری کاری ارزش بررسی دارد یا خیر\&. اگر بیت skip\-worktree تنظیم شده باشد و فایل در درخت کاری حضور نداشته باشد، عدم حضور آن نادیده گرفته می‌شود\&. گیت از پر کردن محتوای آن فایل‌ها خودداری می‌کند، که این امر چک‌اوت تنک را هنگام کار در مخزنی با فایل‌های فراوان که تنها تعداد اندکی از آن‌ها برای کاربر جاری اهمیت دارند، بسیار مفید می‌سازد\&.
.sp
فایل \fB$GIT_DIR/info/sparse\-checkout\fR برای تعریف نگاشت بیتی مرجع skip\-worktree استفاده می‌شود\&. هنگامی که گیت دایرکتوری کاری را به‌روزرسانی می‌کند، بیت‌های skip\-worktree را در ایندکس بر اساس این فایل به‌روز می‌نماید\&. فایل‌های منطبق بر الگوهای موجود در این فایل در دایرکتوری کاری پدیدار خواهند شد و مابقی پدیدار نمی‌شوند\&.
.SH "سازوکار داخلی \(em مشکلات حالت غیرمخروطی (INTERNALS \(em NON\-CONE PROBLEMS)"
.sp
فایل \fB$GIT_DIR/info/sparse\-checkout\fR که با زیردستورات \fBset\fR و \fBadd\fR پر می‌شود، به عنوان مجموعه‌ای از الگوها (یک الگو در هر خط) با استفاده از همان نحو فایل‌های \fB\&.gitignore\fR تعریف می‌شود\&. در حالت مخروطی، این الگوها محدود به تطابق دایرکتوری‌ها هستند (و کاربران تنها نیاز به ارائه یا مشاهده نام دایرکتوری‌ها دارند)، در حالی که در حالت غیرمخروطی هرگونه الگوی شبیه به gitignore مجاز است\&. استفاده از الگوهای کامل شبیه به gitignore در حالت غیرمخروطی چندین نقص به همراه دارد:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اساساً، این امر باعث می‌شود که فرآیندهای گوناگون به‌روزرسانی درخت کاری (pull، merge، rebase، switch، reset، checkout و غیره) به تطابق الگوی O(N*M) نیاز داشته باشند، که در آن N تعداد الگوها و M تعداد مسیرهای موجود در ایندکس است\&. این وضعیت مقیاس‌پذیری بسیار ضعیفی دارد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اجتناب از مشکل مقیاس‌پذیری باید از طریق محدود کردن تعداد الگوها به وسیله مشخص کردن نام دایرکتوری آغازین یا glob انجام شود\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
ارسال الگوهای گلوب (globs) در خط فرمان مستعد خطا است زیرا کاربران ممکن است نقل‌قول کردن (کوتیشن) گلوب را فراموش کنند، که باعث می‌شود شل آن را به تمام فایل‌های منطبق بسط دهد و همه آن‌ها را به صورت تک‌تک به sparse\-checkout set/add بفرستد\&. اگرچه این موضوع می‌تواند مثلاً در "git grep \(em *\&.c" نیز یک مشکل باشد، اما اشتباهات در grep/log/status بلافاصله در خروجی نمایان می‌شوند\&. در sparse\-checkout، این اشتباه در همان زمان اجرای دستور sparse\-checkout ثبت می‌شود و ممکن است تا زمانی که کاربر بعداً شاخه‌ها را عوض کند یا rebase یا merge انجام دهد مشکلی ایجاد نکند، بنابراین فاصله‌ای زمانی میان خطای کاربر و زمانی که فرصت متوجه شدن آن را دارد ایجاد می‌شود\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
مرتبط با مورد پیشین، دستور sparse\-checkout دارای زیردستور
\fIadd\fR
است اما فاقد زیردستور
\fIremove\fR
می‌باشد\&. حتی اگر زیردستور
\fIremove\fR
اضافه می‌شد، لغو یک گلوب بدون کوتیشن تصادفی با خطر «حذف بیش از حد» مواجه می‌شد، چرا که ممکن بود مدخل‌هایی را حذف کند که پیش از افزودن تصادفی نیز وجود داشته‌اند\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
حالت غیرمخروطی از الگوهای به سبک gitignore برای انتخاب موارد جهت
\fBگنجاندن (include)\fR
استفاده می‌کند (به استثنای الگوهای منفی)، در حالی که فایل‌های \&.gitignore از الگوهای به سبک gitignore برای انتخاب موارد جهت
\fBمستثنی کردن (exclude)\fR
استفاده می‌نمایند (به استثنای الگوهای منفی)\&. مستندات مربوط به الگوهای سبک gitignore معمولاً بر حسب تطابق داشتن یا نداشتن صحبت نمی‌کنند، بلکه بر این اساس است که کاربر چه چیزی را می‌خواهد «مستثنی» کند\&. این موضوع می‌تواند برای کاربرانی که تلاش می‌کنند چگونگی تعیین الگوهای sparse\-checkout را برای دستیابی به رفتار مورد نظرشان یاد بگیرند، سردرگمی ایجاد کند\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
تمام زیردستورهای دیگر گیت که می‌خواهند نوعی «تطابق الگوی مسیر خاص» ارائه دهند از pathspec استفاده می‌کنند، اما حالت غیرمخروطی برای sparse\-checkout از الگوهای gitignore استفاده می‌کند که ناسازگار به نظر می‌رسد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
دارای حالت‌های حدی است که رفتار «درست» در آن‌ها نامشخص است\&. دو مثال:
.sp
نخست، دو کاربر در یک زیردایرکتوری هستند و اولی اجرا می‌کند:
.sp
.if n \{\
.RS 4
.\}
.nf
git sparse\-checkout set \*(Aq/toplevel\-dir/*\&.c\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
در حالی که دومی اجرا می‌کند:
.sp
.if n \{\
.RS 4
.\}
.nf
git sparse\-checkout set relative\-dir
.fi
.if n \{\
.RE
.\}
.sp
آیا این آرگومان‌ها پیش از درج در فایل sparse\-checkout باید به صورت
.sp
.if n \{\
.RS 4
.\}
.nf
current/subdirectory/toplevel\-dir/*\&.c
.fi
.if n \{\
.RE
.\}
.sp
و
.sp
.if n \{\
.RS 4
.\}
.nf
current/subdirectory/relative\-dir
.fi
.if n \{\
.RE
.\}
.sp
تبدیل شوند؟ کاربری که دستور اول را تایپ کرده احتمالاً می‌داند که آرگومان‌های set/add در حالت غیرمخروطی باید الگو باشند و احتمالاً از چنین تبدیلی خرسند نخواهد شد\&. با این حال، بسیاری از الگوهای سبک gitignore صرفاً مسیر هستند، که ممکن است همان چیزی باشد که کاربر تایپ‌کننده دستور دوم در ذهن داشته است، و اگر آرگومان او تبدیل نمی‌شد ناراحت می‌شد\&.
.sp
دوم، تکمیل خودکار بش (bash\-completion) برای دستورات set/add کاربران غیرمخروطی چه چیزی را باید پیشنهاد دهد؟ اگر مسیرها را پیشنهاد دهد، آیا مشکل بالا را تشدید نمی‌کند؟ همچنین، اگر مسیرها را پیشنهاد دهد، چه می‌شود اگر کاربر فایل یا دایرکتوری داشته باشد که نام آن با
\fI!\fR
یا
\fI#\fR
آغاز شود یا شامل
\fI*\fR،
\fI\e\fR،
\fI?\fR،
\fI[\fR
یا
\fI]\fR
باشد؟ و اگر مسیرها را پیشنهاد دهد، آیا "/pro" را به "/proc" (در فایل‌سیستم ریشه) تکمیل می‌کند به جای اینکه به "/progress\&.txt" در دایرکتوری جاری تکمیل کند؟ (توجه داشته باشید که کاربران در حالت غیرمخروطی احتمالاً تمایل دارند مسیرها را با یک
\fI/\fR
آغازین شروع کنند، به همان دلیلی که فایل‌های \&.gitignore اغلب یکی دارند\&.) تکمیل بر روی فایل‌ها یا دایرکتوری‌ها ممکن است در تمام این حالت‌ها غافلگیری‌های ناخوشایندی ایجاد کند\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
انعطاف‌پذیری بیش از حد، سایر افزونه‌ها را عملاً غیرکاربردی کرده است\&.
\fB\-\-sparse\-index\fR
احتمالاً در حالت غیرمخروطی غیرممکن است؛ حتی اگر به نحوی شدنی باشد، پیاده‌سازی آن مستلزم کار بسیار بیشتری بوده و ممکن بود در عمل بیش از حد کند باشد\&. برخی ایده‌ها برای اتصال میان کلون‌های جزئی (partial clones) و چک‌اوت‌های تنک نیز تنها با مجموعه‌ای محدودتر از مسیرها عملی هستند\&.
.RE
.sp
به تمامی این دلایل، حالت غیرمخروطی منسوخ شده است\&. لطفاً به استفاده از حالت مخروطی روی آورید\&.
.SH "سازوکار داخلی \(em مدیریت حالت مخروطی (INTERNALS \(em CONE MODE HANDLING)"
.sp
«حالت مخروطی» (cone mode) که حالت پیش‌فرض است، به شما امکان می‌دهد تنها مشخص کنید چه دایرکتوری‌هایی گنجانده شوند\&. برای هر دایرکتوری مشخص‌شده، تمام مسیرهای زیر آن دایرکتوری گنجانده خواهند شد، و هر مسیری که بلافاصله زیر دایرکتوری‌های راهنما (از جمله دایرکتوری سطح بالا) قرار دارد نیز گنجانده می‌شود\&. بدین ترتیب، اگر دایرکتوری Documentation/technical/ را مشخص کرده باشید، چک‌اوت تنک شما شامل موارد زیر خواهد بود:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
تمامی فایل‌های موجود در دایرکتوری سطح بالا
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
تمامی فایل‌های بلافاصله زیر Documentation/
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
تمامی فایل‌ها در هر عمقی زیر Documentation/technical/
.RE
.sp
همچنین در حالت مخروطی، حتی اگر هیچ دایرکتوری مشخص نشده باشد، فایل‌های موجود در دایرکتوری سطح بالا گنجانده خواهند شد\&.
.sp
هنگام تغییر الگوهای sparse\-checkout در حالت مخروطی، گیت هر دایرکتوری ردیابی‌شده‌ای را که در مخروط sparse\-checkout قرار ندارد بررسی می‌کند تا ببیند آیا حاوی فایل‌های ردیابی‌نشده است یا خیر\&. اگر تمامی آن فایل‌ها به دلیل الگوهای \fB\&.gitignore\fR نادیده گرفته شده باشند، آنگاه دایرکتوری حذف خواهد شد\&. اگر هر یک از فایل‌های ردیابی‌نشده درون آن دایرکتوری نادیده گرفته نشده باشد، هیچ حذفی در آن دایرکتوری رخ نخواهد داد و یک پیام هشدار پدیدار می‌شود\&. اگر این فایل‌ها مهم هستند، تعریف sparse\-checkout خود را بازنشانی کنید تا آن‌ها گنجانده شوند، از \fBgit\fR \fBadd\fR و \fBgit\fR \fBcommit\fR برای ذخیره آن‌ها استفاده کنید، سپس هر فایل باقی‌مانده را به صورت دستی حذف کنید تا اطمینان حاصل شود گیت می‌تواند به شکل بهینه رفتار کند\&.
.sp
همچنین برای آگاهی از اینکه چگونه دایرکتوری‌ها در پس پرده به زیرمجموعه‌ای از «مجموعه الگوهای کامل» چک‌اوت تنک تبدیل می‌شوند، به بخش «سازوکار داخلی \(em مجموعه الگوهای مخروطی» مراجعه کنید\&.
.SH "سازوکار داخلی \(em مجموعه الگوهای کامل (INTERNALS \(em FULL PATTERN SET)"
.sp
مجموعه الگوهای کامل، امکان تطابق الگوهای دلخواه و قواعد پیچیده گنجاندن/مستثنی‌سازی را فراهم می‌آورد\&. این موارد هنگام به‌روزرسانی ایندکس می‌توانند منجر به تطابق‌های الگوی O(N*M) شوند، که در آن N تعداد الگوها و M تعداد مسیرهای موجود در ایندکس است\&. برای مقابله با این مشکل کارایی، زمانی که \fBcore\&.sparseCheckoutCone\fR فعال باشد، مجموعه الگوی محدودتری مجاز است\&.
.sp
فایل sparse\-checkout از همان نحو فایل‌های \fB\&.gitignore\fR استفاده می‌کند؛ برای جزئیات به \fBgitignore\fR(5) مراجعه کنید\&. با این حال در اینجا، الگوها معمولاً برای انتخاب فایل‌هایی که باید گنجانده شوند استفاده می‌شوند نه فایل‌هایی که باید مستثنی گردند\&. (البته این می‌تواند کمی گیج‌کننده باشد، زیرا الگوهای سبک gitignore دارای نفی‌هایی هستند که با الگوهایی با شروع \fI!\fR تعریف می‌شوند، بنابراین می‌توانید فایل‌هایی را نیز برای \fIنگنجاندن\fR انتخاب کنید)\&.
.sp
برای نمونه، جهت انتخاب همه‌چیز و سپس حذف فایل \fBunwanted\fR (به‌طوری که تمام فایل‌ها به جز فایلی با نام \fBunwanted\fR در درخت کاری شما حاضر شوند):
.sp
.if n \{\
.RS 4
.\}
.nf
git sparse\-checkout set \-\-no\-cone \*(Aq/*\*(Aq \*(Aq!unwanted\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
این الگوها عیناً در \fB$GIT_DIR/info/sparse\-checkout\fR قرار می‌گیرند، بنابراین محتوای آن فایل در این مرحله به صورت زیر خواهد بود:
.sp
.if n \{\
.RS 4
.\}
.nf
/*
!unwanted
.fi
.if n \{\
.RE
.\}
.sp
.sp
همچنین برای اطلاعات بیشتر درباره الگوهای سبک gitignore مورد استفاده در چک‌اوت‌های تنک، به بخش «Sparse Checkout» در \fBgit-read-tree\fR(1) مراجعه کنید\&.
.SH "سازوکار داخلی \(em مجموعه الگوهای مخروطی (INTERNALS \(em CONE PATTERN SET)"
.sp
در حالت مخروطی، تنها دایرکتوری‌ها پذیرفته می‌شوند، اما آن‌ها به همان الگوهای به سبک gitignore که در مجموعه الگوی کامل استفاده می‌شوند ترجمه می‌گردند\&. الگوهای خاص استفاده‌شده در این حالت را متعلق به یکی از این دو نوع می‌دانیم:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
\fBبازگشتی (Recursive):\fR
تمامی مسیرهای درون یک دایرکتوری گنجانده می‌شوند\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
\fBوالد (Parent):\fR
تمامی فایل‌های بلافاصله درون یک دایرکتوری گنجانده می‌شوند\&.
.RE
.sp
از آنجا که حالت مخروطی همیشه فایل‌های موجود در بالاترین سطح را در بر می‌گیرد، هنگام اجرای \fBgit\fR \fBsparse\-checkout\fR \fBset\fR بدون تعیین هیچ دایرکتوری، دایرکتوری بالاترین سطح به عنوان یک الگوی والد اضافه می‌شود\&. در این مرحله، فایل sparse\-checkout شامل الگوهای زیر است:
.sp
.if n \{\
.RS 4
.\}
.nf
/*
!/*/
.fi
.if n \{\
.RE
.\}
.sp
.sp
این یعنی «همه‌چیز را بلافاصله زیر دایرکتوری بالاترین سطح بگنجان، اما هیچ‌چیزی در هیچ سطحی زیر آن را نگنجان\&.»
.sp
هنگامی که در حالت مخروطی هستید، زیردستور \fBgit\fR \fBsparse\-checkout\fR \fBset\fR فهرستی از دایرکتوری‌ها را دریافت می‌کند\&. دستور \fBgit\fR \fBsparse\-checkout\fR \fBset\fR \fBA/B/C\fR دایرکتوری \fBA/B/C\fR را به عنوان یک الگوی بازگشتی تنظیم می‌کند، و دایرکتوری‌های \fBA\fR و \fBA/B\fR به عنوان الگوهای والد افزوده می‌شوند\&. فایل sparse\-checkout حاصل اکنون به این صورت است:
.sp
.if n \{\
.RS 4
.\}
.nf
/*
!/*/
/A/
!/A/*/
/A/B/
!/A/B/*/
/A/B/C/
.fi
.if n \{\
.RE
.\}
.sp
.sp
در اینجا، ترتیب اهمیت دارد، بنابراین الگوهای منفی توسط الگوهای مثبت که پایین‌تر در فایل قرار دارند لغو می‌شوند\&.
.sp
مگر اینکه \fBcore\&.sparseCheckoutCone\fR صراحتاً روی \fBfalse\fR تنظیم شده باشد، گیت فایل sparse\-checkout را به این انتظار که الگوها از این نوع باشند تجزیه می‌کند\&. اگر الگوها مطابقت نداشته باشند، گیت هشدار خواهد داد\&. اگر الگوها با قالب مورد انتظار مطابقت داشته باشند، گیت از الگوریتم‌های مبتنی بر هش سریع‌تر برای محاسبه گنجاندن در چک‌اوت تنک استفاده خواهد کرد\&. اگر مطابقت نداشته باشند، صرف‌نظر از مقدار تنظیمی آن، رفتار گیت به گونه‌ای خواهد بود که گویی \fBcore\&.sparseCheckoutCone\fR برابر با false است\&.
.sp
در مورد حالت مخروطی، با وجود این واقعیت که الگوهای کامل در فایل $GIT_DIR/info/sparse\-checkout نوشته می‌شوند، زیردستور \fBgit\fR \fBsparse\-checkout\fR \fBlist\fR دایرکتوری‌هایی را که الگوهای بازگشتی را تعریف می‌کنند فهرست خواهد کرد\&. برای فایل نمونه sparse\-checkout بالا، خروجی به شرح زیر است:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git sparse\-checkout list
A/B/C
.fi
.if n \{\
.RE
.\}
.sp
.sp
اگر \fBcore\&.ignoreCase=true\fR باشد، الگوریتم تطبیق الگو از بررسی حساس‌نبودن به حروف بزرگ و کوچک استفاده خواهد کرد\&. این امر عدم تطابق حروف بزرگ و کوچک نام‌فایل‌ها در دستور \fIgit sparse\-checkout set\fR را تصحیح می‌کند تا مخروط مورد انتظار در دایرکتوری کاری منعکس شود\&.
.SH "سازوکار داخلی \(em زیرماژول‌ها (INTERNALS \(em SUBMODULES)"
.sp
اگر مخزن شما دارای یک یا چند زیرماژول (submodule) باشد، زیرماژول‌ها بر اساس تعامل با دستور \fBgit\fR \fBsubmodule\fR پر می‌شوند\&. به طور مشخص، \fBgit\fR \fBsubmodule\fR \fBinit\fR \fB\-\-\fR \fI<path>\fR اطمینان حاصل می‌کند که زیرماژول در \fI<path>\fR حاضر است، در حالی که \fBgit\fR \fBsubmodule\fR \fBdeinit\fR [\fB\-f\fR] \fB\-\-\fR \fI<path>\fR فایل‌های زیرماژول را در \fI<path>\fR حذف می‌کند (شامل هرگونه فایل ردیابی‌نشده، تغییرات کامیت‌نشده، و تاریخچه push‌نشده)\&. همانند نحوه حذف فایل‌ها از درخت کاری توسط sparse\-checkout در حالی که همچنان مدخل‌ها در ایندکس باقی می‌مانند، زیرماژول‌های خارج‌شده از مقداردهی اولیه (deinitialized) نیز از دایرکتوری کاری حذف می‌شوند اما همچنان یک مدخل در ایندکس دارند\&.
.sp
از آنجا که زیرماژول‌ها ممکن است دارای تغییرات push‌نشده یا فایل‌های ردیابی‌نشده باشند، حذف آن‌ها می‌تواند منجر به از دست رفتن داده‌ها شود\&. بنابراین، تغییر قواعد گنجاندن/مستثنی‌سازی تنک باعث حذف زیرماژولی که از قبل چک‌اوت شده است از نسخه کاری نخواهد شد\&. به بیانی دیگر، درست همان‌طور که \fBcheckout\fR باعث حذف یا مقداردهی اولیه خودکار زیرماژول‌ها نمی‌شود (حتی هنگام جابه‌جایی میان شاخه‌هایی که زیرماژول‌ها را حذف یا اضافه می‌کنند)، استفاده از \fBsparse\-checkout\fR برای کاهش یا گسترش دامنه فایل‌های «مورد نظر» نیز موجب deinit یا init خودکار زیرماژول‌ها نخواهد شد\&.
.sp
علاوه بر این، واقعیت‌های فوق نشان می‌دهند که چندین دلیل برای عدم حضور فایل‌های «ردیابی‌شده» در نسخه کاری وجود دارد: اعمال الگوی تنکی از سوی sparse\-checkout، و وضعیت مقداردهی اولیه زیرماژول\&. بدین ترتیب، دستوراتی مانند \fBgit\fR \fBgrep\fR که روی فایل‌های ردیابی‌شده در نسخه کاری عمل می‌کنند ممکن است نتایجی را برگردانند که توسط یکی از این محدودیت‌ها یا هر دوی آن‌ها محدود شده باشد\&.
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBgit-read-tree\fR(1) \fBgitignore\fR(5)
.SH "گیت (GIT)"
.sp
بخشی از مجموعه \fBgit\fR(1)