Borrar archivos sin seguimiento de git: el ritual de clean sin riesgos

■ espacio · carril de prosa

EL RADIO DE ALCANCE

Cada archivo de tu árbol vive en una de tres zonas — y cada flag de clean llega exactamente a un anillo:

el cuarto cubo es la trampa: los archivos ignorados ni siquiera aparecen como ?? — un clean sencillo los salta en silencio, por eso «no borra nada»

QUÉ SIGNIFICA «UNTRACKED»

Sin seguimiento significa que git ve el archivo en el disco pero nunca se le ha pedido rastrearlo — no está en el índice, no hay historial de commits. git status agrupa todo en cubos, y cada uno necesita una herramienta de borrado diferente:

$ git status --short
 M src/app.ts        # modified: tracked, changed
?? notes.txt         # untracked: new file git doesn't know
?? build/            # untracked directory: entirely new to git

Los archivos rastreados-modificados se revierten con git restore o se llevan a un commit — git clean no los toca. Solo las ?? líneas son territorio del clean. Si tu problema real es un archivo rastreado que nunca debió ser commiteado, clean es la herramienta equivocada — eso es trabajo de git rm --cached, o un reset del último commit.

EL RITUAL

# 1. see exactly what will be deleted (dry run — deletes nothing)
git clean -nd
# Would remove:
# notes.txt
# build/

# 2. confirm nothing precious is in the list, then delete for real
git clean -fd

verify: git clean -nd → muestra «Would remove notes.txt build/» · tras -fd: git status --short ya no lista líneas ??

Una costumbre que vale la pena copiar: trata git clean -nd como git diff — miras antes de commitear, miras antes de limpiar. Flag por flag:

• -f / --force — obligatorio. Borra de verdad los archivos sin seguimiento. Sin él git se niega e imprime una advertencia — un riel de seguridad deliberado.
• -d — descender en los directorios. Un -f sencillo solo borra archivos sin seguimiento del primer nivel y reporta los directorios que rehusó tocar.
• -n / --dry-run — mostrar lo que se borraría. Siempre primero.
• -x — además borrar ignorados archivos (node_modules, output de build, .env).
• -X — borrar únicamente los archivos ignorados, conservando los sin seguimiento pero no ignorados.
• -i — modo interactivo; útil cuando la lista del dry-run es larga.
• -e <path> — excluir — «limpia todo excepto notes.txt» es git clean -fd -e notes.txt.

«CLEAN NO BORRA NADA» — LAS TRES CAUSAS

1. Los archivos están dentro de un directorio sin seguimiento. Solo con -f, git borra los archivos sueltos pero se detiene en los directorios — informando incluso Would remove build/ sin borrarla en una corrida real.-d: git clean -fd.
2. Los archivos están gitignored. node_modules/, dist/, .venv/ — las rutas ignoradas son invisibles para un clean sencillo; el dry run tampoco las lista. Pídelas explícitamente: git clean -fdx.
3. Un repositorio git anidado o un submódulo estorba. Git nunca borra el contenido de otro repositorio desde fuera. Quita el submódulo como es debido o pasa --force dos veces (git clean -ffd) — mejor la primera.

Si el dry run no lista nada pero git status sigue mostrando ?? entradas, probablemente estás en el árbol de trabajo equivocado — git rev-parse --show-toplevel y comprueba que estás en el repositorio que intentabas limpiar.

UN SOLO DIRECTORIO A LA VEZ

Delimita el clean pasando una ruta — todo lo demás queda intacto. La ruta es relativa a tu directorio actual: desde la raíz del repositorio delimita todo el repo; desde un subdirectorio, ese subárbol:

git clean -fd build/          # only inside build/
git clean -fd src/generated   # one specific tree

QUITAR SIN BORRAR

Cuando el dry run muestra archivos que quizá quieras después, no juegas — preserva primero, limpia después. git stash -u mueve los archivos sin seguimiento fuera del árbol pero los deja recuperables — esa es la semántica «quitar sin borrar» que la gente busca de verdad:

# stash untracked files (including ignored with -a) without deleting
git stash push --include-untracked
git clean -fd                      # tree is clean
git stash pop                      # bring them back when needed

verify: git stash list → stash@{0} guarda lo que levantó git stash -u

Para una previsualización que puedas conservar: git clean -nd > clean-plan.txt. No hay marcha atrás tras git clean -f: borrado significa perdido — la papelera nunca interviene.

CLEAN VS RM VS RESTORE

La regla de una línea: clean gestiona lo que git no conoce; rm y restore gestionan lo que sí conoce. Mezclarlos es como la gente pierde trabajo — ejecutar git clean -fdx creyendo que se comporta como git restore.

08LO QUE NUNCA HAY QUE EJECUTAR

1. Nunca ejecutes git clean -fdx a ciegas en un monorepo o un workspace. Borra cada directorio ignorado — cada node_modules, cada virtualenv, cada .env local en el árbol..env puede que no sea recuperable en absoluto.
2. Nunca dejes el force en duro dentro de un alias de clean. git config alias.wipe "clean -fd" parece eficiente hasta que escribes mal la ruta. Ten el dry run a una tecla de distancia y conviértelo en un ritual de dos comandos: previsualizar, luego borrar.

El flujo completo, condensado:

git status --short        # what's in the tree?
git clean -nd             # preview: what WOULD go?
git clean -fd             # delete untracked files + directories
git clean -fdX            # (optional) clear only ignored build output
git status --short        # confirm: working tree clean

Previsualizar, borrar, verificar — treinta segundos, cero arrepentimiento, y git status por fin se lee limpio otra vez. El primo de este problema: .gitignore que parecen no hacer nada — si tus reglas son ignoradas, suelen ser archivos rastreados más que sintaxis. Y un árbol ordenado justo antes de un fork sync mantiene pequeña la superficie de fusión — el seguro de conflictos más barato que hay.

fin de la página clean · nada se descargó · todo es local