GIT-GC(1) Git Manual GIT-GC(1)

git-gc - پاکسازی فایل‌های غیرضروری و بهینه‌سازی مخزن محلی

git gc [--aggressive] [--auto] [--[no-]detach] [--quiet] [--prune=<date> | --no-prune] [--force] [--keep-largest-pack]

تعدادی از وظایف نگهداری و مرتب‌سازی (housekeeping) را در مخزن فعلی اجرا می‌کند؛ مانند فشرده‌سازی نسخه‌های فایل (جهت کاهش فضای دیسک و افزایش کارایی)، حذف اشیاء غیرقابل‌دسترس که ممکن است از فراخوانی‌های قبلی git add ایجاد شده باشند، بسته‌بندی ارجاعات (refs)، هرس کردن reflog، فراداده‌های rerere یا درخت‌های کاری (working trees) بی‌استفاده و کهنه. همچنین ممکن است نمایه‌های کمکی مانند گراف کامیت (commit-graph) را به‌روزرسانی کند.

هنگامی که عملیات متداول پرسلین (دستورات سطح بالای کاربری که شیء جدید ایجاد می‌کنند) اجرا می‌شوند، بررسی می‌کنند که آیا مخزن از زمان آخرین نگهداری رشد چشمگیری داشته است یا خیر، و در صورت لزوم، git gc را به صورت خودکار اجرا می‌کنند. برای چگونگی غیرفعال کردن این رفتار، پیکربندی gc.auto را در ادامه ببینید.

اجرای دستی git gc تنها زمانی مورد نیاز است که اشیایی بدون اجرای منظم چنین دستورات پرسلینی به مخزن افزوده شوند، یا برای انجام یک بهینه‌سازی یک‌باره مخزن، یا مثلاً برای پاکسازی پس از یک درون‌ریزی انبوه غیراستاندارد (mass-import). برای جزئیات بیشتر در مورد موارد درون‌ریزی، بخش «PACKFILE OPTIMIZATION» در git-fast-import(1) را ببینید.

--aggressive

معمولاً git gc بسیار سریع اجرا می‌شود و در عین حال استفاده بهینه‌ای از فضای دیسک و کارایی مناسبی ارائه می‌دهد. این گزینه باعث می‌شود git gc مخزن را به صورت تهاجمی‌تر بهینه‌سازی کند که این امر به بهای صرف زمان بسیار بیشتری تمام خواهد شد. اثرات این بهینه‌سازی تا حد زیادی ماندگار است. برای جزئیات، بخش «بهینه‌سازی تهاجمی (AGGRESSIVE)» در زیر را ببینید.

--auto

با این گزینه، git gc بررسی می‌کند که آیا نیازی به کارهای نگهداری وجود دارد یا خیر؛ اگر نیازی نباشد، بدون انجام هیچ کاری خارج می‌شود.

برای چگونگی کارکرد این روش مکاشفه‌ای (heuristic)، گزینه gc.auto در بخش «پیکربندی (CONFIGURATION)» در زیر را ببینید.

به محض آنکه کارهای نگهداری به دلیل عبور از محدودیت‌های گزینه‌های پیکربندی نظیر gc.auto و gc.autoPackLimit آغاز شود، تمامی وظایف دیگر نگهداری (مانند rerere، درخت‌های کاری، reflog و غیره) نیز اجرا خواهند شد.

--detach, --no-detach

اجرا در پس‌زمینه در صورتی که سیستم از آن پشتیبانی کند. این گزینه تنظیمات gc.autoDetach را بازنویسی می‌کند.

--cruft, --no-cruft

هنگام منقضی کردن اشیاء غیرقابل‌دسترس، آن‌ها را به جای ذخیره به عنوان اشیاء آزاد، به طور جداگانه درون یک بسته باطله (cruft pack) بسته‌بندی می‌کند. --cruft به طور پیش‌فرض فعال است.

--max-cruft-size=<n>

هنگام بسته‌بندی اشیاء غیرقابل‌دسترس در یک بسته باطله (cruft pack)، اندازه بسته‌های جدید cruft را به حداکثر <n> بایت محدود می‌کند. هر مقداری که از طریق پیکربندی gc.maxCruftSize تعیین شده باشد را نادیده می‌گیرد. برای اطلاعات بیشتر، گزینه --max-cruft-size از git-repack(1) را ببینید.

--expire-to=<dir>

هنگام بسته‌بندی اشیاء غیرقابل‌دسترس در یک cruft pack، یک بسته باطله شامل اشیاء هرس‌شده (در صورت وجود) را در دایرکتوری <dir> می‌نویسد. این گزینه تنها در صورتی کاربرد دارد که همراه با --cruft استفاده شود. برای اطلاعات بیشتر، گزینه --expire-to از git-repack(1) را ببینید.

--prune=<date>

هرس کردن اشیاء آزاد قدیمی‌تر از تاریخ مشخص‌شده (پیش‌فرض ۲ هفته قبل است که با متغیر پیکربندی gc.pruneExpire قابل تغییر است). مقدار --prune=now اشیاء آزاد را صرف‌نظر از سن آن‌ها هرس می‌کند و اگر فرآیند دیگری به طور همزمان در حال نوشتن در مخزن باشد، خطر خراب شدن مخزن را افزایش می‌دهد؛ بخش «نکات (NOTES)» را در ادامه ببینید. گزینه --prune به طور پیش‌فرض فعال است.

--no-prune

هیچ‌یک از اشیاء آزاد را هرس نمی‌کند.

--quiet

فرونشاندن تمام گزارش‌های پیشرفت (حالت بی‌صدا).

--force

اجبار git gc به اجرا حتی اگر نمونه دیگری از git gc روی این مخزن در حال اجرا باشد.

--keep-largest-pack

تمام بسته‌ها به جز بزرگترین بسته غیر باطله (non-cruft)، بسته‌های نشانه‌گذاری‌شده با فایل .keep و هر بسته cruft، درون یک بسته واحد تجمیع می‌شوند. هنگام استفاده از این گزینه، gc.bigPackThreshold نادیده گرفته می‌شود.

هنگامی که گزینه --aggressive مشخص شود، دستور git-repack(1) با فلگ -f فراخوانی خواهد شد، که به نوبه خود فلگ --no-reuse-delta را به git-pack-objects(1) ارسال می‌کند. این کار تمام دلتاهای موجود را دور ریخته و آن‌ها را مجدداً محاسبه می‌کند، که به قیمت صرف زمان بسیار بیشتری در بسته‌بندی مجدد تمام خواهد شد.

اثرات این بهینه‌سازی تا حد زیادی ماندگار هستند؛ به عنوان مثال هنگامی که بسته‌ها و اشیاء آزاد درون یک بسته دیگر ادغام می‌شوند، ممکن است دلتاهای موجود در آن بسته مجدداً استفاده شوند، اما موارد متعددی نیز وجود دارد که در آن‌ها ممکن است دلتایی غیراپتیمال از یک بسته جدیدتر انتخاب شود.

علاوه بر این، ارائه --aggressive گزینه‌های --depth و --window ارسالی به git-repack(1) را تنظیم می‌کند. تنظیمات gc.aggressiveDepth و gc.aggressiveWindow را در زیر ببینید. با استفاده از اندازه پنجره بزرگتر، احتمال یافتن دلتاهای بهینه‌تر بیشتر می‌شود.

احتمالاً استفاده از این گزینه روی یک مخزن خاص بدون اجرای بنچمارک‌های کارایی متناسب، ارزشش را ندارد. این گزینه زمان بسیار بیشتری می‌برد و بهینه‌سازی حاصل در فضا و دلتا ممکن است ارزش این زمان را داشته باشد یا نداشته باشد. عدم استفاده از این گزینه برای اکثر کاربران و مخازن آن‌ها بهترین مصالحه (trade-off) است.

تمام موارد زیر این خط در این بخش، به صورت انتخابی از مستندات git-config(1) گنجانده شده‌اند. محتوا همان چیزی است که در آنجا یافت می‌شود:

gc.aggressiveDepth

پارامتر عمق استفاده‌شده در الگوریتم فشرده‌سازی دلتا توسط git gc --aggressive. مقدار پیش‌فرض آن ۵۰ است که همان پیش‌فرض گزینه --depth در زمانی است که --aggressive استفاده نمی‌شود.

برای جزئیات بیشتر، مستندات مربوط به گزینه --depth در git-repack(1) را ببینید.

gc.aggressiveWindow

پارامتر اندازه پنجره در الگوریتم فشرده‌سازی دلتا که توسط git gc --aggressive استفاده می‌شود. مقدار پیش‌فرض آن ۲۵۰ است که اندازه پنجره بسیار تهاجمی‌تری نسبت به پیش‌فرض --window با مقدار ۱۰ است.

برای جزئیات بیشتر، مستندات گزینه --window در git-repack(1) را ببینید.

gc.auto

هنگامی که تقریباً بیش از این تعداد شیء آزاد در مخزن وجود داشته باشد، git gc --auto آن‌ها را بسته‌بندی می‌کند. برخی دستورات Porcelain هر از چند گاهی از این دستور برای انجام یک جمع‌آوری سبک داده‌های بلااستفاده (garbage collection) استفاده می‌کنند. مقدار پیش‌فرض ۶۷۰۰ است.

تنظیم این مقدار روی صفر نه تنها بسته‌بندی خودکار بر اساس تعداد اشیاء آزاد را غیرفعال می‌کند، بلکه سایر روش‌های مکاشفه‌ای که git gc --auto برای تشخیص نیاز به کار استفاده می‌کند (مانند gc.autoPackLimit) را نیز غیرفعال می‌سازد.

gc.autoPackLimit

هنگامی که بیش از این تعداد بسته بدون فایل نشانه‌گذاری *.keep در مخزن وجود داشته باشد، git gc --auto آن‌ها را در یک بسته بزرگتر ادغام می‌کند. مقدار پیش‌فرض ۵۰ است. تنظیم آن روی ۰ این قابلیت را غیرفعال می‌کند. تنظیم gc.auto روی ۰ نیز این ویژگی را غیرفعال خواهد کرد.

متغیر پیکربندی gc.bigPackThreshold را در ادامه ببینید. در صورت استفاده، بر چگونگی عملکرد محدودیت بسته‌بندی خودکار تأثیر می‌گذارد.

gc.autoDetach

باعث می‌شود git gc --auto در صورت پشتیبانی سیستم، بلافاصله مقدار خروجی را برگرداند و در پس‌زمینه اجرا شود. مقدار پیش‌فرض true است. این متغیر در صورتی که maintenance.autoDetach تنظیم نشده باشد، به عنوان جایگزین عمل می‌کند.

gc.bigPackThreshold

اگر غیر صفر باشد، هنگام اجرای git gc، تمام بسته‌های غیر باطله (non-cruft) بزرگتر از این حد نگه داشته می‌شوند. این کار بسیار شبیه به --keep-largest-pack است، به جز اینکه تمامی بسته‌های غیر باطله واجد شرایط نگه داشته می‌شوند، نه فقط بزرگترین بسته. مقدار پیش‌فرض صفر است. پسوندهای رایج k، m یا g پشتیبانی می‌شوند.

توجه داشته باشید که اگر تعداد بسته‌های نگه‌داشته‌شده بیشتر از gc.autoPackLimit باشد، این متغیر پیکربندی نادیده گرفته شده و تمام بسته‌ها به جز بسته پایه مجدداً بسته‌بندی می‌شوند. پس از این، تعداد بسته‌ها باید به زیر gc.autoPackLimit برسد و gc.bigPackThreshold دوباره اعمال شود.

اگر مقدار حافظه تخمین‌زده‌شده برای اجرای روان git repack در دسترس نباشد و gc.bigPackThreshold تنظیم نشده باشد، بزرگترین بسته نیز مستثنی خواهد شد (این معادل اجرای git gc با گزینه --keep-largest-pack است).

gc.writeCommitGraph

اگر true باشد، هنگام اجرای git-gc(1) فایل commit-graph بازنویسی می‌شود. در هنگام استفاده از git gc --auto، اگر نگهداری مخزن لازم باشد، گراف کامیت به‌روز خواهد شد. مقدار پیش‌فرض true است. برای جزئیات git-commit-graph(1) را ببینید.

gc.logExpiry

اگر فایل gc.log وجود داشته باشد، git gc --auto محتوای آن را چاپ کرده و با وضعیت صفر خارج می‌شود، مگر اینکه سن آن فایل بیشتر از gc.logExpiry باشد. مقدار پیش‌فرض "1.day" است. برای روش‌های دیگر تعیین مقدار، gc.pruneExpire را ببینید.

gc.packRefs

اجرای git pack-refs در یک مخزن، آن را برای نسخه‌های گیت قبل از ۱.۵.۱.۲ روی پروتکل‌های انتقال ساده مانند HTTP غیرقابل کلون می‌کند. این متغیر مشخص می‌کند که آیا git gc دستور git pack-refs را اجرا کند یا خیر. این گزینه می‌تواند روی notbare تنظیم شود تا در تمام مخازن غیر bare فعال شود، یا می‌تواند یک مقدار بولی باشد. مقدار پیش‌فرض true است.

gc.cruftPacks

اشیاء غیرقابل‌دسترس را در یک بسته باطله (cruft pack - نگاه کنید به git-repack(1)) به جای اشیاء آزاد ذخیره می‌کند. مقدار پیش‌فرض true است.

gc.maxCruftSize

محدود کردن اندازه بسته‌های باطله (cruft) جدید هنگام بسته‌بندی مجدد. در صورت تعیین همزمان با --max-cruft-size، گزینه خط فرمان اولویت دارد. گزینه --max-cruft-size از git-repack(1) را ببینید.

gc.pruneExpire

هنگامی که git gc اجرا می‌شود، دستور prune --expire 2.weeks.ago (و در صورت استفاده از بسته‌های cruft از طریق gc.cruftPacks یا --cruft، دستور repack --cruft --cruft-expiration 2.weeks.ago) را فراخوانی می‌کند. با این متغیر پیکربندی می‌توانید مهلت تنفس را تغییر دهید. مقدار "now" ممکن است برای غیرفعال کردن این دوره و هرس فوری اشیاء غیرقابل‌دسترس استفاده شود، و "never" برای لغو کلی هرس به کار می‌رود. این ویژگی به جلوگیری از آسیب دیدن مخزن هنگام اجرای همزمان git gc با فرآیند دیگری که در حال نوشتن روی مخزن است کمک می‌کند؛ بخش «نکات (NOTES)» در git-gc(1) را ببینید.

gc.worktreePruneExpire

هنگامی که git gc اجرا می‌شود، git worktree prune --expire 3.months.ago را فراخوانی می‌کند. این متغیر پیکربندی می‌تواند برای تعیین مهلت متفاوت استفاده شود. مقدار "now" می‌تواند برای غیرفعال کردن مهلت و هرس فوری $GIT_DIR/worktrees به کار رود، یا "never" می‌تواند برای لغو هرس استفاده شود.

gc.reflogExpire, gc.<pattern>.reflogExpire

دستور git reflog expire مدخل‌های reflog قدیمی‌تر از این زمان را حذف می‌کند؛ پیش‌فرض ۹۰ روز است. مقدار "now" تمام مدخل‌ها را بلافاصله منقضی می‌کند و "never" به کلی مانع انقضا می‌شود. با قرار دادن "<pattern>" (مانند "refs/stash") در میانه، تنظیمات تنها برای ارجاعاتی که با الگو مطابقت دارند اعمال می‌شود.

gc.reflogExpireUnreachable, gc.<pattern>.reflogExpireUnreachable

دستور git reflog expire مدخل‌های reflog که قدیمی‌تر از این زمان هستند و از نوک شاخه فعلی قابل دستیابی نیستند را حذف می‌کند؛ پیش‌فرض ۳۰ روز است. مقدار "now" تمام این مدخل‌ها را فوراً منقضی کرده و "never" انقضا را کلاً متوقف می‌کند. با قرار دادن "<pattern>" (مانند "refs/stash") در میانه، تنظیمات تنها به ارجاعات منطبق با الگو اعمال می‌شود.

این نوع مدخل‌ها عموماً در نتیجه استفاده از git commit --amend یا git rebase ایجاد می‌شوند و کامیت‌های قبل از انجام amend یا rebase هستند. از آنجا که این تغییرات بخشی از پروژه فعلی نیستند، بیشتر کاربران مایلند آن‌ها را زودتر منقضی کنند، به همین دلیل پیش‌فرض آن تهاجمی‌تر از gc.reflogExpire است.

gc.recentObjectsHook

هنگام بررسی حذف یا عدم حذف یک شیء (چه هنگام ایجاد یک cruft pack و چه هنگام ذخیره اشیاء غیرقابل دسترس به عنوان شیء آزاد)، از پوسته (shell) برای اجرای دستور(های) مشخص‌شده استفاده می‌کند. خروجی آن‌ها به عنوان شناسه‌های اشیاء (object IDs) تفسیر می‌شود که گیت آن‌ها را صرف‌نظر از سن‌شان به عنوان "recent" (اخیر) در نظر می‌گیرد. با تلقی زمان تغییر (mtime) آن‌ها به عنوان "اکنون"، هر شیء (و فرزندان آن) که در خروجی ذکر شده باشند، بدون در نظر گرفتن سن واقعی‌شان نگه داشته می‌شوند.

خروجی باید دقیقاً شامل یک شناسه هگزادسیمال شیء در هر خط و بدون هیچ چیز دیگری باشد. اشیایی که در مخزن یافت نشوند نادیده گرفته می‌شوند. چندین قلاب (hook) پشتیبانی می‌شوند، اما همه آن‌ها باید با موفقیت به پایان برسند، در غیر این صورت عملیات (تولید بسته باطله یا باز کردن اشیاء غیرقابل دسترس) متوقف خواهد شد.

gc.repackFilter

هنگام بسته‌بندی مجدد، از فیلتر مشخص‌شده برای انتقال برخی اشیاء به یک فایل بسته جداگانه استفاده می‌کند. گزینه --filter=<filter-spec> در git-repack(1) را ببینید.

gc.repackFilterTo

هنگام بسته‌بندی مجدد و استفاده از فیلتر (به gc.repackFilter مراجعه کنید)، مکان مشخص‌شده برای ایجاد فایل بسته‌ای که شامل اشیاء فیلترشده است استفاده می‌شود. هشدار: مکان مشخص‌شده باید قابل دسترس باشد (مثلاً با استفاده از سازوکار جایگزین‌های گیت یا alternates)، در غیر این صورت ممکن است مخزن از نظر گیت خراب تلقی شود زیرا نمی‌تواند به اشیاء موجود در آن فایل بسته دسترسی یابد. گزینه --filter-to=<dir> در git-repack(1) و بخش objects/info/alternates از gitrepository-layout(5) را ببینید.

gc.rerereResolved

سوابق ادغام‌های دارای تعارض که قبلاً حل کرده‌اید، هنگام اجرای git rerere gc به مدت این تعداد روز نگهداری می‌شوند. همچنین می‌توانید از فرمت خواناتر "1.month.ago" و غیره استفاده کنید. مقدار پیش‌فرض ۶۰ روز است. به git-rerere(1) مراجعه کنید.

gc.rerereUnresolved

سوابق ادغام‌های دارای تعارض که حل نکرده‌اید، هنگام اجرای git rerere gc به مدت این تعداد روز نگهداری می‌شوند. همچنین می‌توانید از مقادیر خواناتر مانند "1.month.ago" و غیره استفاده کنید. مقدار پیش‌فرض ۱۵ روز است. به git-rerere(1) مراجعه کنید.

دستور git gc تلاش فراوانی می‌کند تا اشیایی را که در هر کجای مخزن شما ارجاع داده شده‌اند حذف نکند. به‌ویژه، نه تنها اشیاء ارجاع‌شده توسط شاخه‌ها و برچسب‌های فعلی شما را نگه می‌دارد، بلکه اشیاء ارجاع‌شده توسط نمایه (index)، شاخه‌های ردیابی از راه دور (remote-tracking branches)، لاگ‌های ارجاع یا reflogs (که ممکن است به کامیت‌هایی در شاخه‌هایی که بعداً بازنویسی یا اصلاح شده‌اند ارجاع دهند) و هر چیز دیگری در فضای نام refs/* را نیز حفظ می‌کند. توجه داشته باشید یادداشتی (از نوع ایجادشده با git notes) که به یک شیء پیوست شده است، نقشی در زنده نگه داشتن آن شیء ایفا نمی‌کند. اگر انتظار دارید برخی از اشیاء حذف شوند اما نشده‌اند، تمام آن مکان‌ها را بررسی کنید و تصمیم بگیرید که آیا در مورد شما حذف آن ارجاعات منطقی است یا خیر.

از سوی دیگر، هنگامی که git gc همزمان با فرآیند دیگری اجرا می‌شود، این خطر وجود دارد که شیئی را حذف کند که فرآیند دیگر از آن استفاده می‌کند اما هنوز ارجاعی به آن ایجاد نکرده است. این امر ممکن است باعث شکست فرآیند دیگر شود یا اگر فرآیند دیگر بعداً ارجاعی به شیء حذف‌شده اضافه کند، موجب خرابی مخزن گردد. گیت دو ویژگی دارد که این مشکل را به طور چشمگیری کاهش می‌دهد:

1.هر شیئی با زمان تغییر (mtime) جدیدتر از تاریخ --prune به همراه هر آنچه از آن قابل دستیابی است نگه داشته می‌شود.
2.اکثر عملیاتی که شیئی را به پایگاه‌داده اضافه می‌کنند، در صورتی که شیء از قبل وجود داشته باشد، زمان تغییر آن را به‌روز می‌کنند تا مورد شماره ۱ اعمال شود.

با این حال، این ویژگی‌ها راه‌حل کاملی نیستند، بنابراین کاربرانی که دستورات را به صورت همزمان اجرا می‌کنند، باید مقداری از خطر خرابی (که در عمل کم به نظر می‌رسد) را بپذیرند.

دستور git gc --auto قلاب (hook) با نام pre-auto-gc را اجرا خواهد کرد. برای اطلاعات بیشتر به githooks(5) مراجعه کنید.

git-prune(1) git-reflog(1) git-repack(1) git-rerere(1)

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

2026-06-29 Git 2.55.0