La lección anterior dejó a gestor-tareas con un historial legible, bisecable y reversible. Pero un historial impecable puede contener basura, y el de gestor-tareas la contiene: Bruno subió sin darse cuenta la carpeta node_modules completa —14.000 ficheros y 180 MB—, Carla ha ido sembrando Thumbs.db por los directorios de imágenes, el macOS de Bruno deja un .DS_Store en cada carpeta que abre en el Finder, y en algún commit de hace meses hay un fichero config.js con la contraseña de la base de datos de pruebas.

Esta lección trata de la primera línea de defensa contra todo eso: .gitignore, el mecanismo con el que se le dice a Git qué ficheros no debe ni proponerse versionar. Lo mencionamos de pasada en la lección 02-04, al ver git status, y prometimos desarrollarlo aquí.

Es un fichero engañosamente simple. Su sintaxis tiene esquinas que confunden a todo el mundo —la negación, la barra inicial, la trampa de los directorios— y, sobre todo, esconde una regla que es la causa del 90 % de las preguntas sobre Git en foros: .gitignore no sirve para dejar de seguir un fichero que ya está versionado.

1. Por qué importa lo que no se versiona
2. Qué no debe entrar nunca: tabla por categorías
3. Cómo funciona: precedencia y ámbito
4. Sintaxis completa de los patrones
5. La negación con ! y su trampa
6. Los tres niveles: proyecto, local y global
7. La regla que confunde a todo el mundo: solo afecta a lo no seguido
8. Sacar del seguimiento con git rm --cached
9. Depurar con git check-ignore -v
10. Forzar con git add -f
11. Plantillas por lenguaje
12. El patrón para secretos: .env y .env.ejemplo

Versionar lo que no toca tiene cuatro costes, y los cuatro son mayores de lo que parecen:

Hay un principio que ordena todas las decisiones:

Se versiona la fuente, no el resultado. Si un fichero se puede regenerar a partir de otros ficheros del repositorio, no se versiona. Si contiene información propia de una máquina o de una persona, no se versiona. Si es un secreto, no se versiona jamás.

Con dos excepciones importantes que conviene conocer, porque son las que confunden:

• Los ficheros de bloqueo de dependencias (package-lock.json, yarn.lock, Cargo.lock en aplicaciones) sí se versionan. No son un resultado: son la fuente de la reproducibilidad. Sin ellos, dos personas instalan versiones distintas.
• La configuración compartida del proyecto (.editorconfig, .gitattributes, la parte del .vscode/ que define tareas y extensiones recomendadas) sí se versiona. Es fuente, no resultado.

El .gitignore que el equipo de gestor-tareas acabó adoptando:

Fíjate en los dos usos de ! (negación) al final de bloques: !.env.ejemplo y !.vscode/extensions.json. Los explicamos en el apartado 5, junto con la trampa que esconden.

Tres reglas gobiernan el comportamiento:

Regla 1: .gitignore se aplica por directorio y hacia abajo. Un .gitignore afecta a su propio directorio y a todos sus subdirectorios. Puedes tener varios en un mismo repositorio.

Regla 2: gana el patrón más específico. Git evalúa, en este orden de prioridad creciente:

1. core.excludesFile (global del usuario)
2. .git/info/exclude (local del repositorio)
3. .gitignore de los directorios, de la raíz hacia abajo (el más profundo gana)
4. La línea de órdenes (git add -f)

Regla 3: dentro de un mismo fichero, gana la última línea que coincida. Por eso las negaciones van después del patrón que anulan:

El .gitignore se versiona. Es parte del proyecto y debe estar en el primer commit. Si no lo está, cada persona del equipo tiene que descubrir por su cuenta qué no debe subir, y alguien fallará.

Git usa una sintaxis derivada de los globs de shell, con algunas particularidades propias.

La barra inicial ancla a la raíz. Es la diferencia más importante y la más olvidada:

Si tu proyecto tiene build/ en la raíz y también src/componentes/build/ que sí quieres versionar, necesitas la barra inicial.

Una barra en medio del patrón también ancla. Esta es la regla que sorprende: si el patrón contiene una / en cualquier posición que no sea la final, se interpreta como relativo al directorio del .gitignore, no como "a cualquier profundidad".

Git no versiona directorios, solo ficheros: un directorio vacío simplemente no existe para Git. Si tu aplicación necesita que exista datos/ al arrancar, el patrón habitual es:

Y creas un fichero vacío datos/.gitkeep. El nombre no tiene nada de especial —Git no lo conoce—; es solo una convención para decir "este fichero existe para que el directorio exista".

Fíjate en que usamos datos/* y no datos/. La razón es la trampa del apartado siguiente.

La regla que más tiempo hace perder en todo .gitignore:

Si un directorio está ignorado, Git no entra en él. Por tanto, no se puede des-ignorar un fichero que esté dentro de un directorio ignorado.

Es una optimización deliberada: Git no recorre miles de ficheros de node_modules/ solo por si alguna regla posterior rescata alguno. Y produce este fallo, que parece un error de Git y no lo es:

datos/importante.csv sigue ignorado. Git ha descartado datos/ entero y nunca ha llegado a evaluar la segunda línea.

La forma correcta es ignorar el contenido, no el directorio:

Con datos/*, Git sí entra en datos/, ignora cada uno de sus hijos individualmente, y la negación puede rescatar uno.

Si el fichero que quieres rescatar está más profundo, hay que des-ignorar cada nivel intermedio:

Traducido: ignora todo (*), pero no ignores los directorios (!*/, necesario para que Git pueda entrar en ellos), y rescata explícitamente ese fichero.

Este patrón de lista blanca —"ignorar todo y rescatar lo que quiero"— es agresivo pero muy útil en repositorios donde lo versionable es una minoría (por ejemplo, un repositorio de configuración):

Volvamos a las dos negaciones que dejamos pendientes:

Funciona porque .env.* ignora ficheros, no un directorio, y la negación posterior rescata uno. Correcto.

Fíjate en .vscode/* y no .vscode/. Si hubiéramos escrito .vscode/, las dos negaciones no harían nada. Este es exactamente el error que comete todo el mundo la primera vez.

Hay tres sitios donde declarar exclusiones, y elegir mal es la causa de una discusión recurrente en el equipo: Carla propuso añadir .idea/ al .gitignore del proyecto y Ana se opuso porque nadie más usa ese IDE. Los dos tenían parte de razón, y el problema era de nivel.

¿Este fichero aparecería en la máquina de cualquiera que trabajase en este proyecto? Si sí, va en el .gitignore del proyecto. Si aparece solo por tu sistema operativo o tu editor, va en tu global. Si es un capricho tuyo en este repositorio concreto, va en .git/info/exclude.

Estrictamente, .DS_Store e .idea/ van en el global. En la práctica, casi todos los proyectos los ponen también en el .gitignore del proyecto, como red de seguridad para quien no tenga el global configurado. Es defensivo y es razonable; simplemente hay que saber que es una duplicación deliberada.

En macOS y Linux, Git ya usa ~/.config/git/ignore sin necesidad de configurar nada si el fichero existe. Es la ubicación por defecto según el estándar XDG:

Es un .gitignore normal que vive dentro de .git/. Como todo lo que hay ahí (lección 01-04), no se versiona ni se clona:

Ventaja frente a modificar el .gitignore del proyecto: no ensucias el fichero compartido con tus manías, y no tienes que justificarlas en una revisión. Desventaja: se pierde si borras y vuelves a clonar el repositorio.

Aquí está la fuente del 90 % de las preguntas sobre .gitignore:

.gitignore solo afecta a ficheros SIN SEGUIMIENTO. Si un fichero ya está en el índice, Git seguirá registrando sus cambios por muchos patrones que escribas.

Recuerda los tres estados de la lección 01-03 y el ciclo de la lección 02-03. .gitignore actúa exclusivamente sobre la transición de sin seguimiento a preparado: le dice a Git "ni me lo propongas en git status, ni lo cojas con git add .". Sobre un fichero que ya cruzó esa frontera, no tiene ningún efecto.

El escenario típico, que le pasó a Bruno:

Sigue ahí. El .gitignore no ha hecho nada, porque esos ficheros ya están seguidos.

La flecha de vuelta —git rm --cached— es la única forma de devolver un fichero al estado donde .gitignore puede protegerlo.

git rm --cached quita el fichero del índice pero lo deja en tu disco. A partir de ese momento pasa a estar sin seguimiento, el .gitignore empieza a aplicarse y desaparece de git status.

El flujo completo, tal como lo hizo Ana:

Cuando hay muchos ficheros que ahora deberían estar ignorados, hay una receta que los saca todos a la vez respetando el .gitignore actual:

git rm -r --cached . no borra nada del disco: vacía el índice. git add . lo rellena de nuevo, y esta vez sí respeta el .gitignore. La diferencia entre ambos estados es exactamente el conjunto de ficheros que sobraban.

Comprueba siempre con git status antes de confirmar. Si el .gitignore tiene un patrón demasiado amplio, esta receta puede sacar del seguimiento ficheros que sí querías.

Advertencia 1: el fichero se borra en las demás máquinas. Para Git, un git rm --cached seguido de commit es un borrado. Cuando Bruno y Carla hagan pull, ese fichero desaparecerá de su copia de trabajo. Con node_modules/ da igual (se regenera con npm ci), pero si sacas del seguimiento un config.js que la gente necesita, se lo estás borrando. Avisa al equipo antes de hacerlo.

Advertencia 2: no borra nada del historial. Y esta es crítica:

El fichero desaparece de la punta, pero sigue en todos los commits anteriores:

Si config.js contenía una contraseña, la contraseña sigue en el repositorio y en todos los clones. git rm no es una herramienta de seguridad. El procedimiento correcto para un secreto ya filtrado —rotar primero la credencial, luego reescribir el historial— es el contenido de la lección 08-05.

Llega el día en que un fichero se ignora y no sabes por qué, o al revés. git check-ignore -v responde: te dice qué fichero de exclusión, qué línea y qué patrón están decidiendo.

Se lee: el patrón dist/, en la línea 8 del fichero .gitignore, es el que ignora dist/app.min.js.

Ejemplos de las tres respuestas posibles:

git status --ignored merece un apartado propio, porque es la forma de descubrir sorpresas:

Cada !! es un fichero o directorio que Git está ocultando. Si ves ahí algo que sí querías versionar, ya sabes que un patrón es demasiado amplio.

Si un fichero está seguido, check-ignore puede resultar confuso, porque los patrones sí casan aunque no tengan efecto. Para preguntar "¿casaría algún patrón, con independencia de si está seguido?":

Es decir: hay un patrón que lo cubriría, pero como el fichero ya está en el índice, no surte efecto. Ese diagnóstico —"el patrón está bien, el problema es el apartado 7"— es exactamente lo que necesitas saber.

A veces hace falta versionar un fichero que un patrón amplio está ignorando. git add -f (o --force) salta las reglas para esa operación concreta:

Sin -f, Git avisa y no hace nada:

Cuidado con lo que ocurre después. Una vez añadido con -f, el fichero pasa a estar seguido, y por la regla del apartado 7 el .gitignore deja de tener efecto sobre él para siempre: cada modificación aparecerá en git status. -f no es una excepción puntual, es un cambio de estado permanente.

Por eso casi siempre es mejor arreglar el patrón que forzar:

Así la excepción queda documentada en el repositorio en lugar de vivir en la memoria de quien un día escribió -f.

Y una advertencia que enlaza con la lección siguiente: -f es la vía por la que se cuelan los secretos. Alguien tiene prisa, Git se queja de que .env está ignorado, y git add -f .env resuelve el problema de los próximos cinco minutos a cambio de crear uno permanente. Si Git se resiste a añadir un fichero, párate a pensar por qué.

No hace falta escribir un .gitignore desde cero. Hay colecciones mantenidas por la comunidad con plantillas por lenguaje, framework, sistema operativo y editor; la más conocida es el repositorio github/gitignore, y la mayoría de plataformas ofrecen elegir una al crear el repositorio.

Recomendaciones de uso:

1. Parte de la plantilla de tu lenguaje, pero léela. Contiene reglas para herramientas que quizá no uses, y a veces ignora cosas que tú sí quieres.
2. Combina, no concatenes a ciegas. Una plantilla de Node más una de Python más tres de editores producen un fichero de 300 líneas que nadie mantiene.
3. Agrupa por secciones con comentarios, como en el ejemplo del apartado 2. Un .gitignore se lee muchas veces.
4. Las reglas de sistema operativo y editor, a tu global. Si todo el equipo tiene el global bien configurado, el .gitignore del proyecto queda corto y significativo.
5. Revísalo cuando cambien las herramientas. Un .gitignore con reglas para un empaquetador que dejasteis de usar hace dos años es ruido.

Una comprobación útil de vez en cuando, para ver qué reglas ya no sirven para nada:

Si una regla no aparece nunca aquí en ninguna máquina del equipo, probablemente sobra.

El problema real: la aplicación necesita saber la URL de la base de datos, la clave de la API de correo y un secreto de sesión. Esos valores no pueden estar en el repositorio, pero quien clone el proyecto tiene que saber qué valores necesita y cómo se llaman.

La solución convencional son dos ficheros:

.env — con los valores reales. Ignorado, nunca versionado.

.env.ejemplo — con las claves y valores de muestra, sin nada real. Versionado.

Y en el .gitignore, con la negación que ya conocemos:

Por qué funciona bien:

• Diego clona su fork, copia .env.ejemplo a .env, rellena sus valores y arranca. La documentación de qué hace falta está en el repositorio, actualizada, porque forma parte del código.
• Cuando alguien añade una variable nueva, la revisión de la PR detecta que falta en .env.ejemplo. Es un buen candidato a comprobación automática en el CI.
• Los valores de muestra son evidentemente falsos (pon-aqui-tu-clave), así que nadie los confunde con reales ni intenta usarlos.

Los tres errores que arruinan el patrón:

1. Poner valores reales en .env.ejemplo "para que sea más cómodo". Entonces el fichero versionado es el que tiene el secreto, y no has ganado nada.
2. Escribir .env* sin la negación. El .env.ejemplo también queda ignorado, nadie lo sube, y el patrón entero deja de existir.
3. Añadir el .gitignore demasiado tarde. Si .env ya se confirmó alguna vez, git rm --cached lo quita de la punta pero no del historial (apartado 8). El secreto sigue ahí.

Ese tercer caso —el secreto ya filtrado— tiene un procedimiento propio, con un orden de pasos que importa mucho: primero se rota la credencial, después se reescribe el historial. Es el núcleo de la lección 08-05.

Error 1: creer que .gitignore deja de seguir un fichero ya versionado. Es el malentendido número uno. Solo actúa sobre ficheros sin seguimiento; para el resto, git rm --cached.

Error 2: datos/ cuando querías datos/*. Si el directorio está ignorado, Git no entra y ninguna negación posterior funciona. Ignora el contenido, no el directorio.

Error 3: poner la negación antes del patrón. Gana la última línea que coincide. !errores.log seguido de *.log no sirve de nada.

Error 4: olvidar la barra inicial. build/ ignora cualquier build del proyecto; /build/ solo el de la raíz. Suele importar más de lo que parece.

Error 5: usar git add -f como solución habitual. Convierte el fichero en seguido para siempre y la excepción queda sin documentar. Arregla el patrón y escribe la negación.

Error 6: .env* sin !.env.ejemplo. Rompe el patrón de secretos entero.

Error 7: confiar en git rm --cached para eliminar un secreto. Solo lo quita de la punta. El historial y todos los clones lo conservan. Lección 08-05.

Error 8: llenar el .gitignore del proyecto con reglas personales. .idea/ y *.swp son de tu máquina; van a core.excludesFile. El .gitignore del proyecto debería contener solo lo que le pasaría a cualquiera.

Consejo 1: crea el .gitignore en el primer commit. Antes de instalar dependencias. Es infinitamente más barato que limpiarlo después.

Consejo 2: git status --ignored de vez en cuando. Es la única forma de ver qué está ocultando Git, y de detectar patrones demasiado amplios.

Consejo 3: git check-ignore -v en cuanto dudes. Responde en un segundo lo que si no se convierte en media hora de prueba y error.

Consejo 4: configura tu core.excludesFile una vez en la vida. Te ahorra ensuciar todos los repositorios en los que trabajes.

Consejo 5: comenta el .gitignore por secciones. Y explica los patrones raros. Dentro de un año nadie recordará por qué !config/produccion/ajustes.json está ahí.

Consejo 6: valida .env.ejemplo en el CI. Una comprobación que compare las claves de .env.ejemplo con las que el código lee de process.env evita que se desincronicen.

En un repositorio de pruebas, crea esta estructura:

1. Escribe un .gitignore con datos/ y !datos/publico.csv. Comprueba con git status y con git check-ignore -v que publico.csv sigue ignorado, y explica por qué.
2. Corrígelo para que publico.csv se versione y todo lo demás siga ignorado.
3. Ahora consigue que además se versione datos/copias/privado-2026.csv, sin versionar privado.csv.
4. Verifica cada paso con git check-ignore -v.

Simula el desastre de Bruno:

1. Crea un repositorio, un app.js, un directorio node_modules/ con tres ficheros, un .env con una contraseña ficticia y un .DS_Store.
2. Confírmalo todo sin .gitignore (el error de partida).
3. Añade ahora un .gitignore correcto, con el patrón de secretos del apartado 12.
4. Comprueba que git status sigue mostrando los ficheros que deberían estar ignorados y explica por qué.
5. Sácalos del seguimiento con la receta del apartado 8, sin borrarlos del disco.
6. Verifica que git status queda limpio, que los ficheros siguen en tu disco y que git status --ignored los muestra como ignorados.
7. Demuestra que la contraseña del .env sigue accesible en el historial y di qué lección lo resuelve.

1. Configura un core.excludesFile global con las reglas de tu sistema operativo y tu editor.
2. En un repositorio de pruebas, añade a .git/info/exclude un fichero notas-personales.md.
3. Añade al .gitignore del proyecto la regla dist/.
4. Crea los tres tipos de fichero y comprueba con git check-ignore -v que cada uno se ignora por el nivel correcto.
5. Para cada uno de estos ficheros, decide razonadamente en qué nivel debería estar la regla: node_modules/, .idea/workspace.xml, pruebas-de-carla.js, coverage/, .DS_Store, .env.

Solución 1:

datos/publico.csv no aparece: sigue ignorado.

El diagnóstico es explícito: quien decide es la línea 1, con el patrón datos/. La negación de la línea 2 nunca se evalúa, porque Git, al ignorar el directorio datos/, no entra en él. Es una optimización deliberada de rendimiento.

La clave del paso 3: hay que des-ignorar el directorio intermedio (!datos/copias/) para que Git entre en él, y luego volver a ignorar su contenido (datos/copias/*) para poder rescatar solo lo que interesa. Cada nivel de profundidad exige su propio par de líneas.

Solución 2:

Sigue apareciendo porque ya está seguido. .gitignore solo actúa en la frontera "sin seguimiento → preparado", y estos ficheros la cruzaron en el paso 2.

Las D son exactamente los ficheros que sobraban. app.js no aparece porque su contenido no ha cambiado.

Ahí está. Cualquiera con acceso al repositorio, ahora o dentro de cinco años, puede recuperarla con un solo comando, y todos los clones existentes la contienen. git rm --cached protege el futuro, no repara el pasado. El procedimiento correcto —rotar primero la credencial y después reescribir el historial con git filter-repo— es el contenido de la lección 08-05.

Solución 3:

app.js no aparece: no está ignorado por ninguna regla. Cada uno de los otros tres se ignora exactamente por el nivel que le corresponde.

5. Dónde va cada regla:

La última fila es el criterio de fondo: cuanto mayor sea la consecuencia de que la regla falte, más arriba debe estar y más versionada.

Lo esencial de esta lección:

• Se versiona la fuente, no el resultado. Fuera quedan dependencias, artefactos de compilación, ficheros del sistema operativo, configuración personal del editor, registros, temporales, binarios grandes y —por encima de todo— secretos. Dentro se quedan los ficheros de bloqueo de dependencias y la configuración compartida del proyecto.
• La sintaxis tiene tres reglas que hay que interiorizar: la barra final significa "solo directorios", la barra inicial ancla a la raíz, y cualquier barra en medio del patrón también ancla. Dentro de un fichero, gana la última línea que coincide.
• La negación con ! tiene un límite duro: no se puede des-ignorar un fichero dentro de un directorio ignorado, porque Git ni siquiera entra. Se ignora el contenido (datos/*), no el directorio (datos/).
• Hay tres niveles: el .gitignore del proyecto (versionado, para lo que le pasa a cualquiera), .git/info/exclude (local, para tus cosas en ese repositorio) y core.excludesFile (global, para lo que genera tu sistema operativo o tu editor). Cuanto más grave sea la consecuencia de que falte una regla, más arriba y más versionada debe estar.
• La regla que confunde a todo el mundo: .gitignore solo afecta a ficheros sin seguimiento. Sobre lo ya versionado no tiene ningún efecto. La vuelta atrás es git rm --cached, que quita del índice pero conserva en disco, con dos advertencias: borra el fichero en las demás máquinas al hacer pull, y no toca el historial.
• git check-ignore -v responde en un segundo qué fichero, qué línea y qué patrón deciden. git status --ignored muestra lo que Git te está ocultando.
• git add -f fuerza, pero convierte el fichero en seguido para siempre. Casi siempre es mejor escribir la excepción como negación, para que quede documentada.
• El patrón para secretos es .env ignorado + .env.ejemplo versionado con claves y valores evidentemente falsos, más la negación !.env.ejemplo. Es la mejor documentación posible de qué configuración necesita el proyecto.

gestor-tareas ya sabe qué ficheros no deben entrar. Queda el otro lado del problema: los ficheros que sí entran, pero que Git no debería tratar como si todos fueran iguales. Un PNG no es un fichero de texto y no tiene sentido intentar fusionarlo. Un CHANGELOG.md sí querría fusionarse de una forma especial. Y, sobre todo, está el problema que Carla lleva arrastrando desde el módulo 1: cada vez que edita un fichero en Windows, el git diff marca todas las líneas como modificadas.

Ese es el terreno de la lección 08-04: Atributos de Fichero con .gitattributes.