Sinopsis
git subtree add --prefix=<path> <repo> <ref> [--squash]
git subtree pull --prefix=<path> <repo> <ref>
git subtree push --prefix=<path> <repo> <ref>
git subtree split --prefix=<path> -b <new-branch>Descripción
El comando git subtree es una alternativa a git submodule para incluir el historial de otro repo dentro del tuyo. A diferencia de los submódulos, subtree fusiona el contenido directamente en tu repo, así que tus colaboradores no necesitan pasos adicionales tras un clone.
Usa git subtree add para incluir, git subtree pull para actualizar y git subtree push para enviar cambios de vuelta al repo upstream. La trampa es que el historial se vuelve más complejo y los splits no siempre son exactos.
En el uso diario, este comando se integra estrechamente con alias de shell, plugins de editor e integración continua. Los usuarios avanzados a menudo añaden alias que combinan los flags que siempre pasan. El formato de salida puede personalizarse vía configuración de Git. Cuando algo sale mal, ejecuta el comando con GIT_TRACE=1 para revelar las llamadas plumbing subyacentes.
Entender cómo este comando interactúa con el resto del modelo de datos de Git rinde dividendos. Cada comando opera sobre algún subconjunto de las piezas (objetos, index, refs, árbol de trabajo), y saber cuáles toca ayuda a predecir resultados y a recuperarse de errores.
Opciones comunes
| Subcomando | Descripción |
|---|---|
add | Import an external repo into a subdirectory. |
pull | Merge upstream changes for that prefix. |
push | Push prefix-only history back upstream. |
merge | Merge an arbitrary tree into the prefix. |
split | Extract a subdirectory's history as a standalone branch. |
--squash | Flatten foreign history into a single commit. |
--prefix=<path> | Subdirectory under which to place the subtree. |
Ejemplos
git subtree add --prefix=vendor/foo https://github.com/lib/foo.git main --squash
# Import foo into vendor/foo, squashing history
git subtree pull --prefix=vendor/foo https://github.com/lib/foo.git main --squash
# Pull updates
git subtree split --prefix=lib -b lib-only
# Extract lib/ as its own branch for sharing
git subtree push --prefix=vendor/foo upstream main
# Send prefix-scoped commits back to upstreamErrores comunes
Mixing --squash on some operations and not others creates messy history. Pick one mode and stick with it. Subtree merges produce nontrivial commit graphs that confuse some tooling. git subtree split can be slow on large histories.
Comandos relacionados
git submodule, git merge, git filter-repo