Git LFS (Large File Storage)

O que é Git LFS

Git LFS (Large File Storage) é uma extensão open-source do Git que mantém arquivos binários grandes — vídeos, conjuntos de dados, recursos de design, arte de jogos — fora do histórico do Git. Em vez de armazenar um arquivo de 500 MB no repositório, o Git LFS armazena um pequeno ponteiro de texto e mantém o conteúdo real em um armazenamento LFS separado. O resultado: os clones permanecem rápidos e o repositório permanece pequeno, mesmo quando o projeto possui gigabytes de recursos.

Este capítulo aborda quando usar o LFS, como instalar e rastrear arquivos, o que um ponteiro realmente contém, os comandos do dia a dia, bloqueio de arquivos para binários que não podem ser mesclados, e os problemas que costumam pegar as pessoas de surpresa.

Por que arquivos grandes prejudicam o Git

O Git foi criado para texto e armazena o histórico completo de cada arquivo. Ele também armazena arquivos pelo conteúdo: quando um binário muda, o Git geralmente mantém toda a nova cópia em vez de um pequeno diff, porque binários não geram diffs de forma eficiente. Faça commit de um binário grande algumas vezes e cada clone terá que baixar todas as versões para sempre — mesmo versões que ninguém precisa. O histórico aumenta, os clones ficam lentos e os pushes expiram. O Git LFS contorna isso versionando um pequeno ponteiro em vez do conteúdo pesado.

Use o LFS quando os arquivos forem grandes e mudarem ao longo do tempo — fontes de design, recursos compilados, conjuntos de dados, áudio e vídeo. Para arquivos que nunca precisam de versionamento, mantenha-os fora do repositório completamente com .gitignore.

Configuração

Primeiro instale o Git, depois instale a extensão LFS. Na maioria dos sistemas, o Git LFS é distribuído separadamente (brew install git-lfs, apt install git-lfs, ou o instalador de git-lfs.com). Ative-o uma vez por máquina:

git lfs install

Updated Git hooks.
Git LFS initialized.

Indique ao LFS quais arquivos gerenciar rastreando padrões. Isso escreve regras no .gitattributes:

git lfs track "*.psd"
git lfs track "*.mp4"
git add .gitattributes

O .gitattributes deve ser commitado para que todos os colaboradores obtenham as mesmas regras. A partir de agora, os arquivos correspondentes são armazenados pelo LFS automaticamente. Faça commit e push normalmente:

git add design.psd
git commit -m "Add hero design source"
git push

O Git faz upload do ponteiro para o repositório e do conteúdo binário para o armazenamento LFS. Em um novo clone, os hooks do Git LFS são ativados automaticamente e baixam o conteúdo real para o commit em uso.

Como é um ponteiro

No repositório, o arquivo rastreado é substituído por um pequeno ponteiro de texto que registra o hash e o tamanho do conteúdo:

version https://git-lfs.github.com/spec/v1
oid sha256:9af1c2a3b4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f7
size 471859200

As três linhas são a versão da especificação, o id do objeto SHA-256 do conteúdo (oid) e o tamanho em bytes. Esse é o footprint completo no histórico do Git — algumas centenas de bytes independentemente do tamanho do recurso. Quando alguém faz checkout do arquivo, o Git LFS usa esse ponteiro para buscar o conteúdo real sob demanda.

Comandos comuns

Para confirmar o que o LFS está gerenciando, liste os arquivos rastreados:

git lfs ls-files

9af1c2a3b4 * design.psd
1c0ffee5d6 * intro.mp4

Cada linha mostra o id de objeto curto, um * quando o conteúdo real está presente localmente (- se apenas o ponteiro está em checkout), e o caminho.

Bloqueio de arquivos

Binários como .psd ou .fbx não podem ser mesclados — se duas pessoas editam o mesmo arquivo, um conjunto de alterações é perdido. O Git LFS adiciona bloqueio de arquivos para que um colega possa reivindicar um arquivo antes de editá-lo:

git lfs lock images/banner.psd
git lfs locks
git lfs unlock images/banner.psd

Marque um padrão como bloqueável no .gitattributes para sinalizá-lo como somente leitura até ser bloqueado, o que evita edições acidentais:

git lfs track "*.psd" --lockable

O bloqueio requer suporte do servidor (GitHub e GitLab fornecem isso).

Movendo arquivos existentes para o LFS

O rastreamento afeta apenas os arquivos commitados após a adição da regra. Arquivos já no histórico permanecem no Git como binários completos. Para movê-los, reescreva o histórico com git lfs migrate:

git lfs migrate import --include="*.mp4"

Isso reescreve commits, alterando seus hashes — coordene com sua equipe e faça force-push depois, como em qualquer reescrita de histórico.

O que saber

• É necessário suporte do servidor. GitHub, GitLab e Bitbucket fornecem LFS, geralmente com cotas de armazenamento e largura de banda que podem gerar custos. Um repositório pode exceder sua cota de LFS mesmo que o tamanho do Git continue pequeno.
• Todos precisam da extensão. Qualquer pessoa que clone o repositório deve ter o Git LFS instalado, ou verá o texto do ponteiro em vez do arquivo real. Se isso acontecer, instalar o LFS e executar git lfs pull resolve o problema.
• Ponteiros são objetos Git normais. Branch, merge e diff do ponteiro funcionam normalmente; o LFS apenas substitui pelo conteúdo real no momento do checkout.

Prática