HOWTO · Git

Clonar subdirectorio del repositorio Git

Este tutorial trata sobre la clonación de un subdirectorio del repositorio de Git.

En esta página

Para trabajar con un directorio de un proyecto Git, usa sparse-checkout para seleccionar las rutas del árbol de trabajo. Así, el trabajo permanece dentro del repositorio original; no se crea un repositorio independiente que contenga únicamente ese directorio.

Qué hace (y qué no hace) sparse-checkout

Un clon normal incorpora los archivos del repositorio al árbol de trabajo. Git sparse-checkout permite elegir qué rutas con seguimiento se incorporan allí, mientras el árbol de trabajo sigue vinculado al mismo repositorio y a su historial. Es útil cuando necesitas trabajar principalmente en un módulo, como frontend de un proyecto que también tiene los directorios backend y documentation.

Seleccionar rutas no garantiza una descarga más pequeña. Sparse-checkout controla el árbol de trabajo; la cantidad de datos del repositorio que se obtiene depende de las opciones de clonación y de la configuración de Git. Si necesitas un proyecto independiente con su propio historial, el proyecto de origen debe proporcionar un repositorio separado para ese módulo.

Clonar un repositorio con sparse-checkout

Primero, confirma que la versión instalada de Git ofrece el comando sparse-checkout; por ejemplo, compruébalo con git help -a. Usa los comandos siguientes solo si esa interfaz está disponible. Clonan el repositorio sin llenar el árbol de trabajo y, después, seleccionan frontend. Sustituye la URL del repositorio y los nombres de directorio de ejemplo por tus propios valores; la URL y las rutas que aparecen aquí son marcadores de posición.

Este ejemplo autónomo en Bash crea un pequeño repositorio local y selecciona el directorio frontend. La salida muestra frontend; ese nombre permanece en inglés porque es el nombre del directorio:

set -eu
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT

git init --quiet "$work/source"
git -C "$work/source" config user.name "Example User"
git -C "$work/source" config user.email "example@example.com"
mkdir -p "$work/source/frontend" "$work/source/backend"
printf 'app source\n' > "$work/source/frontend/app.txt"
printf 'service source\n' > "$work/source/backend/service.txt"
git -C "$work/source" add frontend backend
git -C "$work/source" commit -m "Add project modules" >/dev/null
branch=$(git -C "$work/source" branch --show-current)

git clone --no-checkout --branch "$branch" "$work/source" "$work/project" >/dev/null 2>&1
git -C "$work/project" sparse-checkout init --cone
git -C "$work/project" sparse-checkout set frontend
git -C "$work/project" sparse-checkout list
frontend

Para un proyecto remoto, los pasos equivalentes son git clone --no-checkout <repository-url> my_project, cd my_project, git sparse-checkout init --cone y git sparse-checkout set frontend. Ejecútalos en ese orden. Las rutas seleccionadas son relativas a la raíz del repositorio. Si tu instalación de Git no ofrece sparse-checkout, usa git clone <repository-url> my_project para obtener en su lugar un árbol de trabajo completo.

Cambiar los directorios seleccionados

Para sustituir las rutas seleccionadas por backend y documentation, ejecuta git sparse-checkout set backend documentation desde el repositorio. Para mantener frontend y añadir otro directorio, usa git sparse-checkout add backend. El modo cone está pensado para seleccionar directorios, así que indica rutas de directorio en lugar de archivos individuales.

Usa rutas relativas a la raíz del repositorio y respeta la escritura y las mayúsculas de las rutas con seguimiento. Si la selección no muestra los archivos esperados, comprueba las rutas de nivel superior con git ls-tree --name-only HEAD y luego establece el directorio correcto. Puedes seleccionar una ruta anidada indicando su ruta desde la raíz, como frontend/components.

Verificar el árbol de trabajo y resolver problemas habituales

Ejecuta git sparse-checkout list para ver las rutas seleccionadas y git status --short para inspeccionar el árbol de trabajo. Confirma que estás en el repositorio previsto con git rev-parse --show-toplevel; los nombres de los directorios seleccionados se interpretan en relación con esa raíz.

Si el comando no está disponible, esa instalación de Git no admite la interfaz sparse-checkout o el flujo de trabajo del repositorio no permite usarla, haz un clon completo. Si el directorio está seleccionado, pero faltan archivos esperados, comprueba que la ruta exista en el commit extraído y que esté escrita correctamente. Los archivos sin seguimiento que ya estén en el árbol de trabajo pueden seguir visibles aunque sus rutas queden fuera de la selección sparse.

Para obtener más información, consulta la documentación de Git sparse-checkout, la documentación de git clone y la documentación de git help.