Eliminar archivos untracked en git: guía segura de git clean

TL;DR: para eliminar archivos untracked en git, ejecuta git clean -fd — pero previsualiza siempre con git clean -nd antes, porque clean borra de forma permanente y esos archivos nunca pasan por la papelera. -f para archivos, -fd para archivos y directorios, y -fdx si el output de build que está en .gitignore también debe irse. La queja más común — "git clean no me borra los archivos untracked" — casi siempre significa que los archivos viven dentro de un directorio untracked (añade -d) o que son archivos ignorados (añade -x). El desorden untracked es el subproducto normal de experimentos, builds y scripts de apoyo; esta guía muestra cómo previsualizar cada borrado, limpiar un solo directorio y qué combinaciones nunca ejecutar en un repo que te importa.

¿Qué significa "untracked files" en git status?

Untracked significa que git ve el archivo en disco pero nadie le ha dicho que lo rastree — no está en el índice ni tiene historial de commits. git status agrupa todo en tres grupos:

$ git status --short
 M src/app.ts        # modificado: rastreado, con cambios
?? notes.txt         # untracked: archivo nuevo que git no conoce
?? build/            # directorio untracked: totalmente nuevo para git

Esa distinción importa porque cada grupo necesita una herramienta de borrado distinta. Los archivos rastreados pero modificados se revierten con git restore o se van por commit — git clean no los toca. Solo las líneas ?? son territorio de git clean. Los archivos ignorados (todo lo que coincide con .gitignore) son un cuarto grupo oculto: ni siquiera aparecen como ??, y git clean los salta a menos que entres explícitamente con -x.

Si tu problema real es un archivo rastreado que nunca debió commitearse, limpiar es la herramienta equivocada — ese es trabajo de git rm --cached, o de un reset del último commit como el que cubre git undo last commit: keep the changes.

¿Cómo elimino todos los archivos y carpetas untracked en git?

El comando base es git clean -f. Sin -f, git se niega a borrar nada y solo imprime una advertencia — una barra de seguridad deliberada. La rutina completa se ve así:

# 1. Mira exactamente qué se va a borrar (dry run — no borra nada)
git clean -nd

# Borraría:
# notes.txt
# build/
# scratch/

# 2. Confirma que no hay nada valioso en la lista y borra de verdad
git clean -fd

Flag por flag:

• -f / --force — obligatorio. Borra de verdad los archivos untracked.
• -d — recorre los directorios untracked. Un -f a secas solo elimina archivos untracked del nivel superior y reporta los directorios que se negó a tocar.
• -n / --dry-run — muestra qué se borraría. Ejecútalo siempre primero.
• -x — también borra los archivos ignorados (node_modules, output de build, .env).
• -X — borra solo los ignorados, conservando los untracked que no lo son.
• -i — modo interactivo; útil cuando la lista del dry-run es larga.

Un hábito que vale la pena copiar: trata git clean -nd como git diff — miras antes de commitear, miras antes de limpiar.

¿Por qué git clean no me borra los archivos untracked?

Tres causas reales, ordenadas por frecuencia:

1. Los archivos están dentro de un directorio untracked. Con solo -f, git elimina los archivos untracked sueltos pero se detiene en los directorios, incluso reportando Would remove build/ sin borrarlo en una ejecución real. Añade -d:

git clean -fd

2. Los archivos están en .gitignore. node_modules/, dist/, .venv/ — las rutas ignoradas son invisibles para un clean normal. El dry run no las lista, y el clean tampoco las borra. Entra explícitamente:

git clean -fdx   # archivos y directorios untracked + ignorados

3. Hay un repositorio git anidado o un submodule en el camino. Git nunca borra el contenido del repo de otro desde afuera. Elimina el submodule como corresponde o pasa --force dos veces (git clean -ffd), y prefiere la primera opción.

Si el dry run no lista nada pero git status sigue mostrando entradas ??, seguramente estás en el working tree equivocado — ejecuta git rev-parse --show-toplevel y confirma que estás dentro del repo que querías limpiar.

¿Cómo elimino archivos untracked solo de un directorio específico?

Acota el clean pasándole una ruta — todo lo demás queda intacto:

git clean -fd build/          # solo dentro de build/
git clean -fd src/generated   # un árbol concreto

Esta es la respuesta al "quiero borrar los archivos y carpetas untracked de build/ pero conservar mis notas en la raíz del repo". La ruta es relativa a tu directorio actual: desde la raíz del repo el alcance es todo el repo; desde un subdirectorio, ese subárbol.

¿Cómo elimino archivos untracked sin borrarlos?

Cuando el dry run muestra archivos que quizá quieras después, no apuestes — preserva primero, limpia después:

# Guarda los archivos untracked (los ignorados también, con -a) sin borrarlos
git stash push --include-untracked
git clean -fd                      # el árbol queda limpio
git stash pop                      # tráelos de vuelta cuando hagan falta

git stash -u saca los archivos untracked del árbol pero los deja recuperables — esa es la semántica de "eliminar sin borrar" que la gente busca de verdad. Para una vista previa que puedas conservar, git clean -nd > clean-plan.txt te da la lista exacta antes de comprometerte a nada. No hay undo después de git clean -f: borrado significa desaparecido.

git clean vs git rm vs git restore: cuál usar cuando

Comando	Toca	Borra del disco	Úsalo cuando
git clean -fd	Archivos/dirs untracked	Sí	Eliminar archivos que git nunca rastreó
git clean -fdx	Untracked + ignorados	Sí	Reset completo, incluidos node_modules y output de build
git rm <file>	Archivos rastreados	Sí (staged)	Borrar un archivo y registrar el borrado en git
git rm --cached <file>	Archivos rastreados	No	Dejar de rastrear un archivo, conservarlo en disco
git restore <file>	Archivos rastreados	No	Descartar ediciones locales, conservar el archivo

La regla de una línea: clean gestiona lo que git no conoce; rm y restore gestionan lo que sí. Confundirlos es la forma clásica de perder trabajo — ejecutar git clean -fdx creyendo que se comporta como git restore.

¿Qué combinaciones de git clean nunca deberías ejecutar?

Dos hábitos que evitar de raíz:

1. Nunca ejecutes git clean -fdx a ciegas en un monorepo o workspace. Borra cada directorio ignorado — o sea, cada node_modules, cada virtualenv, cada .env local del árbol. Recuperarlos puede costar una hora de reinstalación, y un .env borrado puede que no se recupere nunca.
2. Nunca crees un alias de clean con el force incorporado. git config alias.wipe "clean -fd" se siente eficiente hasta que escribes mal la ruta. Mantén el dry run a una tecla de distancia (git clean -nd) y conviértelo en un ritual de dos comandos: previsualizar y luego borrar.

También conviene saber: limpiar los archivos untracked justo antes de un pull tipo [sync a fork with upstream] mantiene pequeña la superficie de merge — un árbol ordenado es el seguro contra conflictos más barato que existe: sync a fork with upstream, step by step.

El flujo seguro de git clean, condensado

git status --short        # ¿qué hay en el árbol?
git clean -nd             # previsualización: ¿qué SE iría?
git clean -fd             # borra archivos + directorios untracked
git clean -fdX            # (opcional) limpia solo el output de build ignorado
git status --short        # confirma: working tree limpio

Previsualiza, borra, verifica — treinta segundos, cero arrepentimientos, y git status por fin vuelve a leerse limpio.