.gitignore — El archivo que te salva de incluir node_modules

Cada desarrollador ha hecho esto al menos una vez: cometer accidentalmente node_modules, a .env un archivo lleno de claves de API, o un artifacto de construcción de 200MB. El pánico es real. La solución es tediosa. Y todo esto podría haberse evitado con un solo archivo: .gitignore.

Esta guía explica qué .gitignore es, cómo funciona, qué poner en él, y algunos trampolines que atrapan incluso a desarrolladores experimentados.

¿Qué es .gitignore?

.gitignore es un archivo de texto plano que indica a Git qué archivos y directorios excluir del control de versiones. Cuando Git ve un camino listado en .gitignore, se imagina que ese camino no existe — no lo pondrá en staging, no lo incluirá en el commit ni lo mostrará en git status salida.

El archivo se encuentra en la raíz de tu repositorio, aunque también puedes colocar archivos específicos del proyecto en subdirectorios. Las reglas en un archivo de subdirectorio solo se aplican a ese directorio y a sus hijos. .gitignore ¿Por qué necesitas uno? (Versión corta)

— mantiene secretos, claves de API y contraseñas fuera de tu historia de Git

• Seguridad Tamaño del repositorio
• — evita que archivos generados y dependencias enriquezcan tu repositorio Reducción de ruido
• — evita que archivos de configuración del editor y basura del sistema operativo empañen cada diferencia Sana del equipo
• — todos clonan un repositorio limpio y instalan dependencias localmente Cómo funciona la sintaxis

Las reglas son simples pero tienen algunos bordes no obvios:

Líneas en blanco y líneas que comienzan con

• se ignoran (usa # para comentarios) # Un patrón sin barra invertida
• aplica a cualquier archivo o directorio con ese nombre en cualquier parte del repositorio: ignora todos los archivos de registro en cualquier profundidad *.log Una barra al final
• aplica solo a directorios: ignora el directorio pero no un archivo llamado dist/ Una barra al principio dist
• ancla el patrón al root del repositorio: ignora solo un /todo.txt en la raíz absoluta todo.txt Dos asteriscos (
• aplica a través de límites de directorio:**) en cualquier parte del árbol **/logs coincide logs/ Un signo de exclamación (
• negará un patrón, re-incluyendo un archivo que fue excluido por una regla anterior!) Ejemplo mínimo

Las entradas más comunes (y por qué importan)

# Dependencies
node_modules/

# Environment files
.env
.env.local
.env.*.local

# Build output
dist/
build/

# Editor noise
.vscode/
.idea/
*.swp

# OS files
.DS_Store
Thumbs.db

# Logs
*.log
npm-debug.log*

node_modules/

Este es el más importante. Un proyecto típico de Node.js tiene miles de archivos en

— a menudo cientos de megabytes. Ninguno de ellos pertenece al control de versiones. Cualquier persona que clone tu repositorio ejecuta node_modules/ y lo reconstruye localmente desde npm install . Siempre ignóralo. package.json.env y archivos secretos

Los archivos de entorno contienen contraseñas de bases de datos, claves de API y tokens de servicios. Un archivo .env comprometido es un incidente de seguridad por venir — GitHub escanea por secretos filtrados, pero también lo hacen los bots. Ignora el archivo, y comitea un

con valores de ejemplo en lugar de eso, para que los compañeros de equipo sepan qué variables deben configurar. .env dist/ y build/ .env.example El resultado compilado o empaquetado se deriva del código fuente. Tu pipeline de CI lo reconstruye en cada despliegue. Cometer artefactos de compilación crea conflictos de fusión y diferencias falsas que ocultan cambios reales en el código.

Archivos del editor y del sistema operativo

(macOS),

(Windows),

.DS_Store (JetBrains), Thumbs.db (configuraciones de VS Code) — estos son archivos personales del entorno. Cometerlos obliga a que tus preferencias se carguen en todos los demás contribuyentes. Usa un archivo global .idea/ para el ruido específico de la máquina, así que no tengas que agregarlos a cada proyecto. .vscode/ .gitignore global: Configurarlo una vez, olvídate de él ~/.gitignore_global Puedes configurar un archivo de ignoración global que se aplique a todos los repositorios en tu máquina:

Coloca allí archivos del editor, basura del sistema operativo y herramientas personales. Reserva el archivo de proyecto para lo que toda la gente de equipo acuerde ignorar — como

El engaño de "ya trazado"

git config --global core.excludesfile ~/.gitignore_global

Aquí es donde los desarrolladores se quedan sin recursos: .gitignore solo previene que los archivos no trazados se agreguen. Si un archivo ya está en tu historia de Git, agregarlo a node_modules/ o dist/.

no hace nada. Git sigue rastreándolo y seguirá cometiendo cambios en él.

Para detener el rastreo de un archivo ya cometido: .gitignore Después de eso, el archivo permanece en el disco pero Git lo ignora a partir de ahora. Reglas de negación: re-incluir archivos A veces deseas ignorar un directorio, pero mantener un archivo específico — por ejemplo, ignorar .gitignore pero mantener

ya en el repositorio:

# Remove the file from git tracking without deleting it locally
git rm --cached path/to/file

# Or remove a whole directory
git rm -r --cached node_modules/

# Then commit the removal
git commit -m "Stop tracking node_modules"

Una limitación: la negación no puede deshacer el ignorado de un archivo dentro de un directorio ignorado. Git deja de descender en directorios ignorados, así que la

regla nunca tiene la oportunidad de activarse. Debes ignorar el contenido en lugar de ignorar el directorio mismo:

Generar un .gitignore para tu pila config/ No necesitas escribirlo desde cero. config/defaults.json gitignore.io

config/
!config/defaults.json

(también en ! ) te permite elegir tu lenguaje, marco y editor y genera un archivo de ignoración completo en segundos. GitHub también ofrece plantillas oficiales en su repositorio

# Wrong — Git never sees defaults.json inside an ignored directory
config/
!config/defaults.json

# Right — ignore everything in config/ except defaults.json
config/*
!config/defaults.json

github/gitignore

— estas son bien mantenidas y cubren cientos de entornos. Para la mayoría de proyectos web, un punto de partida sólido combina plantillas para tu lenguaje (Node, Python, PHP, etc.), tu editor (VS Code, JetBrains) y tu sistema operativo (macOS, Windows). Verificar qué está siendo ignorado por Git gitignore.ioDos comandos ayudan a depurar una regla de ignoración inesperada: es especialmente útil cuando una regla no hace lo que esperas — muestra el archivo, el número de línea y el patrón responsable. Referencia rápida: hoja de cálculo de patrones

¿Qué ignora?

archivos en cualquier lugar

Solo

# See which files are being ignored in the current directory
git status --ignored

# Find out exactly which rule is causing a file to be ignored
git check-ignore -v path/to/file

git check-ignore -v en la raíz

Cualquier directorio llamado

Patrón	directorio en cualquier profundidad
*.log	Todo .log Re-incluir
/debug.log	aunque debug.log lo coincida
logs/	archivos directamente dentro de logs
**/logs	logs (no subdirectorios)
!important.log	archivos en cualquier lugar bajo important.log .gitignore — El archivo que te salva de cometer node_modules 2 *.log .gitignore — El archivo que te salva de cometer node_modules 1
doc/*.txt	.txt archivos directamente dentro doc/ (no subdirectorios)
doc/**/*.txt	.txt archivos en cualquier lugar bajo doc/

También te puede interesar