git rm

El comando git rm elimina uno o más archivos de un repositorio Git. Esta página explica qué hace git rm, las opciones que acepta, en qué se diferencia del rm del shell, cómo deshacer una eliminación y algunas recetas prácticas.

Qué hace git rm

git rm elimina archivos rastreados — archivos que Git ya conoce. Por defecto, elimina el archivo tanto del directorio de trabajo (los archivos en tu disco) como del índice de staging (la instantánea que Git registrará en el siguiente commit), y luego prepara esa eliminación para que quede en tu próximo commit.

Algunos aspectos importantes que conviene saber de entrada:

• git rm solo funciona con archivos rastreados. Falla con fatal: pathspec '...' did not match any files si intentas eliminar un archivo no rastreado — Git no estaba siguiendo ese archivo, por lo que no hay nada que registrar.
• Puede eliminar un archivo únicamente del índice de staging (con --cached), pero no puede eliminar un archivo solo del directorio de trabajo — eso es simplemente una eliminación normal, que es lo que hace el rm del shell.
• No elimina ramas, etiquetas ni commits. Solo afecta a archivos.
• La eliminación no es permanente hasta que hagas un commit. Antes de eso, es fácil deshacerla (consulta Deshacer git rm).

Un flujo de trabajo típico se ve así:

git rm notes.txt        # deletes notes.txt and stages the deletion
git commit -m "Remove notes.txt"

Opciones del comando git rm

Deshacer git rm

git rm actualiza el índice de staging y el directorio de trabajo, pero el cambio no es permanente hasta que hagas un commit. Hasta entonces, puedes recuperar el archivo con comandos Git ordinarios. Cuál necesitas depende de hasta qué punto quieras revertir.

Antes de confirmar la eliminación

Para deshacer la preparación de la eliminación pero mantener el archivo eliminado en disco, restablece la entrada del índice a HEAD:

git reset HEAD <file>

Para recuperar el archivo por completo — tanto en el índice de staging como en el directorio de trabajo — usa el moderno comando git restore:

git restore --staged --worktree <file>

Los equivalentes más antiguos git reset HEAD <file> seguido de git checkout -- <file> siguen funcionando, pero git restore es la forma recomendada en las versiones actuales de Git.

Después de confirmar la eliminación

Si ya creaste un commit que registra la eliminación, el archivo vive únicamente en el historial. Encuentra un punto seguro con git reflog y restaura el archivo desde un commit donde todavía existía:

git restore --source=HEAD~1 <file>

Git rm vs rm

El rm del shell y git rm ambos eliminan archivos del disco, pero Git los trata de manera muy diferente.

Cuando ejecutas el rm del shell sobre un archivo rastreado, el repositorio Git nota que el archivo ha desaparecido y muestra la eliminación como un cambio no preparado. Aún tienes que ejecutar git add (o git add -u) para registrarlo en el índice de staging antes de hacer el commit.

git rm realiza ambos pasos a la vez: elimina el archivo y prepara la eliminación, por lo que está listo para el próximo commit de inmediato.

# Shell rm — deletion is unstaged, needs git add afterwards
rm notes.txt
git add notes.txt

# git rm — deletion is staged in one step
git rm notes.txt

Eliminar archivos solo del índice

Un caso habitual es mantener un archivo en disco pero dejar de hacer que Git lo rastree — por ejemplo, un archivo de configuración o un artefacto de compilación que confirmaste accidentalmente y ahora quieres ignorar. Usa --cached:

git rm --cached secrets.env

El archivo permanece en tu directorio de trabajo; solo se elimina la copia rastreada. Añade la ruta a .gitignore después para que no vuelva a añadirse.

Ejemplos

Eliminar todos los archivos .txt de una carpeta (comodín):

git rm folder/\*.txt

La barra invertida antes de * evita que el shell expanda el glob, de modo que Git mismo lo expande sobre los archivos rastreados bajo folder/. Esto también coincide con rutas en subdirectorios, no solo con los hijos directos.

Forzar la eliminación de archivos con cambios sin confirmar:

git rm -f git-*.sh

Sin -f, git rm se niega a eliminar un archivo cuyo contenido en el directorio de trabajo o en el área de staging difiere de HEAD, para protegerte de perder trabajo. El indicador de fuerza anula esa verificación.

Previsualizar una eliminación sin borrar nada:

git rm -r --dry-run logs/

Esto lista los archivos que se eliminarían bajo logs/, permitiéndote confirmar el conjunto antes de ejecutar el comando de verdad.

Eliminar archivos ya borrados con rm del shell

Si has eliminado varios archivos rastreados con el rm del shell y quieres registrarlos todos en tu próximo commit, prepara todas las eliminaciones a la vez:

git add -u
git commit -m "Remove obsolete files"

git add -u prepara las actualizaciones de archivos ya rastreados, incluidas las eliminaciones. Alternativamente, crea una lista de las rutas eliminadas y pásalas por pipe a git rm --cached:

git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached

--diff-filter=D selecciona solo las rutas eliminadas, y el par -z / -0 usa separadores NUL para que los nombres de archivo con espacios se manejen de forma segura.

Práctica