Git LFS — przechowywanie dużych plików w repozytoriach Git

Opublikowano: 10 kwietnia 2026 · Kategoria: Hosting

Repozytorium Git, które kiedyś ważyło 50 MB, po roku pracy z grafikami i nagraniami może urosnąć do kilku GB. Każda zmiana pliku binarnego (PSD, MP4, model 3D) trafia do historii jako pełna kopia — Git nie robi diff na plikach binarnych. Klonowanie takiego repo trwa minuty, CI/CD jeszcze dłużej. Git LFS rozwiązuje ten problem: zamiast przechowywać dane binarne w Git, zapisuje tam tylko lekkie wskaźniki (pointers), a rzeczywiste dane trzyma na dedykowanym serwerze LFS. Ten artykuł pokazuje instalację, konfigurację .gitattributes, migrację istniejących repozytoriów i self-hosted LFS przez Gitea.

Instalacja Git LFS

# Ubuntu / Debian
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt install git-lfs

# macOS (Homebrew)
brew install git-lfs

# Windows
# Pobierz installer z git-lfs.com lub uzywaj GitHub Desktop (ma LFS wbudowane)

# Aktywacja Git LFS globalnie (raz na uzytkownika)
git lfs install
# Updated git hooks.
# Git LFS initialized.

# Sprawdz instalacje
git lfs version
# git-lfs/3.5.1 (GitHub; linux amd64; go 1.22.0)

Konfiguracja .gitattributes — śledzenie typów plików

Deklarujesz które typy plików mają być śledzone przez LFS w pliku .gitattributes. Git automatycznie stosuje LFS dla nowych plików pasujących do wzorca. Plik .gitattributes commitujesz razem z kodem — obowiązuje wszystkich w zespole.

# Dodaj wzorce przez CLI (automatycznie edytuje .gitattributes)
git lfs track "*.psd"
git lfs track "*.ai"
git lfs track "*.mp4" "*.mov" "*.avi"
git lfs track "*.png" "*.jpg" "*.gif"   # tylko duze grafiki
git lfs track "*.zip" "*.tar.gz"
git lfs track "*.jar" "*.war" "*.exe"
git lfs track "models/**"               # cały katalog modeli 3D

# Wygenerowany .gitattributes:
*.psd filter=lfs diff=lfs merge=lfs -text
*.ai filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text
*.png filter=lfs diff=lfs merge=lfs -text
*.jar filter=lfs diff=lfs merge=lfs -text
models/** filter=lfs diff=lfs merge=lfs -text

# PAMIETAJ: .gitattributes commituj!
git add .gitattributes
git commit -m "chore: configure Git LFS tracking"

# Sprawdz co jest sledzone przez LFS
git lfs track

# Sprawdz status LFS w repozytorium
git lfs status

Jak działa pointer LFS — podgląd

Gdy dodasz plik PNG śledzony przez LFS i zrobisz commit, w historii Git zapisany zostaje mały plik tekstowy (pointer) zamiast binarnych danych. Rzeczywiste dane trafiają do serwera LFS. Pointer wygląda tak:

version https://git-lfs.github.com/spec/v1
oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
size 12345678

Migracja istniejących plików do LFS

Jeśli masz repozytorium z już dodanymi dużymi plikami, użyj git lfs migrate. Przepisuje historię — wykonaj backup i uzgodnij z zespołem!

# Backup repozytorium PRZED migracją
git clone --mirror [email protected]:user/myrepo.git myrepo-backup

# Sprawdz które pliki sa najwyzszej - znajdz kandydatow do LFS
git lfs migrate info --everything

# Migruj konkretne rozszerzenia (PRZEPISUJE HISTORIĘ)
git lfs migrate import --include="*.psd,*.mp4,*.jar" --everything

# Lub migruj pliki powyzej progu rozmiaru
git lfs migrate import --above=10mb --everything

# Po migracji sprawdz rozmiar repozytorium
git count-objects -vH

# Opublikuj przepisaną historię (force push!)
git push --force origin --all
git push --force origin --tags

# Wszyscy wspolpracownicy muszą:
git pull --rebase
# lub
git clone (świeże klonowanie)

Self-hosted LFS przez Gitea

Gitea ma wbudowany serwer LFS — włączenie to zmiana jednej opcji w app.ini. Dane LFS są przechowywane na dysku serwera Gitea (lub na S3-compatible storage dla dużych instalacji).

# /etc/gitea/app.ini lub /data/gitea/conf/app.ini

[lfs]
ENABLED = true
PATH    = /var/lib/gitea/data/lfs  ; katalog przechowywania
; Opcjonalnie: S3-compatible storage (MinIO, AWS S3)
; STORAGE_TYPE = minio
; MINIO_ENDPOINT = minio.example.com
; MINIO_ACCESS_KEY_ID = klucz
; MINIO_SECRET_ACCESS_KEY = sekret
; MINIO_BUCKET = gitea-lfs

# Limit rozmiaru pojedynczego pliku LFS (domyslnie bez limitu)
[repository]
LFS_MAX_FILE_SIZE = 0  ; 0 = bez limitu, lub np. 5368709120 (5GB)

# Po zmianie konfiguracji:
sudo systemctl restart gitea

# Sprawdz pojemnosc LFS na koncie Gitea
# UI: Admin Panel → System Status → LFS Objects

Limity i polityki przechowywania

Platforma	Darmowy limit LFS	Koszt dodatkowego storage	Max rozmiar pliku
GitHub	1 GB storage + 1 GB bandwidth	$5/msc (50 GB + 50 GB)	2 GB
GitLab.com	5 GB storage	$60/rok (10 GB)	5 GB
Gitea (self-hosted)	Brak limitu (dysk VPS)	Koszt VPS/dysku	Konfigurowalne
Bitbucket	1 GB (Free)	W planie Premium	Zależnie od planu

Przydatne komendy Git LFS

# Lista wszystkich plikow LFS w repo
git lfs ls-files

# Pobierz wszystkie pliki LFS (gdy brakowalo przy clone)
git lfs pull

# Pobierz LFS dla konkretnej gałęzi
git lfs fetch origin main

# CI/CD: pomiń pobieranie plików LFS (tylko pointery)
GIT_LFS_SKIP_SMUDGE=1 git clone [email protected]:user/repo.git

# Usuń lokalny cache LFS (zwolnij miejsce na deweloperskiej maszynie)
git lfs prune

# Sprawdz stan serwera LFS
git lfs env

# Zweryfikuj integralnosc wszystkich plikow LFS
git lfs fsck

Najczęstsze pytania

Czym jest Git LFS i kiedy go używać? +

Git LFS (Large File Storage) to rozszerzenie Git, które zastępuje duże pliki w repozytorium wskaźnikami (pointers), a faktyczne dane przechowuje na zewnętrznym serwerze LFS. Używaj go gdy repozytorium zawiera pliki binarne: grafiki (PSD, AI), modele 3D, nagrania audio/wideo, skompilowane pliki (*.jar, *.exe), zbiory danych ML. Bez LFS każda zmiana dużego pliku binarnego trafia do historii Git i rozrasta repozytorium na GigaBajty.

Jak Git LFS wpływa na wydajność clone? +

Git LFS przyspiesza clone repozytoriów z dużymi plikami, bo domyślnie pobiera tylko bieżące wersje plików LFS (nie całą historię). Możesz też użyć git lfs fetch --recent lub --all aby kontrolować ile historii LFS pobrać. W CI/CD, gdzie nie potrzebujesz plików LFS, użyj GIT_LFS_SKIP_SMUDGE=1 przed git clone — pliki LFS pojawią się jako pointers, a clone będzie błyskawiczny.

Jak zmigrować istniejące duże pliki do Git LFS? +

Używasz git lfs migrate import --include="*.psd,*.mp4" --everything. To przepisuje historię Git (podobnie jak git filter-branch), zastępując duże pliki pointerami LFS we wszystkich commitach. UWAGA: przepisuje historię, więc wszyscy współpracownicy muszą wykonać git pull --rebase lub sklonować repo na nowo. Backup repozytorium przed migracją jest obowiązkowy.

Czy można hostować LFS server samodzielnie? +

Tak. Gitea ma wbudowany LFS server (włącz [lfs] enabled = true w app.ini). Istnieją też dedykowane serwery: git-lfs-s3-proxy (przechowuje na S3/MinIO), lfs-server-go i inne. Docker Registry Harbor nie obsługuje LFS. GitHub i GitLab mają własne serwery LFS. Self-hosted LFS przez Gitea to najprostsze rozwiązanie — jeden serwer obsługuje Git + LFS.