gitignore no funciona: cómo dejar de rastrear archivos

Contenido
A veces escribes las reglas correctamente en el .gitignore de la raíz del proyecto y, aun así, el archivo sigue apareciendo en git status y se incluye tal cual en los commits. Reescribir las reglas no cambia nada.
La causa no es una errata, sino el alcance de las reglas. La documentación oficial de Git define .gitignore como el archivo que especifica los archivos que no se pretende rastrear y deja bien claro que los archivos que Git ya está rastreando no se ven afectados. Una vez que un archivo entra en el índice con git add, ignora las reglas y Git lo sigue rastreando.
Resumen ①
.gitignoresolo se aplica a los archivos que aún no están rastreados. No tiene ningún efecto sobre archivos ya rastreados. ② Para comprobar si un archivo está rastreado, usagit ls-files --error-unmatch <ruta>; para comprobar si coincide con alguna regla,git check-ignore -v --no-index <ruta>. ③ El comando para dejar de rastrearlo esgit rm --cached <ruta>: el archivo se queda en la carpeta de trabajo y solo desaparece del índice.
Por qué un archivo sigue apareciendo aunque la regla sea correcta
Git clasifica los archivos en dos grupos: los rastreados, registrados en el índice (staging area), y los no rastreados, que aún no lo están.
.gitignore solo afecta al segundo grupo. Es una lista que dice «deja estos archivos fuera de los candidatos a rastrear», no una orden de «deja en paz los archivos que ya estás rastreando».
Por eso, un orden de pasos muy habitual provoca el problema. Si creas el proyecto, ejecutas git add . y solo después rellenas el .gitignore, los node_modules/, los artefactos de compilación y los archivos de configuración local que entraron en el índice mientras tanto no se van a quitar aunque escribas las reglas.
El síntoma también tarda en aparecer por esta misma razón. Mientras no cambie el contenido de un archivo rastreado, no aparece en git status. En cuanto modificas una sola línea, aparece de golpe con la marca M y ahí te preguntas, desconcertado, por qué aparece si se supone que lo habías ignorado.
Dos comandos para separar las dos causas
Antes de corregir nada, hay que determinar cuál es la causa. Un problema de rastreo y un problema de patrón se resuelven de maneras completamente distintas.
Paso 1: comprueba si el archivo está siendo rastreado
git ls-files --error-unmatch config.local
Si la ruta se muestra tal cual, significa que está rastreada. Si no está en el índice, obtendrás el error did not match any file(s) known to git y un código de salida 1. Si quieres comprobarlo a nivel de carpeta, basta con pasar la ruta: git ls-files node_modules.
Paso 2: comprueba si la regla captura realmente esa ruta
git check-ignore -v --no-index config.local
Si alguna regla lo captura, se mostrará algo como .gitignore:1:config.local config.local, es decir, qué patrón, de qué archivo y en qué línea lo ha capturado. Si no aparece nada y el código de salida es 1, significa que ningún patrón captura esa ruta.
--no-index es clave aquí. Por defecto, git check-ignore no muestra en absoluto los archivos rastreados, así que si no lo añades, obtendrás una salida vacía aunque la regla esté bien y buscarás la causa donde no está.
Al combinar los dos resultados, obtienes la respuesta.
| Paso 1 (rastreo) | Paso 2 (regla) | Causa |
|---|---|---|
| Se muestra | Coincide | Problema de rastreo: desactívalo con git rm --cached (ver más abajo) |
| Se muestra | No coincide | Los dos problemas: corrige el patrón y deja de rastrearlo |
| Error (no rastreado) | No coincide | Problema de patrón: revisa la sección de sintaxis |
Dejar de rastrear: git rm --cached
Si añades --cached a git rm, el archivo se elimina solo del índice. Tal como dice la documentación oficial, el archivo del árbol de trabajo se queda como está, independientemente de si tiene cambios o no. Nunca se borra el archivo del disco.
git rm --cached config.local # un solo archivo
git rm -r --cached node_modules # la carpeta entera (-r = recursivo)
git commit -m "chore: stop tracking ignored files"
Al ejecutarlo, el estado D (eliminado) queda preparado en el staging y se aplica cuando haces el commit. Después del commit, el archivo queda cubierto por la regla del .gitignore y deja de aparecer en git status.
Si has reorganizado las reglas y quieres volver a aplicarlas a todo el repositorio, puedes hacer primero commit de los cambios en curso y después vaciar el índice y volver a llenarlo.
git rm -r --cached .
git add .
git status # revisa sin falta la lista de lo que se eliminará
git commit -m "chore: apply .gitignore"
Las entradas que aparecen como D en git status son exactamente la lista de archivos que se ignorarán a partir de ahora. Si entre ellas hay algún archivo que no debería eliminarse, no hagas el commit y corrige primero el .gitignore.
Hay dos cosas que tener en cuenta. Primera: esta operación solo corta el rastreo a partir de ahora. El archivo sigue intacto en el historial de commits, así que, si se trata de algo como una clave de autenticación que llegó a un repositorio compartido, lo seguro es generar un valor nuevo.
Segunda: cuando otra persona haga pull, es posible que el archivo desaparezca de su carpeta de trabajo. Si es un archivo de configuración local que cada persona crea y usa por su cuenta, conviene incluir en el mensaje del commit o en un aviso al equipo una nota de que cada persona tendrá que volver a crearlo.
Compruébalo con nuestro Generador de .gitignore. Si el problema estaba en las reglas, tienes que completar el .gitignore antes de volver a hacer commit. Marca presets como Node, Python, macOS o VSCode y obtendrás en un solo bloque el conjunto de reglas estándar combinado.
Sin instalación ni registro, las plantillas se combinan en tu navegador y el contenido que eliges no se envía al servidor.

Sintaxis de los patrones: barras, ** y !
Si el problema era el patrón, la mayoría de las veces se resuelve con solo revisar tres reglas de sintaxis. Todas las que siguen provienen de la sección PATTERN FORMAT de la documentación oficial de Git.
La posición de las barras determina el alcance. Si un patrón tiene una barra al principio o en medio, se trata de una ruta relativa a la ubicación del archivo .gitignore; si no tiene barra, coincide a cualquier profundidad por debajo. Si termina en barra, solo captura directorios.
| Patrón | Qué captura |
|---|---|
build/ | Cualquier directorio llamado build, a cualquier profundidad |
/build/ | Solo el directorio build en la ubicación de ese .gitignore |
build | Tanto archivos como directorios llamados build |
**/foo | Cualquier foo en cualquier ubicación (equivale a foo) |
abc/** | Todo lo que hay dentro de abc, sin límite de profundidad |
a/**/b | a/b, a/x/b, a/x/y/b… |
! vuelve a incluir lo que se excluyó antes. Pero hay una restricción, y es la trampa con la que más se tropieza: si se excluye por completo el directorio padre, sus archivos no se pueden volver a incluir. Git, por rendimiento, no inspecciona el interior de los directorios excluidos, así que un patrón dirigido a un archivo interno no tendrá efecto, se escriba donde se escriba.
.vscode/ # ✗ excluye la carpeta entera → el ! de abajo queda anulado
!.vscode/settings.json
.vscode/* # ✓ excluye 'los elementos de dentro' → el ! funciona
!.vscode/settings.json
De hecho, si ejecutas git check-ignore -v --no-index .vscode/settings.json, con la primera forma verás que la regla que coincide es .vscode/, y con la segunda, que coincide !.vscode/settings.json. Así se ve directamente qué línea se ha impuesto. El preset de VSCode de nuestro Generador de .gitignore también usa la forma .vscode/* por este mismo motivo.
Dentro del mismo archivo, gana el último patrón que coincide. Por eso, la excepción con ! debe ir siempre en una línea posterior a la regla de exclusión. Lo mismo se aplica cuando el .gitignore de un subdirectorio se impone a las reglas de un directorio superior.
Puntos que suelen darte problemas
| Situación | Qué comprobar |
|---|---|
| Escribiste una regla, pero el archivo sigue entrando en los commits | Ya está rastreado — git rm --cached |
check-ignore no devuelve nada | ¿Olvidaste --no-index? |
La excepción ! no funciona | ¿Excluiste el directorio padre por completo? |
| Se ignora un archivo para el que no escribiste ninguna regla | .git/info/exclude de cada repositorio, core.excludesFile global |
| Patrón con espacios al final | Los espacios finales se ignoran (protégelos con una barra invertida, no con comillas) |
Nombre de archivo que empieza por # o ! | Debes anteponer una barra invertida al primer carácter para que se trate de forma literal |
Las dos últimas filas pueden confundirte. Una línea que empieza por # es un comentario y una que empieza por ! es una negación, así que para ignorar de verdad un archivo que empieza por ese carácter tienes que anteponer una barra invertida al primer carácter, como en \#temp.
La situación contraria —que se ignore algo sin que hayas escrito ninguna regla— se detecta con el mismo comando. La primera columna de la salida de git check-ignore -v --no-index es la ruta del archivo del que procede la regla, así que puedes distinguir al instante si viene de la configuración global o de una regla dentro del repositorio. La ubicación del archivo global se consulta con git config --get core.excludesFile.
Resumen
.gitignorese aplica solo a archivos que aún no están rastreados. No tiene efecto sobre archivos ya rastreados.- El seguimiento se comprueba con
git ls-files --error-unmatch <ruta>y la coincidencia de una regla, congit check-ignore -v --no-index <ruta>. - El comando para dejar de rastrear es
git rm --cached(añade-rpara carpetas) y no borra los archivos de la carpeta de trabajo. Los cambios se aplican al hacer commit. - Esta operación solo interrumpe el seguimiento a partir de ahora. Como el contenido sigue en el historial anterior, lo más seguro es volver a emitir los valores de autenticación expuestos.
- En los patrones, la posición de las barras define el alcance y la barra final indica si se limita a directorios.
- La excepción
!no funciona si excluyes el directorio padre por completo. Usa.vscode/*en lugar de.vscode/.
Sin instalación ni registro, las plantillas se combinan en tu navegador y el contenido que eliges no se envía al servidor.
Preguntas frecuentes
¿git rm --cached borra realmente el archivo?
No lo borra. La documentación oficial explica que esta opción elimina la ruta solo del índice y deja intacto el archivo del árbol de trabajo, tenga cambios o no.
El archivo sigue en el disco; lo único que ocurre es que, tras el commit, Git ya no lo rastrea. Eso sí, en el árbol de trabajo de otra persona que reciba ese commit de eliminación, el archivo puede desaparecer.
Si ahora ignoro un archivo de configuración que ya está en un commit, ¿también desaparece del historial?
No. Añadir .gitignore y ejecutar git rm --cached solo cortan el seguimiento futuro. El contenido permanece tal cual en los commits anteriores, así que quien reciba el repositorio puede sacar el archivo del historial.
Para borrar el historial en sí hace falta una tarea aparte que reescriba los commits, y si trabajas en equipo el impacto es considerable. Cuando se han expuesto valores como claves de autenticación, volver a emitir los valores es la medida fiable antes de tocar el historial.
¿También se aplica el .gitignore de las subcarpetas?
Sí. Git revisa el .gitignore del directorio donde está la ruta y de sus directorios superiores, y las reglas del archivo inferior se imponen a las del superior.
Después revisa, por orden, .git/info/exclude de cada repositorio y, por último, el archivo global definido por core.excludesFile. Para ver qué archivo y qué línea se impusieron, consulta la salida de git check-ignore -v --no-index.
¿Se envían al servidor las opciones que elijo en el generador?
No. Las plantillas predefinidas están dentro de la página, así que la selección, la combinación y la copia se procesan por completo en el navegador. Si eliges varias plantillas a la vez aparecen líneas que se repiten, como build/; si dejas activada la opción "Eliminar líneas duplicadas", cada línea repetida aparecerá una sola vez.
Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano