git sparse-checkout para coding agents: menos disco, no otro clone

git sparse-checkout reduce el working tree a un subconjunto de archivos tracked. El man (git-sparse-checkout(1); git-scm.com/docs/git-sparse-checkout HTTP 200, last-modified 2026-08-31; pie del man local Git 2.54.0, 2026-04-19; binario Git 2.50.1 / Apple Git-155): Reduce your working tree to a subset of tracked files. SYNOPSIS del binario: git sparse-checkout (init | list | set | add | reapply | disable | check-rules) [<options>]. El man 2.54 añade clean; este binario no.

No es clone. Clone crea otro objeto store. Sparse recorta este working tree. Tampoco es worktree: worktree es otro directorio con su HEAD. Sparse es el mismo checkout, con menos archivos en disco.

El man lo marca EXPERIMENTAL: THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE FUTURE. Un agente no lo usa “por si el monorepo pesa”.

Contrato: git sparse-checkout set -- <dir>… (cone, default). Luego list. Cero --no-cone. Cero init. Cero clean. Cero add antes de set.

Qué hace (y qué no)

Cone mode (default): los args son directorios, como git ls-tree -d --name-only. Entran todos los archivos bajo esos dirs, más los hermanos inmediatos de cada ancestro y el toplevel. Por eso set -- apps/web deja README.md aunque no lo hayas pedido.

--no-cone trata los args como patrones. El man: we do not recommend using it. No funciona con --sparse-index.

set enciende core.sparseCheckout y core.sparseCheckoutCone por worktree (extensions.worktreeConfig; archivo .git/config.worktree). No pisa el sparse de otro worktree.

Verificado 2026-09-06 (Git 2.50.1 / Apple Git-155). Repo apps/web, apps/api, docs, README.md:

• git sparse-checkout set -- apps/web: 0. list imprime apps/web. En disco: README.md + apps/web/. Sin docs/, sin apps/api/.
• git sparse-checkout add -- apps/api: 0. list = apps/api + apps/web. Vuelve apps/api/b.ts.
• add antes de set: 128, no sparse-checkout to add to.
• reapply antes de set: 128, must be in a sparse-checkout to reapply sparsity patterns.
• reapply con sparse activo: 0.
• printf 'docs/c.md\n' | git sparse-checkout check-rules: 0, cero stdout (docs/c.md no entra al cono).
• check-rules con apps/web/a.ts y README.md: 0, imprime esos paths.
• set -- does/not/exist: 0. list muestra ese dir. En disco solo el toplevel (README.md). Git no valida que el path exista.
• set sin args: 0. Queda el toplevel.
• Sin subcomando: 129, need a subcommand.
• disable: 0. Vuelve docs/ y apps/api/. disable sin sparse previo: también 0.
• clean / clean --dry-run: 129, unknown subcommand: clean' (binario 2.50.1; el man 2.54 sí lo documenta).
• Fuera de un repo: 128.
• index.sparse tras set: false. El sparse-index no se enciende solo.
• git clone --sparse: el help lo define como initialize sparse-checkout file to include only files at root. No es set de un dir de app.

El man: git commit -a no registra como borrados los paths fuera del sparse. Un agente que “no ve” docs/ y commitea con -a no los elimina del repo. Tampoco clean es el inverso: clean borra untracked; sparse oculta tracked.

Lo que el agente sí / no corre

Quiero	Comando	Trampa
Sesión aislada	worktree add	sparse “para no pisar al humano”
Primer clone liviano	clone + set -- <dir>	clone --sparse y asumir el dir de la app
Ver el cono	git sparse-checkout list	find / ls como inventario del repo
¿Este path entra?	check-rules por stdin	adivinar por el cwd
Volver al árbol completo	disable	clean -f o restore masivo

Prohibido en autónomo:

• --no-cone. El man no lo recomienda. Rompe --sparse-index. Verificado: set --no-cone -- 'apps/web/*' sale 0 y list muestra el glob, no un dir.
• init. Deprecated. El man: históricamente vaciaba casi todo el árbol y luego set devolvía archivos; se perdían ignorados. Verificado: init sale 0 sin paths. No lo corras.
• clean / clean -f. En 2.50.1 ni existe (129). El man 2.54 exige -f o clean.requireForce=false para borrar dirs fuera del cono. Un agente no borra disco “para alinear el índice”.
• add antes de set. Verificado: 128.
• set de un path inventado “por si acaso”. Verificado: 0 y el árbol queda en el toplevel. Mentiría “ya está el paquete”.
• --sparse-index autónomo. El man: experimental; tools externos no entienden las entradas sparse del índice. Default verificado: index.sparse=false.
• Tratar archivos ausentes como rm o como untracked. Son tracked con skip-worktree. ls-files los sigue listando.
• clone --sparse como atajo de “solo apps/web”. El help: solo el root. Después hace falta set.
• Sparse para aislar un agente. Eso es worktree. Sparse recorta el mismo HEAD.
• Correrlo fuera de un repo. Verificado: 128.

Receta (60 segundos)

Solo si un humano pidió menos disco en este worktree. Si el ticket es “no tocar el checkout del humano”: worktree.

git status -sb
git sparse-checkout set -- apps/web
git sparse-checkout list

• 0 + list con los dirs pedidos: reporta el cono y para. No commitees.
• Otro: error. No reintentes con --no-cone ni init.

Para ampliar:

git sparse-checkout add -- apps/api
git sparse-checkout list

Para deshacer:

git sparse-checkout disable

Cierre = list (o el árbol completo tras disable). Cero push a main.

sparse vs clone vs worktree

clone copia el repo. --filter=blob:none recorta objetos (partial clone). Sparse recorta el working tree; el objeto store sigue ahí.

worktree es otro directorio + otra rama. Sparse vive dentro de un worktree (config worktree-specific). Un agente que necesita aislarse: worktree. Un humano que ya está en el monorepo y solo quiere apps/web en disco: sparse.

check-rules no es ls-tree. ls-tree lista el tree object. check-rules filtra paths contra el cono actual.

El curso instalar un agente cubre el loop local. Hub: comparativas y decisiones. Sparse no es sandbox: oculta tracked; no aísla HEAD.

Checklist

• ¿Hace falta recortar disco, o basta un worktree?
• git status -sb. set -- dirs reales. list coincide.
• Cero --no-cone, cero init, cero clean, cero add antes de set.
• Paths que no ves siguen tracked. No commit -a “para limpiar”.
• Cierre = list o disable. No push a main.

FAQ

¿set -- apps/web quita README.md? No. Cone incluye el toplevel. Verificado.

¿add crea el sparse? No. Verificado: 128 si no hubo set.

¿clean --dry-run para ver qué borraría? En Git 2.50.1: 129. No lo uses.

¿clone --sparse deja solo mi app? No. Help: solo archivos del root. Luego set.

¿HEAD cambia? No. Cambia qué paths hay en disco. Para otra rama: worktree o switch.

sparse-checkout es experimental. El siguiente paso lo decide un humano: o disable, o un worktree propio.