gitignore no es un sandbox: qué ignora Git y qué sigue viendo el agente

.gitignore no es un firewall. El manual de Git lo dice: especifica untracked files que Git no debe listar ni añadir. Los archivos ya trackeados no se afectan. Y un agente con read_file / cat no es Git: si el path existe, lo lee.

Esta guía no sustituye sandboxing. Es el malentendido que hace que un .env “seguro” aparezca en un PR review del modelo. El curso instalar un agente asume un repo limpio; aquí el disco no lo está.

Precedencia (oficial)

Al decidir si ignorar un path, Git mira fuentes de mayor a menor (dentro del mismo nivel, gana el último patrón):

1. Patrones por CLI (comandos que los aceptan).
2. .gitignore en el directorio del path y padres, hasta la raíz del worktree. El de más abajo pisa al de arriba. Los patrones son relativos al archivo .gitignore.
3. $GIT_DIR/info/exclude (local al clone, no se comparte).
4. core.excludesFile (default ~/.config/git/ignore o $XDG_CONFIG_HOME/git/ignore).

Dónde va cada cosa:

Archivo	Se clona	Para qué
.gitignore en el repo	Sí	Build artifacts, .env, node_modules que todos quieren fuera
info/exclude	No	Basura de tu máquina / un agente
core.excludesFile	No	Editor backups en todos tus repos

Patrones que importan

• Línea vacía: separador.
• # comentario; \# si el patrón empieza con hash.
• / al final = solo directorio.
• / al inicio (en un .gitignore de raíz) = solo desde ese archivo.
• ! negación. Un * previo puede haber excluido el directorio entero: no puedes re-incluir un archivo dentro de un dir ignorado a menos que negues el dir y vuelvas a ignorar el resto. El man page lo detalla; los agentes se equivocan aquí todo el día.

git check-ignore -v .env te dice qué regla ganó. Pídele eso al agente en vez de “¿está ignorado?”.

El agente no respeta gitignore

Harness típico (Claude Code, Codex, Cursor): tools de glob/read recorren el FS. Algunos respetan .gitignore en búsqueda; casi ninguno bloquea un path absoluto que el modelo pide. Por eso:

1. Deny-list del sandbox: .env, .env.*, *.pem, id_rsa.
2. .gitignore para que no se commiteen.
3. No copiar secretos al worktree del agente.

Un .env gitignored sí entra en git add -f. El agente que “arregla” el ignore con -f es un incidente. Prohíbelo en las instrucciones.

Archivos trackeados: si commiteaste .env hace un año, gitignore no lo saca. git rm --cached .env + rotar la clave. El agente que solo edita .gitignore no cierra el leak.

Receta mínima de repo con agentes

node_modules/
.env
.env.*
!.env.example
.DS_Store
*.pem

Más info/exclude para outputs locales del agente (.agent-scratch/). No pongas secretos en AGENTS.md.

git status limpio no significa “el agente no vio .env”. Significa que Git no lo va a commitear si nadie hace add -f.

FAQ

¿.cursorignore / .claudeignore? Capa extra del producto; no reemplaza gitignore ni el sandbox. Si existe, duplícalo. Si no, deny-list.

¿Negar node_modules y re-incluir un paquete? Dolor. No. El agente no debe “arreglar” node_modules a mano.

¿Worktrees? Cada worktree tiene su disco; .gitignore del repo se comparte. .env no. No asumas que el ignore copia secretos.

¿git ls-files -o -i --exclude-standard? Lista untracked ignorados. Útil en CI para ver si el agente dejó basura.

Verificado 2026-09-03 contra git help gitignore y https://git-scm.com/docs/gitignore.