Git LFS: paano mag-imbak ng malalaking file sa Git repository

Ano ang Git LFS at bakit ito kailangan

Ang Git LFS (Large File Storage) ay opisyal na extension ng Git para sa malalaking file: video, PSD na mock-up, dataset, model ng neural network, at game asset. Sa halip na buong file, ang inilalagay sa commit ay text pointer na mga 130 byte, at ang aktwal na nilalaman ay napupunta sa hiwalay na LFS storage sa server. Sa checkout, ilalagay ng extension ang totoong file sa working directory, kaya para sa inyo, normal lang ang itsura ng lahat.

Ang problemang nilulutas ng git lfs ay nasa mismong disenyo ng Git. Nananatili sa history magpakailanman ang bawat bersyon ng bawat file, at kapag nag-clone, kinukuha ang buong history. Kung sampung beses ninyong pinalitan ang 200 MB na video, aabot na sa humigit-kumulang 2 GB ang repository, at dina-download ng bawat bagong developer ang sampung bersyon kahit ang pinakahuli lang ang kailangan. Ang compression at delta na mahusay sa text ay halos walang silbi sa binary file.

Sa LFS, sa pag-clone, nada-download lang ang mga bersyon ng malalaking file para sa kasalukuyang commit. Nasa server ang mga lumang bersyon at kinukuha lang kapag lumipat kayo sa lumang commit.

Paano gumagana ang Git LFS sa loob

Nakabatay ang mekanismo sa Git filter: ang clean at smudge. Kapag nag-git add kayo ng file na tinatrack ng LFS, tatakbo ang clean filter: inilalagay nito ang nilalaman sa lokal na cache na .git/lfs/objects, at ang pointer ang ipinapasa sa index. Sa checkout, ginagawa ng smudge filter ang kabaligtaran: hinahanap ang object ayon sa hash sa cache (o dinadownload sa server) at isinusulat ang totoong file.

Ganito ang itsura ng pointer:

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

Tatlong linya: bersyon ng spesipikasyon, SHA-256 ng nilalaman, at laki sa byte. Ito ang nakaimbak sa history ng Git, kaya nananatiling magaan ang history. Sa git push, tatakbo ang pre-push hook: unang ina-upload ang mga bagong LFS object sa pamamagitan ng LFS API, at pagkatapos ay ipinapadala ang mga commit sa karaniwang protocol.

Ang mga file na ibibigay sa LFS ay tinutukoy ng .gitattributes file sa root ng repository. Ina-commit ito kasama ng code, kaya pareho ang tuntunin para sa buong team.

Paano i-install ang Git LFS

Sa Git para sa Windows, kasama na ang extension sa installer. Sa macOS at Linux, ini-install ito bilang package:

# macOS (Homebrew)
brew install git-lfs

# Debian / Ubuntu
sudo apt install git-lfs

# Fedora
sudo dnf install git-lfs

Pagkatapos ma-install, isang beses lang patakbuhin para sa user:

git lfs install

Inilalagay ng command ang mga LFS filter sa global na ~/.gitconfig at nagse-set ng hook sa kasalukuyang repository, kung nasa loob kayo nito. Para tingnan kung kumpleto ang lahat, patakbuhin ang git lfs version, at ang detalyadong configuration (address ng server, path ng cache) ay ipinapakita ng git lfs env.

Paano magsimulang mag-track ng malalaking file

Karaniwang sitwasyon para sa bagong project:

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

git add .gitattributes
git add design/banner.psd
git commit -m "Idagdag ang banner mock-up gamit ang LFS"
git push origin main

Kailangan ang quotes sa paligid ng pattern: kung wala ang mga ito, palalawakin ng shell ang *.psd sa listahan ng mga file sa kasalukuyang folder, at magiging mali ang tuntunin. Pagkatapos ng git lfs track, may lalabas na linya sa .gitattributes:

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

Pinapatay ng attribute na -text ang conversion ng line ending, na sisira sana sa binary file. Mahalaga ang pagkakasunod-sunod: una ang track rule, tapos ang git add ng file. Kung naidagdag na ang file sa normal na paraan bago ang rule, mananatili ito sa history bilang karaniwang blob.

Paano tingnan na nasa LFS ang file

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

git lfs status

Ipinapakita ng git lfs ls-files ang mga file ng kasalukuyang commit na nasa LFS. Ang asterisk ay nangangahulugang na-download na ang nilalaman; ang dash ay nangangahulugang pointer lang ang nasa working copy. Ang listahan ng mga pattern ng pagsubaybay ay makikita sa git lfs track nang walang argumento, at maaaring alisin ang rule gamit ang git lfs untrack "*.psd".

Pag-clone at pagkuha ng mga file

Gumagana nang transparent ang karaniwang git clone kasama ang LFS: kung naka-install ang extension, awtomatikong nada-download ang malalaking file. Pero kung walang LFS ang katrabaho ninyo, makikita niya sa working copy ang mga text pointer sa halip na mga larawan; ito ang pinakakaraniwang sintomas ng "bakit text ang nasa PSD ko". Ang lunas ay ang pag-install at ang command:

git lfs install
git lfs pull

Dina-download ng git lfs pull ang mga object para sa kasalukuyang commit at inilalagay ang mga ito sa working directory. Mayroon ding hiwalay na git lfs fetch, na nagda-download lang sa cache nang hindi ginagalaw ang mga file. Kapag may flag na --all, dina-download ang mga object para sa lahat ng reference, kapaki-pakinabang para sa buong backup o paglipat sa ibang server.

Paano mag-clone nang walang malalaking file

Sa CI o kapag code lang ang kailangan, hindi kailangang mag-download ng gigabyte ng asset. Pinapatay ng environment variable ang smudge filter:

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

Naka-clone ang repository na may pointer, at pagkatapos ay pipiliin ninyo ang mga kailangang file gamit ang --include (may --exclude din). Malaki ang nababawas sa oras ng build sa pipeline.

Paano ilipat ang mga umiiral nang file sa Git LFS

Karaniwang kaso: lumaki na ang repository at nasa history na ang malalaking file. Hindi nakakaapekto sa nakaraan ang git lfs track; sa mga bagong commit lang ito gumagana. Para baguhin ang history, gamitin ang git lfs migrate.

Una, alamin kung ano ang kumukuha ng espasyo:

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

Pagkatapos, ilipat ang mga kailangang uri sa lahat ng branch:

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

Ang migrasyon ay muling isinusulat ang bawat commit kung saan lumitaw ang mga file na iyon, kaya magbabago ang lahat ng hash. Kapareho ito ng sitwasyon sa rebase ng nai-publish na branch: kailangang bigyan ng babala ang lahat ng kalahok, at pagkatapos ng force push, kailangan nilang i-clone ulit ang repository o i-reset nang mahigpit ang kanilang mga branch. Bago ang migrasyon, gumawa ng backup (git clone --mirror).

Kung hindi maaaring isulat ulit ang history, may mas banayad na opsyon: git lfs migrate import --no-rewrite path/to/file. Gumagawa ito ng bagong commit na naglilipat ng mga file sa LFS mula sa puntong iyon. Mananatili sa history ang lumang bersyon, pero titigil na ang paglaki ng repository.

Pag-lock ng file: proteksyon laban sa conflict sa binary

Dalawang designer ang nag-e-edit ng iisang PSD: hindi ito kayang i-merge ng Git, at may mawawalang trabaho. Para sa ganitong mga file, may lock ang LFS. Minamarkahan ninyo ang uri bilang lockable:

git lfs track "*.psd" --lockable

Idaragdag ang attribute na lockable sa .gitattributes, at magiging read-only ang mga ganoong file sa working copy hanggang sa i-lock ninyo ang mga ito:

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

# pagkatapos ng push ng mga pagbabago
git lfs unlock design/banner.psd

Habang naka-lock ang file, tatanggihan ang push ng pagbabago rito mula sa ibang tao. Sinusuportahan ng server ang mga lock, kaya gumagana ang mga ito sa malalaking Git hosting, pero maaaring walang ganoon sa sariling server. Maaaring alisin ng administrator ang lock ng iba gamit ang git lfs unlock --force.

Saan nakatira ang LFS object at magkano ang gastos

Nasa server na sumusuporta sa LFS API ang mga LFS object. Ipinapatupad ito ng mga sikat na Git hosting at ng self-hosted na solusyon, pati na ng hiwalay na server. May limitasyon ang mga cloud hosting sa laki ng storage at trapiko ng LFS, at magkakaiba ang mga ito sa iba't ibang serbisyo at plano. Suriin ang kasalukuyang kondisyon ng inyong platform bago magtago roon ng dataset na ilang daang gigabyte.

Tandaan na binibilang ang trapiko sa bawat pag-download: maaaring maubos ng CI na nagclo-clone ng repository na may LFS file sa bawat commit ang limitasyon nang mas mabilis kaysa sa mga tao. I-cache ang .git/lfs sa pagitan ng mga build, o gamitin ang GIT_LFS_SKIP_SMUDGE.

Lumalaki rin ang cache sa lokal. Binubura ng git lfs prune ang mga lumang object na nasa server na at hindi na kailangan para sa kasalukuyan at kamakailang commit.

Kailan angkop ang Git LFS at kailan hindi

Karaniwang pagkakamali at paano ayusin

Text pointer ang nasa working copy sa halip na file

Walang naka-install na LFS, o ginawa ang clone gamit ang GIT_LFS_SKIP_SMUDGE=1. Patakbuhin ang git lfs install at git lfs pull.

Napasok ang file sa history nang hindi dumadaan sa LFS

Idinagdag ang track rule pagkatapos ng git add. Kung hindi pa naipapadala ang commit, alisin ang file sa index (git rm --cached file), tiyaking may rule sa .gitattributes, at idagdag ulit. Kung naipadala na, gamitin ang git lfs migrate import. Makakatulong sa paghahanap ng ganitong file ang git lfs fsck --pointers.

Tinatanggihan ang push dahil sa laki ng file

Maraming hosting ang naglilimita sa laki ng isang object sa karaniwang Git. Ang mensaheng gaya ng "this exceeds the file size limit" ay nangangahulugang dapat ay sa LFS napunta ang file. Isulat ulit ang huling commit o history, gaya ng nakasulat sa itaas; hindi makakatulong ang simpleng commit na "burahin ang file", dahil nananatili ito sa mga naunang commit.

Nasira ang lahat sa mga katrabaho pagkatapos ng git lfs migrate

Nakabatay sa lumang hash ang kanilang mga lokal na branch. Pinakaligtas na i-clone ulit ang repository; kung may hindi pa naipapadalang trabaho, ilipat ito sa mga bagong branch gamit ang cherry-pick.

Cheat sheet ng Git LFS

Buod

Inililipat ng Git LFS ang malalaking binary file mula sa history papunta sa hiwalay na storage, at sa mga commit, magagaan na pointer lang ang naiiwan. Ang pangunahing tuntunin: i-set ang git lfs track bago ang unang commit ng malalaking file, i-commit ang .gitattributes, at bantayan ang quota ng hosting. Kapag nasa history na ang mga file, makakatulong ang git lfs migrate, pero ito ay pagsusulat ng history na may kasamang mga kahihinatnan. Ang pagtatrabaho sa history, rebase, at iba pang advanced na tool ng Git ay itinuturo nang praktikal sa kursong Git namin.