git clean

Qué hace git clean

El comando git clean elimina los archivos sin seguimiento de tu directorio de trabajo. Un archivo sin seguimiento es aquel que existe en el disco pero Git aún no lo rastrea, es decir, nunca ha sido añadido con git add y no está en el índice.

Esto diferencia a git clean de sus vecinos entre los comandos para deshacer cambios:

• git reset mueve el puntero de la rama y puede quitar cambios rastreados del área de preparación.
• git checkout restaura archivos rastreados a un estado anterior.
• git clean elimina los archivos que Git no rastrea en absoluto.

Juntos cubren todo el árbol de trabajo: reset/checkout manejan el contenido rastreado y preparado; clean se encarga del resto. Un uso típico es limpiar artefactos de compilación, archivos generados o restos de experimentos para partir de una copia prístina del árbol confirmado.

git clean es irreversible. Elimina archivos directamente del sistema de archivos, no en un área recuperable como el stash. No existe un comando para deshacer git clean. Siempre haz una vista previa con una ejecución en seco (-n) primero.

El ejemplo a continuación configura un repositorio con un elemento rastreado y varios sin rastrear para que puedas ver la distinción:

Configurar un repositorio de ejemplo

mkdir test_directory
cd test_directory/
git init .
#Initialized empty Git repository in /Users/kev/code/test_directory/.git/
echo "tracked file" > ./test_tracked_file
git add ./test_tracked_file
echo "untracked" > ./test_untracked_file
mkdir ./test_untracked_dir && touch ./test_untracked_dir/file
git status
#On branch master
#No commits yet
#Changes to be committed:
#  (use "git rm --cached <file>..." to unstage)
#        new file:   test_tracked_file
#Untracked files:
#  (use "git add <file>..." to include in what will be committed)
#        test_untracked_dir/
#        test_untracked_file

Después de ejecutar esto tendrás un repositorio nuevo con un archivo preparado, test_tracked_file, más un archivo sin rastrear (test_untracked_file) y un directorio sin rastrear (test_untracked_dir). git status los reporta en secciones separadas, exactamente la división que le importa a git clean. Todo lo que sigue opera sobre este repositorio.

Por qué se requiere force

Ejecuta el comando sin opciones y Git lo rechaza:

git clean
#fatal: clean.requireForce defaults to true and neither -i, -n, nor -f given; refusing to clean

Dado que la eliminación es permanente, Git no se ejecutará a menos que lo confirmes con -f (forzar), -n (ejecución en seco) o -i (interactivo). Puedes cambiar el valor predeterminado con la configuración de git config clean.requireForce, pero dejarlo activado es la opción segura.

Opciones comunes y uso

El comportamiento de git clean se controla casi en su totalidad mediante un puñado de indicadores cortos que se combinan libremente.

-n: ejecución en seco (vista previa)

El indicador -n (o --dry-run) lista lo que se eliminaría sin borrar nada. Conviértelo en tu primer paso predeterminado.

git clean -n
#Would remove test_untracked_file

La salida nombra test_untracked_file. Observa que el directorio sin rastrear no aparece en la lista, porque de forma predeterminada git clean ignora los directorios (ver -d más abajo).

-f: forzar la eliminación

El indicador -f (o --force) realiza la eliminación de forma efectiva. Es obligatorio a menos que clean.requireForce esté establecido en false.

git clean -f
#Removing test_untracked_file

test_untracked_file ha desaparecido; un git status posterior ya no lo lista. De forma predeterminada, git clean -f actúa sobre todos los archivos sin rastrear en el directorio actual. Los archivos que coincidan con .gitignore se dejan intactos a menos que añadas -x (ver más abajo).

Para limitar la operación a una ubicación específica, pasa una ruta:

git clean -f path/to/dir

-d: incluir directorios sin rastrear

De forma predeterminada, git clean omite los directorios sin rastrear. Añade -d para eliminarlos también. Combínalo con -n para una vista previa y luego con -f para confirmar:

git clean -dn
#Would remove test_untracked_dir/
#Would remove test_untracked_file
git clean -df
#Removing test_untracked_dir/
#Removing test_untracked_file

Con -d, la ejecución en seco ahora lista el directorio además del archivo sin rastrear, y la ejecución forzada elimina ambos, borrando el directorio y todo su contenido.

-x: incluir archivos ignorados

Normalmente git clean respeta .gitignore. El indicador -x le indica que también elimine los archivos ignorados, como node_modules/, la salida de compilación o carpetas de editores como .idea/. Es potente y fácil de lamentar, así que realiza siempre una ejecución en seco primero.

git clean -xn
#Would remove .idea/
#Would remove build/

-x se combina con los demás indicadores. La combinación siguiente limpia archivos sin rastrear, directorios sin rastrear y archivos ignorados en un solo paso, el equivalente a "restablecer este checkout a exactamente lo que está confirmado":

git clean -xdf

Referencia rápida

Modo interactivo

Si no estás seguro de qué debería eliminarse, ejecuta git clean en modo interactivo con el indicador -i. Es la forma más segura de limpiar un árbol de trabajo desordenado, porque nada se elimina hasta que lo confirmes. El ejemplo a continuación también añade -d para incluir directorios. Git imprime los elementos candidatos y luego un indicador What now> con seis comandos:

git clean -di
#Would remove the following items:
#  test_untracked_dir/ test_untracked_file
#*** Commands ***
#    1: clean                2: filter by pattern    3: select by numbers
#    4: ask each             5: quit                 6: help
#What now>

Esto es lo que hace cada comando.

6 — help. Escribe 6 para imprimir una descripción de cada comando:

What now> 6
#clean               - start cleaning files and directories
#filter by pattern   - exclude items from deletion
#select by numbers   - select items to be deleted by numbers
#ask each            - confirm each deletion (like "rm -i")
#quit                - stop cleaning
#help                - this screen
#?                   - help for prompt selection

1 — clean. Elimina los elementos listados actualmente y luego sale:

What now> 1
#Removing test_untracked_dir/
#Removing test_untracked_file

2 — filter by pattern. Te permite excluir elementos mediante un glob. Aquí el patrón *_file elimina test_untracked_file de la lista de eliminación, dejando solo el directorio en la cola:

What now> 2
#test_untracked_dir/ test_untracked_file
#Input ignore patterns>> *_file
#test_untracked_dir/

3 — select by numbers. Refina la lista por número de elemento en lugar de patrón. Git numera cada candidato y escribes los que deseas conservar:

What now> 3
#           1: test_untracked_dir/  2: test_untracked_file
#Select items to delete>>

4 — ask each. Recorre cada candidato con un indicador y/N, como rm -i. Responde N para conservar un elemento:

What now> 4
#Remove test_untracked_dir/ [y/N]? N
#Remove test_untracked_file [y/N]? N

5 — quit. Sale del modo interactivo sin eliminar nada:

What now> 5
#Bye.

git clean vs. stashing y reset

git clean solo afecta a los archivos sin rastrear, así que úsalo cuando quieras descartar trabajo en lugar de guardarlo. Si puede que quieras recuperar los cambios más adelante, prefiere una de estas opciones:

• git stash — guarda las modificaciones rastreadas (y, con -u, los archivos sin rastrear) para que puedas restaurarlas más tarde. Reversible.
• git reset — mueve el puntero de la rama y quita del área de preparación o descarta los cambios rastreados.
• git checkout — restaura los archivos rastreados a su estado confirmado.

Un restablecimiento completo habitual del árbol de trabajo consiste en combinar reset para el contenido rastreado con clean para el contenido sin rastrear:

git reset --hard   # discard tracked changes
git clean -xdf     # remove untracked and ignored files

Tras esos dos comandos, el directorio de trabajo coincide exactamente con el último commit, sin archivos sobrantes de ningún tipo.

Práctica