git clean para coding agents: dry-run primero, -x casi nunca

git clean elimina archivos que Git no rastrea. Esa definición parece simple hasta que un coding agent encuentra una carpeta llena de artefactos, ejecuta una variante agresiva para “dejar limpio” el proyecto y descubre que allí también vivían un .env, una base local o resultados todavía no incorporados. Como esos archivos no están en commits, Git normalmente no puede restaurarlos.

La solución no es prohibir toda limpieza. Es convertirla en un contrato verificable: inventariar, simular, limitar el alcance y borrar solo lo explicado. La documentación oficial de Git recomienda ejecutar primero -n o --dry-run; Pro Git añade que git stash --all puede ser una alternativa recuperable cuando de verdad necesitas apartar todo.

Esta guía complementa qué puede leer un agente aunque exista .gitignore y el flujo de ramas y pull requests con GitHub CLI. Para aislar tareas simultáneas, conviene empezar antes por un worktree por coding agent.

Qué borra git clean y qué deja intacto

Sin opciones especiales, git clean apunta a archivos untracked que no están ignorados. No revierte archivos rastreados modificados: para eso existen comandos como git restore. Tampoco entra normalmente en directorios untracked; -d amplía el alcance a esos directorios.

Git exige -f cuando clean.requireForce conserva su valor predeterminado verdadero. Esa barrera evita una eliminación accidental, pero no decide si el contenido es prescindible. En automatización, -f debe ser el último paso de una revisión, no el primero.

Los archivos ignorados merecen atención aparte:

• -x desactiva las reglas normales de ignore e incluye todos los archivos untracked, también los ignorados.
• -X elimina solo archivos ignorados.
• -e <patrón> añade una exclusión específica para esa ejecución.

-x y -X pueden servir para reconstruir productos generados desde cero, pero un repositorio real también suele ignorar secretos, cachés costosos, bases locales y archivos del editor. Por eso un agente no debe interpretar “ignored” como “desechable”.

El procedimiento seguro en cinco pasos

1. Confirma el directorio y el estado

Antes de limpiar, el agente debe demostrar en qué repositorio y worktree está. Un comando destructivo ejecutado en el checkout equivocado puede afectar otra tarea válida.

git rev-parse --show-toplevel
git status --short --untracked-files=all
git worktree list

El primer comando fija la raíz; el segundo muestra el inventario; el tercero revela otros worktrees. Si hay cambios rastreados inesperados, la tarea se detiene: git clean no los borrará, pero indican que el entorno no está bajo control.

2. Ejecuta siempre un dry-run

git clean -n
git clean -n -d

-n muestra lo que se eliminaría sin hacerlo. La documentación también aclara que el dry-run no necesita la protección de clean.requireForce, precisamente porque no borra. La segunda variante añade directorios untracked al preview; todavía no autoriza su eliminación.

El output es una lista de revisión. Cada línea debería clasificarse como artefacto reproducible, scratch de la tarea o contenido desconocido. Si aparece algo desconocido, el resultado correcto no es “probablemente basura”: es conservarlo y escalar la duda.

3. Reduce el alcance con un pathspec

El patrón más seguro no limpia todo el repositorio. Restringe la operación a una ruta creada por la tarea:

git clean -n -d -- tmp/agent-run-42
git clean -f -d -- tmp/agent-run-42

La segunda línea solo es aceptable si el preview anterior contiene exactamente ese scratch. El separador -- deja claro que lo siguiente es una ruta, no otro flag. Evita comodines amplios: una carpeta explícita es más fácil de auditar que tmp/*.

Si el objetivo es un único archivo generado, limita todavía más:

git clean -n -- reports/preview.json
git clean -f -- reports/preview.json

4. Reserva -x, -X y el doble -f

La documentación de Git explica un caso especial: un directorio untracked que contiene otro repositorio Git no se elimina con un solo -f; exige un segundo -f. Esa resistencia protege clones anidados. Un agente autónomo no debería superar esa barrera: podría estar ante otro proyecto o un worktree colocado allí deliberadamente.

Del mismo modo, git clean -fdx combina directorios, force e inclusión de ignorados. Es útil en entornos efímeros creados específicamente para builds limpios, pero no es un valor por defecto razonable en la laptop o workspace persistente de una persona. Si una CI descarta por completo el checkout al terminar, recrear el workspace suele ser más claro que enseñar al agente a barrerlo sin contexto.

5. Verifica el resultado

Después de una limpieza permitida, vuelve a consultar el estado y ejecuta la validación que motivó la acción:

git status --short --untracked-files=all
pnpm test

El comando de validación cambia según el repositorio. La prueba importante es que desapareció únicamente el artefacto objetivo y que el proyecto sigue funcionando. El log del agente debe conservar el dry-run, la orden final limitada y el estado posterior.

Tabla de decisión para coding agents

Situación	Acción preferida	Evitar
Quieres saber qué sobra	git status + git clean -n	Empezar con -f
Scratch conocido de una tarea	-n -- <ruta> y luego -f -- <ruta>	Limpiar toda la raíz
Directorio scratch conocido	Añadir -d con pathspec	-fd sin alcance
Necesitas apartar trabajo recuperable	Considerar git stash --all	Borrar antes de revisar
Build realmente efímero	Recrear checkout o contenedor	-fdx en workspace persistente
Aparece un repo anidado	Detenerse y pedir decisión	Añadir un segundo -f
Hay .env o secretos en preview	Detenerse	Confiar en que ignored es basura

Regla lista para AGENTS.md

Puedes incorporar un contrato breve y comprobable al repositorio:

Never run git clean -fdx in a persistent workspace.
Run git status --untracked-files=all and git clean -n first.
Delete only a reviewed pathspec created by the current task.
Do not use -x, -X, or a second -f without explicit human approval.
After cleaning, show git status and run the relevant verification.

La regla funciona porque describe evidencia observable. “Ten cuidado con Git” es ambiguo; “muestra el dry-run y limita el pathspec” puede comprobarse en logs y tests.

Preguntas frecuentes

¿git clean también borra archivos modificados que ya están en Git?

No. Su objetivo son archivos untracked. Los cambios sobre archivos rastreados siguen visibles en git status. No uses esa diferencia como permiso para limpiar: un untracked puede contener trabajo valioso aunque Git no lo conozca.

¿git clean -i es más seguro?

El modo interactivo permite filtrar o seleccionar elementos, pero espera respuestas en un prompt. Puede ser útil para una persona sentada frente a la terminal; es mala interfaz para un agente headless. Para automatización, un dry-run registrado y un pathspec explícito son más reproducibles.

¿Puedo limpiar node_modules con -X?

Solo si confirmaste que la carpeta está ignorada, que no comparte cachés importantes y que reinstalar es aceptable. En este proyecto la política es usar pnpm; aun así, borrar dependencias no debería ser una solución genérica para cualquier fallo de build.

¿Cuál es la alternativa si todavía no sé si los archivos sirven?

No borres. Muévelos fuera del flujo mediante una acción recuperable y explícita, o usa git stash --all cuando encaje. Luego valida el proyecto y elimina el respaldo únicamente cuando ya no haga falta.

Consultado el 3 de septiembre de 2026: documentación oficial de git-clean y capítulo “Stashing and Cleaning” de Pro Git. El principio operativo es sencillo: si el agente no puede explicar cada línea del dry-run, todavía no tiene autorización técnica para reemplazar -n por -f.