Git LFS: manejar archivos grandes en git

Guía rápida para trabajar con archivos pesados en los repos del HackLab sin inflar el historial. Si vas a subir PDFs, videos o comprimidos a un repo, esto es lo que necesitas saber.

Qué es y por qué existe

Git fue hecho para código, que es texto. Guarda cada versión de cada archivo en el historial, y para texto eso funciona muy bien. El problema aparece con los binarios grandes, como PDFs, videos, comprimidos o datasets. Cada vez que uno de esos cambia, git guarda una copia completa, y el repo se infla rápido. Clonarlo se vuelve lento y pesado para todos.

Git LFS (Large File Storage) resuelve eso. Guarda los archivos grandes en un lugar aparte y dentro de git deja solo un "puntero", que es un archivito de texto que dice dónde está el archivo real. Así el historial se mantiene liviano y los archivos grandes se bajan solo cuando se necesitan.

Cuándo usarlo

Úsalo para binarios que pesan o que se van acumulando: imágenes pesadas, PDF, videos, audio, comprimidos (.zip), archivos de diseño (.psd, .ai), modelos y datasets.

No lo necesitas para código ni para texto. Los .md, .py, .js y demás van bien en git normal.

Instalación

Se hace una sola vez por computador.

En mac:

brew install git-lfs

En Linux (Debian o Ubuntu):

sudo apt install git-lfs

En Windows normalmente ya viene incluido con Git for Windows. Si no lo tienes, descárgalo de git-lfs.com.

Después de instalarlo, actívalo para tu usuario (también una sola vez):

git lfs install

Uso básico

Trabajas casi igual que con git normal. Lo único distinto es decirle a LFS qué tipos de archivo manejar.

1. Dile a LFS qué archivos rastrear

Dentro del repo, por tipo de archivo:

git lfs track "*.pdf"
git lfs track "*.png"
git lfs track "*.zip"

Esto crea o actualiza un archivo llamado .gitattributes, donde queda anotado qué patrones maneja LFS.

2. Confirma el .gitattributes primero

Esto importa. El .gitattributes tiene que entrar antes que los archivos grandes, o no quedan capturados por LFS.

git add .gitattributes
git commit -m "Configura git lfs"

3. Ahora sí, agrega los archivos como siempre

git add mi-archivo.pdf
git commit -m "Agrega documento"
git push

4. Verifica que quedaron en LFS

git lfs ls-files

Si tus archivos aparecen en esa lista, quedó bien.

Clonar un repo que ya usa LFS

Si tienes git-lfs instalado, un git clone normal baja los archivos reales sin que hagas nada más.

Si clonaste y ves punteros (archivos de texto raros en vez del PDF o la imagen), es porque te faltaba LFS. Instálalo y corre:

git lfs pull

Y bajan los archivos de verdad.

Mover archivos que ya estaban en el repo

Ojo con esto. Rastrear un tipo de archivo solo afecta lo que subas de ahí en adelante. Lo que ya estaba en el historial no se mueve solo a LFS.

Si necesitas pasar a LFS archivos que ya habías subido antes, usa:

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

Esto reescribe el historial, así que hazlo con cuidado y coordinando con quien más use el repo. Después toca forzar el push y todos tienen que volver a clonar o resincronizar.

Comandos útiles

• git lfs track "*.ext" — empezar a manejar un tipo de archivo
• git lfs untrack "*.ext" — dejar de manejarlo
• git lfs ls-files — ver qué archivos están en LFS
• git lfs status — ver el estado de los archivos LFS
• git lfs pull — bajar los archivos reales
• git lfs migrate import --include="*.ext" — mover a LFS archivos ya existentes

Errores comunes

• Subiste el archivo y no quedó en LFS. Casi siempre es porque agregaste el binario antes de confirmar el .gitattributes. El orden correcto es: rastrear, confirmar el .gitattributes, y después agregar los archivos.
• Ves punteros en vez de los archivos. Te falta git-lfs instalado, o no corriste git lfs pull.
• Algo que construye desde el repo (un sitio, un pipeline de CI) sale con archivos rotos. Ese proceso también necesita bajar los archivos de LFS. Si usas GitHub Actions, el paso de checkout debe traer LFS con la opción lfs: true.