نام (NAME)

git-sparse-checkout - کاهش درخت کاری به زیرمجموعه‌ای از فایل‌های ردیابی‌شده

خلاصه دستور (SYNOPSIS)

git sparse-checkout (init | list | set | add | reapply | disable | check-rules | clean) [<options>]

توضیحات (DESCRIPTION)

این دستور برای ایجاد چک‌اوت‌های تنک (sparse checkouts) استفاده می‌شود، که درخت کاری را از داشتن تمامی فایل‌های ردیابی‌شده به داشتن تنها زیرمجموعه‌ای از آن فایل‌ها تغییر می‌دهد. همچنین می‌تواند زیرمجموعه فایل‌های حاضر را تعویض کند، یا تغییرات را برگردانده و دوباره تمام فایل‌های ردیابی‌شده را در نسخه کاری حاضر سازد.

زیرمجموعه فایل‌ها با ارائه فهرستی از دایرکتوری‌ها در حالت مخروطی (cone mode، حالت پیش‌فرض)، یا با ارائه فهرستی از الگوها در حالت غیرمخروطی (non-cone mode) انتخاب می‌شود.

هنگامی که در حالت چک‌اوت تنک هستید، سایر دستورات گیت کمی متفاوت رفتار می‌کنند. برای نمونه، تغییر شاخه باعث به‌روزرسانی مسیرهای خارج از دایرکتوری‌ها/الگوهای چک‌اوت تنک نمی‌شود، و دستور git commit -a مسیرهای خارج از دایرکتوری‌ها/الگوهای چک‌اوت تنک را به عنوان حذف‌شده ثبت نخواهد کرد.

این دستور آزمایشی است. رفتار آن و رفتار سایر دستورات در حضور چک‌اوت‌های تنک، به احتمال زیاد در آینده تغییر خواهد کرد.

دستورات (COMMANDS)

list

توصیف دایرکتوری‌ها یا الگوهای موجود در فایل sparse-checkout.

set

تنظیمات پیکربندی لازم برای چک‌اوت تنک (شامل core.sparseCheckout، core.sparseCheckoutCone و index.sparse) را در صورتی که پیش‌تر روی مقادیر مورد نظر تنظیم نشده باشند فعال می‌کند، فایل sparse-checkout را از فهرست آرگومان‌های پس از زیردستور set پر می‌کند، و دایرکتوری کاری را برای مطابقت با آن به‌روزرسانی می‌نماید.

برای اطمینان از اینکه تنظیم گزینه‌های چک‌اوت تنک در یک درخت کاری (worktree) تنظیمات چک‌اوت تنک را در سایر درخت‌های کاری دگرگون نسازد، زیردستور set پیکربندی مخزن شما را به استفاده از پیکربندی مختص هر درخت کاری ارتقا می‌دهد، مگر اینکه از قبل فعال باشد. تُنکی (sparsity) تعریف‌شده با آرگومان‌های زیردستور set در فایل sparse-checkout مختص همان درخت کاری ذخیره می‌شود. برای جزئیات بیشتر به git-worktree(1) و مستندات extensions.worktreeConfig در git-config(1) مراجعه کنید.

هنگامی که گزینه --stdin ارائه شود، دایرکتوری‌ها یا الگوها به جای آرگومان‌ها، از ورودی استاندارد به صورت فهرستی که با خط جدید از هم جدا شده‌اند خوانده می‌شوند.

به‌طور پیش‌فرض، فهرست ورودی به عنوان فهرستی از دایرکتوری‌ها در نظر گرفته می‌شود، مطابق با خروجی git ls-tree -d --name-only. این شامل تفسیر نام مسیرهایی است که با علامت نقل‌قول دوگانه ( مجموعه الگوهای مخروطی (CONE PATTERN SET) در ادامه مراجعه کنید). در گذشته، این رفتار پیش‌فرض نبود و نیاز بود گزینه --cone مشخص شود یا core.sparseCheckoutCone فعال گردد.

هنگامی که --no-cone داده شود، فهرست ورودی به عنوان فهرستی از الگوها در نظر گرفته می‌شود. این حالت دارای چندین نقطه‌ضعف است، از جمله عدم کارکرد با برخی گزینه‌ها مانند --sparse-index. همان‌طور که در بخش «مشکلات حالت غیرمخروطی» در ادامه توضیح داده شده است، استفاده از آن را توصیه نمی‌کنیم.

از گزینه --[no-]sparse-index برای استفاده از یک ایندکس تنک استفاده کنید (حالت پیش‌فرض عدم استفاده از آن است). یک ایندکس تنک، اندازه ایندکس را کاهش می‌دهد تا با تعریف چک‌اوت تنک شما هماهنگ‌تر باشد. این امر می‌تواند مزایای عملکردی چشمگیری برای دستوراتی نظیر git status یا git add داشته باشد. این ویژگی هنوز آزمایشی است. برخی از دستورات ممکن است تا زمانی که به طور مناسب با این ویژگی یکپارچه شوند، با ایندکس تنک کندتر کار کنند.

هشدار: استفاده از ایندکس تنک مستلزم اصلاح ایندکس به گونه‌ای است که توسط ابزارهای خارجی کاملاً درک نمی‌شود. اگر با سازگاری مشکلی دارید، دستور git sparse-checkout init --no-sparse-index را اجرا کنید تا ایندکس شما بازنویسی شده و غیرتنک شود. نگارش‌های قدیمی‌تر گیت افزونه ایندکس مدخل‌های دایرکتوری تنک را درک نمی‌کنند و ممکن است تا زمان غیرفعال شدن آن نتوانند با مخزن شما تعامل داشته باشند.

add

به‌روزرسانی فایل sparse-checkout برای افزودن دایرکتوری‌های بیشتر (در حالت مخروطی) یا الگوها (در حالت غیرمخروطی). به‌طور پیش‌فرض، این دایرکتوری‌ها یا الگوها از آرگومان‌های خط فرمان خوانده می‌شوند، اما با استفاده از گزینه --stdin می‌توان آن‌ها را از ورودی استاندارد خواند.

reapply

اعمال دوباره قواعد الگوی تنکی روی مسیرهای درخت کاری. دستوراتی مانند merge یا rebase می‌توانند برای انجام کار خود مسیرها را پدیدار کنند (برای مثال جهت نشان دادن یک تعارض به شما)، و سایر دستورات sparse-checkout ممکن است در تنک‌سازی یک فایل منفرد شکست بخورند (مثلاً به دلیل داشتن تغییرات استیج‌نشده یا تعارض‌ها). در چنین مواردی، منطقی است که بعداً پس از پاکسازی مسیرهای متأثر (مانند حل تعارض‌ها، بازگرداندن یا کامیت تغییرات و غیره)، دستور git sparse-checkout reapply را اجرا کنید.

دستور reapply همچنین می‌تواند فلگ‌های --[no-]cone و --[no-]sparse-index را بپذیرد، با همان مفهومی که در دستور set دارند، تا بدون نیاز به مشخص کردن مجدد تمام مسیرهای تنکی، حالت تنکی مورد استفاده را تغییر دهد.

clean

حذف مقتضی و فرصت‌طلبانه فایل‌های خارج از تعریف sparse-checkout. این دستور برای تعیین فایل‌هایی که باید حذف شوند به حالت مخروطی نیاز دارد تا از تطابق بازگشتی دایرکتوری‌ها استفاده کند. فایلی واجد شرایط حذف در نظر گرفته می‌شود که درون دایرکتوری ردیابی‌شده‌ای قرار داشته باشد که خارج از تعریف sparse-checkout است.

برخی شرایط ویژه، مانند تعارض‌های ادغام (merge conflicts) یا فایل‌های تغییریافته خارج از تعریف sparse-checkout، می‌توانند منجر به نگه‌داشتن فایل‌هایی شوند که در غیر این صورت حذف می‌شدند. تعارض‌ها را حل کنید، تغییرات را استیج کنید و از دستور git sparse-checkout reapply همراه با git sparse-checkout clean برای حل این موارد استفاده کنید.

از این دستور می‌توان برای اطمینان از کارکرد کارآمد ایندکس تنک استفاده کرد، هرچند که نیازی به فعال‌سازی ویژگی ایندکس تنک از طریق پیکربندی index.sparse=true ندارد.

برای جلوگیری از حذف تصادفی فایل‌های درخت کاری، زیردستور clean هیچ فایلی را بدون گزینه -f یا --force حذف نخواهد کرد، مگر اینکه گزینه پیکربندی clean.requireForce روی false تنظیم شده باشد.

گزینه --dry-run دایرکتوری‌هایی را که بدون حذف واقعی پاک خواهند شد فهرست می‌کند. اجرا در این حالت می‌تواند برای پیش‌بینی رفتار دستور clean یا تعیین اینکه چه نوع فایل‌هایی در دایرکتوری‌های تنک باقی مانده‌اند مفید باشد.

گزینه --verbose تک‌تک فایل‌های درون دایرکتوری‌های در نظر گرفته‌شده برای حذف را فهرست می‌کند. این گزینه برای تشخیص اینکه آیا آن فایل‌ها واقعاً مهم هستند یا شاید برای توضیح اینکه چرا دایرکتوری با وجود sparse-checkout جاری همچنان حضور دارد مفید است.

disable

تنظیم پیکربندی core.sparseCheckout را غیرفعال کرده و دایرکتوری کاری را برای در بر گرفتن تمامی فایل‌ها بازیابی می‌کند.

init

دستوری منسوخ‌شده که رفتاری مانند set بدون هیچ مسیر مشخص‌شده دارد. ممکن است در آینده حذف شود.

از نظر تاریخی، دستور set همه تنظیمات پیکربندی لازم را انجام نمی‌داد، به این معنی که هر دو دستور init و set باید فراخوانی می‌شدند. فراخوانی هر دو به این معنی بود که گام init ابتدا تقریباً تمام فایل‌های ردیابی‌شده (و در حالت مخروطی، فایل‌های نادیده‌گرفته‌شده را نیز) حذف می‌کرد، سپس گام set بسیاری از فایل‌های ردیابی‌شده (اما نه فایل‌های نادیده‌گرفته‌شده) را بازمی‌گرداند. افزون بر فایل‌های از دست رفته، کارایی و رابط کاربری این ترکیب ضعیف بود.

همچنین از نظر تاریخی، init اگر فایل sparse-checkout از قبل وجود داشت، در واقع آن را مقداردهی اولیه نمی‌کرد. این بدان معنا بود که بازگشت به یک چک‌اوت تنک بدون به‌خاطر سپردن مسیرهایی که باید به دستور بعدی set یا add داده شوند امکان‌پذیر بود. با این حال، گزینه‌های --cone و --sparse-index پس از دستور disable به خاطر سپرده نمی‌شدند، بنابراین کاربرد بازیابی آسان با فراخوانی یک init ساده کاهش یافت.

check-rules

بررسی اینکه آیا قواعد تنکی با یک یا چند مسیر مطابقت دارند یا خیر.

به‌طور پیش‌فرض، check-rules فهرستی از مسیرها را از ورودی استاندارد می‌خواند و تنها آن‌هایی را که با قواعد تنکی جاری مطابقت دارند خروجی می‌دهد. انتظار می‌رود ورودی شامل یک مسیر در هر سطر باشد، مطابق با خروجی git ls-tree --name-only، شامل اینکه نام مسیرهایی که با نقل‌قول دوگانه (

هنگامی که با فلگ --rules-file <file> فراخوانی شود، فایل‌های ورودی با قواعد چک‌اوت تنک موجود در <file> به جای قواعد جاری مقایسه و تطبیق داده می‌شوند. انتظار می‌رود قواعد موجود در فایل‌ها به همان شکلی باشند که توسط git sparse-checkout set --stdin پذیرفته می‌شوند (به ویژه اینکه باید با خط جدید از یکدیگر جدا شده باشند).

به‌طور پیش‌فرض، قواعد ارائه‌شده به گزینه --rules-file به عنوان دایرکتوری‌های حالت مخروطی تفسیر می‌شوند. برای ارسال الگوهای حالت غیرمخروطی با --rules-file، این گزینه را با گزینه --no-cone ترکیب کنید.

هنگامی که با فلگ -z فراخوانی شود، قالب مسیرهای ورودی در ورودی استاندارد و همچنین مسیرهای خروجی با \0 خاتمه یافته و نقل‌قول نمی‌شوند. توجه داشته باشید که این موضوع شامل قالب قواعد ارائه‌شده با گزینه --rules-file نمی‌شود.

مثال‌ها (EXAMPLES)

git sparse-checkout set MY/DIR1 SUB/DIR2

تغییر به یک چک‌اوت تنک که در آن تمامی فایل‌ها (در هر عمقی) زیر MY/DIR1/ و SUB/DIR2/ در نسخه کاری حضور دارند (به علاوه تمامی فایل‌های بلافاصله زیر MY/ و SUB/ و دایرکتوری سطح بالا). اگر هم‌اکنون در یک چک‌اوت تنک هستید، فایل‌های حاضر در نسخه کاری را به این انتخاب جدید تغییر می‌دهد. توجه داشته باشید که این دستور همچنین تمام فایل‌های نادیده‌گرفته‌شده را در هر دایرکتوری که دیگر هیچ فایل ردیابی‌شده یا فایل ردیابی‌نشده‌ی نادیده‌نگرفته‌شده‌ای در آن حضور ندارد، حذف خواهد کرد.

git sparse-checkout disable

پر کردن مجدد دایرکتوری کاری با تمام فایل‌ها و غیرفعال کردن چک‌اوت‌های تنک.

git sparse-checkout add SOME/DIR/ECTORY

افزودن تمامی فایل‌های زیر SOME/DIR/ECTORY/ (در هر عمقی) به چک‌اوت تنک، و همچنین تمامی فایل‌های بلافاصله زیر SOME/DIR/ و بلافاصله زیر SOME/. پیش از استفاده از این دستور باید از قبل در یک چک‌اوت تنک باشید.

git sparse-checkout reapply

این امکان وجود دارد که دستورات درخت کاری را به گونه‌ای به‌روزرسانی کنند که دایرکتوری‌های تنکی انتخاب‌شده رعایت نشوند. این حالت می‌تواند ناشی از ابزارهای خارج از گیت باشد که فایل می‌نویسند، یا حتی دستورات گیت را تحت تأثیر قرار دهد؛ چه به دلیل حالت‌های خاص (مانند برخورد با تعارض‌ها هنگام ادغام/rebase)، یا به این دلیل که برخی دستورات به طور کامل از چک‌اوت‌های تنک پشتیبانی نمی‌کردند (برای نمونه، بک‌اند قدیمی ادغام recursive تنها پشتیبانی محدودی داشت). این دستور مشخصات دایرکتوری تنک موجود را مجدداً اعمال می‌کند تا دایرکتوری کاری با آن همخوان شود.

سازوکار داخلی — چک‌اوت تنک (INTERNALS — SPARSE CHECKOUT)

«چک‌اوت تنک» (Sparse checkout) امکان پر کردن تنک و پراکنده دایرکتوری کاری را فراهم می‌آورد. این قابلیت از بیت skip-worktree (نگاه کنید به git-update-index(1)) استفاده می‌کند تا به گیت اعلام کند که آیا فایلی در دایرکتوری کاری ارزش بررسی دارد یا خیر. اگر بیت skip-worktree تنظیم شده باشد و فایل در درخت کاری حضور نداشته باشد، عدم حضور آن نادیده گرفته می‌شود. گیت از پر کردن محتوای آن فایل‌ها خودداری می‌کند، که این امر چک‌اوت تنک را هنگام کار در مخزنی با فایل‌های فراوان که تنها تعداد اندکی از آن‌ها برای کاربر جاری اهمیت دارند، بسیار مفید می‌سازد.

فایل $GIT_DIR/info/sparse-checkout برای تعریف نگاشت بیتی مرجع skip-worktree استفاده می‌شود. هنگامی که گیت دایرکتوری کاری را به‌روزرسانی می‌کند، بیت‌های skip-worktree را در ایندکس بر اساس این فایل به‌روز می‌نماید. فایل‌های منطبق بر الگوهای موجود در این فایل در دایرکتوری کاری پدیدار خواهند شد و مابقی پدیدار نمی‌شوند.

سازوکار داخلی — مشکلات حالت غیرمخروطی (INTERNALS — NON-CONE PROBLEMS)

فایل $GIT_DIR/info/sparse-checkout که با زیردستورات set و add پر می‌شود، به عنوان مجموعه‌ای از الگوها (یک الگو در هر خط) با استفاده از همان نحو فایل‌های .gitignore تعریف می‌شود. در حالت مخروطی، این الگوها محدود به تطابق دایرکتوری‌ها هستند (و کاربران تنها نیاز به ارائه یا مشاهده نام دایرکتوری‌ها دارند)، در حالی که در حالت غیرمخروطی هرگونه الگوی شبیه به gitignore مجاز است. استفاده از الگوهای کامل شبیه به gitignore در حالت غیرمخروطی چندین نقص به همراه دارد:

•اساساً، این امر باعث می‌شود که فرآیندهای گوناگون به‌روزرسانی درخت کاری (pull، merge، rebase، switch، reset، checkout و غیره) به تطابق الگوی O(N*M) نیاز داشته باشند، که در آن N تعداد الگوها و M تعداد مسیرهای موجود در ایندکس است. این وضعیت مقیاس‌پذیری بسیار ضعیفی دارد.

•اجتناب از مشکل مقیاس‌پذیری باید از طریق محدود کردن تعداد الگوها به وسیله مشخص کردن نام دایرکتوری آغازین یا glob انجام شود.

•ارسال الگوهای گلوب (globs) در خط فرمان مستعد خطا است زیرا کاربران ممکن است نقل‌قول کردن (کوتیشن) گلوب را فراموش کنند، که باعث می‌شود شل آن را به تمام فایل‌های منطبق بسط دهد و همه آن‌ها را به صورت تک‌تک به sparse-checkout set/add بفرستد. اگرچه این موضوع می‌تواند مثلاً در "git grep — *.c" نیز یک مشکل باشد، اما اشتباهات در grep/log/status بلافاصله در خروجی نمایان می‌شوند. در sparse-checkout، این اشتباه در همان زمان اجرای دستور sparse-checkout ثبت می‌شود و ممکن است تا زمانی که کاربر بعداً شاخه‌ها را عوض کند یا rebase یا merge انجام دهد مشکلی ایجاد نکند، بنابراین فاصله‌ای زمانی میان خطای کاربر و زمانی که فرصت متوجه شدن آن را دارد ایجاد می‌شود.

•مرتبط با مورد پیشین، دستور sparse-checkout دارای زیردستور add است اما فاقد زیردستور remove می‌باشد. حتی اگر زیردستور remove اضافه می‌شد، لغو یک گلوب بدون کوتیشن تصادفی با خطر «حذف بیش از حد» مواجه می‌شد، چرا که ممکن بود مدخل‌هایی را حذف کند که پیش از افزودن تصادفی نیز وجود داشته‌اند.

•حالت غیرمخروطی از الگوهای به سبک gitignore برای انتخاب موارد جهت گنجاندن (include) استفاده می‌کند (به استثنای الگوهای منفی)، در حالی که فایل‌های .gitignore از الگوهای به سبک gitignore برای انتخاب موارد جهت مستثنی کردن (exclude) استفاده می‌نمایند (به استثنای الگوهای منفی). مستندات مربوط به الگوهای سبک gitignore معمولاً بر حسب تطابق داشتن یا نداشتن صحبت نمی‌کنند، بلکه بر این اساس است که کاربر چه چیزی را می‌خواهد «مستثنی» کند. این موضوع می‌تواند برای کاربرانی که تلاش می‌کنند چگونگی تعیین الگوهای sparse-checkout را برای دستیابی به رفتار مورد نظرشان یاد بگیرند، سردرگمی ایجاد کند.

•تمام زیردستورهای دیگر گیت که می‌خواهند نوعی «تطابق الگوی مسیر خاص» ارائه دهند از pathspec استفاده می‌کنند، اما حالت غیرمخروطی برای sparse-checkout از الگوهای gitignore استفاده می‌کند که ناسازگار به نظر می‌رسد.

•دارای حالت‌های حدی است که رفتار «درست» در آن‌ها نامشخص است. دو مثال:

نخست، دو کاربر در یک زیردایرکتوری هستند و اولی اجرا می‌کند:

git sparse-checkout set '/toplevel-dir/*.c'

در حالی که دومی اجرا می‌کند:

git sparse-checkout set relative-dir

آیا این آرگومان‌ها پیش از درج در فایل sparse-checkout باید به صورت

current/subdirectory/toplevel-dir/*.c

و

current/subdirectory/relative-dir

تبدیل شوند؟ کاربری که دستور اول را تایپ کرده احتمالاً می‌داند که آرگومان‌های set/add در حالت غیرمخروطی باید الگو باشند و احتمالاً از چنین تبدیلی خرسند نخواهد شد. با این حال، بسیاری از الگوهای سبک gitignore صرفاً مسیر هستند، که ممکن است همان چیزی باشد که کاربر تایپ‌کننده دستور دوم در ذهن داشته است، و اگر آرگومان او تبدیل نمی‌شد ناراحت می‌شد.

دوم، تکمیل خودکار بش (bash-completion) برای دستورات set/add کاربران غیرمخروطی چه چیزی را باید پیشنهاد دهد؟ اگر مسیرها را پیشنهاد دهد، آیا مشکل بالا را تشدید نمی‌کند؟ همچنین، اگر مسیرها را پیشنهاد دهد، چه می‌شود اگر کاربر فایل یا دایرکتوری داشته باشد که نام آن با ! یا # آغاز شود یا شامل *، \، ?، [ یا ] باشد؟ و اگر مسیرها را پیشنهاد دهد، آیا "/pro" را به "/proc" (در فایل‌سیستم ریشه) تکمیل می‌کند به جای اینکه به "/progress.txt" در دایرکتوری جاری تکمیل کند؟ (توجه داشته باشید که کاربران در حالت غیرمخروطی احتمالاً تمایل دارند مسیرها را با یک / آغازین شروع کنند، به همان دلیلی که فایل‌های .gitignore اغلب یکی دارند.) تکمیل بر روی فایل‌ها یا دایرکتوری‌ها ممکن است در تمام این حالت‌ها غافلگیری‌های ناخوشایندی ایجاد کند.

•انعطاف‌پذیری بیش از حد، سایر افزونه‌ها را عملاً غیرکاربردی کرده است. --sparse-index احتمالاً در حالت غیرمخروطی غیرممکن است؛ حتی اگر به نحوی شدنی باشد، پیاده‌سازی آن مستلزم کار بسیار بیشتری بوده و ممکن بود در عمل بیش از حد کند باشد. برخی ایده‌ها برای اتصال میان کلون‌های جزئی (partial clones) و چک‌اوت‌های تنک نیز تنها با مجموعه‌ای محدودتر از مسیرها عملی هستند.

به تمامی این دلایل، حالت غیرمخروطی منسوخ شده است. لطفاً به استفاده از حالت مخروطی روی آورید.

سازوکار داخلی — مدیریت حالت مخروطی (INTERNALS — CONE MODE HANDLING)

«حالت مخروطی» (cone mode) که حالت پیش‌فرض است، به شما امکان می‌دهد تنها مشخص کنید چه دایرکتوری‌هایی گنجانده شوند. برای هر دایرکتوری مشخص‌شده، تمام مسیرهای زیر آن دایرکتوری گنجانده خواهند شد، و هر مسیری که بلافاصله زیر دایرکتوری‌های راهنما (از جمله دایرکتوری سطح بالا) قرار دارد نیز گنجانده می‌شود. بدین ترتیب، اگر دایرکتوری Documentation/technical/ را مشخص کرده باشید، چک‌اوت تنک شما شامل موارد زیر خواهد بود:

•تمامی فایل‌های موجود در دایرکتوری سطح بالا

•تمامی فایل‌های بلافاصله زیر Documentation/

•تمامی فایل‌ها در هر عمقی زیر Documentation/technical/

همچنین در حالت مخروطی، حتی اگر هیچ دایرکتوری مشخص نشده باشد، فایل‌های موجود در دایرکتوری سطح بالا گنجانده خواهند شد.

هنگام تغییر الگوهای sparse-checkout در حالت مخروطی، گیت هر دایرکتوری ردیابی‌شده‌ای را که در مخروط sparse-checkout قرار ندارد بررسی می‌کند تا ببیند آیا حاوی فایل‌های ردیابی‌نشده است یا خیر. اگر تمامی آن فایل‌ها به دلیل الگوهای .gitignore نادیده گرفته شده باشند، آنگاه دایرکتوری حذف خواهد شد. اگر هر یک از فایل‌های ردیابی‌نشده درون آن دایرکتوری نادیده گرفته نشده باشد، هیچ حذفی در آن دایرکتوری رخ نخواهد داد و یک پیام هشدار پدیدار می‌شود. اگر این فایل‌ها مهم هستند، تعریف sparse-checkout خود را بازنشانی کنید تا آن‌ها گنجانده شوند، از git add و git commit برای ذخیره آن‌ها استفاده کنید، سپس هر فایل باقی‌مانده را به صورت دستی حذف کنید تا اطمینان حاصل شود گیت می‌تواند به شکل بهینه رفتار کند.

همچنین برای آگاهی از اینکه چگونه دایرکتوری‌ها در پس پرده به زیرمجموعه‌ای از «مجموعه الگوهای کامل» چک‌اوت تنک تبدیل می‌شوند، به بخش «سازوکار داخلی — مجموعه الگوهای مخروطی» مراجعه کنید.

سازوکار داخلی — مجموعه الگوهای کامل (INTERNALS — FULL PATTERN SET)

مجموعه الگوهای کامل، امکان تطابق الگوهای دلخواه و قواعد پیچیده گنجاندن/مستثنی‌سازی را فراهم می‌آورد. این موارد هنگام به‌روزرسانی ایندکس می‌توانند منجر به تطابق‌های الگوی O(N*M) شوند، که در آن N تعداد الگوها و M تعداد مسیرهای موجود در ایندکس است. برای مقابله با این مشکل کارایی، زمانی که core.sparseCheckoutCone فعال باشد، مجموعه الگوی محدودتری مجاز است.

فایل sparse-checkout از همان نحو فایل‌های .gitignore استفاده می‌کند؛ برای جزئیات به gitignore(5) مراجعه کنید. با این حال در اینجا، الگوها معمولاً برای انتخاب فایل‌هایی که باید گنجانده شوند استفاده می‌شوند نه فایل‌هایی که باید مستثنی گردند. (البته این می‌تواند کمی گیج‌کننده باشد، زیرا الگوهای سبک gitignore دارای نفی‌هایی هستند که با الگوهایی با شروع ! تعریف می‌شوند، بنابراین می‌توانید فایل‌هایی را نیز برای نگنجاندن انتخاب کنید).

برای نمونه، جهت انتخاب همه‌چیز و سپس حذف فایل unwanted (به‌طوری که تمام فایل‌ها به جز فایلی با نام unwanted در درخت کاری شما حاضر شوند):

git sparse-checkout set --no-cone '/*' '!unwanted'

این الگوها عیناً در $GIT_DIR/info/sparse-checkout قرار می‌گیرند، بنابراین محتوای آن فایل در این مرحله به صورت زیر خواهد بود:

/*
!unwanted

همچنین برای اطلاعات بیشتر درباره الگوهای سبک gitignore مورد استفاده در چک‌اوت‌های تنک، به بخش «Sparse Checkout» در git-read-tree(1) مراجعه کنید.

سازوکار داخلی — مجموعه الگوهای مخروطی (INTERNALS — CONE PATTERN SET)

در حالت مخروطی، تنها دایرکتوری‌ها پذیرفته می‌شوند، اما آن‌ها به همان الگوهای به سبک gitignore که در مجموعه الگوی کامل استفاده می‌شوند ترجمه می‌گردند. الگوهای خاص استفاده‌شده در این حالت را متعلق به یکی از این دو نوع می‌دانیم:

1.بازگشتی (Recursive): تمامی مسیرهای درون یک دایرکتوری گنجانده می‌شوند.

2.والد (Parent): تمامی فایل‌های بلافاصله درون یک دایرکتوری گنجانده می‌شوند.

از آنجا که حالت مخروطی همیشه فایل‌های موجود در بالاترین سطح را در بر می‌گیرد، هنگام اجرای git sparse-checkout set بدون تعیین هیچ دایرکتوری، دایرکتوری بالاترین سطح به عنوان یک الگوی والد اضافه می‌شود. در این مرحله، فایل sparse-checkout شامل الگوهای زیر است:

/*
!/*/

این یعنی «همه‌چیز را بلافاصله زیر دایرکتوری بالاترین سطح بگنجان، اما هیچ‌چیزی در هیچ سطحی زیر آن را نگنجان.»

هنگامی که در حالت مخروطی هستید، زیردستور git sparse-checkout set فهرستی از دایرکتوری‌ها را دریافت می‌کند. دستور git sparse-checkout set A/B/C دایرکتوری A/B/C را به عنوان یک الگوی بازگشتی تنظیم می‌کند، و دایرکتوری‌های A و A/B به عنوان الگوهای والد افزوده می‌شوند. فایل sparse-checkout حاصل اکنون به این صورت است:

/*
!/*/
/A/
!/A/*/
/A/B/
!/A/B/*/
/A/B/C/

در اینجا، ترتیب اهمیت دارد، بنابراین الگوهای منفی توسط الگوهای مثبت که پایین‌تر در فایل قرار دارند لغو می‌شوند.

مگر اینکه core.sparseCheckoutCone صراحتاً روی false تنظیم شده باشد، گیت فایل sparse-checkout را به این انتظار که الگوها از این نوع باشند تجزیه می‌کند. اگر الگوها مطابقت نداشته باشند، گیت هشدار خواهد داد. اگر الگوها با قالب مورد انتظار مطابقت داشته باشند، گیت از الگوریتم‌های مبتنی بر هش سریع‌تر برای محاسبه گنجاندن در چک‌اوت تنک استفاده خواهد کرد. اگر مطابقت نداشته باشند، صرف‌نظر از مقدار تنظیمی آن، رفتار گیت به گونه‌ای خواهد بود که گویی core.sparseCheckoutCone برابر با false است.

در مورد حالت مخروطی، با وجود این واقعیت که الگوهای کامل در فایل $GIT_DIR/info/sparse-checkout نوشته می‌شوند، زیردستور git sparse-checkout list دایرکتوری‌هایی را که الگوهای بازگشتی را تعریف می‌کنند فهرست خواهد کرد. برای فایل نمونه sparse-checkout بالا، خروجی به شرح زیر است:

$ git sparse-checkout list
A/B/C

اگر core.ignoreCase=true باشد، الگوریتم تطبیق الگو از بررسی حساس‌نبودن به حروف بزرگ و کوچک استفاده خواهد کرد. این امر عدم تطابق حروف بزرگ و کوچک نام‌فایل‌ها در دستور git sparse-checkout set را تصحیح می‌کند تا مخروط مورد انتظار در دایرکتوری کاری منعکس شود.

سازوکار داخلی — زیرماژول‌ها (INTERNALS — SUBMODULES)

اگر مخزن شما دارای یک یا چند زیرماژول (submodule) باشد، زیرماژول‌ها بر اساس تعامل با دستور git submodule پر می‌شوند. به طور مشخص، git submodule init -- <path> اطمینان حاصل می‌کند که زیرماژول در <path> حاضر است، در حالی که git submodule deinit [-f] -- <path> فایل‌های زیرماژول را در <path> حذف می‌کند (شامل هرگونه فایل ردیابی‌نشده، تغییرات کامیت‌نشده، و تاریخچه push‌نشده). همانند نحوه حذف فایل‌ها از درخت کاری توسط sparse-checkout در حالی که همچنان مدخل‌ها در ایندکس باقی می‌مانند، زیرماژول‌های خارج‌شده از مقداردهی اولیه (deinitialized) نیز از دایرکتوری کاری حذف می‌شوند اما همچنان یک مدخل در ایندکس دارند.

از آنجا که زیرماژول‌ها ممکن است دارای تغییرات push‌نشده یا فایل‌های ردیابی‌نشده باشند، حذف آن‌ها می‌تواند منجر به از دست رفتن داده‌ها شود. بنابراین، تغییر قواعد گنجاندن/مستثنی‌سازی تنک باعث حذف زیرماژولی که از قبل چک‌اوت شده است از نسخه کاری نخواهد شد. به بیانی دیگر، درست همان‌طور که checkout باعث حذف یا مقداردهی اولیه خودکار زیرماژول‌ها نمی‌شود (حتی هنگام جابه‌جایی میان شاخه‌هایی که زیرماژول‌ها را حذف یا اضافه می‌کنند)، استفاده از sparse-checkout برای کاهش یا گسترش دامنه فایل‌های «مورد نظر» نیز موجب deinit یا init خودکار زیرماژول‌ها نخواهد شد.

علاوه بر این، واقعیت‌های فوق نشان می‌دهند که چندین دلیل برای عدم حضور فایل‌های «ردیابی‌شده» در نسخه کاری وجود دارد: اعمال الگوی تنکی از سوی sparse-checkout، و وضعیت مقداردهی اولیه زیرماژول. بدین ترتیب، دستوراتی مانند git grep که روی فایل‌های ردیابی‌شده در نسخه کاری عمل می‌کنند ممکن است نتایجی را برگردانند که توسط یکی از این محدودیت‌ها یا هر دوی آن‌ها محدود شده باشد.

همچنین ببینید (SEE ALSO)

git-read-tree(1) gitignore(5)

گیت (GIT)

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