وقتی یک فایل صوتی ۱۲۸ مگابایتی مانع ارسال پروژه به گیتهاب شد
حتماً برای شما هم پیش آمده که بعد از روزها کار روی یک پروژه، هنگام push کردن به گیتهاب با پیغام قرمزرنگی مواجه شوید که میگوید:
remote: error: File file.mp3 is 128.34 MB;
this exceeds GitHub's file size limit of 100.00 MBاین دقیقاً همان خطایی بود که من هنگام کار روی یک پروژهٔ پادکست با VS Code تجربه کردم. چند کامیت پشت سر هم انجام داده بودم و آخرین کامیت شامل یک فایل MP3 با حجم ۱۲۸ مگابایت بود. اما گیتهاب اجازهٔ آپلود فایلهای بزرگتر از ۱۰۰ مگابایت را نمیدهد.
در این مقاله، قدمبهقدم توضیح میدهم که چگونه این مشکل را بدون از دست دادن تغییرات دیگر حل کردم و با دو روش اصولی آشنا میشوید: استفاده از Git LFS و پاکسازی تاریخچه با دستورات reset.
اگر شما هم با چنین خطایی مواجه شدهاید یا میخواهید از ابتدا از بروز آن جلوگیری کنید، این مطلب را تا انتها بخوانید.
خطا چیست و چرا رخ میدهد؟
گیتهاب بهطور پیشفرض برای هر فایل حداکثر ۱۰۰ مگابایت حجم در نظر گرفته است. این محدودیت به دلیل حفظ کارایی مخزن و جلوگیری از سنگین شدن بیش از حد کلونها و fetchهاست. اگر فایلی بزرگتر از این حد باشد، سرور گیتهاب آن را رد میکند و پیغام GH001: Large files detected را نشان میدهد.
این محدودیت حتی اگر فایل را در کامیتهای قبلی هم اضافه کرده باشید، باز هم مانع از push میشود، چون گیت کل تاریخچه را بررسی میکند.
راهحل اول: استفاده از Git LFS (پیشنهاد اصلی)
Git LFS (مخفف Large File Storage) یک افزونهٔ رسمی از گیتهاب است که فایلهای حجیم را با یک اشارهگر (pointer) در مخزن جایگزین میکند و خود فایل را در سرور اختصاصی LFS ذخیره میسازد. این روش هم تاریخچه را حفظ میکند و هم مخزن شما را سبک نگه میدارد.
مراحل انجام کار در VS Code
۱. نصب Git LFS
اگر روی ویندوز هستید، از سایت git-lfs.github.com فایل نصبی را دانلود کنید. روی مک و لینوکس هم با دستورهای زیر نصب میشود:
# macOS
brew install git-lfs
# Linux (Debian/Ubuntu)
sudo apt install git-lfs۲. فعالسازی LFS در مخزن
ترمینال VS Code را باز کنید و اجرا کنید:
git lfs install۳. تعیین نوع فایلهای تحت نظارت LFS
مثلاً برای همهٔ فایلهای MP3:
git lfs track "*.mp3"این دستور فایل .gitattributes را میسازد یا بهروز میکند. حتماً این فایل را به گیت اضافه کنید:
git add .gitattributes۴. مهاجرت تاریخچه به LFS
برای اینکه فایلهای MP3 قدیمی هم به LFS منتقل شوند، از دستور زیر استفاده کنید:
git lfs migrate import --include="*.mp3" --everythingاین دستور تمام کامیتها را بازنویسی میکند و فایلهای MP3 را به LFS تبدیل مینماید. اگر فقط آخرین کامیت را میخواهید اصلاح کنید، میتوانید از --include-ref=main استفاده کنید.
۵. ارسال به گیتهاب
حالا دیگر خطای حجم را نخواهید داشت. با خیال راحت push کنید:
git push origin mainنکته مهم: گیتهاب به هر مخزن ۱ گیگابایت فضای رایگان برای LFS میدهد. اگر از این مقدار بیشتر شود، باید بستهٔ اضافی خریداری کنید. همچنین همتیمیهای شما هم باید Git LFS را نصب کنند تا فایلها را بهدرستی دریافت کنند.
راهحل دوم: حذف فایل از تاریخچه با دستور reset (وقتی نمیخواهید فایل را در گیت نگه دارید)
اگر به هر دلیلی نمیخواهید آن فایل بزرگ را در مخزن نگهداری کنید (مثلاً قصد دارید آن را روی یک هاست جداگانه قرار دهید و فقط لینک آن را در سایت بیاورید)، میتوانید آن را بهکلی از تاریخچه پاک کنید.
من در VS Code دقیقاً از این روش استفاده کردم، چون چند کامیت پشت سر هم ایجاد شده بود و نمیخواستم آنها را یکبهیک ویرایش کنم.
پاکسازی 1 کامیت آخر با reset —hard
فرض کنید متوجه شدید که فایل بزرگ در کامیت پنجم قبل اضافه شده و پنج کامیت جدید روی آن ساخته شده است. با دستور زیر میتوانید به وضعیت قبل از آن کامیت برگردید و همهٔ آن ۵ کامیت را یکجا حذف کنید:
git reset --hard HEAD~1این دستور:
- HEAD را 1 کامیت به عقب میبرد
- همهٔ تغییرات آن 1 کامیت را از روی دیسک پاک میکند (دقت کنید که فایلها برای همیشه حذف میشوند، مگر اینکه قبلاً پشتیبان گرفته باشید)
اگر نمیخواهید فایلهای تغییر یافته از دیسک پاک شوند، از --soft استفاده کنید تا فقط کامیتها حذف شوند و تغییرات در منطقهٔ Stage باقی بمانند:
git reset --soft HEAD~1سپس میتوانید فایل مزاحم را با git rm --cached از Stage خارج کنید و یک کامیت جدید بسازید.
حذف فایل از آخرین کامیت بدون بازنویسی کل تاریخچه
اگر فقط آخرین کامیت مشکل دارد، بهترین راه استفاده از amend است:
۱. فایل را از ایندکس خارج کنید (روی دیسک باقی میماند):
git rm --cached file.mp3۲. آخرین کامیت را اصلاح کنید:
git commit --amend --no-edit۳. فایل را به .gitignore اضافه کنید تا دوباره اضافه نشود:
echo "*.mp3" >> .gitignore
git add .gitignore
git commit --amend --no-edit۴. حالا push کنید:
git push origin mainمقایسه دو روش
| معیار | Git LFS | حذف با reset |
|---|---|---|
| حفظ تاریخچه فایل | ✅ بله | ❌ خیر |
| نیاز به نصب افزونه | ✅ بله | ❌ خیر |
| فضای ذخیرهسازی در گیتهاب | از فضای LFS جداگانه استفاده میکند | در خود مخزن ذخیره نمیشود |
| مناسب برای | فایلهایی که باید نسخهگذاری شوند | فایلهای موقت یا قابل هاست خارجی |
| تأثیر روی همتیمیها | باید LFS نصب کنند | نیازی نیست |
| پیچیدگی اجرا | متوسط | ساده |
تجربه عملی من در VS Code
من در محیط VS Code و با استفاده از ترمینال داخلی، ابتدا چند کامیت انجام دادم که آخرین آنها شامل فایل MP3 بود. هنگام push خطا خورد. ابتدا فکر کردم با reset --hard HEAD~1 یک کامیت را حذف کنم و دوباره کامیت کنم، اما دیدم که فایل هنوز در آخرین کامیت باقی مانده است.
سپس از git rm --cached و git commit --amend استفاده کردم و فایل را از آن کامیت حذف کردم. بعد از آن push بهراحتی انجام شد.
اگر قصد داشتم آن فایل را برای همیشه در گیتهاب نگهداری کنم، حتماً از Git LFS استفاده میکردم، چون هم تاریخچه حفظ میشود و هم از محدودیت ۱۰۰ مگابایت عبور میکند.
نکات امنیتی و هماهنگی تیمی
اگر با تیم کار میکنید
- قبل از هر گونه بازنویسی تاریخچه (reset، amend، rebase) با اعضای تیم هماهنگ کنید، چون هش کامیتها تغییر میکند و ممکن است باعث بروز Conflict شود.
- اگر از
reset --hardاستفاده میکنید، حتماً قبل از آن یک Branch پشتیبان بگیرید یا ازstashاستفاده کنید تا تغییرات ناخواسته از دست نرود.
فضای LFS رایگان
گیتهاب به ازای هر مخزن ۱ گیگابایت فضای LFS رایگان ارائه میدهد. اگر بیش از این نیاز دارید، میتوانید بستههای اضافی خریداری کنید. همچنین اگر مخزن شما عمومی باشد، فضای LFS رایگان بیشتری هم تعلق میگیرد.
جمعبندی
برخورد با خطای حجم فایل در گیتهاب ممکن است در ابتدا ترسناک به نظر برسد، اما با ابزارهای مناسب بهراحتی قابل حل است:
- اگر نیاز به نگهداری فایلهای حجیم در مخزن دارید، Git LFS بهترین گزینه است.
- اگر فایل موقتی است یا میتوانید آن را خارج از گیت هاست کنید، با
resetوamendتاریخچه را پاک کنید.
در هر دو حالت، همیشه قبل از بازنویسی تاریخچه از پروژه خود بکاپ بگیرید تا در صورت بروز مشکل، بتوانید به حالت قبل برگردید.
اگر سؤال یا تجربهای در این زمینه دارید، خوشحال میشویم در بخش نظرات با ما در میان بگذارید.
آیا شما هم با خطای حجم فایل در گیتهاب مواجه شدهاید؟ از کدام روش برای رفع آن استفاده کردید؟
برای مطالعه بیشتر: