Clonación superficial de Git: qué es, cuándo usarla y cómo

Clonar un repositorio con git clone normalmente extrae todo el historial de commits. Pero, ¿qué pasa si no necesitas todo? Ahí es donde entran las clonaciones superficiales. En este artículo, explicaremos qué es una clonación superficial, cómo funciona y cuándo tiene sentido usarla — con ejemplos listos para copiar y pegar.

¿Qué es una clonación superficial en Git?

Una clonación superficial es una clonación de Git que extrae solo una parte del historial de un repositorio en lugar de todo desde el principio. Esto reduce significativamente el tamaño de la descarga y el tiempo. Es especialmente útil cuando:

• No necesitas el historial completo de commits
• Quieres una configuración más rápida para pipelines de CI/CD
• Estás trabajando con repositorios grandes

Clonación superficial vs clonación normal

Característica Clonación Normal Clonación Superficial Obtiene todo el historial Sí No (commits limitados) Velocidad de clonación Más lenta Más rápida Operaciones Git (rebase, bisect) Totalmente compatibles Algunas limitaciones Ideal para CI/CD No óptima Sí

Cómo realizar una clonación superficial

Clonar solo el commit más reciente

git clone --depth=1 https://github.com/owner/repo.git

Clonar una rama específica con historial limitado

git clone --depth=1 --branch main --single-branch https://github.com/owner/repo.git

Clonar commits desde una fecha específica

git clone --shallow-since="2024-01-01" https://github.com/owner/repo.git

También puedes usar --filter=blob:none con clonaciones parciales si quieres omitir por completo la descarga de archivos grandes.

¿Puedes “desuperficializar” una clonación superficial?

Sí. Si más tarde decides que necesitas el historial completo:

git fetch --unshallow

Esto extrae los commits faltantes y convierte tu clonación superficial en una completa.

¿Cuándo deberías usar una clonación superficial?

Usa una clonación superficial cuando:

• Solo necesitas la última versión del código
• Estás ejecutando pipelines de CI y quieres compilaciones más rápidas
• Estás inspeccionando o probando código sin necesitar el historial completo

Evita las clonaciones superficiales cuando:

• Necesitas realizar operaciones git bisect, git rebase o merge
• Estás contribuyendo con cambios y necesitas acceso al historial de commits
• Estás escribiendo herramientas que dependen del contexto completo del repositorio

Problemas comunes con clonaciones superficiales

Las operaciones de Git pueden fallar

Algunos comandos asumen un historial completo y arrojarán errores en clonaciones superficiales:

• git merge-base
• git rebase
• git bisect

Solución: Ejecuta git fetch --unshallow o evita la clonación superficial en esos contextos.

Las clonaciones superficiales pueden romper herramientas de monorepo

Herramientas como Lerna o Nx pueden asumir acceso completo al historial de commits del repositorio para gráficos de dependencias o paquetes afectados. Prueba con tu cadena de herramientas específica.

Conclusión

Las clonaciones superficiales son una excelente manera de acelerar los flujos de trabajo de desarrollo, especialmente en CI o cuando se trabaja con repositorios grandes. Solo debes ser consciente de las compensaciones — y siempre puedes desuperficializar más tarde si es necesario.

Preguntas frecuentes