Tecnología · GUÍA PRÁCTICA
¿Git LFS dice que un archivo debía ser un puntero? Repara el índice sin perder la copia de trabajo
Conserva primero el archivo, demuestra qué atributo y objeto discrepan, elige una renormalización limitada o una migración coordinada y valida un clon nuevo.
Este aviso suele significar que .gitattributes asigna la ruta a Git LFS, pero un commit o el índice conserva el archivo completo como blob normal. El filtro clean produce un puntero para comparar y el archivo puede volver a parecer modificado tras reset.
No empieces con git reset --hard, borrando .git/lfs ni con force push. Conserva los bytes, inspecciona regla y objeto, repara el alcance mínimo y demuestra que el objeto LFS existe en remoto.
1. Conserva bytes antes de cambiar Git
Copia el archivo fuera del repositorio o registra un hash criptográfico antes de reset, checkout o migración. Guarda también git status, ruta y rama actual.
Si hay trabajo no relacionado, detente. Renormaliza en una rama limpia o clon desechable y conserva la copia fuera.
2. Demuestra la discrepancia
Ejecuta git check-attr -a -- path para hallar la regla efectiva, incluidos .gitattributes anidados y patrones sensibles a mayúsculas. Inspecciona índice o HEAD sin reemplazar el archivo de trabajo.
Un puntero LFS real es texto corto con versión, OID y tamaño. Si la ruta usa LFS pero HEAD contiene el blob completo, es una discrepancia de representación.
3. Repara primero la rama actual
Para corregir la rama actual, deja explícita la regla, ejecuta git add --renormalize -- path en un árbol limpio y revisa el diff preparado. El índice debe guardar el puntero y el archivo conservar sus bytes útiles.
Confirma solo regla y puntero revisados. Corrige la rama desde ese commit; trata deliberadamente otras ramas afectadas.
4. Reescribe historia solo si hace falta
Usa git lfs migrate solo si debes convertir commits antiguos o el host aún detecta blobs grandes históricos. Prueba --no-rewrite o import --fixup y refs exactas en un clon desechable.
La migración cambia IDs y puede exigir force push y clones nuevos. Respalda refs, coordina el cambio y no descubras el alcance en el remoto compartido.
5. Verifica punteros y objetos remotos
Ejecuta git lfs fsck --pointers en el rango y git lfs fsck para objetos locales. Revisa git lfs ls-files y el OID del puntero antes de enviar.
Envía objetos LFS además de la referencia Git. Un push correcto o estado limpio no prueba que el objeto grande llegó. Conserva hashes original y restaurado.
6. Acepta solo un clon nuevo
Clona en un directorio vacío con Git LFS, extrae la referencia reparada y confirma que no hay aviso ni cambio fantasma. Compara hash y tamaño restaurados con el original.
Acepta solo si atributos, punteros, objetos remotos y archivo nuevo coinciden. Conserva el respaldo hasta que otro colaborador o CI supere la misma prueba.
