Tecnología · GUÍA PRÁCTICA
¿Git LFS dejó archivos puntero después del clone? Audita atributos y objetos antes de clonar de nuevo
Ver texto de puntero en el árbol de trabajo clonado es un síntoma, no una causa raíz. Conserva los cambios locales, identifica el objeto LFS exacto y separa los fallos de atributos y filtros de los de descarga, autenticación, objeto local y checkout antes de volver a clonar o restablecer nada.
Git LFS guarda un puntero pequeño en Git y el objeto grande en otro almacenamiento. Que el puntero aparezca en el árbol de trabajo puede significar que Git LFS no estaba instalado cuando se materializaron los archivos, que se omitió smudge de forma intencionada, que los atributos no coinciden con la ruta, que el objeto no se descargó o que checkout evitó sustituir un archivo modificado. Por sí solo, el puntero no demuestra que el repositorio esté dañado.
El diagnóstico más seguro sigue al objeto desde el puntero hasta los atributos, filtros, caché local, fetch remoto y checkout del árbol de trabajo. Cada etapa produce pruebas distintas y requiere una corrección diferente. Repetir el clone a ciegas puede reproducir la misma configuración, consumir ancho de banda y eliminar contexto local útil.
Esta guía prioriza las comprobaciones de solo lectura. No reescribe el historial, no ejecuta hard reset ni clean, no elude credenciales y no borra el clone existente. El resultado es un registro breve de pruebas y la siguiente acción segura más limitada.
1. Conserva el árbol de trabajo y confirma que sea un puntero real
Empieza con `git status --short` y guarda la salida. Antes de probar nada, copia fuera del repositorio cualquier archivo con aspecto de puntero que pueda tener ediciones locales, además del trabajo no rastreado. Durante el diagnóstico no ejecutes `git reset --hard`, `git clean`, migraciones de historial ni borres el clone.
Abre el pequeño archivo de texto anómalo en modo de solo lectura. Un puntero válido de Git LFS v1 contiene la línea de especificación, una línea `oid sha256:` y el `size` declarado. Anota la ruta relativa, el OID y el tamaño. Si solo parece un puntero pero no se puede analizar con ese formato, trátalo como una rama separada de posible corrupción de contenido.
Si tu versión lo admite, ejecuta `git lfs pointer --check --file="PATH"` o compara el archivo con la estructura documentada. No incluyas credenciales del repositorio, URL firmadas ni detalles de remotos privados en las pruebas públicas.
2. Comprueba si la ruta está realmente administrada por atributos LFS
En el commit afectado, ejecuta `git check-attr -a -- "PATH"`. Para una ruta que debería estar rastreada por LFS, comprueba los atributos filter, diff, merge y text que Git leyó realmente. El nombre del archivo en el árbol de trabajo no prueba que la regla de atributos actual coincida.
Examina la versión de `.gitattributes` guardada en Git, no solo una copia local todavía sin commit. Los patrones de atributos dependen de la ruta. La FAQ oficial también señala que las diferencias entre plataformas pueden revelar patrones incorrectos o hacer que archivos históricos, confirmados antes de activar la regla, se comporten de forma distinta.
Si la ruta de ese commit no tiene el atributo filter de LFS, detente aquí. Instalar Git LFS o descargar objetos no corrige por sí solo un atributo que no coincide. Revisa por separado qué archivos y commits deben cambiar antes de considerar renormalization o migration.
3. Registra los filtros y la selección local de Git LFS
Registra `git lfs version` y una salida de `git lfs env` sin secretos. Confirma que Git LFS esté instalado para el usuario y el repositorio actuales, y anota si al crear el árbol se usó `GIT_LFS_SKIP_SMUDGE=1`, `git lfs install --skip-smudge` o una configuración equivalente.
No supongas primero que todos los objetos LFS debían descargarse. Revisa las reglas include y exclude. El manual de pull describe los filtros por ruta, mientras que partial clone o sparse checkout también pueden limitar deliberadamente qué rutas entran al árbol de trabajo.
Registra además el estado de sparse-checkout y todos los partial-clone filter. Un issue real de Git LFS muestra un caso con punteros únicamente relacionado con partial checkout y un filtro include, pero esa rama de regresión concreta solo debe considerarse después de revisar los límites normales de atributos, filtros, fetch y checkout.
4. Separa la descarga del objeto de su checkout en el árbol
`git lfs pull` combina fetch y checkout. En cambio, `git lfs checkout` por sí solo nunca descarga contenido ausente: solo usa objetos que ya existen en el almacenamiento LFS local para sustituir punteros que cumplen las condiciones. Por eso repetir checkout puede no cambiar nada.
Antes de descargar a gran escala, limita el fetch a la referencia y ruta afectadas. Tras confirmar la estructura del repositorio, por ejemplo, ejecuta `git lfs fetch REMOTE REF --include="PATH"` y registra el remoto exacto, la referencia y el primer error sin datos sensibles.
Si fetch devuelve claramente un error de autenticación, autorización, objeto ausente o cuota, detente en ese límite. Que el clone normal de Git haya terminado bien no prueba que el endpoint separado de objetos LFS acepte la solicitud ni que aún conserve ese OID.
5. Verifica el OID exacto en el almacenamiento local antes del checkout
Después de un fetch correcto, confirma que el almacenamiento LFS local contenga el objeto correspondiente al OID SHA-256 registrado y que su longitud en bytes coincida con el size declarado por el puntero. Usa comandos de Git LFS y diagnóstico del repositorio; no lo deduzcas por un nombre de archivo igual.
Cuando sea apropiado para el repositorio, ejecuta `git lfs fsck --objects` y conserva la salida. Si el tamaño o el hash del objeto local no coincide, es un problema de integridad. Si el objeto no existe localmente, el problema sigue estando en fetch o en la disponibilidad remota.
No sobrescribas el puntero con un binario cualquiera solo porque tenga el mismo nombre. El OID del puntero es la identidad del contenido. Un checkout correcto debe resolver el objeto exacto y no modificar archivos que no están relacionados.
6. Deja que checkout proteja los cambios e interpreta el resultado
Cuando hayas confirmado que el objeto exacto existe localmente, ejecuta `git lfs checkout -- "PATH"` limitado a la ruta. El manual de checkout indica que no sobrescribe archivos modificados. Por tanto, si el archivo con aspecto de puntero difiere del índice, que no cambie puede ser una protección intencionada y no un fallo de instalación.
Compara `git status --short`, `git diff -- "PATH"` y el puntero registrado en el índice. Antes de restaurar un marcador limpio, respalda todos los cambios locales y determina si la diferencia es trabajo del usuario, daño de saltos de línea o un resultado anómalo de checkout.
Tras un checkout correcto, confirma que el archivo del árbol ya no se analice como puntero y que su tamaño coincida con el valor declarado. Cuando el diseño habitual de Git LFS lo permita, verifica también su hash frente al OID.
Prueba | Límite que falló | Acción segura mínima La ruta no tiene atributo filter de LFS | Atributos | Corregir y revisar aparte la regla de rastreo; no descargar a ciegas LFS no está instalado o smudge se omitió a propósito | Instalación del filtro | Instalar o configurar LFS y después hacer un pull limitado fetch devuelve autenticación u objeto ausente | Acceso remoto o disponibilidad del objeto | Corregir el acceso o restaurar el OID exacto; no repetir el clone El objeto está local, pero checkout deja un puntero modificado | Protección del árbol de trabajo | Respaldar cambios, comparar con el índice y ejecutar checkout limitado Tras las comprobaciones normales, solo falla una ruta partial/sparse | Selección de checkout o regresión | Reproducir con versión exacta y filtros mínimos antes de elevar un issue
7. Valida la recuperación y prepara pruebas para soporte
Define criterios de aceptación concretos: el puntero se puede analizar; el OID y el tamaño declarado están registrados; después de fetch, ese mismo OID existe localmente; la ruta del árbol contiene el contenido resuelto; y los cambios no relacionados permanecen intactos. Como comprobación práctica adicional, abre el archivo con la aplicación esperada.
Una solicitud de soporte debe incluir, sin secretos, las versiones de Git y Git LFS, el sistema operativo, el prefijo y tamaño del OID, el resultado de `check-attr`, el estado de filtros e include/exclude, el nombre del remoto, el resultado de fetch, el resultado del objeto local, el estado sparse o partial checkout y el resultado del checkout limitado a la ruta. Separa observaciones de conclusiones.
Solo informa de una posible regresión específica de versión cuando los atributos, la configuración, el acceso remoto, la presencia del objeto y la protección de cambios ya se hayan descartado y la reproducción mínima siga fallando. No atribuyas todos los checkout que dejan punteros a un mismo issue conocido.
Preguntas frecuentes
Si el clone de Git terminó bien, ¿por qué no se descargaron los archivos de Git LFS? El repositorio Git y el servicio de objetos LFS son límites distintos. Git puede clonar los punteros aunque LFS no esté instalado, se haya omitido smudge, la ruta esté excluida, fallen las credenciales o falte el objeto remoto.
¿`git lfs checkout` descarga los objetos que faltan? No. checkout solo usa objetos que ya están en el almacenamiento LFS local. Los objetos ausentes deben obtenerse antes con fetch o pull.
¿Debo ejecutar `git reset --hard` para sustituir los punteros? No durante el diagnóstico. hard reset puede eliminar trabajo no relacionado y no prueba que el objeto LFS requerido esté disponible. Registra primero el estado, los atributos, el OID y las pruebas de fetch.
¿Ver texto de puntero significa que el archivo está dañado? No necesariamente. El puntero es un dato normal del repositorio. El problema es que el objeto grande correspondiente no se materializó en el árbol, y varios límites distintos pueden causar ese estado.
