Git LFS

Cuando extraes una confirmación que contiene punteros de Git LFS, se sustituyen por archivos de la caché local de Git LFS o se descargan del almacenamiento remoto de Git LFS.

Git LFS funciona sin problemas: en tu copia de trabajo solo verás el contenido real del archivo. De esta forma, puedes usar Git LFS sin cambiar tu flujo de trabajo de Git existente; tan solo tienes que hacer git checkout, editar, git add y git commit como harías normalmente. Las operaciones de git clone y git pull serán mucho más rápidas, ya que solo descargas las versiones de archivos grandes a los que hacen referencia las confirmaciones que realmente extraes, en lugar de todas las versiones del archivo que hayan existido.

Para usar Git LFS, necesitarás un host compatible con Git LFS, como Bitbucket Cloud o Bitbucket Data Center. Los usuarios del repositorio deberán tener instalado el cliente de línea de comandos de Git LFS o un cliente de GUI compatible con Git LFS, como Sourcetree. Como curiosidad, Steve Streeting, el desarrollador de Atlassian que inventó Sourcetree, también es uno de los principales colaboradores del proyecto Git LFS, por lo que Sourcetree y Git LFS funcionan bastante bien juntos.

1. Hay tres formas de instalar Git LFS, todas muy sencillas:

a. Instálalo con tu gestor de paquetes favorito. Hay paquetes de git-lfs para Homebrew, MacPorts, dnf y packagecloud.

b. Descarga e instala Git LFS desde el sitio web del proyecto.

c. Instala Sourcetree, un cliente GUI de Git gratuito que viene incluido con Git LFS.

2. Cuando git-lfs esté en tu ruta, ejecuta git lfs install para inicializar Git LFS (puedes saltar este paso si has instalado Sourcetree):

Solo tienes que ejecutar git lfs install una vez. Una vez inicializado para tu sistema, Git LFS se iniciará automáticamente cada vez que clones un repositorio que tenga contenido de Git LFS.

Para crear un nuevo repositorio compatible con Git LFS, tendrás que ejecutar git lfs install después de crear el repositorio:

Esto instala un hook de Git especial pre-push en tu repositorio que transferirá los archivos de Git LFS al servidor cuando hagas git push.

Git LFS se habilita automáticamente para todos los repositorios de Bitbucket Cloud. Para Bitbucket Data Center, tendrás que habilitar Git LFS en la configuración del repositorio:

En cuanto Git LFS se inicializa para tu repositorio, puedes especificar qué archivos quieres rastrear con git lfs track.

Una vez instalado Git LFS, puedes clonar un repositorio de Git LFS de forma normal con git clone. Al finalizar la clonación, Git extraerá la rama predeterminada (normalmente main) y se descargarán automáticamente todos los archivos de Git LFS necesarios para llevar a cabo el proceso de extracción. Por ejemplo:

Git LFS está rastreando cuatro PNG en este repositorio. Al ejecutar git clone, los archivos de Git LFS se descargan uno por uno a medida que los archivos de puntero se extraen de tu repositorio.

Si vas a clonar un repositorio con una gran cantidad de archivos LFS, el comando git lfs clone explícito ofrece un rendimiento mucho mejor:

En lugar de descargar los archivos de Git LFS de uno en uno, el comando git lfs clone espera hasta que finaliza la extracción y, a continuación, descarga los archivos de Git LFS necesarios en lote. Esto aprovecha las descargas en paralelo y reduce enormemente la cantidad de solicitudes y procesos HTTP generados (lo cual es especialmente importante para mejorar el rendimiento en Windows).

Al igual que con la clonación, puedes incorporar cambios desde un repositorio de Git LFS usando un git pull normal. Todos los archivos de Git LFS necesarios se descargarán dentro del proceso de extracción automático una vez que se lleve a cabo la incorporación:

No se necesitan comandos explícitos para recuperar el contenido de Git LFS. Sin embargo, si la extracción falla por un motivo inesperado, puedes descargar los contenidos de Git LFS que falten para la confirmación actual con git lfs pull:

Al igual que git lfs clone, git lfs pull descarga los archivos de Git LFS en lote. Si sabes que una gran cantidad de archivos han cambiado desde la última vez que incorporaste cambios, es posible que quieras deshabilitar la descarga automática de Git LFS durante la extracción y, a continuación, descargar por lotes el contenido de Git LFS con un comando git lfs pull explícito. Para esto puedes anular tu configuración de Git con la opción -c cuando invocas git pull:

Como esto supone mucha escritura, es posible que quieras crear un alias de Git sencillo para que realice una incorporación por lotes de Git y Git LFS:

Esto mejorará en gran medida el rendimiento cuando tengas que descargar una gran cantidad de archivos de Git LFS (como he dicho, esto es muy práctico en Windows).

Cuando añadas un nuevo tipo de archivo grande a tu repositorio, tendrás que indicarle a Git LFS que lo rastree especificando un patrón con el comando git lfs track:

Ten en cuenta que las comillas de "*.ogg" son importantes. Si las omites, el shell expandirá el comodín y se crearán entradas individuales para cada archivo .ogg de tu directorio actual:

Los patrones admitidos por Git LFS son los mismos que los que admite .gitignore, por ejemplo:

Estos patrones se refieren al directorio en el que ejecutó el comando git lfs track. Para simplificar las cosas, es mejor ejecutar git lfs track desde la raíz del repositorio. Recuerda que Git LFS no admite patrones negativos, a diferencia de .gitignore que sí lo hace.

Después de ejecutar git lfs track, verás un nuevo archivo llamado .gitattributes en el directorio desde el que ejecutaste el comando. .gitattributes es un mecanismo de Git para vincular comportamientos especiales a ciertos patrones de archivo. Git LFS crea o actualiza automáticamente archivos .gitattributes para vincular patrones de archivo rastreados al filtro de Git LFS. Sin embargo, tendrás que confirmar los cambios en el archivo .gitattributes en tu repositorio tú mismo:

Para facilitar el mantenimiento, lo más sencillo es mantener todos los patrones de Git LFS en un solo archivo .gitattributes ejecutando siempre git lfs track desde la raíz del repositorio. Sin embargo, puedes mostrar una lista de todos los patrones de los que Git LFS (y los archivos .gitattributes en los que se definen) invocando git lfs track sin argumentos:

Para dejar de rastrear un patrón en particular con Git LFS, puedes eliminar la línea apropiada de tu archivo .gitattributes o ejecutar el comando git lfs untrack:

Después de ejecutar git lfs untrack, tendrás que volver a confirmar los cambios en .gitattributes tú mismo.

Puedes confirmar y enviar de forma normal a un repositorio que tenga contenido de Git LFS. Si has confirmado cambios en archivos rastreados por Git LFS, verás algunos resultados adicionales de git push cuando el contenido de Git LFS se transfiera al servidor:

Si la transferencia de los archivos LFS falla por algún motivo, el envío se anulará y podrás volver a intentarlo de forma segura. Al igual que Git, el almacenamiento de Git LFS es direccionable por contenido: el contenido se almacena en una clave que es un hash SHA-256 del contenido en sí. Esto significa que siempre es seguro volver a intentar transferir archivos de Git LFS al servidor; no puedes sobrescribir accidentalmente el contenido de un archivo de Git LFS con una versión incorrecta.

Para migrar un repositorio de Git LFS de un proveedor de alojamiento a otro, puedes usar una combinación de git lfs fetch y git lfs push especificando la opción --all.

Por ejemplo, para mover todos los repositorios Git y Git LFS de un remoto llamado github a un repositorio remoto llamado bitbucket 😉:

Por lo general, Git LFS solo descarga los archivos necesarios para las confirmaciones que extraigas de forma local. Sin embargo, puedes forzar a Git LFS a descargar contenido adicional para otras ramas modificadas recientemente con git lfs fetch --recent:

Esto es práctico para descargar por lotes nuevo contenido de Git LFS mientras estás fuera de la oficina o si vas a revisar el trabajo de tus compañeros de equipo y luego no tendrás una buena conexión a Internet para descargar el contenido. Por ejemplo, podrías ejecutar git lfs fetch --recent antes de subir a un avión.

Git LFS considera como reciente cualquier rama o etiqueta que tengan una confirmación de más de siete días. Puedes configurar el número de días que se consideran recientes con la propiedad lfs.fetchrecentrefsdays:

De forma predeterminada, git lfs fetch --recent solo descargará el contenido de Git LFS para la confirmación que está en la punta de una rama o etiqueta reciente.

Sin embargo, puedes configurar Git LFS para que descargue contenido para confirmaciones anteriores en ramas y etiquetas recientes con la propiedad lfs.fetchrecentcommitsdays:

Ten cuidado con este ajuste: si tienes ramas que se mueven rápidamente, puede hacer que se descargue una gran cantidad de datos. Sin embargo, puede venirte bien si tienes que revisar cambios intersticiales en una rama, seleccionar confirmaciones entre ramas distintas con cherry-pick o reescribir el historial.

Como se explica en Mover un repositorio de Git LFS entre hosts, también puedes recuperar todo el contenido de Git LFS para tu repositorio con git lfs fetch --all:

Puedes eliminar archivos de tu caché local de Git LFS con el comando git lfs prune:

Esto eliminará todos los archivos de Git LFS locales que se consideren antiguos. Un archivo antiguo es cualquier archivo al que no hagan referencia:

• la confirmación que se está extrayendo en ese momento,
• una confirmación que aún no se ha enviado (al origen o según la configuración de lfs.pruneremotetocheck) y
• una confirmación reciente

De forma predeterminada, una confirmación reciente es cualquier confirmación que se haya creado en los últimos diez días. Para calcularlo, se suma lo siguiente:

• el valor de la propiedad lfs.fetchrecentrefsdays que se describe en Recuperar historial extra de Git LFS (cuyo valor predeterminado es siete) y
• el valor de la propiedad lfs.pruneoffsetdays (cuyo valor predeterminado es tres).

Puedes configurar el desplazamiento de prune y conservar el contenido de Git LFS durante más tiempo:

A diferencia de la recolección de elementos no utilizados integrada de Git, el contenido de Git LFS no se elimina automáticamente, por lo que es conveniente ejecutar git lfs prune de forma regular para reducir el tamaño del repositorio local.

Puedes probar qué efecto tendrá una operación de prune con git lfs prune --dry-run:

También puedes ver qué objetos de Git LFS se eliminarán con git lfs prune --verbose --dry-run:

Las cadenas hexadecimales largas generadas por el modo --verbose son hashes SHA-256 (también conocidos como ID de objeto u OID) de los objetos Git LFS que se van a eliminar. Puedes usar las técnicas detalladas en Buscar rutas o confirmaciones que hagan referencia a un objeto de Git LFS para obtener más información sobre los objetos que se eliminarán.

Como comprobación de seguridad adicional, puedes usar la opción --verify-remote para comprobar si el almacenamiento remoto de Git LFS tiene una copia de tus objetos de Git LFS antes de que se eliminen:

Esto hace mucho más lento el proceso de eliminación, pero te da la tranquilidad de saber que los objetos eliminados se podrán recuperar del servidor. Puedes habilitar la opción --verify-remote permanentemente en el sistema configurando la propiedad lfs.pruneverifyremotealways de forma global:

También puedes omitir la opción --global del comando anterior para habilitar la verificación remota solamente para el repositorio de contexto.

El cliente de línea de comandos de Git LFS no permite eliminar archivos del servidor con prune, y la forma de eliminarlos dependerá de tu proveedor de alojamiento.

En Bitbucket Cloud, puedes ver y eliminar archivos de Git LFS en Configuración del repositorio> Git LFS:

Recuerda que todos los archivos de Git LFS están indexados por su OID SHA-256; las rutas que hacen referencia a cada archivo no se pueden ver a través de la interfaz de usuario. Esto es así porque puede haber muchas rutas diferentes en muchas confirmaciones diferentes que pueden referirse a un objeto determinado, por lo que buscarlas sería un proceso muy lento.

Para determinar qué contiene realmente un archivo de Git LFS determinado, tienes tres opciones:

• Fíjate en la imagen de vista previa del archivo y en el tipo de archivo en la columna izquierda de la interfaz de usuario de Bitbucket Git LFS.
• Descarga el archivo con el enlace en la columna derecha de la interfaz de usuario de Bitbucket Git LFS. O busca confirmaciones que hagan referencia al OID SHA-256 del objeto Git LFS, como se explica en la siguiente sección.

Si tienes un OID SHA-256 de Git LFS, puedes determinar qué confirmaciones le hacen referencia con git log --all -p -S< OID>:

Este código de git log genera un parche (-p) a partir de confirmaciones de cualquier rama (--all) que agregan o eliminan una línea (-S) que contiene la cadena especificada (un OID SHA-256 de Git LFS).

El parche te muestra la confirmación y la ruta al objeto de LFS, así como quién lo ha añadido y cuándo se confirmó. Puedes extraer la confirmación y Git LFS descargará el archivo si es necesario y lo colocará en tu copia de trabajo.

Si sospechas que un objeto de Git LFS en particular está en tu HEAD o en una rama en particular, puedes usar git grep para buscar la ruta del archivo de referencia:

Puedes sustituir HEAD o power-ups con cualquier referencia, confirmación o árbol que contenga el objeto de Git LFS.

En algunos casos, puede que quieras descargar solo un subconjunto del contenido disponible de Git LFS para una confirmación en particular. Por ejemplo, al configurar una compilación de CI para ejecutar pruebas unitarias, es posible que solo necesites tu código fuente y excluir archivos pesados que no son necesarios para compilar el código.

Puedes excluir un patrón o subdirectorio con git lfs fetch -X (o --exclude):

También puede que solo quieras incluir un patrón o subdirectorio en particular. Por ejemplo, un ingeniero de sonido podría recuperar solamente archivos ogg y wav con git lfs fetch -I (o --include):

Si combinas inclusiones y exclusiones, solo se recuperarán archivos que coincidan con un patrón de inclusión y no coincidan con un patrón de exclusión. Por ejemplo, puedes recuperar todo lo que hay en tu directorio Assets, salvo los gif con:

Las exclusiones e inclusiones son compatibles con los mismos patrones que git lfs track y .gitignore. Puedes hacer que estos patrones sean permanentes para un repositorio en particular estableciendo las propiedades de configuración lfs.fetchinclude y lfs.fetchexclude:

Estas configuraciones también se pueden aplicar a todos los repositorios de tu sistema agregando la opción --global.

Lamentablemente, no hay una forma sencilla de resolver los conflictos de fusión binaria. Con el bloqueo de archivos de Git LFS, puedes bloquear archivos por extensión o por nombre de archivo y evitar que los archivos binarios se sobrescriban durante una fusión.

Para utilizar la función de bloqueo de archivos de LFS, primero debes decirle a Git qué tipo de archivos se pueden bloquear. En el ejemplo siguiente, la marca `--lockable` se añade al comando `git lfs track` que almacena archivos PSD en LFS y los marca como bloqueables.

A continuación, añade lo siguiente a tu archivo que aparece a continuación:

Cuando te prepares para hacer cambios en un archivo LFS, utilizarás el comando lock para registrar el archivo como bloqueado en el servidor de Git.

Cuando ya no necesites el bloqueo de archivos, puedes eliminarlo con el comando de desbloqueo de Git LFS.

Los bloqueos de archivos de Git LFS se pueden anular (de manera similar a git push) con una marca --force. No uses la marca --force a menos de que tengas absoluta certeza de lo que estás haciendo.