Submódulos, subtrees o vendoring: tres formas de incluir otro repositorio

Qué es

Hay tres mecanismos para llevar código de otro repositorio al tuyo:

• Submódulo. El árbol del superproyecto contiene una entrada gitlink con el ID del commit en el que debe estar el submódulo, y .gitmodules registra la ruta y la URL. El submódulo conserva su propio historial y su propio directorio de Git. La documentación indica que, tras git submodule update, se hace checkout del commit registrado en un HEAD desacoplado (detached HEAD).
• Subtree. git subtree add --prefix=<dir> <repository> <ref> importa los archivos del otro proyecto en un subdirectorio como archivos rastreados normales; con --squash se importa un único commit en lugar de todo el historial. git subtree pull y git subtree push transfieren cambios en ambos sentidos. El manual subraya que los subtrees no requieren construcciones especiales como .gitmodules o gitlinks y no obligan a los usuarios finales a hacer nada.
• Vendoring. Se copian los archivos, se hace commit de ellos y se escribe la versión original, la URL de origen y los parches locales en un archivo junto a ellos (VENDOR.md o un lock file).

Por qué importa

La elección determina el aspecto de un clon nuevo, cómo se realiza una actualización y si es posible modificar el código localmente. Los submódulos son exactos, pero exigen a todos, también a CI, usar git clone --recurse-submodules o git submodule update --init --recursive; si se olvida, aparecen directorios vacíos. Los subtrees y el vendoring producen un clon autocontenido, a costa de un historial más voluminoso y de un origen menos evidente.

Cómo aplicarlo

• Da preferencia a un gestor de paquetes cuando exista uno para el lenguaje; estas tres opciones son para los casos en que ninguno encaja (configuración compartida, assets, un fork privado).
• Usa submódulos cuando la dependencia sea grande, cambie de forma independiente y deba fijarse a un commit exacto en el que además desarrollas.
• Usa subtrees cuando quienes consumen el código no deban necesitar saberlo y las actualizaciones sean ocasionales (git subtree pull --squash mantiene corto el historial).
• Haz vendoring cuando la dependencia sea pequeña y estable; anota la versión y la licencia para poder auditar y refrescar la copia.
• Elijas lo que elijas, incluye el comando de actualización en el README y ejecuta el build desde un clon nuevo en CI.

Trampas

Si los commits del submódulo se suben al superproyecto pero no al remoto del submódulo, todos los demás clones se rompen. Los commits hechos dentro de un submódulo sobre su HEAD desacoplado no están en ninguna rama y es fácil perderlos, salvo que antes se cree una rama. El manual de subtree pide coherencia con --squash: si todos los merges se hacen con squash, split --rejoin también debe usarlo, o el log mostrará una copia de cada commit. Las copias de vendoring se desvían sin que nadie lo note cuando alguien las parchea sin actualizar el registro.