گیت LFS (ذخیره‌سازی فایل بزرگ)

Git LFS (Large File Storage) یک افزونه Git برای نسخه‌بندی فایل‌های بزرگ مثل تصاویر، ویدیوها، مجموعه داده‌ها و باینری‌ها است. به جای ذخیره مستقیم این فایل‌ها در Git، LFS اشاره‌گرها را در مخزن و فایل‌های واقعی را روی سرور از راه دور ذخیره می‌کند.

نصب Git LFS

Windows

winget install GitLFS

یا از git-lfs.github.com دانلود کنید

macOS

brew install git-lfs

Linux

sudo apt-get install git-lfs

مقداردهی اولیه

git lfs install

استفاده از Git LFS با گیتی‌یار

ردیابی انواع فایل

به Git بگویید کدام فایل‌ها را با LFS ردیابی کند:

# ردیابی تمام فایل‌های PSD
git lfs track "*.psd"

# ردیابی تمام فایل‌های MP4
git lfs track "*.mp4"

# ردیابی تمام فایل‌ها در یک پوشه
git lfs track "assets/*"

# ردیابی فایل بزرگ خاص
git lfs track "dataset.csv"

این فایل .gitattributes را ایجاد یا به‌روز می‌کند:

*.psd filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text

Commit و Push

# افزودن .gitattributes
git add .gitattributes

# افزودن فایل‌های بزرگ
git add large-file.psd

# Commit
git commit -m "افزودن فایل بزرگ با LFS"

# Push (فایل‌های LFS به‌طور خودکار آپلود می‌شوند)
git push origin main

مدیریت فایل‌های LFS

لیست فایل‌های ردیابی‌شده

git lfs track

لیست فایل‌های LFS در مخزن

git lfs ls-files

مشاهده وضعیت LFS

git lfs status

Pull فایل‌های LFS

# Pull تمام فایل‌های LFS
git lfs pull

# Pull branch خاص
git lfs pull origin feature-branch

Fetch فایل‌های LFS

git lfs fetch --all

تنظیمات LFS در گیتی‌یار

فعال‌سازی LFS

LFS به‌طور پیش‌فرض در گیتی‌یار فعال است. برای تأیید:

1. به تنظیمات مخزن بروید
2. بررسی کنید "فعال‌سازی Git LFS" تیک خورده باشد

ذخیره‌سازی LFS

فایل‌های LFS ذخیره می‌شوند در:

data/lfs/

محدودیت‌های ذخیره‌سازی

محدودیت‌های ذخیره‌سازی را در app.ini پیکربندی کنید:

[repository.upload]
LFS_MAX_FILE_SIZE = 104857600  # 100MB
LFS_MAX_STORAGE = 10737418240  # 10GB برای هر مخزن

مهاجرت به LFS

تبدیل فایل‌های موجود به LFS

از git lfs migrate استفاده کنید:

# مهاجرت تمام فایل‌های PSD
git lfs migrate import --include="*.psd"

# مهاجرت انواع فایل متعدد
git lfs migrate import --include="*.psd,*.mp4,*.zip"

# مهاجرت و بازنویسی تاریخچه
git lfs migrate import --include="*.psd" --everything

⚠️ هشدار: بازنویسی تاریخچه hash های commit را تغییر می‌دهد!

Push پس از مهاجرت

git push --force

بهترین شیوه‌ها

چه زمانی از LFS استفاده کنیم

• ✅ فایل‌های بزرگتر از 50MB
• ✅ فایل‌های باینری (تصاویر، ویدیوها، صدا)
• ✅ مجموعه داده‌ها و آرشیوها
• ✅ باینری‌های کامپایل‌شده
• ✅ فایل‌های طراحی (PSD، AI، Sketch)

چه زمانی از LFS استفاده نکنیم

• ❌ فایل‌های کد منبع
• ❌ فایل‌های پیکربندی
• ❌ مستندات
• ❌ فایل‌های متنی کوچک
• ❌ فایل‌هایی که نیاز به diff دارند

نکات عمومی

• ردیابی انواع فایل، نه فایل‌های فردی
• .gitattributes را به‌روز نگه دارید
• استفاده از ذخیره‌سازی LFS را مانیتور کنید
• فایل‌های LFS استفاده‌نشده را دوره‌ای پاک کنید
• استفاده از LFS را برای تیم مستند کنید

عیب‌یابی

مسائل رایج

"اشیاء LFS یافت نشد":

git lfs fetch --all
git lfs checkout

"فضای دیسک ناکافی":

• پاک‌سازی cache LFS: git lfs prune
• افزایش محدودیت‌های ذخیره‌سازی
• حذف فایل‌های LFS غیرضروری

"احراز هویت ناموفق":

• اعتبارنامه‌ها را تأیید کنید
• URL endpoint LFS را بررسی کنید
• اطمینان حاصل کنید LFS فعال است

clone/pull کند:

• از clone کم‌عمق استفاده کنید: git clone --depth 1
• بدون LFS: GIT_LFS_SKIP_SMUDGE=1 git clone
• LFS را بعداً pull کنید: git lfs pull

بررسی اشاره‌گرهای LFS

اگر فایل‌ها به جای محتوای واقعی به عنوان اشاره‌گر نشان داده می‌شوند:

# دانلود فایل‌های LFS
git lfs pull

# تأیید فایل
git lfs fsck

پاک‌سازی Cache LFS

حذف اشیاء قدیمی LFS:

# پیش‌نمایش آنچه حذف خواهد شد
git lfs prune --dry-run

# حذف اشیاء قدیمی
git lfs prune

مرجع دستورات LFS

دستور	توضیح
git lfs install	مقداردهی اولیه LFS
git lfs track	ردیابی الگوهای فایل
git lfs ls-files	لیست فایل‌های LFS
git lfs status	نمایش وضعیت LFS
git lfs pull	دانلود فایل‌های LFS
git lfs fetch	Fetch اشیاء LFS
git lfs push	Push اشیاء LFS
git lfs prune	پاک‌سازی اشیاء قدیمی
git lfs migrate	مهاجرت فایل‌ها به LFS
git lfs fsck	تأیید اشیاء LFS

مراحل بعدی

• درباره مهاجرت بیاموزید
• API را کاوش کنید
• سوالات متداول را بخوانید