Git LFS: cara menyimpan file besar di repositori Git

Apa itu Git LFS dan mengapa diperlukan

Git LFS (Large File Storage) adalah ekstensi resmi Git untuk menyimpan file besar: video, desain PSD, dataset, model jaringan saraf, dan aset game. Alih-alih menyimpan isi file di dalam commit, Git hanya memasukkan pointer teks berukuran sekitar 130 byte, sedangkan isi file dikirim ke penyimpanan LFS di server. Saat checkout, ekstensi ini menggantikan pointer dengan file asli di direktori kerja, sehingga bagi Anda semuanya terlihat seperti Git biasa.

Masalah yang diselesaikan git lfs berasal dari cara kerja Git itu sendiri. Setiap versi setiap file tersimpan selamanya di riwayat, dan saat klon dibuat seluruh riwayat diunduh. Jika Anda mengganti video 200 MB sepuluh kali, repositori sudah sekitar 2 GB, dan setiap pengembang baru harus mengunduh sepuluh versi itu, walaupun yang ia butuhkan hanya yang terbaru. Kompresi dan delta yang bekerja baik untuk teks hampir tidak membantu pada file biner.

Dengan LFS, saat klon dibuat hanya versi file besar untuk commit saat ini yang diunduh. Versi lama tetap tersimpan di server dan diambil ketika Anda berpindah ke commit lama.

Cara kerja Git LFS di dalam

Mekanismenya dibangun di atas filter Git: clean dan smudge. Saat Anda menjalankan git add pada file yang dilacak LFS, filter clean bekerja: isi file disimpan ke cache lokal .git/lfs/objects, lalu pointer dimasukkan ke index. Saat checkout, filter smudge melakukan kebalikannya: objek dicari berdasarkan hash di cache (atau diunduh dari server), lalu file asli ditulis ke direktori kerja.

Bentuk pointer-nya seperti ini:

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

Tiga baris: versi spesifikasi, SHA-256 isi file, dan ukuran dalam byte. Hanya inilah yang tersimpan di riwayat Git, sehingga riwayat tetap ringan. Saat git push, hook pre-push berjalan: objek LFS baru diunggah lewat LFS API lebih dulu, lalu commit dikirim dengan protokol Git biasa.

File mana yang diserahkan ke LFS ditentukan oleh berkas .gitattributes di root repositori. Berkas ini di-commit bersama kode, sehingga aturannya sama untuk seluruh tim.

Cara memasang Git LFS

Di Git untuk Windows, ekstensi ini sudah termasuk dalam installer. Di macOS dan Linux, pasang lewat manajer paket:

# macOS (Homebrew)
brew install git-lfs

# Debian / Ubuntu
sudo apt install git-lfs

# Fedora
sudo dnf install git-lfs

Setelah dipasang, jalankan sekali untuk pengguna Anda:

git lfs install

Perintah ini menambahkan filter LFS ke ~/.gitconfig global, dan memasang hook di repositori saat ini jika Anda berada di dalamnya. Untuk memastikan semuanya terpasang, jalankan git lfs version; konfigurasi lengkap (alamat server, lokasi cache) ditampilkan oleh git lfs env.

Cara mulai melacak file besar

Skenario tipikal untuk proyek baru:

git lfs track "*.psd"
git lfs track "*.mp4"
git lfs track "models/**"

git add .gitattributes
git add design/banner.psd
git commit -m "Tambahkan desain banner lewat LFS"
git push origin main

Tanda kutip di sekitar pola wajib dipakai. Tanpanya, shell akan memperluas *.psd menjadi daftar file di folder saat ini, dan aturannya menjadi salah. Setelah git lfs track, baris berikut muncul di .gitattributes:

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

Atribut -text menonaktifkan konversi akhir baris yang akan merusak file biner. Urutannya penting: pertama aturan track, baru git add file. Jika file sudah telanjur ditambahkan dengan cara biasa sebelum aturan ada, file itu tetap tersimpan di riwayat sebagai blob biasa.

Cara memastikan file benar-benar masuk LFS

git lfs ls-files
4d7a214614 * design/banner.psd
9c1e0b7a3f * video/intro.mp4

git lfs status

git lfs ls-files menampilkan file di commit saat ini yang disimpan di LFS. Tanda bintang berarti isinya sudah diunduh, tanda strip berarti di salinan kerja hanya ada pointer. Daftar pola yang dilacak ditampilkan oleh git lfs track tanpa argumen, dan aturan dihapus dengan git lfs untrack "*.psd".

Klon dan mengambil file

git clone biasa bekerja dengan LFS secara transparan: jika ekstensinya terpasang, file besar diunduh otomatis. Jika rekan Anda belum memasang LFS, di salinan kerjanya ia akan melihat teks pointer alih-alih gambar atau PSD. Ini gejala paling umum dari keluhan «di komputer saya file PSD isinya malah teks». Solusinya adalah memasang LFS lalu menjalankan:

git lfs install
git lfs pull

git lfs pull mengunduh objek untuk commit saat ini dan menaruhnya di direktori kerja. Ada juga git lfs fetch, yang hanya mengunduh ke cache tanpa mengubah file. Dengan --all, objek untuk semua referensi diunduh, berguna untuk cadangan penuh atau pemindahan ke server lain.

Cara mengklon tanpa file besar

Di CI, atau jika Anda hanya butuh kodenya, mengunduh gigabyte aset tidak perlu. Variabel lingkungan berikut menonaktifkan filter smudge:

GIT_LFS_SKIP_SMUDGE=1 git clone https://example.com/team/game.git
cd game
git lfs pull --include="textures/ui/**"

Repositori diklon dengan pointer, lalu Anda mengambil file yang dibutuhkan secara selektif dengan --include (ada juga --exclude). Cara ini mempercepat build di pipeline secara nyata.

Memindahkan file yang sudah ada ke Git LFS

Situasi umum: repositori sudah membengkak dan file besar tersimpan di riwayat. Perintah git lfs track tidak berpengaruh pada masa lalu; ia hanya berlaku untuk commit baru. Untuk menulis ulang riwayat, gunakan git lfs migrate.

Pertama, lihat apa yang memakan tempat:

git lfs migrate info --everything --top=10

Lalu pindahkan jenis file yang dimaksud di semua branch:

git lfs migrate import --include="*.psd,*.mp4" --everything
git push --force --all
git push --force --tags

Migrasi menulis ulang setiap commit yang memuat file tersebut, sehingga semua hash berubah. Ini sama seperti rebase pada branch yang sudah dipublikasikan: semua anggota tim harus diberi tahu, dan setelah force push mereka harus mengklon ulang repositori atau mereset branch mereka secara paksa. Buat cadangan sebelum migrasi dengan git clone --mirror.

Jika riwayat tidak boleh ditulis ulang, ada opsi yang lebih lunak: git lfs migrate import --no-rewrite path/ke/file. Perintah ini membuat commit baru yang memindahkan file ke LFS mulai saat itu. Versi lama tetap ada di riwayat, tetapi pertumbuhan repositori berhenti.

Penguncian file: mencegah konflik pada biner

Dua desainer mengedit PSD yang sama, dan Git tidak bisa menggabungkan perubahan mereka. Satu pekerjaan akan hilang. Untuk kasus seperti ini, LFS menyediakan lock. Tandai jenis file sebagai dapat dikunci:

git lfs track "*.psd" --lockable

Atribut lockable ditambahkan ke .gitattributes, dan file seperti ini di salinan kerja hanya bisa dibaca sampai Anda menguncinya:

git lfs lock design/banner.psd
git lfs locks
design/banner.psd	anna	ID:123

# setelah push perubahan
git lfs unlock design/banner.psd

Selama file terkunci, push perubahan ke file itu dari orang lain akan ditolak. Kunci dikelola oleh server, sehingga fitur ini bekerja di hosting Git besar, tetapi mungkin tidak tersedia di server buatan sendiri. Administrator dapat membuka kunci orang lain dengan git lfs unlock --force.

Di mana objek LFS disimpan dan berapa biayanya

Objek LFS berada di server yang mendukung LFS API. Layanan hosting Git populer dan solusi self-hosted menyediakannya, begitu pula server khusus. Layanan hosting cloud memberlakukan batas penyimpanan dan trafik LFS, dan batas ini berbeda antar-layanan dan paket, jadi periksa ketentuan platform Anda sebelum mengunggah dataset ratusan gigabyte.

Perlu diingat bahwa trafik dihitung setiap kali file diunduh. CI yang mengklon repositori dengan file LFS pada setiap commit bisa lebih cepat mencapai batas dibanding manusia. Simpan .git/lfs di cache antar-build, atau gunakan GIT_LFS_SKIP_SMUDGE.

Cache lokal juga bertambah. Perintah git lfs prune menghapus objek lama yang sudah ada di server dan tidak dibutuhkan lagi untuk commit saat ini maupun yang baru.

Kapan Git LFS cocok dan kapan tidak

Kesalahan umum dan cara memperbaikinya

Di salinan kerja muncul teks pointer, bukan file

LFS belum terpasang, atau klon dibuat dengan GIT_LFS_SKIP_SMUDGE=1. Jalankan git lfs install lalu git lfs pull.

File masuk ke riwayat tanpa lewat LFS

Aturan track ditambahkan setelah git add. Jika commit belum dikirim, keluarkan file dari index (git rm --cached file), pastikan aturannya ada di .gitattributes, lalu tambahkan lagi. Jika sudah dikirim, gunakan git lfs migrate import. Untuk mencari file semacam ini, git lfs fsck --pointers membantu.

Push ditolak karena ukuran file

Banyak hosting membatasi ukuran satu objek di Git biasa. Pesan seperti «this exceeds the file size limit» berarti file seharusnya diserahkan ke LFS. Tulis ulang commit terakhir atau riwayat seperti dijelaskan di atas. Commit biasa berisi «hapus file» tidak akan membantu, karena file tetap ada di commit sebelumnya.

Setelah git lfs migrate, rekan tim mengalami masalah

Branch lokal mereka berbasis hash lama. Cara paling andal adalah mengklon ulang repositori; jika ada pekerjaan yang belum di-push, pindahkan lewat cherry-pick ke branch baru.

Contekan perintah Git LFS

Ringkasan

Git LFS memindahkan file biner besar dari riwayat ke penyimpanan terpisah, dan commit hanya menyimpan pointer yang ringan. Aturan utamanya: atur git lfs track sebelum commit file besar pertama, selalu commit .gitattributes, dan pantau kuota hosting. Jika file sudah ada di riwayat, git lfs migrate bisa membantu, tetapi itu berarti menulis ulang riwayat dengan segala konsekuensinya. Bekerja dengan riwayat, rebase, dan alat Git lanjutan dibahas dengan praktik dalam kursus Git.